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
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:
Word | Symbol | This Symbol's type is SymbolType.Terminal. |
<Sentence> | Symbol | This Symbol's type is SymbolType.NonTerminal. |
Hello | Token | This Token's Symbol is Word. |
world | Token | This Token's Symbol is Word. |
Hello world | Token | This 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:
if( auto typedTok = cast(Token_myLang!("<Optional Fred>", "fred"))token )
{
}
if( token.matches("<Optional Fred>", "fred") )
{
}
To check for the empty rule, you just use null:
if( auto typedTok = cast(Token_myLang!("<Optional Fred>", null))token )
{
}
if( token.matches("<Optional Fred>", null) )
{
}
Simple Examples
For simple examples of how to use GoldieLib, see the GoldieLib Sample Apps.
See Also:
|