SharedMeatAxe  1.0
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:

Here is a short example:

MtxApplicationInfo_t AppInfo = { "sample", "MeatAxe sample application",
"\nSYNTAX\n"
" sample [--all]] [--level <level>] <input> <ouput>\n"
};
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);
...
AppFree(app);
return 0;
}

Data Structures

struct  MtxApplicationInfo_t
 Application information structure. More...
 
struct  MtxApplication_t
 Application data. More...
 

Functions

MtxApplication_tAppAlloc (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...
 

Variables

char MtxBinDir [] = MTXBIN
 MeatAxe Binary Directory. More...
 
char MtxLibDir [] = MTXLIB
 MeatAxe Library Directory. More...
 
char MtxBinDir [1024]
 MeatAxe program directory. More...
 
char MtxLibDir [1024]
 MeatAxe library directory (for multiplication tables etc.) More...
 

Function Documentation

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
    aiApplication information.
    argcNumber of command line arguments.
    argvList of command line arguments.
    Returns
    Pointer to the application object, or 0 on error.
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
appPointer to the application object.
Returns
Directory name or 0 on error.
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.
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
appPointer to the application object.
min_argcMinimum number of arguments expected.
max_argcMaximum number of arguments expected.
Returns
Number of arguments, or -1 on error.
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

1 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
appPointer to the application object.
specThe option name(s), see below.
Returns
Number of times the option is present on the command line.
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
appPointer to the application object.
specA list of names for the option, separated by spaces. See AppGetOption().
dfltDefault value.
minMinimum value of the option.
maxMaximum value of the option.
Returns
Value of the option, or dflt if the option is not present.
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:

1 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:

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

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

Parameters
appPointer to the application object.
specThe option name(s), see below.
Returns
1 if the option is present, 0 otherwise.
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
appPointer to the application object.
specA list of names for the option, separated by spaces. See AppGetOption().
dfltDefault value.
Returns
Value of the option, or dflt if the option is not present.

Variable Documentation

char MtxBinDir[] = MTXBIN

MeatAxe Binary Directory.

MeatAxe program directory.

This variable contains the name of the MeatAxe binary directory. 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.

char MtxBinDir[1024]

MeatAxe program directory.

MeatAxe program directory.

This variable contains the name of the MeatAxe binary directory. 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.

char MtxLibDir[] = MTXLIB

MeatAxe Library Directory.

MeatAxe library directory (for multiplication tables etc.)

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
char MtxLibDir[1024]

MeatAxe library directory (for multiplication tables etc.)

MeatAxe library directory (for multiplication tables etc.)

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

SharedMeatAxe 1.0 documentation, generated on Sat Dec 30 2017 12:13:21