1 // ***************************************************************************
2 // SamHeader.cpp (c) 2010 Derek Barnett
3 // Marth Lab, Department of Biology, Boston College
4 // ---------------------------------------------------------------------------
5 // Last modified: 6 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/BamException_p.h>
13 #include <api/internal/SamFormatParser_p.h>
14 #include <api/internal/SamFormatPrinter_p.h>
15 #include <api/internal/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::ProgramName
47 \brief corresponds to \@PG ID:\<ProgramName\>
49 /*! \var SamHeader::ProgramVersion
50 \brief corresponds to \@PG VN:\<ProgramVersion\>
52 /*! \var SamHeader::ProgramCommandLine
53 \brief corresponds to \@PG CL:\<ProgramCommandLine\>
55 /*! \var SamHeader::Comments
56 \brief corresponds to \@CO entries
59 /*! \fn SamHeader::SamHeader(const std::string& headerText = "")
62 SamHeader::SamHeader(const std::string& headerText)
64 , SortOrder(Constants::SAM_HD_SORTORDER_UNKNOWN)
67 SetHeaderText(headerText);
70 /*! \fn SamHeader::SamHeader(const SamHeader& other)
71 \brief copy constructor
73 SamHeader::SamHeader(const SamHeader& other)
74 : Version(other.Version)
75 , SortOrder(other.SortOrder)
76 , GroupOrder(other.GroupOrder)
77 , Sequences(other.Sequences)
78 , ReadGroups(other.ReadGroups)
79 , Programs(other.Programs)
82 /*! \fn SamHeader::~SamHeader(void)
85 SamHeader::~SamHeader(void) { }
87 /*! \fn void SamHeader::Clear(void)
88 \brief Clears all header contents.
90 void SamHeader::Clear(void) {
92 // clear SAM header components
101 // clear error string
102 m_errorString.clear();
105 /*! \fn std::string SamHeader::GetErrorString(void) const
106 \brief Returns human-readable description of last error encountered
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.
170 \param verbose If set to true, validation errors & warnings will be printed to stderr.
171 Otherwise, messages are available through SamHeader::GetErrorString().
172 \return \c true if SAM header is well-formed
174 bool SamHeader::IsValid(bool verbose) const {
176 SamHeaderValidator validator(*this);
178 // if SAM header is valid, return success
179 if ( validator.Validate() )
185 // print messages to stderr
187 validator.PrintMessages(std::cerr);
189 // or catch in local error string
191 stringstream errorStream("");
192 validator.PrintMessages(errorStream);
193 m_errorString = errorStream.str();
199 /*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
200 \brief Replaces header contents with \a headerText.
201 \param headerText SAM formatted-text that will be parsed into data fields
203 void SamHeader::SetHeaderText(const std::string& headerText) {
209 SamFormatParser parser(*this);
210 parser.Parse(headerText);
211 } catch ( BamException& e ) {
213 // clear anything parsed so far
214 // no telling what's valid and what's partially parsed
218 m_errorString = e.what();
222 /*! \fn std::string SamHeader::ToString(void) const
223 \brief Converts data fields to SAM-formatted text.
225 Applies any local modifications made since creating this object or calling SetHeaderText().
227 \return SAM-formatted header text
229 string SamHeader::ToString(void) const {
230 SamFormatPrinter printer(*this);
231 return printer.ToString();