// ***************************************************************************
// SamHeader.cpp (c) 2010 Derek Barnett
// Marth Lab, Department of Biology, Boston College
-// All rights reserved.
// ---------------------------------------------------------------------------
-// Last modified: 4 March 2011 (DB)
+// Last modified: 25 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides direct read/write access to the SAM header data fields.
// ***************************************************************************
-#include <api/SamHeader.h>
-#include <api/internal/SamFormatParser_p.h>
-#include <api/internal/SamFormatPrinter_p.h>
-#include <api/internal/SamHeaderValidator_p.h>
+#include "api/SamConstants.h"
+#include "api/SamHeader.h"
+#include "api/internal/utils/BamException_p.h"
+#include "api/internal/sam/SamFormatParser_p.h"
+#include "api/internal/sam/SamFormatPrinter_p.h"
+#include "api/internal/sam/SamHeaderValidator_p.h"
using namespace BamTools;
using namespace BamTools::Internal;
using namespace std;
Provides direct read/write access to the SAM header data fields.
- \sa http://samtools.sourceforge.net/SAM-1.3.pdf
+ \sa \samSpecURL
*/
/*! \var SamHeader::Version
\brief corresponds to \@HD VN:\<Version\>
+
+ Required for valid SAM header, if \@HD record is present.
*/
/*! \var SamHeader::SortOrder
\brief corresponds to \@HD SO:\<SortOrder\>
\brief corresponds to \@RG entries
\sa SamReadGroup, SamReadGroupDictionary
*/
-/*! \var SamHeader::ProgramName
- \brief corresponds to \@PG ID:\<ProgramName\>
-*/
-/*! \var SamHeader::ProgramVersion
- \brief corresponds to \@PG VN:\<ProgramVersion\>
-*/
-/*! \var SamHeader::ProgramCommandLine
- \brief corresponds to \@PG CL:\<ProgramCommandLine\>
+/*! \var SamHeader::Programs
+ \brief corresponds to \@PG entries
+ \sa SamProgram, SamProgramChain
*/
/*! \var SamHeader::Comments
\brief corresponds to \@CO entries
*/
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);
}
/*! \fn SamHeader::SamHeader(const SamHeader& other)
, GroupOrder(other.GroupOrder)
, Sequences(other.Sequences)
, ReadGroups(other.ReadGroups)
- , ProgramName(other.ProgramName)
- , ProgramVersion(other.ProgramVersion)
- , ProgramCommandLine(other.ProgramCommandLine)
+ , Programs(other.Programs)
+ , Comments(other.Comments)
{ }
/*! \fn SamHeader::~SamHeader(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();
+}
+
+/*! \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());
}
/*! \fn bool SamHeader::HasVersion(void) const
return (!ReadGroups.IsEmpty());
}
-/*! \fn bool SamHeader::HasProgramName(void) const
- \brief Returns \c true if header contains \@PG ID:\<ProgramName\>
+/*! \fn bool SamHeader::HasPrograms(void) const
+ \brief Returns \c true if header contains any \@PG entries
*/
-bool SamHeader::HasProgramName(void) const {
- return (!ProgramName.empty());
-}
-
-/*! \fn bool SamHeader::HasProgramVersion(void) const
- \brief Returns \c true if header contains \@PG VN:\<ProgramVersion\>
-*/
-bool SamHeader::HasProgramVersion(void) const {
- return (!ProgramVersion.empty());
-}
-
-/*! \fn bool SamHeader::HasProgramCommandLine(void) const
- \brief Returns \c true if header contains \@PG CL:\<ProgramCommandLine\>
-*/
-bool SamHeader::HasProgramCommandLine(void) const {
- return (!ProgramCommandLine.empty());
+bool SamHeader::HasPrograms(void) const {
+ return (!Programs.IsEmpty());
}
/*! \fn bool SamHeader::HasComments(void) const
/*! \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, output is suppressed and only validation check occurs.
+
+ \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 headerText SAM formatted-text that will be parsed into data fields
+
+ \param[in] headerText SAM formatted-text that will be parsed into data fields
*/
void SamHeader::SetHeaderText(const std::string& headerText) {
// clear prior data
Clear();
- // parse header text into data
- SamFormatParser parser(*this);
- parser.Parse(headerText);
+ 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