src/api/SamHeader.cpp

   1 // ***************************************************************************
   2 // SamHeader.cpp (c) 2010 Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // ---------------------------------------------------------------------------
   5 // Last modified: 6 October 2011 (DB)
   6 // ---------------------------------------------------------------------------
   7 // Provides direct read/write access to the SAM header data fields.
   8 // ***************************************************************************
   9
  10 #include <api/SamConstants.h>
  11 #include <api/SamHeader.h>
  12 #include <api/internal/BamException_p.h>
  13 #include <api/internal/SamFormatParser_p.h>
  14 #include <api/internal/SamFormatPrinter_p.h>
  15 #include <api/internal/SamHeaderValidator_p.h>
  16 using namespace BamTools;
  17 using namespace BamTools::Internal;
  18 using namespace std;
  19
  20 /*! \struct BamTools::SamHeader
  21     \brief Represents the SAM-formatted text header that is part of the BAM file header.
  22
  23     Provides direct read/write access to the SAM header data fields.
  24
  25     \sa \samSpecURL
  26 */
  27 /*! \var SamHeader::Version
  28     \brief corresponds to \@HD VN:\<Version\>
  29
  30     Required for valid SAM header, if @HD record is present.
  31 */
  32 /*! \var SamHeader::SortOrder
  33     \brief corresponds to \@HD SO:\<SortOrder\>
  34 */
  35 /*! \var SamHeader::GroupOrder
  36     \brief corresponds to \@HD GO:\<GroupOrder\>
  37 */
  38 /*! \var SamHeader::Sequences
  39     \brief corresponds to \@SQ entries
  40     \sa SamSequence, SamSequenceDictionary
  41 */
  42 /*! \var SamHeader::ReadGroups
  43     \brief corresponds to \@RG entries
  44     \sa SamReadGroup, SamReadGroupDictionary
  45 */
  46 /*! \var SamHeader::ProgramName
  47     \brief corresponds to \@PG ID:\<ProgramName\>
  48 */
  49 /*! \var SamHeader::ProgramVersion
  50     \brief corresponds to \@PG VN:\<ProgramVersion\>
  51 */
  52 /*! \var SamHeader::ProgramCommandLine
  53     \brief corresponds to \@PG CL:\<ProgramCommandLine\>
  54 */
  55 /*! \var SamHeader::Comments
  56     \brief corresponds to \@CO entries
  57 */
  58
  59 /*! \fn SamHeader::SamHeader(const std::string& headerText = "")
  60     \brief constructor
  61 */
  62 SamHeader::SamHeader(const std::string& headerText)
  63     : Version("")
  64     , SortOrder(Constants::SAM_HD_SORTORDER_UNKNOWN)
  65     , GroupOrder("")
  66 {
  67     SetHeaderText(headerText);
  68 }
  69
  70 /*! \fn SamHeader::SamHeader(const SamHeader& other)
  71     \brief copy constructor
  72 */
  73 SamHeader::SamHeader(const SamHeader& other)
  74     : Version(other.Version)
  75     , SortOrder(other.SortOrder)
  76     , GroupOrder(other.GroupOrder)
  77     , Sequences(other.Sequences)
  78     , ReadGroups(other.ReadGroups)
  79     , Programs(other.Programs)
  80 { }
  81
  82 /*! \fn SamHeader::~SamHeader(void)
  83     \brief destructor
  84 */
  85 SamHeader::~SamHeader(void) { }
  86
  87 /*! \fn void SamHeader::Clear(void)
  88     \brief Clears all header contents.
  89 */
  90 void SamHeader::Clear(void) {
  91
  92     // clear SAM header components
  93     Version.clear();
  94     SortOrder.clear();
  95     GroupOrder.clear();
  96     Sequences.Clear();
  97     ReadGroups.Clear();
  98     Programs.Clear();
  99     Comments.clear();
 100
 101     // clear error string
 102     m_errorString.clear();
 103 }
 104
 105 /*! \fn std::string SamHeader::GetErrorString(void) const
 106     \brief Returns human-readable description of last error encountered
 107 */
 108 std::string SamHeader::GetErrorString(void) const {
 109     return m_errorString;
 110 }
 111
 112 /*! \fn bool SamHeader::HasError(void) const
 113     \brief Returns \c true if header encountered an error
 114 */
 115 bool SamHeader::HasError(void) const {
 116     return (!m_errorString.empty());
 117 }
 118
 119 /*! \fn bool SamHeader::HasVersion(void) const
 120     \brief Returns \c true if header contains \@HD ID:\<Version\>
 121 */
 122 bool SamHeader::HasVersion(void) const {
 123     return (!Version.empty());
 124 }
 125
 126 /*! \fn bool SamHeader::HasSortOrder(void) const
 127     \brief Returns \c true if header contains \@HD SO:\<SortOrder\>
 128 */
 129 bool SamHeader::HasSortOrder(void) const {
 130     return (!SortOrder.empty());
 131 }
 132
 133 /*! \fn bool SamHeader::HasGroupOrder(void) const
 134     \brief Returns \c true if header contains \@HD GO:\<GroupOrder\>
 135 */
 136 bool SamHeader::HasGroupOrder(void) const {
 137     return (!GroupOrder.empty());
 138 }
 139
 140 /*! \fn bool SamHeader::HasSequences(void) const
 141     \brief Returns \c true if header contains any \@SQ entries
 142 */
 143 bool SamHeader::HasSequences(void) const {
 144     return (!Sequences.IsEmpty());
 145 }
 146
 147 /*! \fn bool SamHeader::HasReadGroups(void) const
 148     \brief Returns \c true if header contains any \@RG entries
 149 */
 150 bool SamHeader::HasReadGroups(void) const {
 151     return (!ReadGroups.IsEmpty());
 152 }
 153
 154 /*! \fn bool SamHeader::HasPrograms(void) const
 155     \brief Returns \c true if header contains any \@PG entries
 156 */
 157 bool SamHeader::HasPrograms(void) const {
 158     return (!Programs.IsEmpty());
 159 }
 160
 161 /*! \fn bool SamHeader::HasComments(void) const
 162     \brief Returns \c true if header contains any \@CO entries
 163 */
 164 bool SamHeader::HasComments(void) const {
 165     return (!Comments.empty());
 166 }
 167
 168 /*! \fn bool SamHeader::IsValid(bool verbose = false) const
 169     \brief Checks header contents for required data and proper formatting.
 170     \param verbose If set to true, validation errors & warnings will be printed to stderr.
 171                    Otherwise, messages are available through SamHeader::GetErrorString().
 172     \return \c true if SAM header is well-formed
 173 */
 174 bool SamHeader::IsValid(bool verbose) const {
 175
 176     SamHeaderValidator validator(*this);
 177
 178     // if SAM header is valid, return success
 179     if ( validator.Validate() )
 180         return true;
 181
 182     // otherwiser
 183     else {
 184
 185         // print messages to stderr
 186         if ( verbose )
 187             validator.PrintMessages(std::cerr);
 188
 189         // or catch in local error string
 190         else {
 191             stringstream errorStream("");
 192             validator.PrintMessages(errorStream);
 193             m_errorString = errorStream.str();
 194         }
 195         return false;
 196     }
 197 }
 198
 199 /*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
 200     \brief Replaces header contents with \a headerText.
 201     \param headerText SAM formatted-text that will be parsed into data fields
 202 */
 203 void SamHeader::SetHeaderText(const std::string& headerText) {
 204
 205     // clear prior data
 206     Clear();
 207
 208     try {
 209         SamFormatParser parser(*this);
 210         parser.Parse(headerText);
 211     } catch ( BamException& e ) {
 212
 213         // clear anything parsed so far
 214         // no telling what's valid and what's partially parsed
 215         Clear();
 216
 217         // set error string
 218         m_errorString = e.what();
 219     }
 220 }
 221
 222 /*! \fn std::string SamHeader::ToString(void) const
 223     \brief Converts data fields to SAM-formatted text.
 224
 225     Applies any local modifications made since creating this object or calling SetHeaderText().
 226
 227     \return SAM-formatted header text
 228 */
 229 string SamHeader::ToString(void) const {
 230     SamFormatPrinter printer(*this);
 231     return printer.ToString();
 232 }