NCBI C++ ToolKit
Public Member Functions | Static Public Member Functions | Protected Attributes | Private Member Functions | List of all members
CInputStreamSource Class Reference

Search Toolkit Book for CInputStreamSource

class CInputStreamSource encapsulates details of how we supply applications with input data through sets of command-line options, and permits code to work with a standard API for accepting input data from the command-line. More...

#include <util/stream_source.hpp>

+ Collaboration diagram for CInputStreamSource:

Public Member Functions

 CInputStreamSource ()
 Default ctor This ctor leaves the stream source empty. More...
 
 CInputStreamSource (const CArgs &args, const string &prefix="input")
 Initialize our stream source through the arguments provided on a command-line. More...
 
virtual ~CInputStreamSource ()
 
void InitStream (CNcbiIstream &istr, const string &fname=kEmptyStr)
 Initialize from a stream No ownership is claimed by this class - lifetime management of the stream is the responsibility of the caller. More...
 
void InitFile (const string &file_path)
 Initialize from a single file path. More...
 
void InitManifest (const string &manifest)
 Initialize from a manifest file. More...
 
void InitFilesInDirSubtree (const string &file_path, const string &file_mask=kEmptyStr)
 Initialize from a file search path. More...
 
virtual void InitArgs (const CArgs &args, const string &prefix="input")
 Initialize from a set of arguments. More...
 
CNcbiIstreamGetStream (void)
 Access the current stream. More...
 
CNcbiIstreamGetStream (string *fname)
 Access the current stream, and get the file name. More...
 
CNcbiIstreamoperator* ()
 Dereferencing the stream class returns the current stream. More...
 
virtual CInputStreamSourceoperator++ ()
 Advance to the next stream in the class. More...
 
 operator bool () const
 Determine if there are any more streams to be processed. More...
 
CInputStreamSourceRewind (void)
 Resets the iterator to the first stream in the class. More...
 
string GetCurrentFileName (void) const
 Returns the current file name. More...
 
size_t GetCurrentStreamIndex (size_t *count=nullptr) const
 Returns the current file index and the total number of files. More...
 

Static Public Member Functions

static void SetStandardInputArgs (CArgDescriptions &arg_desc, const string &prefix="input", const string &description="data to process", bool is_mandatory=false)
 Supply a standard set of arguments via argument descriptions to an application. More...
 
static vector< stringRecreateInputArgs (const CArgs &args, const string &prefix="input")
 Get the standard input arguments that are present in args so we can pass them on to some other program that also uses CInputStreamSource. More...
 
static bool HaveArgsForPrefix (const string &prefix="input")
 Check whether the arguments for a specific prefix have been set up in this application. More...
 

Protected Attributes

CArgs m_Args
 
string m_Prefix
 
CNcbiIstreamm_Istr
 
unique_ptr< CNcbiIstreamm_IstrOwned
 
vector< stringm_Files
 
size_t m_CurrIndex
 
string m_CurrFile
 

Private Member Functions

 CInputStreamSource (const CInputStreamSource &)
 forbidden More...
 
CInputStreamSourceoperator= (const CInputStreamSource &)
 

Detailed Description

class CInputStreamSource encapsulates details of how we supply applications with input data through sets of command-line options, and permits code to work with a standard API for accepting input data from the command-line.

This class offers many variants for accepting and managing input data. Currently supported modes are:

Once instantiated, this class supports the ability to iterate a set of input streams using the code metaphor:

const CArgs& args = GetArgs();
CNcbiIstream& istr = *source;
...
}
CArgs –.
Definition: ncbiargs.hpp:379
class CInputStreamSource encapsulates details of how we supply applications with input data through s...
IO_PREFIX::istream CNcbiIstream
Portable alias for istream.
Definition: ncbistre.hpp:146
const CharType(& source)[N]
Definition: pointer.h:1149
#define GetArgs
Avoid preprocessor name clash with the NCBI C Toolkit.
Definition: ncbiapp_api.hpp:53

Streams are checked for error conditions at the start (badbit or failbit before being returned from the iterator) and end (badbit after use, prior to iterating to the next stream), throwing an exception in such case. The former handles cases of files which don't exist, and the latter handles cases of disk read errors without preventing operations line getline (which sets failbit on reading the last line of input, with a terminator).

Definition at line 74 of file stream_source.hpp.

Constructor & Destructor Documentation

◆ CInputStreamSource() [1/3]

CInputStreamSource::CInputStreamSource ( )

Default ctor This ctor leaves the stream source empty.

Definition at line 126 of file stream_source.cpp.

