Provides program option support via the command-line or an options file. More...

#include <jwsc/config.h>
#include <stdlib.h>
#include <stdio.h>
#include "jwsc/base/error.h"

Include dependency graph for option.h:

Data Structures
struct	Option_with_arg
	Data structure for an option that takes an argument. More...
struct	Option_no_arg
	Data structure for an option that does not take an argument. More...
Typedefs
typedef const char *	Option_string
	String representing the long name of an option.
typedef char	Option_flag
	Character representing the short name (flag) of an option.
typedef const char *	Option_desc
	String containing a brief option description.
typedef const char *	Option_arg
	Argument to an option.
typedef Error (	Option_func_with_arg )(Option_arg)
	Callback function for processing an option with an argument.
typedef Error (	Option_func_no_arg )(void)
	Callback function for processing an option with no argument.
Functions
void	init_option_with_arg (Option_with_arg *opt, Option_string str, Option_flag flag, Option_desc desc, Option_func_with_arg func)
	Initializes an Option_with_arg.
void	init_option_no_arg (Option_no_arg *opt, Option_string str, Option_flag flag, Option_desc desc, Option_func_no_arg func)
	Initializes an Option_no_arg.
Error *	process_option_with_arg (int argc, const char *argv, int argi, Option_with_arg *opt)
	Processes an Option_with_arg from the command-line arguments.
Error *	process_option_no_arg (int argc, const char *argv, int argi, Option_no_arg *opt)
	Processes an Option_no_arg from the command-line arguments.
Error *	process_options (int argc, const char *argv, int argi, int num_opts_no_arg, Option_no_arg opts_no_arg, int num_opts_with_arg, Option_with_arg opts_with_arg)
	Processes a set of Option_with_arg and Option_no_arg from the command-line arguments.
Error *	process_options_from_file (const char fname, int num_opts_no_arg, Option_no_arg opts_no_arg, int num_opts_with_arg, Option_with_arg *opts_with_arg)
	Processes a set of Option_with_arg and Option_no_arg from an option file.
void	print_option_with_arg (FILE fp, int opt_width, Option_with_arg opt)
	Prints an Option_with_arg to a file stream.
void	print_option_no_arg (FILE fp, int opt_width, Option_no_arg opt)
	Prints an Option_no_arg to a file stream.
void	print_options (FILE fp, int opt_width, int num_opts_no_arg, Option_no_arg opts_no_arg, int num_opts_with_arg, Option_with_arg *opts_with_arg)
	Prints options to a file stream.

Detailed Description

Provides program option support via the command-line or an options file.

Author:: Joseph Schlecht

License:: Creative Commons BY-NC-SA 3.0

A program can use this option support by defining a set of Option_with_arg and Option_no_arg structures and processing the command-line arguments or an option file with them.

The options can be represented by a long Option_string and/or a single character Option_flag. Both can take an argument by defining an Option_with_arg. If no argument is called for, use Option_no_arg.

Definition in file option.h.

Typedef Documentation

typedef const char* Option_string

String representing the long name of an option.

Definition at line 74 of file option.h.

typedef char Option_flag

Character representing the short name (flag) of an option.

Definition at line 77 of file option.h.

typedef const char* Option_desc

String containing a brief option description.

Definition at line 80 of file option.h.

typedef const char* Option_arg

Argument to an option.

Definition at line 83 of file option.h.

typedef Error*(* Option_func_with_arg)(Option_arg)

Callback function for processing an option with an argument.

Definition at line 86 of file option.h.

typedef Error*(* Option_func_no_arg)(void)

Callback function for processing an option with no argument.

Definition at line 89 of file option.h.

Function Documentation

void init_option_with_arg	(	Option_with_arg *	opt,
		Option_string	str,
		Option_flag	flag,
		Option_desc	desc,
		Option_func_with_arg	func
	)

Initializes an Option_with_arg.

One or both of name or flag must be non-NULL.

Parameters:

opt	Option_with_arg to initialize.
str	Long name of the option. If not used, set to NULL.
flag	Character flag for the option. If no used, set to NULL.
desc	String containing a short description of the option. If not used, set to NULL.
func	Function for processing the option, with an argument.

Definition at line 230 of file option.c.

void init_option_no_arg	(	Option_no_arg *	opt,
		Option_string	str,
		Option_flag	flag,
		Option_desc	desc,
		Option_func_no_arg	func
	)

Initializes an Option_no_arg.

One or both of name or flag must be non-NULL.

Parameters:

opt	Option_no_arg to initialize.
str	Long name of the option. If not used, set to NULL.
flag	Character flag for the option. If no used, set to NULL.
desc	String containing a short description of the option. If not used, set to NULL.
func	Function for processing the option, with no argument.

Definition at line 260 of file option.c.

Error* process_option_with_arg	(	int	argc,
		const char **	argv,
		int *	argi,
		Option_with_arg *	opt
	)

Processes an Option_with_arg from the command-line arguments.

Searches argv for a matching Option_with_arg::string or Option_with_arg::flag. If found, Option_with_arg::func is called with the option's argument; otherwise, nothing is done.

If no argument was supplied to the option, NULL is passed to Option_with_arg::func.

Parameters:

argc	Number of command-line arguments.
argv	The command-line arguments.
argi	Index of the argument in argv.
opt	Option to look for and process in argv.

Returns:: On success, NULL is returned and *em *argi is its index in argv. If Option_with_arg::func returned an Error, it is returned and *argi == argc.

Note:: Only the first occurance of the option in argv is processed.

Definition at line 299 of file option.c.

Error* process_option_no_arg	(	int	argc,
		const char **	argv,
		int *	argi,
		Option_no_arg *	opt
	)

