// Marth Lab, Department of Biology, Boston College\r
// All rights reserved.\r
// ---------------------------------------------------------------------------\r
-// Last modified: 11 January 2011 (DB)\r
+// Last modified: 4 March 2011 (DB)\r
// ---------------------------------------------------------------------------\r
// Provides the basic functionality for producing BAM files\r
// ***************************************************************************\r
\r
+#include <api/BamAlignment.h>\r
#include <api/BamWriter.h>\r
+#include <api/SamHeader.h>\r
#include <api/internal/BamWriter_p.h>\r
using namespace BamTools;\r
using namespace BamTools::Internal;\r
#include <iostream>\r
using namespace std;\r
\r
-// constructor\r
-BamWriter::BamWriter(void) {\r
- d = new BamWriterPrivate;\r
-}\r
+/*! \class BamTools::BamWriter\r
+ \brief Provides write access for generating BAM files.\r
+*/\r
+/*! \enum BamTools::BamWriter::CompressionMode\r
+ \brief This enum describes the compression behaviors for output BAM files.\r
+*/\r
+/*! \var BamWriter::CompressionMode BamWriter::Compressed\r
+ \brief Use normal BAM compression\r
+*/\r
+/*! \var BamWriter::CompressionMode BamWriter::Uncompressed\r
+ \brief Disable BAM compression\r
+\r
+ Useful in situations where the BAM data is streamed (e.g. piping).\r
+ It would be wasteful to compress, and then immediately decompress\r
+ the data.\r
+*/\r
+\r
+/*! \fn BamWriter::BamWriter(void)\r
+ \brief constructor\r
+*/\r
+BamWriter::BamWriter(void)\r
+ : d(new BamWriterPrivate)\r
+{ }\r
\r
-// destructor\r
+/*! \fn BamWriter::~BamWriter(void)\r
+ \brief destructor\r
+*/\r
BamWriter::~BamWriter(void) {\r
delete d;\r
d = 0;\r
}\r
\r
-// closes the alignment archive\r
+/*! \fn BamWriter::Close(void)\r
+ \brief Closes the current BAM file.\r
+ \sa Open()\r
+*/\r
void BamWriter::Close(void) {\r
d->Close();\r
}\r
\r
-// opens the alignment archive (using std::string SAM header)\r
-bool BamWriter::Open(const string& filename,\r
- const string& samHeader,\r
- const RefVector& referenceSequences,\r
- bool isWriteUncompressed)\r
+/*! \fn bool BamWriter::IsOpen(void) const\r
+ \brief Returns \c true if BAM file is open for writing.\r
+ \sa Open()\r
+*/\r
+bool BamWriter::IsOpen(void) const {\r
+ return d->IsOpen();\r
+}\r
+\r
+/*! \fn bool BamWriter::Open(const std::string& filename,\r
+ const std::string& samHeaderText,\r
+ const RefVector& referenceSequences)\r
+ \brief Opens a BAM file for writing.\r
+\r
+ Will overwrite the BAM file if it already exists.\r
+\r
+ \param filename name of output BAM file\r
+ \param samHeaderText header data, as SAM-formatted string\r
+ \param referenceSequences list of reference entries\r
+\r
+ \return \c true if opened successfully\r
+ \sa Close(), IsOpen(), BamReader::GetHeaderText(), BamReader::GetReferenceData()\r
+*/\r
+bool BamWriter::Open(const std::string& filename,\r
+ const std::string& samHeaderText,\r
+ const RefVector& referenceSequences)\r
{\r
- return d->Open(filename, samHeader, referenceSequences, isWriteUncompressed);\r
+ return d->Open(filename, samHeaderText, referenceSequences);\r
}\r
\r
-// opens the alignment archive (using SamHeader object)\r
-bool BamWriter::Open(const string& filename,\r
+/*! \fn bool BamWriter::Open(const std::string& filename,\r
+ const SamHeader& samHeader,\r
+ const RefVector& referenceSequences)\r
+ \brief Opens a BAM file for writing.\r
+\r
+ This is an overloaded function.\r
+\r
+ Will overwrite the BAM file if it already exists.\r
+\r
+ \param filename name of output BAM file\r
+ \param samHeader header data, wrapped in SamHeader object\r
+ \param referenceSequences list of reference entries\r
+\r
+ \return \c true if opened successfully\r
+ \sa Close(), IsOpen(), BamReader::GetHeader(), BamReader::GetReferenceData()\r
+*/\r
+bool BamWriter::Open(const std::string& filename,\r
const SamHeader& samHeader,\r
- const RefVector& referenceSequences,\r
- bool isWriteUncompressed)\r
+ const RefVector& referenceSequences)\r
{\r
- return d->Open(filename, samHeader.ToString(), referenceSequences, isWriteUncompressed);\r
+ return d->Open(filename, samHeader.ToString(), referenceSequences);\r
+}\r
+\r
+/*! \fn void BamWriter::SaveAlignment(const BamAlignment& alignment)\r
+ \brief Saves an alignment to the BAM file.\r
+\r
+ \param alignment BamAlignment record to save\r
+ \sa BamReader::GetNextAlignment(), BamReader::GetNextAlignmentCore()\r
+*/\r
+void BamWriter::SaveAlignment(const BamAlignment& alignment) {\r
+ d->SaveAlignment(alignment);\r
}\r
\r
-// saves the alignment to the alignment archive\r
-void BamWriter::SaveAlignment(const BamAlignment& al) {\r
- d->SaveAlignment(al);\r
+/*! \fn void BamWriter::SetCompressionMode(const CompressionMode& compressionMode)\r
+ \brief Sets the output compression mode.\r
+\r
+ Default mode is BamWriter::Compressed.\r
+\r
+ N.B. - Changing the compression mode is disabled on open files (i.e. the request will be ignored).\r
+ Be sure to call this function before opening the BAM file.\r
+\r
+ \code\r
+ BamWriter writer;\r
+ writer.SetCompressionMode(BamWriter::Uncompressed);\r
+ writer.Open( ... );\r
+ // ...\r
+ \endcode\r
+\r
+ \param compressionMode desired output compression behavior\r
+ \sa IsOpen(), Open()\r
+*/\r
+void BamWriter::SetCompressionMode(const CompressionMode& compressionMode) {\r
+ d->SetWriteCompressed( compressionMode == BamWriter::Compressed );\r
}\r
projects / bamtools.git / blobdiff