// ***************************************************************************\r
// BamWriter.cpp (c) 2009 Michael Str�mberg, Derek Barnett\r
// Marth Lab, Department of Biology, Boston College\r
-// All rights reserved.\r
// ---------------------------------------------------------------------------\r
-// Last modified: 22 November 2010 (DB)\r
+// Last modified: 10 October 2011 (DB)\r
// ---------------------------------------------------------------------------\r
// Provides the basic functionality for producing BAM files\r
// ***************************************************************************\r
\r
-#include <api/BamWriter.h>\r
-#include <api/internal/BamWriter_p.h>\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
-\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\r
-bool BamWriter::Open(const string& filename,\r
- const string& samHeader,\r
- const RefVector& referenceSequences,\r
- bool isWriteUncompressed)\r
+/*! \fn std::string BamWriter::GetErrorString(void) const\r
+ \brief Returns a human-readable description of the last error that occurred\r
+\r
+ This method allows elimination of STDERR pollution. Developers of client code\r
+ may choose how the messages are displayed to the user, if at all.\r
+\r
+ \return error description\r
+*/\r
+std::string BamWriter::GetErrorString(void) const {\r
+ return d->GetErrorString();\r
+}\r
+\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[in] filename name of output BAM file\r
+ \param[in] samHeaderText header data, as SAM-formatted string\r
+ \param[in] 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
-// saves the alignment to the alignment archive\r
-void BamWriter::SaveAlignment(const BamAlignment& al) {\r
- d->SaveAlignment(al);\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[in] filename name of output BAM file\r
+ \param[in] samHeader header data, wrapped in SamHeader object\r
+ \param[in] 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
+{\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[in] alignment BamAlignment record to save\r
+ \sa BamReader::GetNextAlignment(), BamReader::GetNextAlignmentCore()\r
+*/\r
+bool BamWriter::SaveAlignment(const BamAlignment& alignment) {\r
+ return d->SaveAlignment(alignment);\r
+}\r
+\r
+/*! \fn void BamWriter::SetCompressionMode(const BamWriter::CompressionMode& compressionMode)\r
+ \brief Sets the output compression mode.\r
+\r
+ Default mode is BamWriter::Compressed.\r
+\r
+ \note Changing the compression mode is disabled on open files (i.e. the request will\r
+ be ignored). 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[in] compressionMode desired output compression behavior\r
+ \sa IsOpen(), Open()\r
+*/\r
+void BamWriter::SetCompressionMode(const BamWriter::CompressionMode& compressionMode) {\r
+ d->SetWriteCompressed( compressionMode == BamWriter::Compressed );\r
}\r
projects / bamtools.git / blobdiff