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)
76 , m_errorString(other.GetErrorString())
79 /*! \fn SamHeader::~SamHeader(void)
82 SamHeader::~SamHeader(void) { }
84 /*! \fn void SamHeader::Clear(void)
85 \brief Clears all header contents.
87 void SamHeader::Clear(void) {
89 // clear SAM header components
99 m_errorString.clear();
102 /*! \fn std::string SamHeader::GetErrorString(void) const
103 \brief Returns a human-readable description of the last error that occurred
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.
108 \return error description
110 std::string SamHeader::GetErrorString(void) const {
111 return m_errorString;
114 /*! \fn bool SamHeader::HasError(void) const
115 \brief Returns \c true if header encountered an error
117 bool SamHeader::HasError(void) const {
118 return (!m_errorString.empty());
121 /*! \fn bool SamHeader::HasVersion(void) const
122 \brief Returns \c true if header contains \@HD ID:\<Version\>
124 bool SamHeader::HasVersion(void) const {
125 return (!Version.empty());
128 /*! \fn bool SamHeader::HasSortOrder(void) const
129 \brief Returns \c true if header contains \@HD SO:\<SortOrder\>
131 bool SamHeader::HasSortOrder(void) const {
132 return (!SortOrder.empty());
135 /*! \fn bool SamHeader::HasGroupOrder(void) const
136 \brief Returns \c true if header contains \@HD GO:\<GroupOrder\>
138 bool SamHeader::HasGroupOrder(void) const {
139 return (!GroupOrder.empty());
142 /*! \fn bool SamHeader::HasSequences(void) const
143 \brief Returns \c true if header contains any \@SQ entries
145 bool SamHeader::HasSequences(void) const {
146 return (!Sequences.IsEmpty());
149 /*! \fn bool SamHeader::HasReadGroups(void) const
150 \brief Returns \c true if header contains any \@RG entries
152 bool SamHeader::HasReadGroups(void) const {
153 return (!ReadGroups.IsEmpty());
156 /*! \fn bool SamHeader::HasPrograms(void) const
157 \brief Returns \c true if header contains any \@PG entries
159 bool SamHeader::HasPrograms(void) const {
160 return (!Programs.IsEmpty());
163 /*! \fn bool SamHeader::HasComments(void) const
164 \brief Returns \c true if header contains any \@CO entries
166 bool SamHeader::HasComments(void) const {
167 return (!Comments.empty());
170 /*! \fn bool SamHeader::IsValid(bool verbose = false) const
171 \brief Checks header contents for required data and proper formatting.
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
177 bool SamHeader::IsValid(bool verbose) const {
179 SamHeaderValidator validator(*this);
181 // if SAM header is valid, return success
182 if ( validator.Validate() )
188 // print messages to stderr
190 validator.PrintMessages(std::cerr);
192 // or catch in local error string
194 stringstream errorStream("");
195 validator.PrintMessages(errorStream);
196 m_errorString = errorStream.str();
202 /*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
203 \brief Replaces header contents with \a headerText.
205 \param[in] headerText SAM formatted-text that will be parsed into data fields
207 void SamHeader::SetHeaderText(const std::string& headerText) {
213 SamFormatParser parser(*this);
214 parser.Parse(headerText);
215 } catch ( BamException& e ) {
217 // clear anything parsed so far
218 // no telling what's valid and what's partially parsed
222 m_errorString = e.what();
226 /*! \fn std::string SamHeader::ToString(void) const
227 \brief Converts data fields to SAM-formatted text.
229 Applies any local modifications made since creating this object or calling SetHeaderText().
231 \return SAM-formatted header text
233 string SamHeader::ToString(void) const {
234 SamFormatPrinter printer(*this);
235 return printer.ToString();