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)
75 , Comments(other.Comments)
78 /*! \fn SamHeader::~SamHeader(void)
81 SamHeader::~SamHeader(void) { }
83 /*! \fn void SamHeader::Clear(void)
84 \brief Clears all header contents.
86 void SamHeader::Clear(void) {
88 // clear SAM header components
98 m_errorString.clear();
101 /*! \fn std::string SamHeader::GetErrorString(void) const
102 \brief Returns a human-readable description of the last error that occurred
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.
107 \return error description
109 std::string SamHeader::GetErrorString(void) const {
110 return m_errorString;
113 /*! \fn bool SamHeader::HasError(void) const
114 \brief Returns \c true if header encountered an error
116 bool SamHeader::HasError(void) const {
117 return (!m_errorString.empty());
120 /*! \fn bool SamHeader::HasVersion(void) const
121 \brief Returns \c true if header contains \@HD ID:\<Version\>
123 bool SamHeader::HasVersion(void) const {
124 return (!Version.empty());
127 /*! \fn bool SamHeader::HasSortOrder(void) const
128 \brief Returns \c true if header contains \@HD SO:\<SortOrder\>
130 bool SamHeader::HasSortOrder(void) const {
131 return (!SortOrder.empty());
134 /*! \fn bool SamHeader::HasGroupOrder(void) const
135 \brief Returns \c true if header contains \@HD GO:\<GroupOrder\>
137 bool SamHeader::HasGroupOrder(void) const {
138 return (!GroupOrder.empty());
141 /*! \fn bool SamHeader::HasSequences(void) const
142 \brief Returns \c true if header contains any \@SQ entries
144 bool SamHeader::HasSequences(void) const {
145 return (!Sequences.IsEmpty());
148 /*! \fn bool SamHeader::HasReadGroups(void) const
149 \brief Returns \c true if header contains any \@RG entries
151 bool SamHeader::HasReadGroups(void) const {
152 return (!ReadGroups.IsEmpty());
155 /*! \fn bool SamHeader::HasPrograms(void) const
156 \brief Returns \c true if header contains any \@PG entries
158 bool SamHeader::HasPrograms(void) const {
159 return (!Programs.IsEmpty());
162 /*! \fn bool SamHeader::HasComments(void) const
163 \brief Returns \c true if header contains any \@CO entries
165 bool SamHeader::HasComments(void) const {
166 return (!Comments.empty());
169 /*! \fn bool SamHeader::IsValid(bool verbose = false) const
170 \brief Checks header contents for required data and proper formatting.
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
176 bool SamHeader::IsValid(bool verbose) const {
178 SamHeaderValidator validator(*this);
180 // if SAM header is valid, return success
181 if ( validator.Validate() )
187 // print messages to stderr
189 validator.PrintMessages(std::cerr);
191 // or catch in local error string
193 stringstream errorStream("");
194 validator.PrintMessages(errorStream);
195 m_errorString = errorStream.str();
201 /*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
202 \brief Replaces header contents with \a headerText.
204 \param[in] headerText SAM formatted-text that will be parsed into data fields
206 void SamHeader::SetHeaderText(const std::string& headerText) {
212 SamFormatParser parser(*this);
213 parser.Parse(headerText);
214 } catch ( BamException& e ) {
216 // clear anything parsed so far
217 // no telling what's valid and what's partially parsed
221 m_errorString = e.what();
225 /*! \fn std::string SamHeader::ToString(void) const
226 \brief Converts data fields to SAM-formatted text.
228 Applies any local modifications made since creating this object or calling SetHeaderText().
230 \return SAM-formatted header text
232 string SamHeader::ToString(void) const {
233 SamFormatPrinter printer(*this);
234 return printer.ToString();