1 // ***************************************************************************
2 // SamHeader.cpp (c) 2010 Derek Barnett
3 // Marth Lab, Department of Biology, Boston College
4 // All rights reserved.
5 // ---------------------------------------------------------------------------
6 // Last modified: 19 April 2011 (DB)
7 // ---------------------------------------------------------------------------
8 // Provides direct read/write access to the SAM header data fields.
9 // ***************************************************************************
11 #include <api/SamConstants.h>
12 #include <api/SamHeader.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 SamFormatParser parser(*this);
68 parser.Parse(headerText);
71 /*! \fn SamHeader::SamHeader(const SamHeader& other)
72 \brief copy constructor
74 SamHeader::SamHeader(const SamHeader& other)
75 : Version(other.Version)
76 , SortOrder(other.SortOrder)
77 , GroupOrder(other.GroupOrder)
78 , Sequences(other.Sequences)
79 , ReadGroups(other.ReadGroups)
80 , Programs(other.Programs)
83 /*! \fn SamHeader::~SamHeader(void)
86 SamHeader::~SamHeader(void) { }
88 /*! \fn void SamHeader::Clear(void)
89 \brief Clears all header contents.
91 void SamHeader::Clear(void) {
101 /*! \fn bool SamHeader::HasVersion(void) const
102 \brief Returns \c true if header contains \@HD ID:\<Version\>
104 bool SamHeader::HasVersion(void) const {
105 return (!Version.empty());
108 /*! \fn bool SamHeader::HasSortOrder(void) const
109 \brief Returns \c true if header contains \@HD SO:\<SortOrder\>
111 bool SamHeader::HasSortOrder(void) const {
112 return (!SortOrder.empty());
115 /*! \fn bool SamHeader::HasGroupOrder(void) const
116 \brief Returns \c true if header contains \@HD GO:\<GroupOrder\>
118 bool SamHeader::HasGroupOrder(void) const {
119 return (!GroupOrder.empty());
122 /*! \fn bool SamHeader::HasSequences(void) const
123 \brief Returns \c true if header contains any \@SQ entries
125 bool SamHeader::HasSequences(void) const {
126 return (!Sequences.IsEmpty());
129 /*! \fn bool SamHeader::HasReadGroups(void) const
130 \brief Returns \c true if header contains any \@RG entries
132 bool SamHeader::HasReadGroups(void) const {
133 return (!ReadGroups.IsEmpty());
136 /*! \fn bool SamHeader::HasPrograms(void) const
137 \brief Returns \c true if header contains any \@PG entries
139 bool SamHeader::HasPrograms(void) const {
140 return (!Programs.IsEmpty());
143 /*! \fn bool SamHeader::HasComments(void) const
144 \brief Returns \c true if header contains any \@CO entries
146 bool SamHeader::HasComments(void) const {
147 return (!Comments.empty());
150 /*! \fn bool SamHeader::IsValid(bool verbose = false) const
151 \brief Checks header contents for required data and proper formatting.
152 \param verbose If set to true, validation errors & warnings will be printed to stderr.
153 Otherwise, output is suppressed and only validation check occurs.
154 \return \c true if SAM header is well-formed
156 bool SamHeader::IsValid(bool verbose) const {
157 SamHeaderValidator validator(*this);
158 return validator.Validate(verbose);
161 /*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
162 \brief Replaces header contents with \a headerText.
163 \param headerText SAM formatted-text that will be parsed into data fields
165 void SamHeader::SetHeaderText(const std::string& headerText) {
170 // parse header text into data
171 SamFormatParser parser(*this);
172 parser.Parse(headerText);
175 /*! \fn std::string SamHeader::ToString(void) const
176 \brief Converts data fields to SAM-formatted text.
178 Applies any local modifications made since creating this object or calling SetHeaderText().
180 \return SAM-formatted header text
182 string SamHeader::ToString(void) const {
183 SamFormatPrinter printer(*this);
184 return printer.ToString();