◆ CInputStreamSource() [2/3]

CInputStreamSource::CInputStreamSource ( const CArgs args,
const string prefix = "input" 
)

Initialize our stream source through the arguments provided on a command-line.

This constructor will interpret the commands supplied via SetStandardInputArgs()

Parameters
argsArgument class for interpretation

Definition at line 132 of file stream_source.cpp.

References InitArgs(), and prefix.

◆ ~CInputStreamSource()

CInputStreamSource::~CInputStreamSource ( )
virtual

Definition at line 139 of file stream_source.cpp.

◆ CInputStreamSource() [3/3]

CInputStreamSource::CInputStreamSource ( const CInputStreamSource )
private

forbidden

Member Function Documentation

◆ GetCurrentFileName()

string CInputStreamSource::GetCurrentFileName ( void  ) const

Returns the current file name.

Definition at line 375 of file stream_source.cpp.

References m_CurrFile.

◆ GetCurrentStreamIndex()

size_t CInputStreamSource::GetCurrentStreamIndex ( size_t *  count = nullptr) const

Returns the current file index and the total number of files.

Parameters
countaddress of variable which receives the total number of files
Returns
the current file index

Definition at line 380 of file stream_source.cpp.

References m_CurrIndex, and m_Files.

◆ GetStream() [1/2]

CNcbiIstream & CInputStreamSource::GetStream ( string fname)

Access the current stream, and get the file name.

Parameters
fnamereceives the name of the current file
Returns
The current stream

Definition at line 278 of file stream_source.cpp.

References eUnknown, m_CurrFile, m_Istr, m_IstrOwned, and NCBI_THROW.

◆ GetStream() [2/2]

CNcbiIstream & CInputStreamSource::GetStream ( void  )

Access the current stream.

Returns
The current stream

Definition at line 297 of file stream_source.cpp.

References eUnknown, m_Istr, m_IstrOwned, and NCBI_THROW.

Referenced by operator*().

◆ HaveArgsForPrefix()

bool CInputStreamSource::HaveArgsForPrefix ( const string prefix = "input")
static

Check whether the arguments for a specific prefix have been set up in this application.

Definition at line 121 of file stream_source.cpp.

References prefix, s_InputStreamSourcePrefixes, and true.

◆ InitArgs()

void CInputStreamSource::InitArgs ( const CArgs args,
const string prefix = "input" 
)
virtual

Initialize from a set of arguments.

Definition at line 143 of file stream_source.cpp.

References CArgs::Assign(), InitFile(), InitFilesInDirSubtree(), InitManifest(), InitStream(), m_Args, m_Prefix, mask, and prefix.

Referenced by CInputStreamSource().

◆ InitFile()

void CInputStreamSource::InitFile ( const string file_path)

Initialize from a single file path.

Definition at line 196 of file stream_source.cpp.

References eUnknown, m_CurrIndex, m_Files, m_Istr, NCBI_THROW, and Rewind().

Referenced by InitArgs().

◆ InitFilesInDirSubtree()

void CInputStreamSource::InitFilesInDirSubtree ( const string file_path,
const string file_mask = kEmptyStr 
)

Initialize from a file search path.

Definition at line 242 of file stream_source.cpp.

References _TRACE, eUnknown, CDir::Exists(), fFF_File, fFF_Recursive, FindFiles(), m_CurrIndex, m_Files, m_Istr, NCBI_THROW, and Rewind().

Referenced by InitArgs().

◆ InitManifest()

void CInputStreamSource::InitManifest ( const string manifest)

Initialize from a manifest file.

See also
CFileManifest

Definition at line 221 of file stream_source.cpp.

References _TRACE, all, copy(), eUnknown, CFileManifest::GetAllFilePaths(), m_CurrIndex, m_Files, m_Istr, NCBI_THROW, and Rewind().

Referenced by InitArgs(), and CPrimeCacheApplication::Run().

◆ InitStream()

void CInputStreamSource::InitStream ( CNcbiIstream istr,
const string fname = kEmptyStr 
)

Initialize from a stream No ownership is claimed by this class - lifetime management of the stream is the responsibility of the caller.

Initialize from a given stream which is the sole content.

Precondition
The stream is in a good condition, else throws an exception.
Parameters
fname(optional) file name from whence the stream was created, for use in output and debug messages.

As precondition, expect that the stream is in a good condition prior to being handed off to consumers.

Definition at line 175 of file stream_source.cpp.

References eUnknown, m_CurrFile, m_CurrIndex, m_Files, m_Istr, and NCBI_THROW.

Referenced by InitArgs(), and CPrimeCacheApplication::Run().

◆ operator bool()

CInputStreamSource::operator bool ( void  ) const

Determine if there are any more streams to be processed.

Returns
boolean, true if there are more streams

Definition at line 388 of file stream_source.cpp.

◆ operator*()

CNcbiIstream & CInputStreamSource::operator* ( void  )

Dereferencing the stream class returns the current stream.

Returns
The current stream

Definition at line 311 of file stream_source.cpp.

References GetStream().

◆ operator++()

CInputStreamSource & CInputStreamSource::operator++ ( void  )
virtual

Advance to the next stream in the class.

Returns
self, satisfying chainability of commands
Postcondition
The old stream, if there was one, is not in a bad condition (badbit set as may occur if there was a disk read error; the failbit is ignored, since operations like geline will set it to indicate the last line with a line terminator).

The current stream, if it exists, is in a good condition (badbit or failbit set).

If these conditions aren't met, throws an exception.

Definition at line 317 of file stream_source.cpp.

References eUnknown, m_CurrFile, m_CurrIndex, m_Files, m_Istr, m_IstrOwned, NCBI_THROW, and NULL.

◆ operator=()

CInputStreamSource& CInputStreamSource::operator= ( const CInputStreamSource )
private

◆ RecreateInputArgs()

vector< string > CInputStreamSource::RecreateInputArgs ( const CArgs args,
const string prefix = "input" 
)
static

Get the standard input arguments that are present in args so we can pass them on to some other program that also uses CInputStreamSource.

Definition at line 99 of file stream_source.cpp.

References prefix, and result.

◆ Rewind()

CInputStreamSource & CInputStreamSource::Rewind ( void  )

Resets the iterator to the first stream in the class.

Returns
self

Definition at line 368 of file stream_source.cpp.

References m_CurrIndex.

Referenced by InitFile(), InitFilesInDirSubtree(), and InitManifest().

◆ SetStandardInputArgs()

void CInputStreamSource::SetStandardInputArgs ( CArgDescriptions arg_desc,
const string prefix = "input",
const string description = "data to process",
bool  is_mandatory = false 
)
static

Supply a standard set of arguments via argument descriptions to an application.

Currently supported arguments are:

  • -i (-input) for a single input stream
  • -input-manifest for a manifest file
  • -input-path (with or without -input-mask) for a file search path

Any or all of these arguments may be supplied by an application

Parameters
arg_descArgument description class into which arguments will be added
prefixThe base prefix to use. Providing a different value here can be used to add a standard panel of additional arguments to control input sources.
descriptionThe description that will appear in -help
is_mandatoryA flag to indicate whether one of the configured arguments must be provided.

Definition at line 41 of file stream_source.cpp.

References CArgDescriptions::AddAlias(), CArgDescriptions::AddDefaultKey(), CArgDescriptions::AddKey(), CArgDescriptions::AddOptionalKey(), CArgDescriptions::eExcludes, CArgDescriptions::eInputFile, CArgDescriptions::eRequires, CArgDescriptions::eString, set< Key, Compare >::insert(), prefix, s_InputStreamSourcePrefixes, CArgDescriptions::SetCurrentGroup(), and CArgDescriptions::SetDependency().

Referenced by CAlignCleanupApplication::Init(), and CAdvancedAlignCleanup::SetupArgDescriptions().

Member Data Documentation

◆ m_Args

CArgs CInputStreamSource::m_Args
protected

Definition at line 217 of file stream_source.hpp.

Referenced by InitArgs().

◆ m_CurrFile

string CInputStreamSource::m_CurrFile
protected

Definition at line 225 of file stream_source.hpp.

Referenced by GetCurrentFileName(), GetStream(), InitStream(), and operator++().

◆ m_CurrIndex

size_t CInputStreamSource::m_CurrIndex
protected

◆ m_Files

vector<string> CInputStreamSource::m_Files
protected

◆ m_Istr

CNcbiIstream* CInputStreamSource::m_Istr
protected

◆ m_IstrOwned

unique_ptr<CNcbiIstream> CInputStreamSource::m_IstrOwned
protected

Definition at line 221 of file stream_source.hpp.

Referenced by GetStream(), and operator++().

◆ m_Prefix

string CInputStreamSource::m_Prefix
protected

Definition at line 218 of file stream_source.hpp.

Referenced by InitArgs().


The documentation for this class was generated from the following files:
Modified on Sat Feb 24 07:47:25 2024 by modify_doxy.py rev. 669887