src/api/SamHeader.cpp

   1 // ***************************************************************************
   2 // SamHeader.cpp (c) 2010 Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // ---------------------------------------------------------------------------
   5 // Last modified: 25 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/utils/BamException_p.h"
  13 #include "api/internal/sam/SamFormatParser_p.h"
  14 #include "api/internal/sam/SamFormatPrinter_p.h"
  15 #include "api/internal/sam/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     , Comments(other.Comments)
  76 { }
  77
  78 /*! \fn SamHeader::~SamHeader(void)
  79     \brief destructor
  80 */
  81 SamHeader::~SamHeader(void) { }
  82
  83 /*! \fn void SamHeader::Clear(void)
  84     \brief Clears all header contents.
  85 */
  86 void SamHeader::Clear(void) {
  87
  88     // clear SAM header components
  89     Version.clear();
  90     SortOrder.clear();
  91     GroupOrder.clear();
  92     Sequences.Clear();
  93     ReadGroups.Clear();
  94     Programs.Clear();
  95     Comments.clear();
  96
  97     // clear error string
  98     m_errorString.clear();
  99 }
 100
 101 /*! \fn std::string SamHeader::GetErrorString(void) const
 102     \brief Returns a human-readable description of the last error that occurred
 103
 104     This method allows elimination of STDERR pollution. Developers of client code
 105     may choose how the messages are displayed to the user, if at all.
 106
 107     \return error description
 108 */
 109 std::string SamHeader::GetErrorString(void) const {
 110     return m_errorString;
 111 }
 112
 113 /*! \fn bool SamHeader::HasError(void) const
 114     \brief Returns \c true if header encountered an error
 115 */
 116 bool SamHeader::HasError(void) const {
 117     return (!m_errorString.empty());
 118 }
 119
 120 /*! \fn bool SamHeader::HasVersion(void) const
 121     \brief Returns \c true if header contains \@HD ID:\<Version\>
 122 */
 123 bool SamHeader::HasVersion(void) const {
 124     return (!Version.empty());
 125 }
 126
 127 /*! \fn bool SamHeader::HasSortOrder(void) const
 128     \brief Returns \c true if header contains \@HD SO:\<SortOrder\>
 129 */
 130 bool SamHeader::HasSortOrder(void) const {
 131     return (!SortOrder.empty());
 132 }
 133
 134 /*! \fn bool SamHeader::HasGroupOrder(void) const
 135     \brief Returns \c true if header contains \@HD GO:\<GroupOrder\>
 136 */
 137 bool SamHeader::HasGroupOrder(void) const {
 138     return (!GroupOrder.empty());
 139 }
 140
 141 /*! \fn bool SamHeader::HasSequences(void) const
 142     \brief Returns \c true if header contains any \@SQ entries
 143 */
 144 bool SamHeader::HasSequences(void) const {
 145     return (!Sequences.IsEmpty());
 146 }
 147
 148 /*! \fn bool SamHeader::HasReadGroups(void) const
 149     \brief Returns \c true if header contains any \@RG entries
 150 */
 151 bool SamHeader::HasReadGroups(void) const {
 152     return (!ReadGroups.IsEmpty());
 153 }
 154
 155 /*! \fn bool SamHeader::HasPrograms(void) const
 156     \brief Returns \c true if header contains any \@PG entries
 157 */
 158 bool SamHeader::HasPrograms(void) const {
 159     return (!Programs.IsEmpty());
 160 }
 161
 162 /*! \fn bool SamHeader::HasComments(void) const
 163     \brief Returns \c true if header contains any \@CO entries
 164 */
 165 bool SamHeader::HasComments(void) const {
 166     return (!Comments.empty());
 167 }
 168
 169 /*! \fn bool SamHeader::IsValid(bool verbose = false) const
 170     \brief Checks header contents for required data and proper formatting.
 171
 172     \param[in] verbose If set to true, validation errors & warnings will be printed to stderr.
 173                        Otherwise, messages are available through SamHeader::GetErrorString().
 174     \return \c true if SAM header is well-formed
 175 */
 176 bool SamHeader::IsValid(bool verbose) const {
 177
 178     SamHeaderValidator validator(*this);
 179
 180     // if SAM header is valid, return success
 181     if ( validator.Validate() )
 182         return true;
 183
 184     // otherwiser
 185     else {
 186
 187         // print messages to stderr
 188         if ( verbose )
 189             validator.PrintMessages(std::cerr);
 190
 191         // or catch in local error string
 192         else {
 193             stringstream errorStream("");
 194             validator.PrintMessages(errorStream);
 195             m_errorString = errorStream.str();
 196         }
 197         return false;
 198     }
 199 }
 200
 201 /*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
 202     \brief Replaces header contents with \a headerText.
 203
 204     \param[in] headerText SAM formatted-text that will be parsed into data fields
 205 */
 206 void SamHeader::SetHeaderText(const std::string& headerText) {
 207
 208     // clear prior data
 209     Clear();
 210
 211     try {
 212         SamFormatParser parser(*this);
 213         parser.Parse(headerText);
 214     } catch ( BamException& e ) {
 215
 216         // clear anything parsed so far
 217         // no telling what's valid and what's partially parsed
 218         Clear();
 219
 220         // set error string
 221         m_errorString = e.what();
 222     }
 223 }
 224
 225 /*! \fn std::string SamHeader::ToString(void) const
 226     \brief Converts data fields to SAM-formatted text.
 227
 228     Applies any local modifications made since creating this object or calling SetHeaderText().
 229
 230     \return SAM-formatted header text
 231 */
 232 string SamHeader::ToString(void) const {
 233     SamFormatPrinter printer(*this);
 234     return printer.ToString();
 235 }