Application Framework

Detailed Description

The MeatAxe library provides a minimal framework for applications.

All MeatAxe applications should use this framework to achieve a consistent behaviour. The functions described above enable an application to process command line options and arguments. They also implement a rudimentary on-line help and automatic processing of some common options like "-V". Typically, a MeatAxe application's main() function should perform the following steps:

• Create an application object using AppAlloc().
• Process all command line options.
• Process simple options without arguments.
• Process options that take an argument. Options taking an integer argument can be handeled with |AppGetIntOption()|. Other option arguments must be processed by the application.
• Call |AppGetArgs()| to process the remaining command line arguments.
• Do whatever the application is supposed to do.

Here is a short example:

MtxApplicationInfo_t AppInfo = { "sample", "MeatAxe sample application",
    "\nSYNTAX\n"
    "    sample [--all]] [--level <level>] <input> <ouput>\n"
};
MtxApplication_t *App;
int DoAll, Level;
char *Input, *Output;
 
int main(int argc, char *argv[])
{
    App = AppAlloc(&AppInfo,argc,argv);
    DoAll = AppGetOption(App,"-a --all");
    Level = AppGetIntOption(App,"-l --level",42,0,100);
    AppGetArguments(App,2,2);
    Input = App->ArgV[0];
    Output = App->ArgV[1];
    DoIt();
    AppFree(App);
    return 0;
}

This sample application expects two arguments and recognizes two options. One option ("-l") has an additional integer argument, level. The value of level must be between 0 and 100. If not specified by the user, a default value of 42 is used.

Temporary Directories

If an application needs a temporary directory to store interdediate files, it can use AppCreateTempDir(). This function creates a new directory and returns its name. The directory will be removed when the application object is destroyed, i.e., in |AppFree()|. Note that the application must not leave any file in the temporary directory. Otherwise, a run-time error is generated when AppFree() tries to remove the directory. The following code example shows how to use AppCreateTempDir():

int main(int argc, char **argv)
{
    MtxApplication_t *app = AppAlloc(argc,argv,&appinfo);
    const char *tmpdir = AppCreateTempDir(app);
    ...
 
    sprintf(file_name,"%s/%s",tempdir,"test");
    MatSave(mat,fn);
    ...
    SysRemoveFile(fn);
 
    AppFree(app);
    return 0;
}

Data Structures
struct	msg_struct
	Internal data structure.

Functions
MtxApplication_t *	AppAlloc (MtxApplicationInfo_t const *ai, int argc, const char **argv)
	Initialize the application. More...
int	AppFree (MtxApplication_t *a)
	End an application. More...
int	AppGetOption (MtxApplication_t *app, const char *spec)
	Check for command line option. More...
int	AppGetCountedOption (MtxApplication_t *app, const char *spec)
	Count repeatable command line option. More...
const char *	AppGetTextOption (MtxApplication_t *app, const char *spec, const char *dflt)
	Check for command line option. More...
int	AppGetIntOption (MtxApplication_t *app, const char *spec, int dflt, int min, int max)
	Check for integer-valued option. More...
int	AppGetArguments (MtxApplication_t *app, int min_argc, int max_argc)
	Get command line arguments. More...
const char *	AppCreateTempDir (MtxApplication_t *app)
	Create a temporary directory. More...
int	MtxFormatMessage (char *buf, int bufsize, const char *msg, va_list al)
	Format a message. More...
int	MtxPrintMessage (FILE *f, const char *fmt,...)
	Print a message. More...

Variables
char	MtxBinDir [250] = MTXBIN
	MeatAxe Binary Directory. More...
char	MtxLibDir [250] = MTXLIB
	MeatAxe Library Directory. More...
int	MtxMessageLevel = 0
	Message level. More...
int	MtxErrNo = 0
	Last error code.

Function Documentation

AppAlloc()

MtxApplication_t* AppAlloc	(	MtxApplicationInfo_t const *	ai,
		int	argc,
		const char **	argv
	)

