X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=src%2Fapi%2FSamHeader.cpp;h=363fb5ce18fa1579cee6885351a1eb2d969cad44;hb=2e049ed7f28881bce09653e60f5aea54bfd7afbf;hp=5134630a7d3a65b11e7e0fe07afe0357ed74e328;hpb=6f5c226a2892eca7e3446db18928ed0ce9f65daf;p=bamtools.git diff --git a/src/api/SamHeader.cpp b/src/api/SamHeader.cpp index 5134630..363fb5c 100644 --- a/src/api/SamHeader.cpp +++ b/src/api/SamHeader.cpp @@ -1,14 +1,15 @@ // *************************************************************************** // SamHeader.cpp (c) 2010 Derek Barnett // Marth Lab, Department of Biology, Boston College -// All rights reserved. // --------------------------------------------------------------------------- -// Last modified: 23 December 2010 (DB) +// Last modified: 6 October 2011 (DB) // --------------------------------------------------------------------------- -// Provides functionality for querying/manipulating SAM header data -// ************************************************************************** +// Provides direct read/write access to the SAM header data fields. +// *************************************************************************** +#include #include +#include #include #include #include @@ -16,111 +17,216 @@ using namespace BamTools; using namespace BamTools::Internal; using namespace std; -// ctor -SamHeader::SamHeader(const string& headerText) +/*! \struct BamTools::SamHeader + \brief Represents the SAM-formatted text header that is part of the BAM file header. + + Provides direct read/write access to the SAM header data fields. + + \sa \samSpecURL +*/ +/*! \var SamHeader::Version + \brief corresponds to \@HD VN:\ + + Required for valid SAM header, if @HD record is present. +*/ +/*! \var SamHeader::SortOrder + \brief corresponds to \@HD SO:\ +*/ +/*! \var SamHeader::GroupOrder + \brief corresponds to \@HD GO:\ +*/ +/*! \var SamHeader::Sequences + \brief corresponds to \@SQ entries + \sa SamSequence, SamSequenceDictionary +*/ +/*! \var SamHeader::ReadGroups + \brief corresponds to \@RG entries + \sa SamReadGroup, SamReadGroupDictionary +*/ +/*! \var SamHeader::ProgramName + \brief corresponds to \@PG ID:\ +*/ +/*! \var SamHeader::ProgramVersion + \brief corresponds to \@PG VN:\ +*/ +/*! \var SamHeader::ProgramCommandLine + \brief corresponds to \@PG CL:\ +*/ +/*! \var SamHeader::Comments + \brief corresponds to \@CO entries +*/ + +/*! \fn SamHeader::SamHeader(const std::string& headerText = "") + \brief constructor +*/ +SamHeader::SamHeader(const std::string& headerText) : Version("") - , SortOrder("") + , SortOrder(Constants::SAM_HD_SORTORDER_UNKNOWN) , GroupOrder("") - , ProgramName("") - , ProgramVersion("") - , ProgramCommandLine("") { - SamFormatParser parser(*this); - parser.Parse(headerText); + SetHeaderText(headerText); } -// copy ctor +/*! \fn SamHeader::SamHeader(const SamHeader& other) + \brief copy constructor +*/ SamHeader::SamHeader(const SamHeader& other) : Version(other.Version) , SortOrder(other.SortOrder) , GroupOrder(other.GroupOrder) , Sequences(other.Sequences) , ReadGroups(other.ReadGroups) - , ProgramName(other.ProgramName) - , ProgramVersion(other.ProgramVersion) - , ProgramCommandLine(other.ProgramCommandLine) + , Programs(other.Programs) { } -// dtor -SamHeader::~SamHeader(void) { - Clear(); -} +/*! \fn SamHeader::~SamHeader(void) + \brief destructor +*/ +SamHeader::~SamHeader(void) { } +/*! \fn void SamHeader::Clear(void) + \brief Clears all header contents. +*/ void SamHeader::Clear(void) { + + // clear SAM header components Version.clear(); SortOrder.clear(); GroupOrder.clear(); Sequences.Clear(); ReadGroups.Clear(); - ProgramName.clear(); - ProgramVersion.clear(); - ProgramCommandLine.clear(); + Programs.Clear(); Comments.clear(); -} -void SamHeader::SetHeaderText(const std::string& headerText) { - - // clear prior data - Clear(); + // clear error string + m_errorString.clear(); +} - // parse header text into data - SamFormatParser parser(*this); - parser.Parse(headerText); +/*! \fn std::string SamHeader::GetErrorString(void) const + \brief Returns human-readable description of last error encountered +*/ +std::string SamHeader::GetErrorString(void) const { + return m_errorString; } -// retrieve the SAM header, with any local modifications -string SamHeader::ToString(void) const { - SamFormatPrinter printer(*this); - return printer.ToString(); +/*! \fn bool SamHeader::HasError(void) const + \brief Returns \c true if header encountered an error +*/ +bool SamHeader::HasError(void) const { + return (!m_errorString.empty()); } -// query if header contains @HD ID: +/*! \fn bool SamHeader::HasVersion(void) const + \brief Returns \c true if header contains \@HD ID:\ +*/ bool SamHeader::HasVersion(void) const { return (!Version.empty()); } -// query if header contains @HD SO: +/*! \fn bool SamHeader::HasSortOrder(void) const + \brief Returns \c true if header contains \@HD SO:\ +*/ bool SamHeader::HasSortOrder(void) const { return (!SortOrder.empty()); } -// query if header contains @HD GO: +/*! \fn bool SamHeader::HasGroupOrder(void) const + \brief Returns \c true if header contains \@HD GO:\ +*/ bool SamHeader::HasGroupOrder(void) const { return (!GroupOrder.empty()); } -// query if header contains @SQ entries +/*! \fn bool SamHeader::HasSequences(void) const + \brief Returns \c true if header contains any \@SQ entries +*/ bool SamHeader::HasSequences(void) const { return (!Sequences.IsEmpty()); } -// query if header contains @RG entries +/*! \fn bool SamHeader::HasReadGroups(void) const + \brief Returns \c true if header contains any \@RG entries +*/ bool SamHeader::HasReadGroups(void) const { return (!ReadGroups.IsEmpty()); } -// query if header contains @PG ID: -bool SamHeader::HasProgramName(void) const { - return (!ProgramName.empty()); +/*! \fn bool SamHeader::HasPrograms(void) const + \brief Returns \c true if header contains any \@PG entries +*/ +bool SamHeader::HasPrograms(void) const { + return (!Programs.IsEmpty()); } -// query if header contains @HD VN: -bool SamHeader::HasProgramVersion(void) const { - return (!ProgramVersion.empty()); -} - -// query if header contains @HD CL: -bool SamHeader::HasProgramCommandLine(void) const { - return (!ProgramCommandLine.empty()); -} - -// query if header contains @CO entries +/*! \fn bool SamHeader::HasComments(void) const + \brief Returns \c true if header contains any \@CO entries +*/ bool SamHeader::HasComments(void) const { return (!Comments.empty()); } -// validation +/*! \fn bool SamHeader::IsValid(bool verbose = false) const + \brief Checks header contents for required data and proper formatting. + \param verbose If set to true, validation errors & warnings will be printed to stderr. + Otherwise, messages are available through SamHeader::GetErrorString(). + \return \c true if SAM header is well-formed +*/ bool SamHeader::IsValid(bool verbose) const { + SamHeaderValidator validator(*this); - return validator.Validate(verbose); + + // if SAM header is valid, return success + if ( validator.Validate() ) + return true; + + // otherwiser + else { + + // print messages to stderr + if ( verbose ) + validator.PrintMessages(std::cerr); + + // or catch in local error string + else { + stringstream errorStream(""); + validator.PrintMessages(errorStream); + m_errorString = errorStream.str(); + } + return false; + } +} + +/*! \fn void SamHeader::SetHeaderText(const std::string& headerText) + \brief Replaces header contents with \a headerText. + \param headerText SAM formatted-text that will be parsed into data fields +*/ +void SamHeader::SetHeaderText(const std::string& headerText) { + + // clear prior data + Clear(); + + try { + SamFormatParser parser(*this); + parser.Parse(headerText); + } catch ( BamException& e ) { + + // clear anything parsed so far + // no telling what's valid and what's partially parsed + Clear(); + + // set error string + m_errorString = e.what(); + } +} + +/*! \fn std::string SamHeader::ToString(void) const + \brief Converts data fields to SAM-formatted text. + + Applies any local modifications made since creating this object or calling SetHeaderText(). + + \return SAM-formatted header text +*/ +string SamHeader::ToString(void) const { + SamFormatPrinter printer(*this); + return printer.ToString(); }