aptk - API

This is the major interface for the user. Usually you will only:

from aptk import *

And then define your grammar, maybe parse-actions. This could for example look like this:

class AdditionGrammar(Grammar):
    r'''Parses addition-expressions.

    .. highlight aptk

    sum :- <number> "+" <sum> | <number>

    :parse-actions aptk.Sum

    <sum> ~~ 5 + 3 -Sum-> 8
    '''

class Sum(ParseActions):
    def sum(self, P, lex):
        return sum([ x.ast for x in lex ])

For parsing a string, you can use parse():

parse_tree = parse("4 + 2", AdditionGrammar, Sum)

For convenience there is also a function ast(), which returns abstract syntax-tree of a node:

result = ast(parse_tree)

For convienece you can shortcut this with:

result = ast("4 + 2", AdditionGrammar, Sum)
class aptk.Grammar(s=None, **kargs)

Default grammar with basic tokens and rules.

This is the grammar, you will usually derive your grammars from.

It provides most common tokens:

SP   = \x20
NL   = \r?\n
LF   = \n
CR   = \r
CRLF = \r\n
ws   = \s+
ws?  = \s*
N    = [^\n]
HWS  = [\x20\t\v]
LINE = [^\n]*\n

And a general ActionMap, which lets you connect your grammar to basic ParseActions:

:parse-action-map
    "$" make_string
    "@" make_list
    "%" make_dict
    "#" make_number
    "<" make_inherit
    ">" make_name
    "~" make_quoted

And most common rules:

ident     $= [A-Za-z_\-][\w\-]*
number    #= [+-]?\d+(?:\.\d+)?
integer   #= \d+
dq-string ~= "(?:\\\\|\\[^\\]|[^"\\])*"
sq-string ~= '(?:\\\\|\\[^\\]|[^'\\])*'
ws        $= \b{ws}\b|{ws?}
line      $= [^\n]*\n

Making explicit the whitespace rule default from BaseGrammar:

:sigspace <.ws>

Define how args of BRANCH are parsed:

:args-of BRANCH string capturing non-capturing regex

Define operation precedence parser:

:args-of  EXPR string capturing non-capturing raw 
            => aptk.oprec.OperatorPrecedenceParser
BRANCH(P, s=None, start=None, end=None, args=None)

lookahead and branch into some rule.

Example:

branched := <BRANCH{
             "a"    <a-rule>
             [bcd]  <bcd-rule>
             a|b    <a-or-b-rule>
             <default-rule>
            }>

If string to be matched startswith

ERROR(P, s=None, start=None, end=None, args=None)

raise a syntax error.

Example:

foo := <x> | <ERROR{Expected "x"}>

Please note that whitespace will be collapsed to single space.

aptk.parse(s, grammar, actions=None, rule=None)

parse s with given grammar and apply actions to produced lexems.

aptk.ast(s, grammar=None, actions=None, rule=None)

return ast of s if has one, else, parse s using grammar and actions and return it then