src/api/SamHeader.cpp

   1 // ***************************************************************************
   2 // SamHeader.cpp (c) 2010 Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // ---------------------------------------------------------------------------
   5 // Last modified: 19 April 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/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 \samSpecURL
  25 */
  26 /*! \var SamHeader::Version
  27     \brief corresponds to \@HD VN:\<Version\>
  28
  29     Required for valid SAM header, if @HD record is present.
  30 */
  31 /*! \var SamHeader::SortOrder
  32     \brief corresponds to \@HD SO:\<SortOrder\>
  33 */
  34 /*! \var SamHeader::GroupOrder
  35     \brief corresponds to \@HD GO:\<GroupOrder\>
  36 */
  37 /*! \var SamHeader::Sequences
  38     \brief corresponds to \@SQ entries
  39     \sa SamSequence, SamSequenceDictionary
  40 */
  41 /*! \var SamHeader::ReadGroups
  42     \brief corresponds to \@RG entries
  43     \sa SamReadGroup, SamReadGroupDictionary
  44 */
  45 /*! \var SamHeader::ProgramName
  46     \brief corresponds to \@PG ID:\<ProgramName\>
  47 */
  48 /*! \var SamHeader::ProgramVersion
  49     \brief corresponds to \@PG VN:\<ProgramVersion\>
  50 */
  51 /*! \var SamHeader::ProgramCommandLine
  52     \brief corresponds to \@PG CL:\<ProgramCommandLine\>
  53 */
  54 /*! \var SamHeader::Comments
  55     \brief corresponds to \@CO entries
  56 */
  57
  58 /*! \fn SamHeader::SamHeader(const std::string& headerText = "")
  59     \brief constructor
  60 */
  61 SamHeader::SamHeader(const std::string& headerText)
  62     : Version("")
  63     , SortOrder(Constants::SAM_HD_SORTORDER_UNKNOWN)
  64     , GroupOrder("")
  65 {
  66     SamFormatParser parser(*this);
  67     parser.Parse(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     Version.clear();
  92     SortOrder.clear();
  93     GroupOrder.clear();
  94     Sequences.Clear();
  95     ReadGroups.Clear();
  96     Programs.Clear();
  97     Comments.clear();
  98 }
  99
 100 /*! \fn bool SamHeader::HasVersion(void) const
 101     \brief Returns \c true if header contains \@HD ID:\<Version\>
 102 */
 103 bool SamHeader::HasVersion(void) const {
 104     return (!Version.empty());
 105 }
 106
 107 /*! \fn bool SamHeader::HasSortOrder(void) const
 108     \brief Returns \c true if header contains \@HD SO:\<SortOrder\>
 109 */
 110 bool SamHeader::HasSortOrder(void) const {
 111     return (!SortOrder.empty());
 112 }
 113
 114 /*! \fn bool SamHeader::HasGroupOrder(void) const
 115     \brief Returns \c true if header contains \@HD GO:\<GroupOrder\>
 116 */
 117 bool SamHeader::HasGroupOrder(void) const {
 118     return (!GroupOrder.empty());
 119 }
 120
 121 /*! \fn bool SamHeader::HasSequences(void) const
 122     \brief Returns \c true if header contains any \@SQ entries
 123 */
 124 bool SamHeader::HasSequences(void) const {
 125     return (!Sequences.IsEmpty());
 126 }
 127
 128 /*! \fn bool SamHeader::HasReadGroups(void) const
 129     \brief Returns \c true if header contains any \@RG entries
 130 */
 131 bool SamHeader::HasReadGroups(void) const {
 132     return (!ReadGroups.IsEmpty());
 133 }
 134
 135 /*! \fn bool SamHeader::HasPrograms(void) const
 136     \brief Returns \c true if header contains any \@PG entries
 137 */
 138 bool SamHeader::HasPrograms(void) const {
 139     return (!Programs.IsEmpty());
 140 }
 141
 142 /*! \fn bool SamHeader::HasComments(void) const
 143     \brief Returns \c true if header contains any \@CO entries
 144 */
 145 bool SamHeader::HasComments(void) const {
 146     return (!Comments.empty());
 147 }
 148
 149 /*! \fn bool SamHeader::IsValid(bool verbose = false) const
 150     \brief Checks header contents for required data and proper formatting.
 151     \param verbose If set to true, validation errors & warnings will be printed to stderr.
 152                    Otherwise, output is suppressed and only validation check occurs.
 153     \return \c true if SAM header is well-formed
 154 */
 155 bool SamHeader::IsValid(bool verbose) const {
 156     SamHeaderValidator validator(*this);
 157     return validator.Validate(verbose);
 158 }
 159
 160 /*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
 161     \brief Replaces header contents with \a headerText.
 162     \param headerText SAM formatted-text that will be parsed into data fields
 163 */
 164 void SamHeader::SetHeaderText(const std::string& headerText) {
 165
 166     // clear prior data
 167     Clear();
 168
 169     // parse header text into data
 170     SamFormatParser parser(*this);
 171     parser.Parse(headerText);
 172 }
 173
 174 /*! \fn std::string SamHeader::ToString(void) const
 175     \brief Converts data fields to SAM-formatted text.
 176
 177     Applies any local modifications made since creating this object or calling SetHeaderText().
 178
 179     \return SAM-formatted header text
 180 */
 181 string SamHeader::ToString(void) const {
 182     SamFormatPrinter printer(*this);
 183     return printer.ToString();
 184 }