Last update: 09-Jun-1999 15:59:59

Where's Your Grammar? Manual

Introduction
Getting and Installing WYG
Running WYG
1. The WYG Configuration File
2. Generated Files
Integrating WYG With Your Code
1. The API
2. Linking the Library
Support
1. To Subscribe
2. To Unsubscribe
License
Author

1. Introduction

Where's Your Grammar (or wyg) is a config-file-parser generator that automates the use of lex, yacc, and GNU getopt_long so that you can worry about more important parts of your code.

2. Getting and Installing WYG

2.1 Distribution

You can pick up the latest version of wyg ftp://ftp.larsshack.org/pub/sw/wyg/wyg.tar.gz. The latest documentation is always available on the WYG web site, http://www.larsshack.org/sw/wyg/.

You can find a list of changes between the current version of WYG and previous versions at http://www.larsshack.org/sw/wyg/ChangeLog.txt.

2.2 Configuration

WYG uses GNU autoconf to figure out a few system-dependent variables (such as the location of your perl interpreter). To configure WYG, cd into the WYG source directory and type:

./configure

configure accepts a variety of parameters. Of interest are --prefix, to specify an installation prefix, and --with-perl to specify which perl interpreter to use.

2.3 Installation

Assuming the configuration step went smoothly, you can now type:

make install

to install wyg and it's accompanying data files. By default, wyg will be installed as /usr/local/bin/wyg and the data fies will go in /usr/local/share/wyg.

3. Running WYG

WYG reads a configuration file describing the configuration variables available to your program and generates a number of output files. The simplest way of running WYG is simply to type:

wyg

This will read the file wyg.conf and generate the output files. If you want to use a different configuration file for input to wyg, you can specify that on the WYG command line:

wyg foo.conf

WYG provides a few options that help automate the generation of the WYG library. To automatically build libwyg.a, type:

wyg --make

This will compile libwyg.a using the rules in Makefile.wyg. If you also want to generate a simple test program to make sure everything is working as expected, you can use the --maketest option:

wyg --maketest

This will build a simple program called wygtest that, when run, will display the value of all your configuration variables. The source code to wygtest can be found in /usr/local/share/wyg/wygtest.c, provided that you installed WYG in its default location.

3.1 The WYG Configuration File

You tell wyg what configuration variables your code will use via the wyg configuration file (usually called wyg.conf). This is a text file that can include blank lines, comments (lines beginning with '#'), or variable descriptions (one per line). Variable descriptions consist of five fields, seperated by whitespace:

Name Letter Type Default Help Text

Name: The name of the configuration variable. This can consist of letters, numbers, and "_". It must start with a letter or with "_".
Letter: The short version of the variable for use on the command line. If this variable has no short equivalent, set this field to "-".
Type: The data type of this variable. This can be int, string, float or bool.
Default: The default value of this variable. This field may not contain any whitespace; thus, strings values are currently limited to single-word defaults. This will probably change soon.
Help Text: Help text for display to the user. This is a free-form field that can contain anything you want (except for embedded newlines).

When you install WYG, the following sample configuration file is installed in /usr/local/share/wyg/wyg.conf.sample:

## wyg 1.0001
## Lars Kellogg-Stedman 
## http://www.larsshack.org/sw/wyg/

## This is a sample wyg configuration file.  For more information,
## please see the accompanying README file.  The format of this file
## is:
##
## name		letter	type	default	help text

server_name	N	string	www	name of server
port		p	int	80	port on server to connect to
maxload		-	float	1.5	shutdown when load is this high

## this boolean variable can be specified in the config file as either
## 'quiet' or '!quiet'.  It can be specified on the command line as
## '-q', '--quiet', or '--noquiet'.
quiet		q	bool	0	turn of copious output

This will build code that could read a configuration file that looks like this:

## this is just a sample
server_name = "www.larsshack.org"
!quiet

Or a command line that looks like this:

your_program_here --server-name=www.larsshack.org --noquiet

3.2 Generated Files

WYG generates the following files:

parse.lex: Input to lex (or flex), the lexical analyzer.
parse.y: Input to yacc (or bison), the parser generator.
parse.c: The C code that drives the parser and handles command line options.
parse.h: Header file for #include'ing into your code. Also provides macros for manipulating variables.
Makefile.wyg: A Makefile that can be used to build the WYG components (via the -f switch to make.

4. Inegrating WYG With Your Code

4.1 The API

There are two functions that you need to use to drive WYG's parsing engine.

init_parser(char *config_filename, int missing_action)

This function tells WYG where to find your configuration file and what to do if it can't find it. If you don't call init_parser(), WYG won't look for a configuration file (it will still process command line options).

missing_action can be one of the following:

PARSE_IGNORE_CONF: Silently ignore a missing configuration file.
PARSE_WARN_CONF: Warn the user if the config file is missing, but continue.
PARSE_ERR_CONF: Exit with an error if the config file is missing.

parse_options(int argc, char *argv[])

This function parses the config file and the command line. You must call parse_options() if you want WYG to do anything. parse_options() returns an integer which is the index into argv[] of the first non-option argument.

There are several macros that you should use to access configuration options. Using these macros will assure that your code will continue to work with future version of WYG, even if the implementation changes.

VI(x), VF(x), VS(x): These macros return, respectively, the integer, floating point, or string value of a configuration variable. X is a variable constant from parse.h. For example, to access the value of server_name from the example wyg configuration file, you would use VS(V_SERVER_NAME).
VT(x): Returns the type of a configuration variable. The type will be one of TYPE_INT, TYPE_FLOAT, TYPE_STRING, or TYPE_BOOL.

There are also several convenience functions available that you may find useful.

show_var_help(char *variable): This displays help text to the user, based on the help text you created in your WYG configuraton file. If variable is null, show_var_help() will display help for all your configuration files. If variable is not null, it will only display the help text for that particular configuration variable.
var_as_string(int variable_index): Returns the value of a variable as a string. var_as_string() takes care of sticky issues like memory allocation so that you don't have to. variable_index is one of the constants defined in parse.h, and will look something like V_SERVER_NAME.

4.2 Linking the Library

When compiling your code, you will have to link it with the WYG library, libwyg.a. Your command line might look something like this:

cc -L. -o myfile myfile.c -lwyg

5. Support

If you have questions about wyg, you can send mail to the wyg-users mailing list (<wyg-users@larsshack.org>). You'll need to subscribe to the list before you can post to it.

There is an archive of the list available at http://www.larsshack.org/lists/wyg-users/.

5.1 To Subscribe

Send an empty message to <wyg-users-request@larsshack.org> with 'subscribe' as the subject.

5.2 To Unsubscribe

Send an empty message to <wyg-users-request@larsshack.org> with 'unsubscribe' as the subject.

6. License

WYG is distributed under the GNU Library General Public License (LGPL).

7. Author

WYG is written by Lars Kellogg-Stedman <lars@larsshack.org>

$Id: manual.html.src,v 1.1 1999/03/22 19:43:02 lars Exp $

This page was generated automatically using wookie, by Lars Kellogg-Stedman <lars@larsshack.org>