Initialize the application.

This function initializes a MeatAxe application. It should be called by the application's |main()| function before any other MeatAxe library function is used. |argc| and |argv| should be the same values that have been passed to |main()|. |ai|, if not NULL, must point to an initialized application information structure.

AppAlloc() performs the following actions:

• It evaluates the MTXLIB and MTXBIN environment variables. If set, these variables overwrite the default directories.
• It calls MtxInitLibrary() to initialize the MeatAxe library.
• It parses the command line and initializes internal data structures for use with AppGetOption() and related functions.
• Common options such as "-V" (see Standard Command Line Options) are immediately evaluated. These options are not visible to the application.

  Parameters

  ai	Application information.
  argc	Number of command line arguments.
  argv	List of command line arguments.

  Returns

  Pointer to the application object, or 0 on error.

AppCreateTempDir()

const char* AppCreateTempDir

(

MtxApplication_t *

app

)

Create a temporary directory.

This function creates a new, empty directory for use by the application. The location of this directory is system dependent. When the application objects is destroyed, the temporary directory will be removed automatically, if there are no files left in it. After successfull creation of the directory, the function returns the directory name. The return value is a pointer to an internal buffer, which must not be modified by the application. If the directory cannot be created for some reason, the return value is 0.

If the application calls AppCreateTempDir() more than once, only the first call actually creates a directory. The later calls just return the name of the directory already created.

Parameters

app	Pointer to the application object.

Returns

Directory name or 0 on error.

AppFree()

int AppFree

(

MtxApplication_t *

a

)

End an application.

This function terminates a MeatAxe application. It should be called immediately before the |main()| function exits. |AppFree()| removes any temporary directory created with |AppCreateTempDir()|. If the directory is not empty at this point, a run-time error will result.

Returns

0 on success, -1 on error.

AppGetArguments()

int AppGetArguments	(	MtxApplication_t *	app,
		int	min_argc,
		int	max_argc
	)

Get command line arguments.

This function must be called after all command line options have been processed (see, for example, AppGetOption()). The remaining words on the command line are treated as non-optional arguments, the global variable ArgV is set to the first argument and the number of arguments is stored in |ArgC. An error message is generated, if there are unprocessed options on the command line, or if the number of arguments is outside the range specified by min_argc and max_argc.

Parameters

app	Pointer to the application object.
min_argc	Minimum number of arguments expected.
max_argc	Maximum number of arguments expected.

Returns

Number of arguments, or -1 on error.

AppGetCountedOption()

int AppGetCountedOption	(	MtxApplication_t *	app,
		const char *	spec
	)

Count repeatable command line option.

This function counts how often a specific option is present on the command line. For example, if the command line is

sample -a -a -aa input output

then MtxGetCountedOption("-a") returns 4. As with all command line processing functions, you must call AppAlloc() before using this function.

Note: This function is included for compatibility reasons only. New applications should not use it.

Parameters

app	Pointer to the application object.
spec	The option name(s), see below.

Returns

Number of times the option is present on the command line.

AppGetIntOption()

int AppGetIntOption	(	MtxApplication_t *	app,
		const char *	spec,
		int	dflt,
		int	min,
		int	max
	)

Check for integer-valued option.

This function checks if an option is present on the command line. The option is expected to have an integer value, and the value is returned. On the command line, the value must be separated from the option by one or more spaces. If the option is present on the command line but has no value, an appropriate error message is generated. If the option is not present on the command line, the function returns dflt as a default value.

If the value on the command line is not within the range defined by min and max, an error message is generated. However, if min is greater than max, no range check is performed.

Parameters

app	Pointer to the application object.
spec	A list of names for the option, separated by spaces. See AppGetOption().
dflt	Default value.
min	Minimum value of the option.
max	Maximum value of the option.

Returns

Value of the option, or dflt if the option is not present.

AppGetOption()

int AppGetOption	(	MtxApplication_t *	app,
		const char *	spec
	)

