X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=src%2Fapi%2FSamHeader.cpp;h=5de2abcd9006d6eb86693973c416b0a61b9b2998;hb=9f1ce8c47aeadb6dc1320b52ee671c3341b97935;hp=405033fa740dff49dea0b14d92c2e150c6c61cbc;hpb=ff5f2ec7c437660185a406d01739f42534105412;p=bamtools.git diff --git a/src/api/SamHeader.cpp b/src/api/SamHeader.cpp index 405033f..5de2abc 100644 --- a/src/api/SamHeader.cpp +++ b/src/api/SamHeader.cpp @@ -1,102 +1,234 @@ // *************************************************************************** // SamHeader.cpp (c) 2010 Derek Barnett // Marth Lab, Department of Biology, Boston College -// All rights reserved. // --------------------------------------------------------------------------- -// Last modified: 23 December 2010 (DB) +// Last modified: 10 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 "api/SamConstants.h" +#include "api/SamHeader.h" +#include "api/internal/BamException_p.h" +#include "api/internal/SamFormatParser_p.h" +#include "api/internal/SamFormatPrinter_p.h" +#include "api/internal/SamHeaderValidator_p.h" using namespace BamTools; using namespace BamTools::Internal; using namespace std; -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::Programs + \brief corresponds to \@PG entries + \sa SamProgram, SamProgramChain +*/ +/*! \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); } -SamHeader::~SamHeader(void) { - Clear(); -} +/*! \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) + , Programs(other.Programs) +{ } + +/*! \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(); + + // clear error string + m_errorString.clear(); } -// retrieve the SAM header, with any local modifications -string SamHeader::ToString(void) const { - SamFormatPrinter printer(*this); - return printer.ToString(); +/*! \fn std::string SamHeader::GetErrorString(void) const + \brief Returns a human-readable description of the last error that occurred + + This method allows elimination of STDERR pollution. Developers of client code + may choose how the messages are displayed to the user, if at all. + + \return error description +*/ +std::string SamHeader::GetErrorString(void) const { + return m_errorString; +} + +/*! \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()); -} - -// 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()); +/*! \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 @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[in] 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[in] 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(); }