Package org.nineml.coffeegrinder.parser

Class SourceGrammar

java.lang.Object

org.nineml.coffeegrinder.parser.Grammar

org.nineml.coffeegrinder.parser.SourceGrammar

public class SourceGrammar
extends Grammar

A grammar for the parser.

A grammar is a list of rules. Each rule defines a non-terminal symbol as a sequence of zero or more symbols (terminals or nonterminals).

A grammar can be used to create a parser. The parser will (successfully) parse inputs that match the rules in the grammar.

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	logcategory	The logging category for log messages about the source grammar.

Constructor Summary

Constructors

Constructor	Description
SourceGrammar()	Create a new grammar with default options.
SourceGrammar(ParserOptions options)	Create a new grammar with a specific set of options.
SourceGrammar(SourceGrammar current)	Create a new grammar from an existing grammar.

Method Summary

Modifier and Type	Method	Description
void	addRule(NonterminalSymbol nonterminal, java.util.List<Symbol> rhs)	Add a rule to the grammar.
void	addRule(NonterminalSymbol nonterminal, Symbol... rhs)	Add a rule to the grammar.
void	addRule(Rule rule)	Add a rule to the grammar.
boolean	contains(Rule candidate)	Does this grammar contain an equivalent rule?
ParserGrammar	getCompiledGrammar(NonterminalSymbol seed)	Compiles the grammar using the default parser type.
ParserGrammar	getCompiledGrammar(ParserType parserType, NonterminalSymbol seed)	Compiles the grammar.
HygieneReport	getHygieneReport(NonterminalSymbol seed)	Get a hygiene report for this grammar.
NonterminalSymbol	getNonterminal(java.lang.String name)	Return the nonterminal symbol identified by name.
NonterminalSymbol	getNonterminal(java.lang.String name, java.util.List<ParserAttribute> attributes)	Return the nonterminal symbol identified by name.
NonterminalSymbol	getNonterminal(java.lang.String name, ParserAttribute attribute)	Return the nonterminal symbol identified by name.
GearleyParser	getParser(ParserOptions options, java.lang.String seed)	Get a parser.
GearleyParser	getParser(ParserOptions options, NonterminalSymbol seed)	Get a parser for this grammar.
ParserOptions	getParserOptions()	Gets the parser options.
boolean	isNullable(Symbol symbol)	Is the symbol nullable?
SourceGrammar	resolveDuplicates()	Resolve duplicate symbols in the grammar.
void	setMetadataProperty(java.lang.String name, java.lang.String value)	Sets a metadata property.

Methods inherited from class org.nineml.coffeegrinder.parser.Grammar

getDefaultPriority, getMetadataProperies, getMetadataProperty, getPriorityStyle, getRules, getRulesBySymbol, getRulesForSymbol, getSymbols, getVersion, setDefaultPriority, setPriorityStyle, setVersion

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

logcategory

public static final java.lang.String logcategory

The logging category for log messages about the source grammar.

See Also:

Constant Field Values

Constructor Detail

SourceGrammar

public SourceGrammar()

Create a new grammar with default options.

SourceGrammar

public SourceGrammar(ParserOptions options)

Create a new grammar with a specific set of options.

Parameters:

options - The options.

Throws:

java.lang.NullPointerException - if options is null.

SourceGrammar

public SourceGrammar(SourceGrammar current)

Create a new grammar from an existing grammar.

Parameters:

current - the grammar to copy

Method Detail

getNonterminal

public NonterminalSymbol getNonterminal(java.lang.String name)

Return the nonterminal symbol identified by name.

Nonterminal symbols are uniquely identified by their name.

Any string can be used as a name.

Parameters:

name - The name of this symbol.

Returns:

The nonterminal for the name specified.

Throws:

java.lang.NullPointerException - if the name is null.

getNonterminal

public NonterminalSymbol getNonterminal(java.lang.String name,
                                        ParserAttribute attribute)

Return the nonterminal symbol identified by name.

Nonterminal symbols are uniquely identified by their name.

Any string can be used as a name.

Parameters:

name - The name of this symbol.

attribute - an attribute.

Returns:

The nonterminal for the name specified.

Throws:

java.lang.NullPointerException - if the name is null or the attribute is null.

getNonterminal

public NonterminalSymbol getNonterminal(java.lang.String name,
                                        java.util.List<ParserAttribute> attributes)

Return the nonterminal symbol identified by name.

Nonterminal symbols are uniquely identified by their name.

Any string can be used as a name.

Parameters:

name - The name of this symbol.

attributes - attributes to associate with this symbol, may be null

