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

GoldieLib Overview

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

Importing

Importing is simple:

import goldie.all;

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.

Example:

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: