NCBI C++ ToolKit
stream_source.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef UTIL___STREAM_SOURCE__HPP
2 #define UTIL___STREAM_SOURCE__HPP
3 
4 /* $Id: stream_source.hpp 77707 2017-05-03 12:47:35Z ivanov $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors: Mike DiCuccio
30  *
31  * File Description:
32  *
33  */
34 
35 #include <corelib/ncbistd.hpp>
36 #include <corelib/ncbiargs.hpp>
37 
39 
40 
41 ///
42 /// class CInputStreamSource encapsulates details of how we supply applications
43 /// with input data through sets of command-line options, and permits code to
44 /// work with a standard API for accepting input data from the command-line.
45 ///
46 /// This class offers many variants for accepting and managing input data.
47 /// Currently supported modes are:
48 ///
49 /// - Supply a single argument for an input stream of data
50 /// - Supply an argument indicating a manifest file (a file whose contents
51 /// list a set of files, one per line; comment lines preceded by '#' will be
52 /// skipped
53 /// - Supply an argument indicating an input search path, with or without a
54 /// search mask, defining the files to be processed
55 ///
56 /// Once instantiated, this class supports the ability to iterate a set of
57 /// input streams using the code metaphor:
58 ///
59 /// \code
60 /// const CArgs& args = GetArgs();
61 /// for (CInputStreamSource source(args); source; ++source) {
62 /// CNcbiIstream& istr = *source;
63 /// ...
64 /// }
65 /// \endcode
66 ///
67 /// Streams are checked for error conditions at the start (badbit or
68 /// failbit before being returned from the iterator) and end (badbit
69 /// after use, prior to iterating to the next stream),
70 /// throwing an exception in such case. The former handles cases of files
71 /// which don't exist, and the latter handles cases of disk read errors
72 /// without preventing operations line getline (which sets failbit
73 /// on reading the last line of input, with a terminator).
75 {
76 public:
77  /// Supply a standard set of arguments via argument descriptions to an
78  /// application
79  ///
80  /// Currently supported arguments are:
81  ///
82  /// - -i (-input) for a single input stream
83  /// - -input-manifest for a manifest file
84  /// - -input-path (with or without -input-mask) for a file search path
85  ///
86  /// Any or all of these arguments may be supplied by an application
87  ///
88  /// @param arg_desc Argument description class into which arguments will be
89  /// added
90  /// @param prefix The base prefix to use. Providing a different value here
91  /// can be used to add a standard panel of additional arguments to control
92  /// input sources.
93  /// @param description The description that will appear in -help
94  /// @param is_mandatory A flag to indicate whether one of the configured
95  /// arguments must be provided.
96  ///
97  static void SetStandardInputArgs(CArgDescriptions& arg_desc,
98  const string &prefix = "input",
99  const string &description = "data to process",
100  bool is_mandatory = false);
101 
102  /// Get the standard input arguments that are present in args
103  /// so we can pass them on to some other program that also uses
104  /// CInputStreamSource.
105  static vector<string> RecreateInputArgs(const CArgs& args,
106  const string &prefix = "input");
107 
108  /// Check whether the arguments for a specific prefix have been set up in
109  /// this application
110  static bool HaveArgsForPrefix(const string &prefix = "input");
111 
112  /// Default ctor
113  /// This ctor leaves the stream source empty
114  ///
116 
117  /// Initialize our stream source through the arguments provided on a
118  /// command-line
119  ///
120  /// This constructor will interpret the commands supplied via
121  /// SetStandardInputArgs()
122  ///
123  /// @param args Argument class for interpretation
124  ///
125  CInputStreamSource(const CArgs& args, const string& prefix = "input");
126 
127  virtual ~CInputStreamSource();
128 
129  /// Initialize from a stream
130  /// No ownership is claimed by this class - lifetime management of the
131  /// stream is the responsibility of the caller.
132  ///
133  /// @pre The stream is in a good condition, else throws an exception.
134  /// @param fname (optional) file name from whence the stream was
135  /// created, for use in output and debug messages.
136  ///
137  void InitStream(CNcbiIstream& istr,
138  const string& fname = kEmptyStr);
139 
140  /// Initialize from a single file path.
141  ///
142  void InitFile(const string& file_path);
143 
144  /// Initialize from a manifest file
145  ///
146  /// @see CFileManifest
147  ///
148  void InitManifest(const string& manifest);
149 
150  /// Initialize from a file search path
151  ///
152  void InitFilesInDirSubtree(const string& file_path,
153  const string& file_mask = kEmptyStr);
154 
155  /// Initialize from a set of arguments
156  ///
157  virtual void InitArgs(const CArgs& args, const string &prefix = "input");
158 
159  /// Access the current stream
160  ///
161  /// @return The current stream
162  ///
163  CNcbiIstream& GetStream(void);
164 
165  /// Access the current stream, and get the file name
166  ///
167  /// @param fname receives the name of the current file
168  /// @return The current stream
169  ///
171  CNcbiIstream& GetStream(string* fname);
172 
173  /// Dereferencing the stream class returns the current stream
174  /// @return The current stream
175  ///
177 
178  /// Advance to the next stream in the class
179  ///
180  /// @return self, satisfying chainability of commands
181  ///
182  /// @post The old stream, if there was one, is not in a bad condition
183  /// (badbit set as may occur if there was a disk read error;
184  /// the failbit is ignored, since operations like geline will
185  /// set it to indicate the last line with a line terminator).
186  ///
187  /// The current stream, if it exists, is in a good condition
188  /// (badbit or failbit set).
189  ///
190  /// If these conditions aren't met, throws an exception.
191  ///
192  virtual CInputStreamSource& operator++();
193 
194  /// Determine if there are any more streams to be processed
195  ///
196  /// @return boolean, true if there are more streams
197  ///
198  operator bool() const;
199 
200  /// Resets the iterator to the first stream in the class
201  ///
202  /// @return self
203  CInputStreamSource& Rewind(void);
204 
205  /// Returns the current file name
206  string GetCurrentFileName(void) const;
207 
208  /// Returns the current file index and the total number of files
209  ///
210  /// @param count
211  /// address of variable which receives the total number of files
212  /// @return
213  /// the current file index
214  size_t GetCurrentStreamIndex(size_t* count = nullptr) const;
215 
216 protected:
218  string m_Prefix;
219 
221  unique_ptr<CNcbiIstream> m_IstrOwned;
222 
223  vector<string> m_Files;
224  size_t m_CurrIndex;
225  string m_CurrFile;
226 
227 private:
228  /// forbidden
231 };
232 
233 
234 
235 
236 
238 
239 
240 #endif // UTIL___STREAM_SOURCE__HPP
#define bool
Definition: bool.h:34
CArgDescriptions –.
Definition: ncbiargs.hpp:541
CArgs –.
Definition: ncbiargs.hpp:379
class CInputStreamSource encapsulates details of how we supply applications with input data through s...
vector< string > m_Files
CNcbiIstream * m_Istr
CInputStreamSource & operator=(const CInputStreamSource &)
CInputStreamSource(const CInputStreamSource &)
forbidden
unique_ptr< CNcbiIstream > m_IstrOwned
Include a standard set of the NCBI C++ Toolkit most basic headers.
CVect2< NCBI_PROMOTE(int,U) > operator*(int v1, const CVect2< U > &v2)
Definition: globals.hpp:371
#define NCBI_DEPRECATED
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
IO_PREFIX::istream CNcbiIstream
Portable alias for istream.
Definition: ncbistre.hpp:146
#define kEmptyStr
Definition: ncbistr.hpp:123
Defines command line argument related classes.
static const char * prefix[]
Definition: pcregrep.c:405
NCBI_XUTIL_EXPORT
Parameter to control printing diagnostic message about conversion of static array data from a differe...
Definition: static_set.hpp:72
Modified on Sun Feb 25 03:09:04 2024 by modify_doxy.py rev. 669887