The Styx Handbook: The Handyman's Guide to Styx

Next Previous Contents

## 6. The Handyman's Guide to Styx

As the title of the chapter suggests, more technical details of how to apply Styx within a concrete project are about to follow in the sequel. We describe inhere the usual steps we take when creating a new project and introduce some of the library material needed.

## 6.1 Setting up a Styx project

Though one can use Styx in whatever way he or she likes, the following notes might be considered helpful. Styx was originally designed to be applied within a highly productive environment, which is only partially released with the Styx sources itself. To interoperate with it, Styx provides some hooks, that may be usefull in other project setups, too.

This left-over is mainly visible in the command line syntax and the way the command line interoperates with the shell environment.

To structure our projects in the file system, we choose to separate original and generated sources from the generated binaries. Names of generated files were automatically derived by changing the extention.

Now, to save us keystrokes, most of the command line arguments, especially the directory pathes, can be supplied by the shell environment, too.

Please refer to the manual pages of the respective programs for more details.

## 6.2 Writing and Testing a Grammar

Like everyone, the author has his own a prefered method of getting a Styx project up. We describe his personal way here while introducing the applied tools and intermediate products.

First, to prevent starting from scratch, we typically "clone" a likely project to have all the initial and one-time-work stuff done. You might want to use one of the examples included in the distribution for this purpose.

Next, we start coding the actual source of the grammar, the '.sty' file. The author preferes doing this iterating the steps described following thereby approximating and finally reaching the intended product, while other (my colleque for instance) might prefere a one pass approach.

Having coded a '.sty' source file, it is time to apply the scanner/parser generator onto it, which is the program named ' styx'. It may or may not come up with diagnostics, we fix them and retry until the generation finally succeeds. At this stage, the use of the '-diagnose' option might help to get enough information to analyse why the specified grammar is not LALR(1). To do so, you should really know a bit about this sort of parser generator, please refer to the BIBLIO("Dragon Book") or the BIBLIO("yacc documentation") if not.

Without any options, all 'styx' creates is the '.abs' file, which contains the generated depth grammar. One might want to validate that the intended abstract grammar has in fact been found by 'styx' and fine-tune it somewhat, if necessary.

Controled by options, the 'styx' program allows to generate different goals and for immediate testing, one might like to choose the '-makeIMG' option, to generate binary table images (a '.lim' and an optional '.pim file), which can be read by two test utilities.

To test the grammar, it needs an example source (technically speaking, a "word" of the grammar) stored in a file. Having this, one can apply the ' lim_test' program to validate the scanner table and the ' pim_test' program for the parser. Both programs use the environment variable BINSTYX which defaults to the enviroment variable PATH, so you want to make sure that the generated images are placed properly.

At this point we have a properly specified grammar of the language and know at least that it will parse our example word yielding an intended abstract grammar.

Since we typically want to continue compiling or interpreting this word, we can finalize the work so far by applying 'styx' with the '-makeINT' and the '-makeC' option to create the C interface of the abstract grammar and to get C sources of the scanner/parser tables that can be compiled into the intended product.

Now comes a little trick. Since the authors of Styx did not write header files for a decade but left this job to a silly program named ' ctoh', you have to apply it onto the generated C sources to get the necessary '.h' files, too. Please refer to the man page of this usefull program (it saves about 1/3 of lines to code) for the parameters.

## 6.3 Using the generated interface

Having parsed a source (which is explained in the next section), we have the root of the derivation tree. To further process the source, one typically has to traverse this tree recursively. Styx provides two complete different means to do so, the first viewing the derivation tree as a term of a typed term algebra as defined in the related '.abs' file, while the second is the "meta" view of the derivation tree, granting grammar independend access. Depending on the particular task, a compiler writer might prefer one or the other view during the process of dealing with the derivation tree.

### The interface derived from the specific grammar

It contains "destructors" for each token, nonterminal and "abstract" production.

### The meta interface

The term interface provides the data type PT_Term along with basic construction and access methods ( positional info etc. ) as well as term iterators.

Iteration of term lists in an abstract grammar will be done with the generic language support which defines the data types GLS_List and GLS_Tok.

### Library data types

- Names of grammar symbols and token values within the derivation tree are represented as symbols.
- The (low level) parse interface gives access to the grammar specification ( tokens, nonterminals and productions etc. )
- Finite maps are an important means for the creation of specific term views. An usual application would be the mapping of identifiers to their corresponding definitions.
- Dynamic arrays and lists

  Refer towards semantics, compare with attributed grammars, refer to "Bits of history and future".

## 6.4 Putting it all together

- initializing and quitting the modules
- actual parsing

Next Previous Contents