Parsing System (v0.8)
Goldie Home (v0.8) -> GoldieLib Overview

GoldieLib Overview

GoldieLib is Goldie's D API. Using GoldieLib, your D programs can parse text according to any GOLD-compatible grammar and access some of Goldie's other capabilities.


Importing is simple:

import goldie.all;

When you compile, make sure to tell the compiler where to find Goldie and SemiTwist D Tools:

>rdmd --build-only -I{path to SemiTwistDTools}/src -I{path to Goldie}/src myMain.d

Conventions Used By GoldieLib

Line and Column Numbers

All line numbers and column numbers are internally stored and treated by the API as zero-indexed and displayed to the user as one-indexed.

When Goldie refers to a "column number", it really means "the number of characters (ie, UTF code-points) from the start of the line". This behavior is more reliable and more useful than a true "column number" because:

Tokens, Symbols, and Symbol Types:
The Front-End's Building Blocks

A Token can be thought of as an instance of a Symbol. A Token is part of the parsed source, and a Symbol is part of the grammar.

For example, consider this grammar:

Word = {Letter}+ <Sentence> ::= <Sentence> Word

And this source:

Hello world

These are the Tokens and Symbols:

WordSymbolThis Symbol's type is SymbolType.Terminal.
<Sentence>SymbolThis Symbol's type is SymbolType.NonTerminal.
HelloTokenThis Token's Symbol is Word.
worldTokenThis Token's Symbol is Word.
Hello worldTokenThis Token's Symbol is <Sentence>.

Note that Goldie defines more symbol types than just Terminal and NonTerminal (see the SymbolType documentation). So if you want to check if a Symbol or Token is a SymbolType.NonTerminal do NOT do it by comparing the type with SymbolType.Terminal. Just because something isn't a SymbolType.Terminal does NOT imply that it's a SymbolType.NonTerminal.

Referring to a rule that has no subtokens

Just use null for the subtokens.


Suppose you have this in your grammar for language "myLang":

<Optional Fred> ::= 'fred' |

The nonterminal <Optional Fred> can be created from either the text fred or from nothing at all. To check if a token matches the first case, ie. the fred rule, you use this:

// static-style: if( auto typedTok = cast(Token_myLang!("<Optional Fred>", "fred"))token ) { // use typedTok } // dynamic-style: if( token.matches("<Optional Fred>", "fred") ) { // use token }

To check for the empty rule, you just use null:

// static-style: if( auto typedTok = cast(Token_myLang!("<Optional Fred>", null))token ) { // use typedTok } // dynamic-style: if( token.matches("<Optional Fred>", null) ) { // use token }

Simple Examples

For simple examples of how to use GoldieLib, see the GoldieLib Sample Apps.

See Also: