X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=src%2Fapi%2FBamReader.h;h=836fbf5e3cbac860f62916c3e717c72618089a7b;hb=72f5b82ad353b4cc9d6f8153f1ad19cc387b9597;hp=6e863b6beded3fbded2b9d70b0442b4c1276dbaf;hpb=90bb3691f9aa2a2e8a4dd906c2439c7bc434eb78;p=bamtools.git

diff --git a/src/api/BamReader.h b/src/api/BamReader.h
index 6e863b6..836fbf5 100644
--- a/src/api/BamReader.h
+++ b/src/api/BamReader.h
@@ -1,28 +1,28 @@
 // ***************************************************************************
 // BamReader.h (c) 2009 Derek Barnett, Michael Str�mberg
 // Marth Lab, Department of Biology, Boston College
-// All rights reserved.
 // ---------------------------------------------------------------------------
-// Last modified: 3 September 2010 (DB)
+// Last modified: 4 March 2011 (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
 
-// C++ includes
+#include <api/api_global.h>
+#include <api/BamAlignment.h>
+#include <api/BamIndex.h>
+#include <api/SamHeader.h>
 #include <string>
 
-// BamTools includes
-#include "BamAux.h"
-
 namespace BamTools {
   
-class BamReader {
+namespace Internal {
+    class BamReaderPrivate;
+} // namespace Internal
+
+class API_EXPORT BamReader {
 
     // constructor / destructor
     public:
@@ -36,70 +36,80 @@ class BamReader {
         // BAM file operations
         // ----------------------
 
-        // close BAM file
+        // closes the current 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
+        // 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 to reference, position
+        // 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)
-        //    these can be accessed, if necessary, from the supportData 
-        // useful for operations requiring ONLY positional or other alignment-related information
-        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 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);
+        // changes the caching behavior of the index data
+        void SetIndexCacheMode(const BamIndex::IndexCacheMode& mode);
+
+    // deprecated methods
+    public:
+        // returns true if index data is available
+        bool IsIndexLoaded(void) const;
         
     // private implementation
     private:
-        struct BamReaderPrivate;
-        BamReaderPrivate* d;
+        Internal::BamReaderPrivate* d;
 };
 
 } // namespace BamTools