src/api/SamHeader.cpp

   1 // ***************************************************************************
   2 // SamHeader.cpp (c) 2010 Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // ---------------------------------------------------------------------------
   5 // Last modified: 10 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::Programs
  47     \brief corresponds to \@PG entries
  48     \sa SamProgram, SamProgramChain
  49 */
  50 /*! \var SamHeader::Comments
  51     \brief corresponds to \@CO entries
  52 */
  53
  54 /*! \fn SamHeader::SamHeader(const std::string& headerText = "")
  55     \brief constructor
  56 */
  57 SamHeader::SamHeader(const std::string& headerText)
  58     : Version("")
  59     , SortOrder(Constants::SAM_HD_SORTORDER_UNKNOWN)
  60     , GroupOrder("")
  61 {
  62     SetHeaderText(headerText);
  63 }
  64
  65 /*! \fn SamHeader::SamHeader(const SamHeader& other)
  66     \brief copy constructor
  67 */
  68 SamHeader::SamHeader(const SamHeader& other)
  69     : Version(other.Version)
  70     , SortOrder(other.SortOrder)
  71     , GroupOrder(other.GroupOrder)
  72     , Sequences(other.Sequences)
  73     , ReadGroups(other.ReadGroups)
  74     , Programs(other.Programs)
  75 { }
  76
  77 /*! \fn SamHeader::~SamHeader(void)
  78     \brief destructor
  79 */
  80 SamHeader::~SamHeader(void) { }
  81
  82 /*! \fn void SamHeader::Clear(void)
  83     \brief Clears all header contents.
  84 */
  85 void SamHeader::Clear(void) {
  86
  87     // clear SAM header components
  88     Version.clear();
  89     SortOrder.clear();
  90     GroupOrder.clear();
  91     Sequences.Clear();
  92     ReadGroups.Clear();
  93     Programs.Clear();
  94     Comments.clear();
  95
  96     // clear error string
  97     m_errorString.clear();
  98 }
  99
 100 /*! \fn std::string SamHeader::GetErrorString(void) const
 101     \brief Returns a human-readable description of the last error that occurred
 102
 103     This method allows elimination of STDERR pollution. Developers of client code
 104     may choose how the messages are displayed to the user, if at all.
 105
 106     \return error description
 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
 171     \param[in] verbose If set to true, validation errors & warnings will be printed to stderr.
 172                        Otherwise, messages are available through SamHeader::GetErrorString().
 173     \return \c true if SAM header is well-formed
 174 */
 175 bool SamHeader::IsValid(bool verbose) const {
 176
 177     SamHeaderValidator validator(*this);
 178
 179     // if SAM header is valid, return success
 180     if ( validator.Validate() )
 181         return true;
 182
 183     // otherwiser
 184     else {
 185
 186         // print messages to stderr
 187         if ( verbose )
 188             validator.PrintMessages(std::cerr);
 189
 190         // or catch in local error string
 191         else {
 192             stringstream errorStream("");
 193             validator.PrintMessages(errorStream);
 194             m_errorString = errorStream.str();
 195         }
 196         return false;
 197     }
 198 }
 199
 200 /*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
 201     \brief Replaces header contents with \a headerText.
 202
 203     \param[in] headerText SAM formatted-text that will be parsed into data fields
 204 */
 205 void SamHeader::SetHeaderText(const std::string& headerText) {
 206
 207     // clear prior data
 208     Clear();
 209
 210     try {
 211         SamFormatParser parser(*this);
 212         parser.Parse(headerText);
 213     } catch ( BamException& e ) {
 214
 215         // clear anything parsed so far
 216         // no telling what's valid and what's partially parsed
 217         Clear();
 218
 219         // set error string
 220         m_errorString = e.what();
 221     }
 222 }
 223
 224 /*! \fn std::string SamHeader::ToString(void) const
 225     \brief Converts data fields to SAM-formatted text.
 226
 227     Applies any local modifications made since creating this object or calling SetHeaderText().
 228
 229     \return SAM-formatted header text
 230 */
 231 string SamHeader::ToString(void) const {
 232     SamFormatPrinter printer(*this);
 233     return printer.ToString();
 234 }