Processes an Option_no_arg from the command-line arguments.

Searches argv for a matching Option_no_arg::string or Option_no_arg::flag. If found, Option_no_arg::func is called; otherwise, nothing is done.

Parameters:

argc	Number of command-line arguments.
argv	The command-line arguments.
argi	Index of the argument in argv.
opt	Option to look for and process in argv.

Returns:: On success, NULL is returned and *em *argi is its index in argv. If Option_no_arg::func returned an Error, it is returned and *argi == argc.

Note:: Only the first occurance of the option in argv is processed.

Definition at line 362 of file option.c.

Error* process_options	(	int	argc,
		const char **	argv,
		int *	argi,
		int	num_opts_no_arg,
		Option_no_arg *	opts_no_arg,
		int	num_opts_with_arg,
		Option_with_arg *	opts_with_arg
	)

Processes a set of Option_with_arg and Option_no_arg from the command-line arguments.

All options preceding non-options in argv are matched to options in either opts_with_arg or opts_no_arg and processed accordingly. An Error is returned if there is an option in argv that cannot be matched.

When the function encounters the first argument in argv that is not an option, processing stops.

For opts_with arg, if no argument was supplied to an option, NULL is passed to its Option_with_arg::func.

Parameters:

argc	Number of command-line arguments.
argv	The command-line arguments.
argi	Result parameter. Index of the first non-option argument in argv.
num_opts_no_arg	Number of elements in opts_no_arg.
opts_no_arg	Options not taking an argument to look for and process in argv.
num_opts_with_arg	Number of elements in opts_with_arg.
opts_with_arg	Options taking an argument to look for and process in argv.

Returns:

On success, NULL is returned and *argi is set to the index of the first non-option argument in argv, or argc if all arguments were options. If an Option_no_arg::func or Option_with_arg::func returned an Error, processing is immediately halted and the Error is returned. If an option in argv cannot be matched, an Error is returned. When an Error is returned, *argi is the index of the argument in argv that caused the error.

ERROR_INV_ARG An option is in argv that cannot be matched.

Definition at line 430 of file option.c.

Error* process_options_from_file	(	const char *	fname,
		int	num_opts_no_arg,
		Option_no_arg *	opts_no_arg,
		int	num_opts_with_arg,
		Option_with_arg *	opts_with_arg
	)

Processes a set of Option_with_arg and Option_no_arg from an option file.

All options in fname are matched to options in either opts_with_arg or opts_no_arg and processed accordingly. An Error is returned if there is an option in fname that cannot be matched.

For opts_with arg, if no argument was supplied to an option, NULL is passed to its Option_with_arg::func.

The format of the options file is as follows

   # comment
   option-1=arg1
   option-2

   # comment 
   option-3=arg3

The comments must begin the line with '#' and run to the end of the line.

Parameters:

fname	Name of the file containing the options to process.
num_opts_no_arg	Number of elements in opts_no_arg.
opts_no_arg	Options not taking an argument to look for and process in fname.
num_opts_with_arg	Number of elements in opts_with_arg.
opts_with_arg	Options taking an argument to look for and process in fname.

Returns:

On success, NULL is returned. If an Option_no_arg::func or Option_with_arg::func returned an Error, processing is immediately halted and the Error is returned. If an option in fname cannot be matched, an Error is returned.

ERROR_INV_ARG An option is in fname that cannot be matched.
ERROR_IO The file fname could not be read.

Note:: If the file is not formatted properly, the Error will say an invalid option was specified.; The format for reading assumes a maximum 255 line (option) length.

Definition at line 584 of file option.c.

void print_option_with_arg	(	FILE *	fp,
		int	opt_width,
		Option_with_arg *	opt
	)

Prints an Option_with_arg to a file stream.

The format for printing is as follows

   -O, --option-string=ARG  Option description.

The Option_with_arg::desc may wrap to multiple lines, but will be aligned properly.

Parameters:

fp	File stream to print formatted option to.
opt_width	Length of the option Option_with_arg::string and Option_with_arg::flag field. If <= 0 or <= the length of the option fields, it is caluclated from opt->string.
opt	Option to print.

Note:: The format for printing assumes an 80 character line width.

Warning:: The maximum opt_width is 60 and is asserted as such.

Definition at line 696 of file option.c.

void print_option_no_arg	(	FILE *	fp,
		int	opt_width,
		Option_no_arg *	opt
	)

Prints an Option_no_arg to a file stream.

The format for printing is as follows

   -O, --option-string  Option description.

The Option_no_arg::desc may wrap to multiple lines, but will be aligned properly.

Parameters:

fp	File stream to print formatted option to.
opt_width	Length of the option Option_no_arg::string and Option_no_arg::flag field. If <= 0 or <= the length of the option fields, it is caluclated from opt->string.
opt	Option to print.

Note:: The format for printing assumes an 80 character line width.

Warning:: The maximum opt_string_width is 60 and is asserted as such.

Definition at line 860 of file option.c.

void print_options	(	FILE *	fp,
		int	opt_width,
		int	num_opts_no_arg,
		Option_no_arg *	opts_no_arg,
		int	num_opts_with_arg,
		Option_with_arg *	opts_with_arg
	)

Prints options to a file stream.

The Option_no_arg are printed first, then the Option_with_arg.

Parameters:

fp	File stream to print formatted options to.
opt_width	Length of the Option_string and Option_flag field. If <= 0 or <= the lenght of any of the option fields, the length is caluclated from the Option_string.
num_opts_no_arg	Number of elements in opts_no_arg.
opts_no_arg	Options not taking an argument to print.
num_opts_with_arg	Number of elements in opts_with_arg.
opts_with_arg	Options taking an argument to print.

Definition at line 1007 of file option.c.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation