Goldie: GoldieLib Overview

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

- Requirements
- Download / Install
- Never Used a Parsing Tool?
- Goldie Overview
- Beginner's Tutorial
- Grammar Definition Language
- Contact / Support
  - Message Board
  - Issue Tracking

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 Static
- Calculator Dynamic
- Sample Generic Parse

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

- Scripts for Developers
- Library Source and StaticLang

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

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:

- Tab-size is a matter of presentation (For better or worse, depending on one's perspective).
- Non-printing characters may exist in a source to be parsed.
- The increasingly popular concept of elastic tabstops makes proportional fonts practical for source code, which renders the traditional concept of "column number" meaningless.

### 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:

// 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:

- GoldieLib API Reference