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

#include <jwsc/config.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <assert.h>
#include "jwsc/base/option.h"
#include "jwsc/base/error.h"
#include "jwsc/base/file_io.h"

Include dependency graph for option.c:

Go to the source code of this file.

Functions
static int	is_option (const char *arg)
	Returns whether or not arg is an option.
static int	is_option_string (const char *arg, Option_string str)
	Returns whether or not arg contains the Option_string str.
static int	is_cmd_line_option_string (const char *arg, Option_string str)
	Returns whether or not arg contains the Option_string str as a command-line option.
static int	is_option_flag (const char *arg, Option_flag flag)
	Returns whether or not arg contains the Option_flag flag.
static Option_arg	get_option_string_arg (const char *str)
	Gets the argument for the an option.
static Option_arg	get_option_flag_arg (int argc, const char **argv, int index)
	Gets the argument for flag in argv at index.
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.
static void	terminate_option_string (char *str)
	Terminates a string containing an option.
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.c.

Function Documentation

static int is_option ( const char * arg ) [static]

Returns whether or not arg is an option.

Will return true if

   arg == '--[1-9a-zA-Z].*' || '-[1-9a-zA-Z]'

Note:: Uses ASCII codes to decide.

Definition at line 83 of file option.c.

static int is_option_string	(	const char *	arg,
		Option_string	str
	)		`[static]`

Returns whether or not arg contains the Option_string str.

Definition at line 112 of file option.c.

static int is_cmd_line_option_string	(	const char *	arg,
		Option_string	str
	)		`[static]`

Returns whether or not arg contains the Option_string str as a command-line option.

Definition at line 141 of file option.c.

static int is_option_flag	(	const char *	arg,
		Option_flag	flag
	)		`[static]`

Returns whether or not arg contains the Option_flag flag.

Definition at line 159 of file option.c.

static Option_arg get_option_string_arg ( const char * str ) [static]

Gets the argument for the an option.

Returns:: If the argument is not in str, NULL is returned; otherwise a pointer to the argument in str.

Definition at line 176 of file option.c.

static Option_arg get_option_flag_arg	(	int	argc,
		const char **	argv,
		int	index
	)		`[static]`

Gets the argument for flag in argv at index.

Returns:: If the the argument index is outside of argv, NULL is returned; otherwise a pointer to the option argument.

Definition at line 204 of file option.c.

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.

static void terminate_option_string ( char * str ) [static]

Terminates a string containing an option.

The first space character encountered in str is set to '\0'.

Note:: Assumes str already is terminated in its very last character with '\0'.

Definition at line 527 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.

Functions

Detailed Description

Function Documentation