Use the engine

How to use the Gold Parser engine?

In few words, in this order: instantiate the parser, load the grammar table file, open a source file for parsing, call Parse() until accepted, and finally walk through the parse tree to construct a syntax tree that is much easier to work with, then with the raw parse tree.

You can also get information from the parser and do stuff after each call to Parse(), like logging progress, output messages, and more - you might also put your main logic after TokenRead and Reduction actions, for example.

1. Create an instance of the parser class:

using GoldParser;
Parser parser = new Parser();

2. Load the grammar tables file:

parser.LoadTables(@"C:\Users\userone\Desktop\my-grammer.egt");

3. Open the source file to be parsed:

string text = File.ReadAllText(@"C:\Users\userone\smartphone-locks.cs");
StringReader reader = new StringReader(text);
parser.Open(reader);

4. Call the Parse() method multiple times, until either some kind of error or "ParseMessage.Accept" is returned (1). A loop can be implemented to facilitate this task (2).

1)
ParseMessage response = parser.Parse();
	
2)
ParseMessage response;
bool flag = false;
while (!done)
{
	response = parser.Parse();
	switch (response)
	{
		//Cannot recognize token
		case ParseMessage.LexicalError:
		//show appropriate error message
		done = true;
		break;

		//Expecting a different token
		case ParseMessage.SyntaxError:
		//show appropriate error message
		done = true;
		break;

		//Done reduce action
		case ParseMessage.Reduction:
		//can also do stuff here
		break;

		//Accepted!
		case ParseMessage.Accept:
		var root = (Reduction)parser.CurrentReduction;  //The root node!
		done = true;
		//do stuff here
		break;

		//Token was produced from the lexer
		case ParseMessage.TokenRead:
		//can also do stuff here
		break;

		//Grammar is corrupt
		case ParseMessage.InternalError:
		//show appropriate error message
		done = true;
		break;

		//Tables not loaded
		case ParseMessage.NotLoadedError:
		//show appropriate error message
		done = true;
		break;

		//Runaway group - Unexpected end of file
		case ParseMessage.GroupError:
		//show appropriate error message
		done = true;
		break;
	}
}

5. Get the parse tree and use your custom logic to translate it to a syntax tree that is much more convenient to work with then the parse tree:

Reduction parseTreeRoot = (Reduction)parser.CurrentReduction;

---

How to get parse information?

1. CurrentReduction

When the Parse() method returns a Reduce, this method will contain the current Reduction. Otherwise, null is returned (1) or (2).

1) object currentReduction = parser.CurrentReduction;
2) Reduction currentReduction = (Reduction)parser.CurrentReduction;

2. CurrentToken()

When the Parse() method returns TokenRead, this method will return that last read token (1).

1) Token token = parser.CurrentToken();

3. ExpectedSymbols()

If the Parse() method returns a SyntaxError, this method will return a list of the symbols the parser expected. Many compilers present such information to the user - something like "Syntax error on line 10, col 22 - expected integer_value, string_value or semicolon" e.g.

1) SymbolList symbolList = parser.ExpectedSymbols();

---

How to get information about the parser and the loaded grammar?

1. About()

Returns the version of the parser - the string "GOLD Parser Engine; Version 5.0" (1)

1) string info = parser.About();

2. Grammar()

Returns metadata about the loaded grammar, as a grammar Properties object (1).

1) Properties properties = parser.Grammar();

3. SymbolTable()

Returns a list of Symbols recognized by the grammar (1).

1) SymbolList symbols = parser.SymbolTable();

4. ProductionTable()

Returns a list of Productions recognized by the grammar (1).

1) ProductionList productions = parser.ProductionTable();

---

How to tweak the parser?

1. TrimReductions

When this option is set to true, and there is a production that has a single nonterminal Symbol on the right hand side (A -> B; for example), if this option is set to true there is not going to be a reduction, but the token values will be changed accordingly(1). To check if the option is set, use (2).

1) parser.TrimReductions = true;
2) bool trim = parser.TrimReductions;

---

How to interfere with the parsing process?

1. DiscardCurrentToken()

Removes the a token from the top of the input stack. For example, when the Parse() method returns TokenRead, you can obtain the token check the token with by calling CurrentToken(), and if it matches some criteria, remove it (1).

1)	
if(parser.CurrentToken().Data().ToString().Contains("undesired"))
{
	Token discarded = parser.DiscardCurrentToken();
}

2. EnqueueInput(Token)

EnqueueInput(Token) adds a token to the bottom of the stack (1).

1) parser.EnqueueInput(token);

3. PushInput(Token)

PushInput(Token) adds a token to the top of the stack (1).

1) parser.PushInput(token);