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 below 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 inter-operate with it, Styx provides some hooks, that may be useful in other project setups, too.

This left-over is mainly visible in the command line syntax and the way the command line inter-operates 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 extension.

Now, to save us keystrokes, most of the command line arguments, especially the directory paths, 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 authors has there own preferred method of getting a Styx project up. We describe our 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. One author prefers doing this iterating the steps described following thereby approximating and finally reaching the intended product, while other might prefer 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 analyze 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 Dragon Book or the 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.

Controlled 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 environment variable PATH, so you want to make sure that the generated images are placed properly.

Version 1.7 allows the visualization of grammars. The program ' lim2dot' converts a binary scanner table image into an appropriate '.dot' file which can be viewed with the graphviz tool ' dotty'. Based on the binary image ' pim2dot' creates '.dot' files for the parse table or the nonterminal relation of the corresponding grammar.

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 useful 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 independent 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

6.4 Putting it all together

Next Previous Contents