srecord: arglex.h Source File

srecord 1.65.0

Loading...
Searching...
No Matches
arglex.h
Go to the documentation of this file.
1//
2// srecord - manipulate eprom load files
3// Copyright (C) 1998-2014 Peter Miller
4//
5// This program is free software; you can redistribute it and/or modify
6// it under the terms of the GNU Lesser General Public License as published by
7// the Free Software Foundation; either version 3 of the License, or
8// (at your option) any later version.
9//
10// This program is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU Lesser General Public License for more details.
14//
15// You should have received a copy of the GNU Lesser General Public License
16// along with this program. If not, see
17// <http://www.gnu.org/licenses/>.
18//
19
20#ifndef LIB_ARGLEX_H
21#define LIB_ARGLEX_H
22
23#include <srecord/format_printf.h>
24
25#include <list>
26#include <vector>
27#include <string>
28
29#define SRECORD_ARGLEX_END_MARKER {0,0}
30
31namespace srecord {
32
33/**
34 * The arglex class is used to implement a lexical analizer for command
35 * line arguments. Each comamnd line argument is analized to determine
36 * if it is a number, a string (file name) or an option.
37 */
38 class arglex
39{
40public:
41 /**
42 * The destructor.
43 */
44 virtual ~arglex();
45
46 /**
47 * The "normal" command line tokens common to all programs.
48 */
49 enum
50 {
51 token_eoln,
52 token_help,
53 token_license,
54 token_number,
55 token_option,
56 token_page_width,
57 token_page_length,
58 token_stdio,
59 token_string,
60 token_tracing,
61 token_verbose,
62 token_version,
63 token_MAX
64 };
65
66 /**
67 * The value_ty struct is used to represent the value of a
68 * command line argument.
69 */
70 struct value_ty
71 {
72 /**
73 * The literal string value of the token.
74 */
75 const char *alv_string;
76
77 /**
78 * The integer vale of the token. Only meaningful
79 * for token_number, otherwise zero.
80 */
81 long alv_number;
82 };
83
84 /**
85 * The table_ty struct is used to repesent a row of a
86 * commandline option table, used to match option names with
87 * their corresponding tokens.
88 */
89 struct table_ty
90 {
91 /**
92 * The name of the commen line option.
93 */
94 const char *name;
95
96 /**
97 * The corresponding token.
98 */
99 int token;
100 };
101
102 /**
103 * The fatal_error method may be used to print a fatal error
104 * message, and then exit via the usage() method.
105 *
106 * @param fmt
107 * The format of the string - it controls the rest of the
108 * arguments. See printf(3) for more information.
109 * @note
110 * This method never returns.
111 */
112 void fatal_error(const char *fmt, ...) FORMAT_PRINTF(2, 3);
113
114 /**
115 * The compare class method is used to compare a command line string
116 * with a formal spec of the option, to see if they compare equal.
117 *
118 * The actual is case-insensitive. Uppercase in the formal means a
119 * mandatory character, while lower case means optional. Any number of
120 * consecutive optional characters may be supplied by actual, but none
121 * may be skipped, unless all are skipped to the next non-lower-case
122 * letter.
123 *
124 * The underscore (_) is like a lower-case minus, it matches "", "-"
125 * and "_".
126 *
127 * The "*" in a pattern matches everything to the end of the line,
128 * anything after the "*" is ignored. The rest of the line is pointed
129 * to by the "partial" variable as a side-effect (else it will be 0).
130 * This rather ugly feature is to support "-I./dir" type options.
131 *
132 * A backslash in a pattern nominates an exact match required, case
133 * must matche excatly here. This rather ugly feature is to support
134 * "-I./dir" type options.
135 *
136 * For example: "-project" and "-P" both match "-Project", as does
137 * "-proJ", but "-prj" does not.
138 *
139 * For example: "-devDir" and "-d_d" both match "-Development_Directory",
140 * but "-dvlpmnt_drctry" does not.
141 *
142 * For example: to match include path specifications, use a pattern
143 * such as "-\\I*", and the partial global variable will have the path
144 * in it on return.
145 */
146 static bool compare(const char *formal, const char *actual);
147
148 /**
149 * The abbreviate class method is used to take an option's long
150 * name, and turn it into the minimum possible string for that
151 * option.
152 */
153 static std::string abbreviate(const char *text);
154
155 /**
156 * The test_ambiguous method is for debugging. It verifies that
157 * all of the option names are unique.
158 */
159 void test_ambiguous(void) const;
160
161private:
162 /**
163 * The arguments instance variable is used to remember the
164 * remaining command line arguments.
165 */
166 std::list<std::string> arguments;
167
168 /**
169 * The token instance variable tracks the current token in the
170 * parse sequence.
171 */
172 int token;
173
174 /**
175 * The value_string_ instance variable tracks the value of the
176 * current command line argument.
177 */
178 std::string value_string_;
179
180 /**
181 * The value_number_ instance variable tracks the numeric value
182 * of the current command line argument. Usually zero unless
183 * the current command line argument is a number.
184 */
185 long value_number_;
186
187 /**
188 * The table_ptr_vec_t type is used to declare the 'tables'
189 * instance variable. Also used to simplify the code use to
190 * manipulate the 'tables' instance variable.
191 */
192 typedef std::vector<const table_ty *> table_ptr_vec_t;
193
194 /**
195 * The tables instance variable tracks the command line token
196 * tables to be scanned to determine if a command line argument
197 * is a particular token. There is usually one per derived
198 * class. Append more tables with the 'table_set' method.
199 */
200 table_ptr_vec_t tables;
201
202 /**
203 * The pushback instance variable tracks command line argument
204 * (or, often, portions of command line arguments) which have
205 * been "pushed back" to be re-scanned later.
206 */
207 std::list<std::string> pushback;
208
209protected:
210 /**
211 * The table_set method is used to append more command line
212 * token tables to the list of tables to be scanned. Usually one
213 * per derived class.
214 */
215 void table_set(const table_ty *);
216
217public:
218 /**
219 * The default constructor.
220 */
221 arglex();
222
223 /**
224 * The copy constructor.
225 */
226 arglex(arglex &);
227
228 /**
229 * The normal constructor. The argv and argv should be those
230 * passed to main(). Not manipulation is required.
231 */
232 arglex(int argc, char **argv);
233
234 /**
235 * The token_cur method is used to get the type of the current
236 * token.
237 */
238 int token_cur() const { return token; }
239
240 /**
241 * The token_next method is used to advance to the next command
242 * line option and determine what type of token it is.
243 * It returns the type of the token; this value may also be
244 * fetched using the token_cur method.
245 */
246 int token_next(void);
247
248 /**
249 * The token_first method is used to fetch the fisrt command
250 * like token (rather than use the token_next method). This does
251 * standard "help" and "version" options.
252 */
253 int token_first(void);
254
255 /**
256 * The value_string method is used to get the string value of
257 * the current token.
258 */
259 const std::string &value_string() const { return value_string_; }
260
261 /**
262 * The value_number method is used to get the numeric value of
263 * the current token.
264 */
265 long value_number() const { return value_number_; }
266
267 /**
268 * The token_name method is used to turn a token type number
269 * into an equivalent string. Useful for some error messages.
270 *
271 * @param tok
272 * The ID of the token to be named.
273 */
274 const char *token_name(int tok) const;
275
276 /**
277 * The token_name method is used to obtain the name of the current
278 * token.
279 */
280 const char *token_name() const { return token_name(token_cur()); }
281
282 /**
283 * The usage method is used to print a usage summary.
284 * This is a fatal error; this method does not return.
285 */
286 void usage() const;
287
288 /**
289 * The help method is used to print a help message.
290 */
291 void help(const char * = 0) const;
292
293 /**
294 * The version method is used to print a version message.
295 */
296 void version() const;
297
298 /**
299 * The license method is used to print the license conditions
300 * of the program.
301 */
302 void license() const;
303
304 /**
305 * The bad_argument method is used to print an error message
306 * when the current token is inappropriate, then it calls usage,
307 * which exits. This method does not return.
308 */
309 void bad_argument() const;
310
311 /**
312 * The usage_tail_set method is used to set the end of the
313 * command line to be printed as part of the usage method.
314 */
315 void usage_tail_set(const char *);
316
317 /**
318 * The default_command_line_processing method is used to process
319 * command line arguments not handled by the derived class.
320 */
321 virtual void default_command_line_processing(void);
322
323private:
324 /**
325 * The usage_tail_ instance variable tracks the end part of
326 * the command line printed by the 'usage' method.
327 * Defaults to the empty string.
328 */
329 mutable const char *usage_tail_;
330
331 /**
332 * The usage_tail_get method is used to get the tail end of
333 * the command line to be printed by the 'usage' method.
334 */
335 const char *usage_tail_get() const;
336
337 /**
338 * The read_arguments_file method is used to process filename
339 * command line arguments. The file is read and separated into
340 * space separated words, and each word added to the arguments
341 * instance variable in the appropriate sequence.
342 *
343 * Blank lines are ignored.
344 * Comments (starting with '#' until end of line) are ignored.
345 *
346 * @param filename
347 * The name of the file (not including the @) to be read.
348 */
349 void read_arguments_file(const char *filename);
350
351private:
352 typedef std::list<std::string> deprecated_options_t;
353
354 /**
355 * The deprecated_options instance variable is used to remember the
356 * options that are not to be used any more, so that a warning may
357 * be issued, recommending an appropriate replacement.
358 */
359 deprecated_options_t deprecated_options;
360
361 /**
362 * The check_deprecated method is used to check an actual command
363 * line option agans the list of deprectaed options, and issue a
364 * suitable warning of necessary.
365 *
366 * @param actual_use
367 * The text given on the command line
368 */
369 void check_deprecated(const std::string &actual_use) const;
370
371protected:
372 /**
373 * The deprecated_option method is used to nominate option patterns
374 * that are deprected.
375 *
376 * @param formal_name
377 * The pattern that is deprected. Must be an entry in one of
378 * the tables, otherwise users are going to be VERY confused.
379 */
380 void deprecated_option(const std::string &formal_name);
381};
382
383};
384
385#endif // LIB_ARGLEX_H
386// vim: set ts=8 sw=4 et :
srecord::arglex::fatal_error
void fatal_error(const char *fmt,...) FORMAT_PRINTF(2
The fatal_error method may be used to print a fatal error message, and then exit via the usage() meth...
srecord::arglex::token_name
const char * token_name() const
The token_name method is used to obtain the name of the current token.
Definition arglex.h:280
srecord::arglex::version
void version() const
The version method is used to print a version message.
srecord::arglex::value_number
long value_number() const
The value_number method is used to get the numeric value of the current token.
Definition arglex.h:265
srecord::arglex::token_cur
int token_cur() const
The token_cur method is used to get the type of the current token.
Definition arglex.h:238
srecord::arglex::value_string
const std::string & value_string() const
The value_string method is used to get the string value of the current token.
Definition arglex.h:259
srecord::arglex::usage
void usage() const
The usage method is used to print a usage summary.
srecord::arglex::abbreviate
static std::string abbreviate(const char *text)
The abbreviate class method is used to take an option's long name, and turn it into the minimum possi...
srecord::arglex::token_next
int token_next(void)
The token_next method is used to advance to the next command line option and determine what type of t...
srecord::arglex::~arglex
virtual ~arglex()
The destructor.
srecord::arglex::bad_argument
void bad_argument() const
The bad_argument method is used to print an error message when the current token is inappropriate,...
srecord::arglex::token_page_width
@ token_page_width
Definition arglex.h:56
srecord::arglex::token_verbose
@ token_verbose
Definition arglex.h:61
srecord::arglex::token_tracing
@ token_tracing
Definition arglex.h:60
srecord::arglex::token_option
@ token_option
Definition arglex.h:55
srecord::arglex::token_MAX
@ token_MAX
Definition arglex.h:63
srecord::arglex::token_license
@ token_license
Definition arglex.h:53
srecord::arglex::token_page_length
@ token_page_length
Definition arglex.h:57
srecord::arglex::token_help
@ token_help
Definition arglex.h:52
srecord::arglex::token_version
@ token_version
Definition arglex.h:62
srecord::arglex::token_string
@ token_string
Definition arglex.h:59
srecord::arglex::token_stdio
@ token_stdio
Definition arglex.h:58
srecord::arglex::token_number
@ token_number
Definition arglex.h:54
srecord::arglex::token_eoln
@ token_eoln
Definition arglex.h:51
srecord::arglex::usage_tail_set
void usage_tail_set(const char *)
The usage_tail_set method is used to set the end of the command line to be printed as part of the usa...
srecord::arglex::compare
void static bool compare(const char *formal, const char *actual)
The compare class method is used to compare a command line string with a formal spec of the option,...
srecord::arglex::help
void help(const char *=0) const
The help method is used to print a help message.
srecord::arglex::default_command_line_processing
virtual void default_command_line_processing(void)
The default_command_line_processing method is used to process command line arguments not handled by t...
srecord::arglex::token_name
const char * token_name(int tok) const
The token_name method is used to turn a token type number into an equivalent string.
srecord::arglex::deprecated_option
void deprecated_option(const std::string &formal_name)
The deprecated_option method is used to nominate option patterns that are deprected.
srecord::arglex::table_set
void table_set(const table_ty *)
The table_set method is used to append more command line token tables to the list of tables to be sca...
srecord::arglex::token_first
int token_first(void)
The token_first method is used to fetch the fisrt command like token (rather than use the token_next ...
srecord::arglex::arglex
arglex()
The default constructor.
srecord::arglex::license
void license() const
The license method is used to print the license conditions of the program.
srecord::arglex::test_ambiguous
void test_ambiguous(void) const
The test_ambiguous method is for debugging.
format_printf.h
FORMAT_PRINTF
#define FORMAT_PRINTF(x, y)
Definition format_printf.h:28
srecord
Definition adler16.h:25
srecord::arglex::table_ty
The table_ty struct is used to repesent a row of a commandline option table, used to match option nam...
Definition arglex.h:90
srecord::arglex::table_ty::name
const char * name
The name of the commen line option.
Definition arglex.h:94
srecord::arglex::table_ty::token
int token
The corresponding token.
Definition arglex.h:99
srecord::arglex::value_ty
The value_ty struct is used to represent the value of a command line argument.
Definition arglex.h:71
srecord::arglex::value_ty::alv_number
long alv_number
The integer vale of the token.
Definition arglex.h:81
srecord::arglex::value_ty::alv_string
const char * alv_string
The literal string value of the token.
Definition arglex.h:75