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: 19 April 2011 (DB)
   7 // ---------------------------------------------------------------------------
   8 // Provides direct read/write access to the SAM header data fields.
   9 // ***************************************************************************
  10
  11 #include <api/SamConstants.h>
  12 #include <api/SamHeader.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     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     , Programs(other.Programs)
  81 { }
  82
  83 /*! \fn SamHeader::~SamHeader(void)
  84     \brief destructor
  85 */
  86 SamHeader::~SamHeader(void) { }
  87
  88 /*! \fn void SamHeader::Clear(void)
  89     \brief Clears all header contents.
  90 */
  91 void SamHeader::Clear(void) {
  92     Version.clear();
  93     SortOrder.clear();
  94     GroupOrder.clear();
  95     Sequences.Clear();
  96     ReadGroups.Clear();
  97     Programs.Clear();
  98     Comments.clear();
  99 }
 100
 101 /*! \fn bool SamHeader::HasVersion(void) const
 102     \brief Returns \c true if header contains \@HD ID:\<Version\>
 103 */
 104 bool SamHeader::HasVersion(void) const {
 105     return (!Version.empty());
 106 }
 107
 108 /*! \fn bool SamHeader::HasSortOrder(void) const
 109     \brief Returns \c true if header contains \@HD SO:\<SortOrder\>
 110 */
 111 bool SamHeader::HasSortOrder(void) const {
 112     return (!SortOrder.empty());
 113 }
 114
 115 /*! \fn bool SamHeader::HasGroupOrder(void) const
 116     \brief Returns \c true if header contains \@HD GO:\<GroupOrder\>
 117 */
 118 bool SamHeader::HasGroupOrder(void) const {
 119     return (!GroupOrder.empty());
 120 }
 121
 122 /*! \fn bool SamHeader::HasSequences(void) const
 123     \brief Returns \c true if header contains any \@SQ entries
 124 */
 125 bool SamHeader::HasSequences(void) const {
 126     return (!Sequences.IsEmpty());
 127 }
 128
 129 /*! \fn bool SamHeader::HasReadGroups(void) const
 130     \brief Returns \c true if header contains any \@RG entries
 131 */
 132 bool SamHeader::HasReadGroups(void) const {
 133     return (!ReadGroups.IsEmpty());
 134 }
 135
 136 /*! \fn bool SamHeader::HasPrograms(void) const
 137     \brief Returns \c true if header contains any \@PG entries
 138 */
 139 bool SamHeader::HasPrograms(void) const {
 140     return (!Programs.IsEmpty());
 141 }
 142
 143 /*! \fn bool SamHeader::HasComments(void) const
 144     \brief Returns \c true if header contains any \@CO entries
 145 */
 146 bool SamHeader::HasComments(void) const {
 147     return (!Comments.empty());
 148 }
 149
 150 /*! \fn bool SamHeader::IsValid(bool verbose = false) const
 151     \brief Checks header contents for required data and proper formatting.
 152     \param verbose If set to true, validation errors & warnings will be printed to stderr.
 153                    Otherwise, output is suppressed and only validation check occurs.
 154     \return \c true if SAM header is well-formed
 155 */
 156 bool SamHeader::IsValid(bool verbose) const {
 157     SamHeaderValidator validator(*this);
 158     return validator.Validate(verbose);
 159 }
 160
 161 /*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
 162     \brief Replaces header contents with \a headerText.
 163     \param headerText SAM formatted-text that will be parsed into data fields
 164 */
 165 void SamHeader::SetHeaderText(const std::string& headerText) {
 166
 167     // clear prior data
 168     Clear();
 169
 170     // parse header text into data
 171     SamFormatParser parser(*this);
 172     parser.Parse(headerText);
 173 }
 174
 175 /*! \fn std::string SamHeader::ToString(void) const
 176     \brief Converts data fields to SAM-formatted text.
 177
 178     Applies any local modifications made since creating this object or calling SetHeaderText().
 179
 180     \return SAM-formatted header text
 181 */
 182 string SamHeader::ToString(void) const {
 183     SamFormatPrinter printer(*this);
 184     return printer.ToString();
 185 }