MeatAxe: Application Framework

MeatAxe 2.4

- Main Page
- Related Pages
- Modules
- Data Structures

Data Structures | Functions | Variables
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.
int | AppFree (MtxApplication_t *a)
| End an application.
int | AppGetOption (MtxApplication_t *app, const char *spec)
| Check for command line option.
int | AppGetCountedOption (MtxApplication_t *app, const char *spec)
| Count repeatable command line option.
const char * | AppGetTextOption (MtxApplication_t *app, const char *spec, const char *dflt)
| Check for command line option.
int | AppGetIntOption (MtxApplication_t *app, const char *spec, int dflt, int min, int max)
| Check for integer-valued option.
int | AppGetArguments (MtxApplication_t *app, int min_argc, int max_argc)
| Get command line arguments.
const char * | AppCreateTempDir (MtxApplication_t *app)
| Create a temporary directory.
int | MtxFormatMessage (char *buf, int bufsize, const char *msg, va_list al)
| Format a message.
int | MtxPrintMessage (FILE *f, const char *fmt,...)
| Print a message.
## Variables
char | MtxBinDir [250] = MTXBIN
| MeatAxe Binary Directory.
char | MtxLibDir [250] = MTXLIB
| MeatAxe Library Directory.
int | MtxMessageLevel = 0
| Message level.
int | MtxErrNo = 0
| Last error code.

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

    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.

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.

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:

  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.

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.

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.

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.

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.

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).

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

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.

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

int MtxMessageLevel = 0

Message level.

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