Here we describe how you structure your source code and make references to libraries so that you can create a parser that is generated in-line, in the same program that runs that parser. The grammar description is provided as either a character string in source code, or as an input stream, meaning it could be read from a database or from a file.

Any in-line parser project will need to include two DLLs among the references. These are Parsing.DLL that contains the classes in the namespace Parsing, and ParserGenerator.DLL that contains the classes in the namespace ParserGenerator. Naturally the addition of using statements to the top of source files that refer to members of these DLLs will simplify your source code.

First your source code will need to have an application specific parser class that you have written. The actual parser class already exists as Parsing.Parser in Parsing.DLL, so all you need to ensure is that your application specific parser class inherits from Parsing.Parser.

An example of the structure of your source file containing your application specific parser class might be:

using Parsing;
 
// ... other using statements ...
 
namespace MyApplication
{
    public class MyParser : Parser
    {
        // ... Application specific class members here ...
    }
}

Your parser will represent a single object that acts as the interface to any data structures that are being built or manipulated while the parser is executing. You would typically include any data members and methods to access them within the application specific parser class.

With both inline and offline parsers, you may have elected for the action code executed on rule reduction to be added to the source code for the parser. These action functions will have had their names listed in the actions section of the grammar description, and will all have the same standard function signature. For example, if we have an action called BumpPlural it should have its implementation written inside your application-specific parser class as follows:

using Parsing;
 
// ... other using statements ...
 
namespace MyApplication
{
    public class MyParser : Parser
    {
        // Application specific class members
         
        public int PluralCount { get; set; }
         
        public void BumpPlural(object[] args)
        {
            if(someErrorOccurred)
                args[0] = new ParserError
                {
                    Message = "Nature of error"
                }
            else
                PluralCount++;
        }
    }
}

Note the signature of the action method. It has a return type of void, as the parsing engine makes no attempt to pick up a return value. The object array passed as the single argument to the action function will have been filled in with a selection of the values from each of the tokens on the right hand side of the production being reduced when this action was called. The array always has a size of at least one element. This zeroth element of the array is used to return a value back to the parser that will be used as the value for the single LHS token that replaces all the RHS tokens that are being removed from the top of the parser stack.

If you construct an instance of a Parsing.ParserError object and place that into args[0] before returning from any action function, this indicates to the parser that your action function identified an error in the parsing process. The Message property of the ParserError object should be filled in with an explanation of the fault, as this field is used to report back to the parser error output channels the nature of the fault.

On receipt of a ParserError object in slot zero of the argument array, the parser will either abort the current parse, or if error recovery has been enabled, will attempt to pop the parser state stack and shift input tokens until a suitable resumption point has been reached. A description of how this error recover mechanism functions is given elsewhere.

If your grammar requires guard functions to be evaluated for some of the tokens as they are parsed, you might have decided to write these guard functions in your application specific parser class. If so, their names will also have been listed in the guards section of the grammar.

Guard functions take a single object argument that contains the value of the most recently received input token. This is usually the terminal token the guard expression is positioned next to in the grammar. However, it is possible for a guard expression to be placed alongside a non-terminal token, in which case the object argument is the value of the terminal token the guard is being tested against. For more details of how guards on non-terminals are mapped back to their respective terminal tokens, see the detailed article describing this mapping.

Guard functions should return a boolean result. This should be set to true if the token should be accepted at this point in the parse, and false if it is not appropriate at this point. An example of a guard function named PluralNoun is given in the parser class below:

using Parsing;
 
namespace MyApplication
{
    public class MyParser : Parser
    {
        // Application specific class members
         
        public int PluralCount { get; set; }
         
        public void BumpPlural(object[] args)
        {
            if(someErrorOccurred)
                args[0] = new ParserError
                {
                    Message = "Nature of error"
                }
            else
                PluralCount++;
        }
         
        public bool PluralNoun(object arg)
        {
            return arg.ToString().EndsWith("s");
        }
    }
}

As a guide to writing boolean guard functions, try to arrange that each function evaluates a single truth value about the state of the parse or its data. Avoid combining several evaluable boolean items with boolean operators within a single function. The reason for this is that the grammar description allows compound boolean expressions to be constructed using the boolean guard functions and the operators 'and', 'or' and 'not'. By keeping the guard functions as primitive as possible, you can reuse them in different combinations for different guard expressions at different points in the grammar.

Your in-line parser class should either have no constructor, or should be written with a default (parameterless) constructor. If you need to initialise members with values, this should be done via a separate initialisation method, or via property assignments after the parser instance has been created. The reason for this is that the ParserFactory<T>.InitializeFromGrammar and the ParserFactory<T>.CreateInstance methods used to create an instance of the resulting parser expect the application-specific parser class to have a default constructor. An example of some suitable creation and initialisation code is given below. Note that the ParserFactory<T>.InitializeFromGrammar and ParserFactory<T>.CreateInstance methods are described elsewhere.

    ParserFactory<MyParser>.InitializeFromGrammar( ... args ... );
    MyParser p = ParserFactory<MyParser>.CreateInstance();
    p.SomeMemberProperty = someValue;