Check for command line option.

This function checks if an option is present on the command line. Before using AppGetOption() you must call AppAlloc() to initialize the command line parser. Only simple options, i.e., options without an argument can be recognized by this function. The return value is 1, if the option is present and 0 otherwise.

The argument spec contains one or more names of the requested options. If there is more than one name, names must be separated by spaces. All names are considered equivalent, the user may use any of the names. The leading "-" must always be included in the name. Typically an option has only one or two names, as in the following example:

int PrintAll = AppGetOption(App,"-a --all");

Here, the user may specify either '-a' or '–all' on the command line.

Each call of AppGetOption() consumes at most one command line option. If the user specifies the same option multiple times, only the first option is recognized. Since this is usually not intended, an appropriate error message will be generated when the application calls AppGetArguments(). If an option can be repeated on the command line the application must make sure that all options are processed:

while (AppGetOption(App,"-a --all"))
{ ... }

The same remark applies to AppGetIntOption() and AppGetTextOption(). You may also use AppGetCountedOption() to achieve a similar behaviour.

Parameters

app	Pointer to the application object.
spec	The option name(s), see below.

Returns

1 if the option is present, 0 otherwise.

AppGetTextOption()

const char* AppGetTextOption	(	MtxApplication_t *	app,
		const char *	spec,
		const char *	dflt
	)

Check for command line option.

This function checks if an option is present on the command line. The option is expected to have a text value, and a pointer to the value is returned. On the command line, the value must be separated from the option by one or more spaces. If the option is present on the command line but has no value, an appropriate error message is generated. If the option is not present on the command line, the function returns dflt as a default value.

Parameters

app	Pointer to the application object.
spec	A list of names for the option, separated by spaces. See AppGetOption().
dflt	Default value.

Returns

Value of the option, or dflt if the option is not present.

MtxFormatMessage()

int MtxFormatMessage	(	char *	buf,
		int	bufsize,
		const char *	msg,
		va_list	al
	)

Format a message.

This function formats a message using a |printf|-like syntax. Only the follwing four format codes may be used within |msg|:

• %d prints a signed decimal integer. The corresponding argument must be of type int.
• %s prints a string. The corresponding argument must be a pointer to a null-terminated string.
• %E takes an int argument, which must be one the MeatAxe error codes (MTX_ERR_xxxx) defined in "meataxe.h". It prints a description of the error.
• %S prints the system error name corresponding to the current value of errno.

Parameters

buf	Buffer for the message.
bufsize	Size of buffer.
msg	The message text.
al	Optional arguments for the message (see description).

MtxPrintMessage()

int MtxPrintMessage	(	FILE *	f,
		const char *	fmt,
			...
	)

Print a message.

This function writes a message to a file using a printf()-like syntax. See MtxFormatMessage() for details.

Parameters

f	File to write to.
fmt	Message to write
...	Optional arguments for the message.

Variable Documentation

MtxBinDir

char MtxBinDir[250] = MTXBIN

MeatAxe Binary Directory.

This variable contains the name of the MeatAxe binary directory. This directory is used, for example, to find the maketab program for automatic arithmetic table generation. The value of MtxBinDir can be set on the command line with the "-B" option. Otherwise, the value of the environment variable MTXBIN is used. If neither "-B" nor MTXBIN are defined, the default directory, which was selected when building the MeatAxe, is used.

MtxLibDir

char MtxLibDir[250] = MTXLIB

MeatAxe Library Directory.

This variable contains the name of the MeatAxe library directory. Arithmetic table files are searched in this directory. The value of MtxLibDir can be set on the command line with the "-L" option. Otherwise, the value of the environment variable MTXLIB is used. If neither "-L" nor MTXLIB are defined, the default directory, which was selected when building the MeatAxe, is used.

See also

MtxBinDir

MtxMessageLevel

int MtxMessageLevel = 0

Message level.

This value determines which messages generated by MSG0()...MSG4() are actually output and which are suppressed.