Goldie: How To Use Goldie

Goldie
Parsing System (v0.4)
Goldie Home (v0.4)
Getting Started

- Requirements
- Download / Install
- Never Used a Parsing Tool?
- How To Use Goldie
- Grammar Definition Language
- Message Board
- Ticket System

Goldie's Tools

- DumpCGT
- GenDocs
  - Template Format
- GRMC: Grammar Compiler
- JsonViewer
  - Parse Tree Mode
- Parse
- StaticLang
- Other Tools

GoldieLib Overview

- Static And Dynamic Styles
- Ambiguous Symbols

GoldieLib Reference

- Base
- Exception
- class Language
- class Lexer
- class Parser
- struct Symbol
- class Token
- Ver

GoldieLib Sample Apps

- Calculator Dynamic
- Calculator Static
- Parse Anything

CGT File Format
FAQ
Change Log
If You Use Trunk
Future Work
Developers

- Library Source and StaticLang

Goldie Home (v0.4) -> Getting Started -> How To Use Goldie

# How To Use Goldie

The process for using Goldie is just like the process for GOLD Parser Builder:

## 1. Write a grammar in the .grm language

Here is a simple example of what a grammar might look like:
! This grammar defines a simple language consisting of ! positive integers separated by a plus sign. "Start Symbol" = <List> Number = {Digit}+ <List> ::= <List> '+' Number | Number

One of the nice things about the GOLD/Goldie systems, unlike most other parsing systems, is that there's no code embedded in the grammars, so grammars are write-once-and-reuse. In other words, if you write a grammar to use in one tool, you can reuse the exact same grammar for any other tool - even if the two tools are written in completely different languages!

More information about the grammar description language used by GOLD and Goldie, including links to premade grammars, can be found on this page: Grammar Definition Language

## 2. Compile the grammar to .cgt format

Goldie uses the LALR(1) and DFA algorithms to parse source. Both of these algorithms can be driven completely by tables of raw data, so Goldie requires grammars be compiled into these tables before they can be used. This provides certain benefits:

- The grammar definition itself can be parsed ahead of time, instead of on-the-fly. (Although, this is typical of just about any parsing system.)
- Grammars can be checked for errors before they're used. (This is also typical.)
- The code to parse a source can be written once and reused for any grammar, even without automatically-generating any code. This is very rare among parsing systems.

That last benefit is very powerful as it allows programs to be written that operate on user-created grammars without compiling any software or using DLL-based plug-in systems. Goldie's Parse tool and Parse Anything sample make use of this ability.

Of course, this doesn't prevent automatically generating source code for a parser as other tools such as ANTLR do. In fact, GOLD has a full template system that does exactly that. Goldie doesn't actually make any use of it, but GoldieLib does offer a static-style which fills a similar role for D v2.x users.

### How to compile a grammar

Grammar files can be compiled in a number of ways:

- #### Goldie's GRMC: Grammar Compiler

  A cross-platform command-line tool.
  >goldie-grmc grammar.grm Or: >goldie-grmc grammar.grm -o:output.cgt

- #### GOLD Parser Builder

  A .NET-based tool in GUI and command-line versions.

- #### GoldieLib's Language.compileGrammar* functions

  A D v2.x API interface. This can be useful for building general language-processing tools. In fact, this is what GRMC: Grammar Compiler uses.
  string grammar1 = "!* grammar definition here *!"; Language lang1 = Language.compileGrammar(grammar1); // Or: Language lang2 = Language.compileGrammarFile("grammar2.grm"); // Optionally save: lang1.save("grammar1.cgt"); lang2.save("grammar2.cgt");

## 3. Use a GOLD engine to load the compiled grammar and parse a source

Any GOLD-compatible engine can be used to load the compiled grammar and parse a source. Such engines are available for a wide variety of languages, since they're fairly easy to make. Goldie includes GoldieLib which serves as just such an engine for D v2.x.

Each engine is used differently, and their features and APIs can vary greatly. To start learning how to use the GoldieLib engine, see the following:

- GoldieLib Sample Apps
- Static And Dynamic Styles
- GoldieLib Overview

The GoldieLib Reference pages may also be useful.

Also, see the Goldie's Tools page for various tools that may be helpful when using Goldie.