#include "options.h"

This page has information from files options.h and options.c.

Public Routines
Public Definitions
Introduction

Public Routines in File options.c

Index

	flag_id_to_str	option_dependencies_state	set_flag
assign_parm	flag_parm_dep_default	option_updates	str_to_flag_id
assign_stringparm	flag_parm_dependency	over_parm_limit	str_to_parm_id
at_parm_limit	flag_stringparm_dep_default	p_options	str_to_stringparm_id
clear_flag	flag_stringparm_dependency	p_options_mem	stringparm
disable_option_dependencies	fprint_options	parm	stringparm1
enable_option_dependencies	fprint_options_mem	parm_default	stringparm1_default
flag_default	init_flag	parm_flag_dependency	stringparm_id_to_str
flag_flag_dep_default	init_parm	parm_id_to_str	update_flag
flag_flag_dependency	init_stringparm	parm_parm_dependency

Details


int flag(int flag_id);

This Boolean routine returns the value of a flag. If the Flag index is out of range, bad things can happen.

void assign_parm(int id, int val, BOOL echo);

This routine assigns a value to a parm. The parm is identified by its integer ID (which is available from str_to_parm_id()). If the ID is not valid, or if the value is out of range, a fatal error occurs.

void assign_stringparm(int id, char *val, BOOL echo);

This routine assigns a value to a stringparm. The stringparm is identified by its integer ID (which is available from str_to_stringparm_id()). If the ID is not valid, or if the value is out of range, a fatal error occurs.

BOOL at_parm_limit(int value, int parm_id);

This assumes that -1 represents infinity.

void clear_flag(int id, BOOL echo);

This routine clears a flag. The flag is identified by its integer ID (which is available from str_to_flag_id()). If the ID is not valid, a fatal error occurs.

void disable_option_dependencies(void);

void enable_option_dependencies(void);

int flag_default(int flag_id);

void flag_flag_dep_default(int id, BOOL val, int dep_id);

This routine declares that a flag depends on another flag. If flag "id" gets value "val", then flag "dep_id" is automatically given its default value.

void flag_flag_dependency(int id, BOOL val, int dep_id, BOOL dep_val);

This routine declares that a flag depends on another flag. If flag "id" gets value "val", then flag "dep_id" is automatically given value "dep_val".

char *flag_id_to_str(int id);

Given a flag ID, return the corresponding name of the flag.

void flag_parm_dep_default(int id, BOOL val, int dep_id);

This routine declares that a parm depends on a flag. If flag "id" gets value "val", then parm "dep_id" is automatically given its default value.

void flag_parm_dependency(int id, BOOL val, int dep_id, int dep_val);

This routine declares that a parm depends on a flag. If flag "id" gets value "val", then parm "dep_id" is automatically given value "dep_val".

void flag_stringparm_dep_default(int id, BOOL val, int dep_id);

This routine declares that a stringparm depends on a flag. If flag "id" gets value "val", then stringparm "dep_id" is automatically given its default value.

void flag_stringparm_dependency(int id, BOOL val, int dep_id, char *dep_val);

This routine declares that a stringparm depends on a flag. If flag "id" gets value "val", then stringparm "dep_id" is automatically given value "dep_val".

void fprint_options(FILE *fp);

This routine prints (to FILE *fp) the current values of all of the the options (flags, parms, and stringparms).

void fprint_options_mem(FILE *fp, BOOL heading);

This routine prints (to FILE *fp) memory usage statistics for data types associated with the options package. The Boolean argument heading tells whether to print a heading on the table.

int init_flag(char *name,
	      BOOL default_value);

Initialize a flag (boolean-valued option). You give it a name and a default value, and an integer id is returned. Flags are typically changed by user commands which are parsed by read_commands(). The value of a flag is checked with flag(ID).

int init_parm(char *name,
	      int default_value,
	      int min_value,
	      int max_value);

Initialize a parm (integer-valued option). You give it a name, a default value, and min and max values. An integer id is returned. Parms are typically changed by user commands which are parsed by read_commands(). The value of a parm is checked with parm(ID).

int init_stringparm(char *name,
		    int n,
		    ...);

Initialize a stringparm (string-valued option). You give it a name, a number n of possible values, and n strings which are the possible values. An integer id is returned The first string given is the default value.

Stringparms are typically changed by user commands which are parsed by read_commands(). The value of a stringparm is checked with the Boolean routine stringparm(ID, string).

BOOL option_dependencies_state(void);

int option_updates(void);

How many times have Flags, Parms, or Stringparms been updated?

BOOL over_parm_limit(int value, int parm_id);

This assumes that -1 represents infinity.

void p_options(void);

This routine prints (to stdout) the current values of the the options (flags, parms, and stringparms).

void p_options_mem();

This routine prints (to stdout) memory usage statistics for data types associated with the options package.

int parm(int parm_id);

This integer routine returns the value of a parameter. If the parm index is out of range, bad things can happen.

int parm_default(int parm_id);

void parm_flag_dependency(int id, int dep_id, int dep_val);

This routine declares that a flag depends on a parm. If parm "id" gets changed, then flag "dep_id" is automatically given value "dep_val".

char *parm_id_to_str(int id);

Given a parm ID, return the corresponding name of the parm.

void parm_parm_dependency(int id, int dep_id, int dep_val, BOOL multiply);

This routine declares that a parm depends on a parm. If (multiply == TRUE), then dep_val is a multiplier instead of a value.

void set_flag(int id, BOOL echo);

This routine sets a flag. The flag is identified by its integer ID (which is available from str_to_flag_id()). If the ID is not valid, a fatal error occurs.

int str_to_flag_id(char *name);

This routine converts the string name of a flag to its integer ID. If the string name is not valid, -1 is returned.

int str_to_parm_id(char *name);

This routine converts the string name of a parm to its integer ID. If the string name is not valid, -1 is returned.

int str_to_stringparm_id(char *name);

This routine converts the string name of a stringparm to its integer ID. If the string name is not valid, -1 is returned.

BOOL stringparm(int id, char *s);

This routine checks if the current value of a stringparm matches the given string. The ID must be valid.

char *stringparm1(int id);

This routine returns the current value of a stringparm. The ID must be valid.

char *stringparm1_default(int id);

char *stringparm_id_to_str(int id);

Given a stringparm ID, return the corresponding name of the stringparm.

void update_flag(FILE *fout, int id, BOOL val, BOOL echo);

This performs the role of set_flag() and clear_flag(). In addition, an output file is given for dependency messages.

Public Definitions in File options.h

#define MAX_FLAGS                100
#define MAX_PARMS                100
#define MAX_STRINGPARMS          100

Introduction

There are 3 types of option:

Flags: Boolean
Parms: Integer
Stringparm: String

To introduce a new option, choose an integer ID that is unique for the type of option, and call the appropriate initialization routine. Then you can change the value of the option and check its value as you like.

The routine read_commands() (in the "commands" package) will parse the user's set, clear, and assign commands, making the appropriate changes to the values of the options.

In most cases, the applications programmer will be using the following routines.