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 // ***************************************************************************
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;
20 /*! \struct BamTools::SamHeader
21 \brief Represents the SAM-formatted text header that is part of the BAM file header.
23 Provides direct read/write access to the SAM header data fields.
27 /*! \var SamHeader::Version
28 \brief corresponds to \@HD VN:\<Version\>
30 Required for valid SAM header, if \@HD record is present.
32 /*! \var SamHeader::SortOrder
33 \brief corresponds to \@HD SO:\<SortOrder\>
35 /*! \var SamHeader::GroupOrder
36 \brief corresponds to \@HD GO:\<GroupOrder\>
38 /*! \var SamHeader::Sequences
39 \brief corresponds to \@SQ entries
40 \sa SamSequence, SamSequenceDictionary
42 /*! \var SamHeader::ReadGroups
43 \brief corresponds to \@RG entries
44 \sa SamReadGroup, SamReadGroupDictionary
46 /*! \var SamHeader::Programs
47 \brief corresponds to \@PG entries
48 \sa SamProgram, SamProgramChain
50 /*! \var SamHeader::Comments
51 \brief corresponds to \@CO entries
54 /*! \fn SamHeader::SamHeader(const std::string& headerText = "")
57 SamHeader::SamHeader(const std::string& headerText)
59 , SortOrder(Constants::SAM_HD_SORTORDER_UNKNOWN)
62 SetHeaderText(headerText);
65 /*! \fn SamHeader::SamHeader(const SamHeader& other)
66 \brief copy constructor
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)
77 /*! \fn SamHeader::~SamHeader(void)
80 SamHeader::~SamHeader(void) { }
82 /*! \fn void SamHeader::Clear(void)
83 \brief Clears all header contents.
85 void SamHeader::Clear(void) {
87 // clear SAM header components
97 m_errorString.clear();
100 /*! \fn std::string SamHeader::GetErrorString(void) const
101 \brief Returns a human-readable description of the last error that occurred
103 This method allows elimination of STDERR pollution. Developers of client code
104 may choose how the messages are displayed to the user, if at all.
106 \return error description
108 std::string SamHeader::GetErrorString(void) const {
109 return m_errorString;
112 /*! \fn bool SamHeader::HasError(void) const
113 \brief Returns \c true if header encountered an error
115 bool SamHeader::HasError(void) const {
116 return (!m_errorString.empty());
119 /*! \fn bool SamHeader::HasVersion(void) const
120 \brief Returns \c true if header contains \@HD ID:\<Version\>
122 bool SamHeader::HasVersion(void) const {
123 return (!Version.empty());
126 /*! \fn bool SamHeader::HasSortOrder(void) const
127 \brief Returns \c true if header contains \@HD SO:\<SortOrder\>
129 bool SamHeader::HasSortOrder(void) const {
130 return (!SortOrder.empty());
133 /*! \fn bool SamHeader::HasGroupOrder(void) const
134 \brief Returns \c true if header contains \@HD GO:\<GroupOrder\>
136 bool SamHeader::HasGroupOrder(void) const {
137 return (!GroupOrder.empty());
140 /*! \fn bool SamHeader::HasSequences(void) const
141 \brief Returns \c true if header contains any \@SQ entries
143 bool SamHeader::HasSequences(void) const {
144 return (!Sequences.IsEmpty());
147 /*! \fn bool SamHeader::HasReadGroups(void) const
148 \brief Returns \c true if header contains any \@RG entries
150 bool SamHeader::HasReadGroups(void) const {
151 return (!ReadGroups.IsEmpty());
154 /*! \fn bool SamHeader::HasPrograms(void) const
155 \brief Returns \c true if header contains any \@PG entries
157 bool SamHeader::HasPrograms(void) const {
158 return (!Programs.IsEmpty());
161 /*! \fn bool SamHeader::HasComments(void) const
162 \brief Returns \c true if header contains any \@CO entries
164 bool SamHeader::HasComments(void) const {
165 return (!Comments.empty());
168 /*! \fn bool SamHeader::IsValid(bool verbose = false) const
169 \brief Checks header contents for required data and proper formatting.
171 \param[in] verbose If set to true, validation errors & warnings will be printed to stderr.
172 Otherwise, messages are available through SamHeader::GetErrorString().
173 \return \c true if SAM header is well-formed
175 bool SamHeader::IsValid(bool verbose) const {
177 SamHeaderValidator validator(*this);
179 // if SAM header is valid, return success
180 if ( validator.Validate() )
186 // print messages to stderr
188 validator.PrintMessages(std::cerr);
190 // or catch in local error string
192 stringstream errorStream("");
193 validator.PrintMessages(errorStream);
194 m_errorString = errorStream.str();
200 /*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
201 \brief Replaces header contents with \a headerText.
203 \param[in] headerText SAM formatted-text that will be parsed into data fields
205 void SamHeader::SetHeaderText(const std::string& headerText) {
211 SamFormatParser parser(*this);
212 parser.Parse(headerText);
213 } catch ( BamException& e ) {
215 // clear anything parsed so far
216 // no telling what's valid and what's partially parsed
220 m_errorString = e.what();
224 /*! \fn std::string SamHeader::ToString(void) const
225 \brief Converts data fields to SAM-formatted text.
227 Applies any local modifications made since creating this object or calling SetHeaderText().
229 \return SAM-formatted header text
231 string SamHeader::ToString(void) const {
232 SamFormatPrinter printer(*this);
233 return printer.ToString();