API - grap.core#

grap.core#

grap.core.action#

class grap.core.action.Action(value)#

An action influences the behaviour of the parser.

There is generally no need to use them. The predefined rules in grap.core.common cover most of them.

GO_BACK = 1#

Moves the pointer to the previous position.

IS_MATCH = 3#

Acts like a rule that always matches anything.

NO_MATCH = 2#

Acts like a rule that never matches anything.

OPTIONAL = 4#

Suppresses errors.ParseErrors for the current rule and each subrule.

REQUIRE = 5#

The parser will raise a ParseErrors when following rules are not consumed. This has no effect when OPTIONAL was yielded by a parent rule.

grap.core.common#

class grap.core.common.OnceOrMore(rule, name=_Nothing.NOTHING)#

Match a rule one or more times.

Method generated by attrs for class OnceOrMore.

Parameters:

  • rule (Rule) –

  • name (str) –

for ... in grammar()#
Return type:

Grammar

name: str#

The name of the rule.

rule: Rule#

The rule to match.

class grap.core.common.Optional(rule, name=_Nothing.NOTHING)#

Optionally match a rule.

Method generated by attrs for class Optional.

Parameters:

  • rule (Rule) –

  • name (str) –

for ... in grammar()#
Return type:

Grammar

name: str#

The name of the rule.

rule: Rule#

The rule to match.

class grap.core.common.RuleUnion(rules, name=_Nothing.NOTHING)#

Match one of multiple rules.

Method generated by attrs for class RuleUnion.

Parameters:

  • rules (Sequence[Rule]) –

  • name (str) –

for ... in grammar()#
Return type:

Grammar

name: str#

The name of the rule.

rules: Sequence[Rule]#

The rules to match.

class grap.core.common.String(string, case_sensitive=True, name=_Nothing.NOTHING)#

Match a string.

Method generated by attrs for class String.

Parameters:

  • string (str) –

  • case_sensitive (bool) –

  • name (str) –

case_sensitive: bool#
for ... in grammar()#
Return type:

Grammar

name: str#
string: str#
class grap.core.common.ZeroOrMore(rule, name=_Nothing.NOTHING)#

Match a rule zero or more times.

Method generated by attrs for class ZeroOrMore.

Parameters:

  • rule (Rule) –

  • name (str) –

for ... in grammar()#
Return type:

Grammar

name: str#

The name of the rule.

rule: Rule#

The rule to match.

grap.core.errors#

exception grap.core.errors.ParseError(message, location)#
Parameters:

  • message (str) –

  • location (int) –

args#
with_traceback()#

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

grap.core.parser#

class grap.core.parser.ParsedRule(*, name, rule, match, span, parent=None, inner=_Nothing.NOTHING)#
Parameters:

  • name (str) –

  • rule (Rule) –

  • match (str) –

  • span (tuple[int, int]) –

  • parent (Optional[Rule]) –

  • inner (list[grap.core.rules.Rule]) –

name#

The name of the rule.

Type:

str

rule#

The parsed rule object.

Type:

grap.core.rules.Rule

match#

The consumed characters.

Type:

str

span#

The index of the consumed characters in the parsed text.

Type:

tuple[int, int]

parent#

The parent rule. This is None when the rule is the root.

Type:

Optional[grap.core.rules.Rule]

inner#

All parsed subrules.

Type:

list[grap.core.rules.Rule]

Method generated by attrs for class ParsedRule.

inner: list[grap.core.rules.Rule]#
match: str#
name: str#
parent: Optional[Rule]#
rule: Rule#
span: tuple[int, int]#
grap.core.parser.parse(rule, text)#
Parameters:

  • rule (Rule) – The rule to parse the text with.

  • text (str) – The text to parse.

Return type:

The parse tree.

grap.core.rules#

class grap.core.rules.Rule(name=None)#
Parameters:

name (Optional[str]) – The name of the rule. Defaults to the class’s name.

abstractmethod grammar()#
Return type:

Generator[Union[Rule, Action, str], str, None]

grap.core.rules.rule(fn: Callable[[], Generator[Union[Rule, Action, str], str, None]], /, *, name: None = None, doc: None = None) → type[grap.core.rules.Rule]#
grap.core.rules.rule(fn: None = None, /, *, name: Optional[str] = None, doc: Optional[str] = None) → Callable[[Callable[[], Generator[Union[Rule, Action, str], str, None]]], type[grap.core.rules.Rule]]

Decorator to quickly define a rule.

The function that is decorated should not take any arguments. The function is converted into a staic method of the newly created rule. The docstring of the decorated function is assigned to the rule class.

Parameters:

  • fn – The function to decorate.

  • name – The name of the rule. Defaults to the function’s name.

  • doc – The docstring of the rule. Defaults to function’s docstring.

Examples

from grap.core import Grammar, rule

 @rule
 def pet() -> Grammar:
     yield "p"
     yield "e"
     yield "t"

from grap.core import Grammar, rule

@rule(name = "dog")
def pet() -> Grammar:
    yield "d"
    yield "o"
    yield "g"