SharedMeatAxe
1.0
|
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:
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.
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():
Data Structures | |
struct | MtxApplicationInfo_t |
Application information structure. More... | |
struct | MtxApplication_t |
Application data. More... | |
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... | |
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... | |
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:
ai | Application information. |
argc | Number of command line arguments. |
argv | List of command line arguments. |
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.
app | Pointer to the application object. |
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.
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.
app | Pointer to the application object. |
min_argc | Minimum number of arguments expected. |
max_argc | Maximum number of arguments expected. |
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
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.
app | Pointer to the application object. |
spec | The option name(s), see below. |
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.
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. |
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:
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:
The same remark applies to AppGetIntOption() and AppGetTextOption(). You may also use AppGetCountedOption() to achieve a similar behaviour.
app | Pointer to the application object. |
spec | The option name(s), see below. |
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.
app | Pointer to the application object. |
spec | A list of names for the option, separated by spaces. See AppGetOption(). |
dflt | Default value. |
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.
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.