Returns:

The nonterminal for the name specified.

Throws:

java.lang.NullPointerException - if the name is null.

addRule

public void addRule(Rule rule)

Add a rule to the grammar.

Multiple rules can exist for the same NonterminalSymbol. There should be at least one rule for every nonterminal symbol that occurs on the "right hand side" of a rule. A symbol that is undefined but unreachable from the specified start symbol when parsing, isn't forbidden by CoffeeGrinder, but it is by CoffeeFilter.

Once added, a rule can never be removed.

Parameters:

rule - The rule to add

Throws:

GrammarException - if any nonterminal in the rule is not from this grammar, or if the grammar is closed

addRule

public void addRule(NonterminalSymbol nonterminal,
                    Symbol... rhs)

Add a rule to the grammar.

This is a convenience method that will construct the Rule for you.

Multiple rules can exist for the same NonterminalSymbol. There must be at least one rule for every nonterminal symbol that occurs on the "right hand side" of a rule.

Parameters:

nonterminal - The nonterminal symbol defined by this rule.

rhs - The list of symbols that define it

Throws:

GrammarException - if any nonterminal in the rule is not from this grammar or if the grammar is closed

addRule

public void addRule(NonterminalSymbol nonterminal,
                    java.util.List<Symbol> rhs)

Add a rule to the grammar.

This is a convenience method that will construct the Rule for you.

Multiple rules can exist for the same NonterminalSymbol. There must be at least one rule for every nonterminal symbol that occurs on the "right hand side" of a rule.

Parameters:

nonterminal - The nonterminal symbol defined by this rule.

rhs - The list of symbols that define it.

Throws:

GrammarException - if any nonterminal in the rule is not from this grammar or if the grammar is closed

isNullable

public boolean isNullable(Symbol symbol)

Description copied from class: Grammar

Is the symbol nullable?

A TerminalSymbol is never nullable.

For a ParserGrammar, the answer is definitive. For an SourceGrammar, a symbol that isn't currently nullable could become nullable by the addition of more rules.

Specified by:

isNullable in class Grammar

Parameters:

symbol - The symbol.

Returns:

true if the symbol is nullable

getParser

public GearleyParser getParser(ParserOptions options,
                               java.lang.String seed)

Get a parser.

Parameters:

options - the options.

seed - the seed.

Returns:

a parser.

getCompiledGrammar

public ParserGrammar getCompiledGrammar(NonterminalSymbol seed)

Compiles the grammar using the default parser type.

Parameters:

seed - the seed

Returns:

the grammar

getCompiledGrammar

public ParserGrammar getCompiledGrammar(ParserType parserType,
                                        NonterminalSymbol seed)

Compiles the grammar.

Parameters:

parserType - the parser type.

seed - the seed.

Returns:

The compiled grammar.

getParser

public GearleyParser getParser(ParserOptions options,
                               NonterminalSymbol seed)

Get a parser for this grammar.

Returns a parser that will parse an input against the rules that define this grammar.

Parameters:

options - the options for this parser.

seed - The NonterminalSymbol that your input is expected to match.

Returns:

the parser

resolveDuplicates

public SourceGrammar resolveDuplicates()

Resolve duplicate symbols in the grammar.

This method may return a different SourceGrammar. In this new grammar, all of the unique nonterminals will have unique names. (That is, if a nonterminal A occurs twice in the grammar with different parser attributes, it will have two different names in the resolved grammar.)

This method is public only so that it is possible to know what all of the nonterminals in the parse grammar will be.

Returns:

a grammar with duplicates resolved

getParserOptions

public ParserOptions getParserOptions()

Gets the parser options.

Returns:

the current options.

getHygieneReport

public HygieneReport getHygieneReport(NonterminalSymbol seed)

Get a hygiene report for this grammar.

Parameters:

seed - The seed rule for hygiene checking.

Returns:

the report.

contains

public boolean contains(Rule candidate)

Does this grammar contain an equivalent rule?

Two rules are equivalent if they have the same symbol, the same list of right-hand-side symbols, and if the attributes and optionality of every symbol on the right-hand-side are the same in both rules.

Parameters:

candidate - the candidate rule

Returns:

true if the grammar contains an equivalent rule

setMetadataProperty

public void setMetadataProperty(java.lang.String name,
                                java.lang.String value)

Sets a metadata property.

Metadata properties exist solely for annotations by an application. They have no bearing on the function of the grammar.

Parameters:

name - the name of the property

value - the value of the property, or null to remove a property

Throws:

java.lang.NullPointerException - if the name is null