1 // ***************************************************************************
2 // SamHeader.cpp (c) 2010 Derek Barnett
3 // Marth Lab, Department of Biology, Boston College
4 // ---------------------------------------------------------------------------
5 // Last modified: 19 April 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/SamFormatParser_p.h>
13 #include <api/internal/SamFormatPrinter_p.h>
14 #include <api/internal/SamHeaderValidator_p.h>
15 using namespace BamTools;
16 using namespace BamTools::Internal;
19 /*! \struct BamTools::SamHeader
20 \brief Represents the SAM-formatted text header that is part of the BAM file header.
22 Provides direct read/write access to the SAM header data fields.
26 /*! \var SamHeader::Version
27 \brief corresponds to \@HD VN:\<Version\>
29 Required for valid SAM header, if @HD record is present.
31 /*! \var SamHeader::SortOrder
32 \brief corresponds to \@HD SO:\<SortOrder\>
34 /*! \var SamHeader::GroupOrder
35 \brief corresponds to \@HD GO:\<GroupOrder\>
37 /*! \var SamHeader::Sequences
38 \brief corresponds to \@SQ entries
39 \sa SamSequence, SamSequenceDictionary
41 /*! \var SamHeader::ReadGroups
42 \brief corresponds to \@RG entries
43 \sa SamReadGroup, SamReadGroupDictionary
45 /*! \var SamHeader::ProgramName
46 \brief corresponds to \@PG ID:\<ProgramName\>
48 /*! \var SamHeader::ProgramVersion
49 \brief corresponds to \@PG VN:\<ProgramVersion\>
51 /*! \var SamHeader::ProgramCommandLine
52 \brief corresponds to \@PG CL:\<ProgramCommandLine\>
54 /*! \var SamHeader::Comments
55 \brief corresponds to \@CO entries
58 /*! \fn SamHeader::SamHeader(const std::string& headerText = "")
61 SamHeader::SamHeader(const std::string& headerText)
63 , SortOrder(Constants::SAM_HD_SORTORDER_UNKNOWN)
66 SamFormatParser parser(*this);
67 parser.Parse(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) {
100 /*! \fn bool SamHeader::HasVersion(void) const
101 \brief Returns \c true if header contains \@HD ID:\<Version\>
103 bool SamHeader::HasVersion(void) const {
104 return (!Version.empty());
107 /*! \fn bool SamHeader::HasSortOrder(void) const
108 \brief Returns \c true if header contains \@HD SO:\<SortOrder\>
110 bool SamHeader::HasSortOrder(void) const {
111 return (!SortOrder.empty());
114 /*! \fn bool SamHeader::HasGroupOrder(void) const
115 \brief Returns \c true if header contains \@HD GO:\<GroupOrder\>
117 bool SamHeader::HasGroupOrder(void) const {
118 return (!GroupOrder.empty());
121 /*! \fn bool SamHeader::HasSequences(void) const
122 \brief Returns \c true if header contains any \@SQ entries
124 bool SamHeader::HasSequences(void) const {
125 return (!Sequences.IsEmpty());
128 /*! \fn bool SamHeader::HasReadGroups(void) const
129 \brief Returns \c true if header contains any \@RG entries
131 bool SamHeader::HasReadGroups(void) const {
132 return (!ReadGroups.IsEmpty());
135 /*! \fn bool SamHeader::HasPrograms(void) const
136 \brief Returns \c true if header contains any \@PG entries
138 bool SamHeader::HasPrograms(void) const {
139 return (!Programs.IsEmpty());
142 /*! \fn bool SamHeader::HasComments(void) const
143 \brief Returns \c true if header contains any \@CO entries
145 bool SamHeader::HasComments(void) const {
146 return (!Comments.empty());
149 /*! \fn bool SamHeader::IsValid(bool verbose = false) const
150 \brief Checks header contents for required data and proper formatting.
151 \param verbose If set to true, validation errors & warnings will be printed to stderr.
152 Otherwise, output is suppressed and only validation check occurs.
153 \return \c true if SAM header is well-formed
155 bool SamHeader::IsValid(bool verbose) const {
156 SamHeaderValidator validator(*this);
157 return validator.Validate(verbose);
160 /*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
161 \brief Replaces header contents with \a headerText.
162 \param headerText SAM formatted-text that will be parsed into data fields
164 void SamHeader::SetHeaderText(const std::string& headerText) {
169 // parse header text into data
170 SamFormatParser parser(*this);
171 parser.Parse(headerText);
174 /*! \fn std::string SamHeader::ToString(void) const
175 \brief Converts data fields to SAM-formatted text.
177 Applies any local modifications made since creating this object or calling SetHeaderText().
179 \return SAM-formatted header text
181 string SamHeader::ToString(void) const {
182 SamFormatPrinter printer(*this);
183 return printer.ToString();