Startup Code: Chimara Reference Manual

Startup Code

Startup Code — Parsing startup options

Types and Values

	glkunix_argumentlist_t
	glkunix_startup_t
#define	glkunix_arg_NoValue
#define	glkunix_arg_ValueFollows
#define	glkunix_arg_ValueCanFollow
#define	glkunix_arg_NumberValue
#define	glkunix_arg_End

Includes

#include <libchimara/glk.h>
#include <libchimara/glkstart.h>

Description

This section describes an extension to Glk for parsing command-line startup options. It was written by Andrew Plotkin for the Glk libraries CheapGlk and GlkTerm.

When you compile a Glk program, you may define a function called glkunix_startup_code(), and an array glkunix_arguments[]. These set up various Unix-specific options used by the Glk library. There is a sample “glkstart.c” file included in this package; you should modify it to your needs.

1	extern glkunix_argumentlist_t glkunix_arguments[];

The glkunix_arguments[] array is a list of command-line arguments that your program can accept. The library will sort these out of the command line and pass them on to your code.

Functions

Types and Values

glkunix_argumentlist_t

typedef struct {
    char *name;
    int argtype;
    char *desc;
} glkunix_argumentlist_t;

`glkunix_arg_NoValue`	The argument appears by itself.
`glkunix_arg_ValueFollows`	The argument must be followed by another argument (the value).
`glkunix_arg_ValueCanFollow`	The argument may be followed by a value, optionally. (If the next argument starts with a dash, it is taken to be a new argument, not the value of this one.)
`glkunix_arg_NumberValue`	The argument must be followed by a number, which may be the next argument or part of this one. (That is, either “`-width 20`” or “`-width20`” will be accepted.)
`glkunix_arg_End`	The `glkunix_arguments[]` array must be terminated with an entry containing this value.

To accept arbitrary arguments which lack dashes, specify a name of "" and an argtype of glkunix_arg_ValueFollows.

If you don't care about command-line arguments, you must still define an empty arguments list, as follows:

1
2
3

glkunix_argumentlist_t glkunix_arguments[] = {
    { NULL, glkunix_arg_End, NULL }
};

Here is a more complete sample list:

glkunix_argumentlist_t glkunix_arguments[] = {
    { "", glkunix_arg_ValueFollows, "filename: The game file to load." },
    { "-hum", glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." },
    { "-bom", glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on
      the NUM, if given)." },
    { "-goo", glkunix_arg_NoValue, "-goo: Find goo." },
    { "-wob", glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." },
    { NULL, glkunix_arg_End, NULL }
};

This would match the arguments “thingfile -goo -wob8 -bom -hum song”.

After the library parses the command line, it does various occult rituals of initialization, and then calls glkunix_startup_code().

1	int glkunix_startup_code(glkunix_startup_t *data);

This should return TRUE if everything initializes properly. If it returns FALSE, the library will shut down without ever calling your glk_main() function.

Members

char *`name`;	the option as it would appear on the command line (including the leading dash, if any.)
int `argtype`;	one of the `glkunix_arg_` constants.
char *`desc`;	a description of the argument; this is used when the library is printing a list of options.

glkunix_startup_t

typedef struct {
    int argc;
    char **argv;
} glkunix_startup_t;

The fields are a standard Unix (argc, argv) list, which contain the arguments you requested from the command line. In deference to custom, argv[0] is always the program name.

Members

int `argc`;	The number of arguments in `argv` .
char **`argv`;	Strings representing command line arguments.

glkunix_arg_NoValue

#define glkunix_arg_NoValue (2)

Indicates an argument which occurs by itself, without a value.

glkunix_arg_ValueFollows

#define glkunix_arg_ValueFollows (1)

Indicates an argument which must be followed by a value, as the next argument.

glkunix_arg_ValueCanFollow

#define glkunix_arg_ValueCanFollow (3)

Indicates an argument which may be followed by a value, or may occur by itself.

glkunix_arg_NumberValue

#define glkunix_arg_NumberValue (4)

Indicates an argument which must be followed by a numerical value, either as the next argument or tacked onto the end of this argument.

glkunix_arg_End

#define glkunix_arg_End (0)

Terminates a list of glkunix_argumentlist_t.