X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=src%2Fapi%2FBamReader.h;h=15b41354d9e2e119e2c1e4e2cc38cd80fd500ecc;hb=e9977c58d60d1a1b2034eb3f01cd0183cbfe8736;hp=132c95b826dbe854750c883fe38d20a4a2ab4806;hpb=b7549281cadae48219dd42fb93a14524b35fdb0f;p=bamtools.git

diff --git a/src/api/BamReader.h b/src/api/BamReader.h
index 132c95b..15b4135 100644
--- a/src/api/BamReader.h
+++ b/src/api/BamReader.h
@@ -1,25 +1,28 @@
 // ***************************************************************************
 // BamReader.h (c) 2009 Derek Barnett, Michael Str�mberg
 // Marth Lab, Department of Biology, Boston College
-// All rights reserved.
 // ---------------------------------------------------------------------------
-// Last modified: 18 September 2010 (DB)
+// Last modified: 18 November 2012 (DB)
 // ---------------------------------------------------------------------------
-// Uses BGZF routines were adapted from the bgzf.c code developed at the Broad
-// Institute.
-// ---------------------------------------------------------------------------
-// Provides the basic functionality for reading BAM files
+// Provides read access to BAM files.
 // ***************************************************************************
 
 #ifndef BAMREADER_H
 #define BAMREADER_H
 
+#include "api/api_global.h"
+#include "api/BamAlignment.h"
+#include "api/BamIndex.h"
+#include "api/SamHeader.h"
 #include <string>
-#include "BamAlignment.h"
 
 namespace BamTools {
   
-class BamReader {
+namespace Internal {
+    class BamReaderPrivate;
+} // namespace Internal
+
+class API_EXPORT BamReader {
 
     // constructor / destructor
     public:
@@ -33,69 +36,82 @@ class BamReader {
         // BAM file operations
         // ----------------------
 
-        // close BAM file
-        void Close(void);
-        // returns whether index data is loaded (i.e. reader is able to Jump() or not)
-        bool IsIndexLoaded(void) const;
-        // returns whether reader is open for reading or not
+        // closes the current BAM file
+        bool Close(void);
+        // returns filename of current BAM file
+        const std::string GetFilename(void) const;
+        // returns true if a BAM file is open for reading
         bool IsOpen(void) const;
-        // performs random-access jump using (reference, position) as a left-bound
+        // performs random-access jump within BAM file
         bool Jump(int refID, int position = 0);
-        // opens BAM file (and optional BAM index file, if provided)
-        // @lookForIndex - if no indexFilename provided, look for an existing index file
-        // @preferStandardIndex - if true, give priority in index file searching to standard BAM index
-        bool Open(const std::string& filename, 
-                  const std::string& indexFilename = "", 
-                  const bool lookForIndex = false, 
-                  const bool preferStandardIndex = false);
-        // returns file pointer to beginning of alignments
+        // opens a BAM file
+        bool Open(const std::string& filename);
+        // returns internal file pointer to beginning of alignment data
         bool Rewind(void);
-        // sets a region of interest (with left & right bound reference/position)
-        // attempts a Jump() to left bound as well
-        // returns success/failure of Jump()
+        // sets the target region of interest
         bool SetRegion(const BamRegion& region);
-        bool SetRegion(const int& leftRefID, const int& leftBound, const int& rightRefID, const int& rightBound);
+        // sets the target region of interest
+        bool SetRegion(const int& leftRefID,
+                       const int& leftPosition,
+                       const int& rightRefID,
+                       const int& rightPosition);
 
         // ----------------------
         // access alignment data
         // ----------------------
 
-        // retrieves next available alignment (returns success/fail)
-        bool GetNextAlignment(BamAlignment& bAlignment);
-        
-        // retrieves next available alignment core data (returns success/fail)
-        // ** DOES NOT parse any character data (read name, bases, qualities, tag data) **
-        // useful for operations requiring ONLY aligner-related information (refId/position, alignment flags, CIGAR, mapQuality, etc)
-        bool GetNextAlignmentCore(BamAlignment& bAlignment);
+        // retrieves next available alignment
+        bool GetNextAlignment(BamAlignment& alignment);
+        // retrieves next available alignmnet (without populating the alignment's string data fields)
+        bool GetNextAlignmentCore(BamAlignment& alignment);
 
         // ----------------------
-        // access auxiliary data
+        // access header data
         // ----------------------
 
-        // returns SAM header text
-        const std::string GetHeaderText(void) const;
-        // returns number of reference sequences
+        // returns a read-only reference to SAM header data
+        const SamHeader& GetConstSamHeader(void) const;
+        // returns an editable copy of SAM header data
+        SamHeader GetHeader(void) const;
+        // returns SAM header data, as SAM-formatted text
+        std::string GetHeaderText(void) const;
+
+        // ----------------------
+        // access reference data
+        // ----------------------
+
+        // returns the number of reference sequences
         int GetReferenceCount(void) const;
-        // returns vector of reference objects
-        const BamTools::RefVector& GetReferenceData(void) const;
-        // returns reference id (used for BamReader::Jump()) for the given reference name
+        // returns all reference sequence entries
+        const RefVector& GetReferenceData(void) const;
+        // returns the ID of the reference with this name
         int GetReferenceID(const std::string& refName) const;
-        // returns the name of the file associated with this BamReader
-        const std::string GetFilename(void) const;
 
         // ----------------------
         // BAM index operations
         // ----------------------
 
-        // creates index for BAM file, saves to file
-        // default behavior is to create the BAM standard index (".bai")
-        // set flag to false to create the BamTools-specific index (".bti")
-        bool CreateIndex(bool useStandardIndex = true);
+        // creates an index file for current BAM file, using the requested index type
+        bool CreateIndex(const BamIndex::IndexType& type = BamIndex::STANDARD);
+        // returns true if index data is available
+        bool HasIndex(void) const;
+        // looks in BAM file's directory for a matching index file
+        bool LocateIndex(const BamIndex::IndexType& preferredType = BamIndex::STANDARD);
+        // opens a BAM index file
+        bool OpenIndex(const std::string& indexFilename);
+        // sets a custom BamIndex on this reader
+        void SetIndex(BamIndex* index);
+
+        // ----------------------
+        // error handling
+        // ----------------------
+
+        // returns a human-readable description of the last error that occurred
+        std::string GetErrorString(void) const;
         
     // private implementation
     private:
-        struct BamReaderPrivate;
-        BamReaderPrivate* d;
+        Internal::BamReaderPrivate* d;
 };
 
 } // namespace BamTools