src/api/SamHeader.cpp

   1 // ***************************************************************************
   2 // SamHeader.cpp (c) 2010 Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // All rights reserved.
   5 // ---------------------------------------------------------------------------
   6 // Last modified: 4 March 2011 (DB)
   7 // ---------------------------------------------------------------------------
   8 // Provides direct read/write access to the SAM header data fields.
   9 // ***************************************************************************
  10
  11 #include <api/SamHeader.h>
  12 #include <api/internal/SamFormatParser_p.h>
  13 #include <api/internal/SamFormatPrinter_p.h>
  14 #include <api/internal/SamHeaderValidator_p.h>
  15 using namespace BamTools;
  16 using namespace BamTools::Internal;
  17 using namespace std;
  18
  19 /*! \struct BamTools::SamHeader
  20     \brief Represents the SAM-formatted text header that is part of the BAM file header.
  21
  22     Provides direct read/write access to the SAM header data fields.
  23
  24     \sa http://samtools.sourceforge.net/SAM-1.3.pdf
  25 */
  26 /*! \var SamHeader::Version
  27     \brief corresponds to \@HD VN:\<Version\>
  28 */
  29 /*! \var SamHeader::SortOrder
  30     \brief corresponds to \@HD SO:\<SortOrder\>
  31 */
  32 /*! \var SamHeader::GroupOrder
  33     \brief corresponds to \@HD GO:\<GroupOrder\>
  34 */
  35 /*! \var SamHeader::Sequences
  36     \brief corresponds to \@SQ entries
  37     \sa SamSequence, SamSequenceDictionary
  38 */
  39 /*! \var SamHeader::ReadGroups
  40     \brief corresponds to \@RG entries
  41     \sa SamReadGroup, SamReadGroupDictionary
  42 */
  43 /*! \var SamHeader::ProgramName
  44     \brief corresponds to \@PG ID:\<ProgramName\>
  45 */
  46 /*! \var SamHeader::ProgramVersion
  47     \brief corresponds to \@PG VN:\<ProgramVersion\>
  48 */
  49 /*! \var SamHeader::ProgramCommandLine
  50     \brief corresponds to \@PG CL:\<ProgramCommandLine\>
  51 */
  52 /*! \var SamHeader::Comments
  53     \brief corresponds to \@CO entries
  54 */
  55
  56 /*! \fn SamHeader::SamHeader(const std::string& headerText = "")
  57     \brief constructor
  58 */
  59 SamHeader::SamHeader(const std::string& headerText)
  60     : Version("")
  61     , SortOrder("")
  62     , GroupOrder("")
  63     , ProgramName("")
  64     , ProgramVersion("")
  65     , ProgramCommandLine("")
  66 {
  67     SamFormatParser parser(*this);
  68     parser.Parse(headerText);
  69 }
  70
  71 /*! \fn SamHeader::SamHeader(const SamHeader& other)
  72     \brief copy constructor
  73 */
  74 SamHeader::SamHeader(const SamHeader& other)
  75     : Version(other.Version)
  76     , SortOrder(other.SortOrder)
  77     , GroupOrder(other.GroupOrder)
  78     , Sequences(other.Sequences)
  79     , ReadGroups(other.ReadGroups)
  80     , ProgramName(other.ProgramName)
  81     , ProgramVersion(other.ProgramVersion)
  82     , ProgramCommandLine(other.ProgramCommandLine)
  83 { }
  84
  85 /*! \fn SamHeader::~SamHeader(void)
  86     \brief destructor
  87 */
  88 SamHeader::~SamHeader(void) { }
  89
  90 /*! \fn void SamHeader::Clear(void)
  91     \brief Clears all header contents.
  92 */
  93 void SamHeader::Clear(void) {
  94     Version.clear();
  95     SortOrder.clear();
  96     GroupOrder.clear();
  97     Sequences.Clear();
  98     ReadGroups.Clear();
  99     ProgramName.clear();
 100     ProgramVersion.clear();
 101     ProgramCommandLine.clear();
 102     Comments.clear();
 103 }
 104
 105 /*! \fn bool SamHeader::HasVersion(void) const
 106     \brief Returns \c true if header contains \@HD ID:\<Version\>
 107 */
 108 bool SamHeader::HasVersion(void) const {
 109     return (!Version.empty());
 110 }
 111
 112 /*! \fn bool SamHeader::HasSortOrder(void) const
 113     \brief Returns \c true if header contains \@HD SO:\<SortOrder\>
 114 */
 115 bool SamHeader::HasSortOrder(void) const {
 116     return (!SortOrder.empty());
 117 }
 118
 119 /*! \fn bool SamHeader::HasGroupOrder(void) const
 120     \brief Returns \c true if header contains \@HD GO:\<GroupOrder\>
 121 */
 122 bool SamHeader::HasGroupOrder(void) const {
 123     return (!GroupOrder.empty());
 124 }
 125
 126 /*! \fn bool SamHeader::HasSequences(void) const
 127     \brief Returns \c true if header contains any \@SQ entries
 128 */
 129 bool SamHeader::HasSequences(void) const {
 130     return (!Sequences.IsEmpty());
 131 }
 132
 133 /*! \fn bool SamHeader::HasReadGroups(void) const
 134     \brief Returns \c true if header contains any \@RG entries
 135 */
 136 bool SamHeader::HasReadGroups(void) const {
 137     return (!ReadGroups.IsEmpty());
 138 }
 139
 140 /*! \fn bool SamHeader::HasProgramName(void) const
 141     \brief Returns \c true if header contains \@PG ID:\<ProgramName\>
 142 */
 143 bool SamHeader::HasProgramName(void) const {
 144     return (!ProgramName.empty());
 145 }
 146
 147 /*! \fn bool SamHeader::HasProgramVersion(void) const
 148     \brief Returns \c true if header contains \@PG VN:\<ProgramVersion\>
 149 */
 150 bool SamHeader::HasProgramVersion(void) const {
 151     return (!ProgramVersion.empty());
 152 }
 153
 154 /*! \fn bool SamHeader::HasProgramCommandLine(void) const
 155     \brief Returns \c true if header contains \@PG CL:\<ProgramCommandLine\>
 156 */
 157 bool SamHeader::HasProgramCommandLine(void) const {
 158     return (!ProgramCommandLine.empty());
 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, output is suppressed and only validation check occurs.
 172     \return \c true if SAM header is well-formed
 173 */
 174 bool SamHeader::IsValid(bool verbose) const {
 175     SamHeaderValidator validator(*this);
 176     return validator.Validate(verbose);
 177 }
 178
 179 /*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
 180     \brief Replaces header contents with \a headerText.
 181     \param headerText SAM formatted-text that will be parsed into data fields
 182 */
 183 void SamHeader::SetHeaderText(const std::string& headerText) {
 184
 185     // clear prior data
 186     Clear();
 187
 188     // parse header text into data
 189     SamFormatParser parser(*this);
 190     parser.Parse(headerText);
 191 }
 192
 193 /*! \fn std::string SamHeader::ToString(void) const
 194     \brief Converts data fields to SAM-formatted text.
 195
 196     Applies any local modifications made since creating this object or calling SetHeaderText().
 197
 198     \return SAM-formatted header text
 199 */
 200 string SamHeader::ToString(void) const {
 201     SamFormatPrinter printer(*this);
 202     return printer.ToString();
 203 }