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