//! This module contains excerpts about the grammar directly from CPython's documentation
//!
//! CPython has it's own DFA based parser generator for which the input is `PythonGrammar`.


/// The grammar as it
/// ASDL's 7 builtin types are:
///
/// - identifier, int, string, bytes, object, singleton, constant
/// -- singleton: None, True or False
/// -- constant can be None, whereas None means "no value" for object.
///
/// ```raw
///
/// module Python
/// {
///     mod = Module(stmt* body)
///         | Interactive(stmt* body)
///         | Expression(expr body)
/// 
///          -- not really an actual node but useful in Jython's typesystem.
///          | Suite(stmt* body)
/// 
///     stmt = FunctionDef(identifier name, arguments args,
///                          stmt* body, expr* decorator_list, expr? returns)
///           | AsyncFunctionDef(identifier name, arguments args,
///                                stmt* body, expr* decorator_list, expr? returns)
/// 
///           | ClassDef(identifier name,
///                expr* bases,
///                keyword* keywords,
///                stmt* body,
///                expr* decorator_list)
///           | Return(expr? value)
/// 
///           | Delete(expr* targets)
///           | Assign(expr* targets, expr value)
///           | AugAssign(expr target, operator op, expr value)
///           -- simple indicates that we annotate simple name without parens
///           | AnnAssign(expr target, expr annotation, expr? value, int simple)
/// 
///           -- use 'orelse' because else is a keyword in target languages
///           | For(expr target, expr iter, stmt* body, stmt* orelse)
///           | AsyncFor(expr target, expr iter, stmt* body, stmt* orelse)
///           | While(expr test, stmt* body, stmt* orelse)
///           | If(expr test, stmt* body, stmt* orelse)
///           | With(withitem* items, stmt* body)
///           | AsyncWith(withitem* items, stmt* body)
/// 
///           | Raise(expr? exc, expr? cause)
///           | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
///           | Assert(expr test, expr? msg)
/// 
///           | Import(alias* names)
///           | ImportFrom(identifier? module, alias* names, int? level)
/// 
///           | Global(identifier* names)
///           | Nonlocal(identifier* names)
///           | Expr(expr value)
///           | Pass | Break | Continue
/// 
///           -- XXX Jython will be different
///           -- col_offset is the byte offset in the utf8 string the parser uses
///           attributes (int lineno, int col_offset)
/// 
///           -- BoolOp() can use left & right?
///     expr = BoolOp(boolop op, expr* values)
///          | BinOp(expr left, operator op, expr right)
///          | UnaryOp(unaryop op, expr operand)
///          | Lambda(arguments args, expr body)
///          | IfExp(expr test, expr body, expr orelse)
///          | Dict(expr* keys, expr* values)
///          | Set(expr* elts)
///          | ListComp(expr elt, comprehension* generators)
///          | SetComp(expr elt, comprehension* generators)
///          | DictComp(expr key, expr value, comprehension* generators)
///          | GeneratorExp(expr elt, comprehension* generators)
///          -- the grammar constrains where yield expressions can occur
///          | Await(expr value)
///          | Yield(expr? value)
///          | YieldFrom(expr value)
///          -- need sequences for compare to distinguish between
///          -- x < 4 < 3 and (x < 4) < 3
///          | Compare(expr left, cmpop* ops, expr* comparators)
///          | Call(expr func, expr* args, keyword* keywords)
///          | Num(object n) -- a number as a PyObject.
///          | Str(string s) -- need to specify raw, unicode, etc?
///          | FormattedValue(expr value, int? conversion, expr? format_spec)
///          | JoinedStr(expr* values)
///          | Bytes(bytes s)
///          | NameConstant(singleton value)
///          | Ellipsis
///          | Constant(constant value)
/// 
///          -- the following expression can appear in assignment context
///          | Attribute(expr value, identifier attr, expr_context ctx)
///          | Subscript(expr value, slice slice, expr_context ctx)
///          | Starred(expr value, expr_context ctx)
///          | Name(identifier id, expr_context ctx)
///          | List(expr* elts, expr_context ctx)
///          | Tuple(expr* elts, expr_context ctx)
/// 
///           -- col_offset is the byte offset in the utf8 string the parser uses
///           attributes (int lineno, int col_offset)
/// 
///     expr_context = Load | Store | Del | AugLoad | AugStore | Param
/// 
///     slice = Slice(expr? lower, expr? upper, expr? step)
///           | ExtSlice(slice* dims)
///           | Index(expr value)
/// 
///     boolop = And | Or
/// 
///     operator = Add | Sub | Mult | MatMult | Div | Mod | Pow | LShift
///                  | RShift | BitOr | BitXor | BitAnd | FloorDiv
/// 
///     unaryop = Invert | Not | UAdd | USub
/// 
///     cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn
/// 
///     comprehension = (expr target, expr iter, expr* ifs, int is_async)
/// 
///     excepthandler = ExceptHandler(expr? type, identifier? name, stmt* body)
///                     attributes (int lineno, int col_offset)
/// 
///     arguments = (arg* args, arg? vararg, arg* kwonlyargs, expr* kw_defaults,
///                  arg? kwarg, expr* defaults)
/// 
///     arg = (identifier arg, expr? annotation)
///            attributes (int lineno, int col_offset)
/// 
///     -- keyword arguments supplied to call (NULL identifier for **kwargs)
///     keyword = (identifier? arg, expr value)
/// 
///     -- import name with optional 'as' alias.
///     alias = (identifier name, identifier? asname)
/// 
///     withitem = (expr context_expr, expr? optional_vars)
/// }
/// ```
///
pub struct PythonASDL;


/// Grammar for Python
///
/// ```raw
///
/// /// # Start symbols for the grammar:
/// #       single_input is a single interactive statement;
/// #       file_input is a module or sequence of commands read from an input file;
/// #       eval_input is the input for the eval() functions.
/// # NB: compound_stmt in single_input is followed by extra NEWLINE!
/// single_input: NEWLINE | simple_stmt | compound_stmt NEWLINE
/// file_input: (NEWLINE | stmt)* ENDMARKER
/// eval_input: testlist NEWLINE* ENDMARKER
/// 
/// decorator: '@' dotted_name [ '(' [arglist] ')' ] NEWLINE
/// decorators: decorator+
/// decorated: decorators (classdef | funcdef | async_funcdef)
/// 
/// async_funcdef: ASYNC funcdef
/// funcdef: 'def' NAME parameters ['->' test] ':' suite
/// 
/// parameters: '(' [typedargslist] ')'
/// typedargslist: (tfpdef ['=' test] (',' tfpdef ['=' test])* [',' [
///         '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef [',']]]
///       | '**' tfpdef [',']]]
///   | '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef [',']]]
///   | '**' tfpdef [','])
/// tfpdef: NAME [':' test]
/// varargslist: (vfpdef ['=' test] (',' vfpdef ['=' test])* [',' [
///         '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef [',']]]
///       | '**' vfpdef [',']]]
///   | '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef [',']]]
///   | '**' vfpdef [',']
/// )
/// vfpdef: NAME
/// 
/// stmt: simple_stmt | compound_stmt
/// simple_stmt: small_stmt (';' small_stmt)* [';'] NEWLINE
/// small_stmt: (expr_stmt | del_stmt | pass_stmt | flow_stmt |
///              import_stmt | global_stmt | nonlocal_stmt | assert_stmt)
/// expr_stmt: testlist_star_expr (annassign | augassign (yield_expr|testlist) |
///                      ('=' (yield_expr|testlist_star_expr))*)
/// annassign: ':' test ['=' test]
/// testlist_star_expr: (test|star_expr) (',' (test|star_expr))* [',']
/// augassign: ('+=' | '-=' | '*=' | '@=' | '/=' | '%=' | '&=' | '|=' | '^=' |
///             '<<=' | '>>=' | '**=' | '//=')
/// # For normal and annotated assignments, additional restrictions enforced by the interpreter
/// del_stmt: 'del' exprlist
/// pass_stmt: 'pass'
/// flow_stmt: break_stmt | continue_stmt | return_stmt | raise_stmt | yield_stmt
/// break_stmt: 'break'
/// continue_stmt: 'continue'
/// return_stmt: 'return' [testlist]
/// yield_stmt: yield_expr
/// raise_stmt: 'raise' [test ['from' test]]
/// import_stmt: import_name | import_from
/// import_name: 'import' dotted_as_names
/// # note below: the ('.' | '...') is necessary because '...' is tokenized as ELLIPSIS
/// import_from: ('from' (('.' | '...')* dotted_name | ('.' | '...')+)
///               'import' ('*' | '(' import_as_names ')' | import_as_names))
/// import_as_name: NAME ['as' NAME]
/// dotted_as_name: dotted_name ['as' NAME]
/// import_as_names: import_as_name (',' import_as_name)* [',']
/// dotted_as_names: dotted_as_name (',' dotted_as_name)*
/// dotted_name: NAME ('.' NAME)*
/// global_stmt: 'global' NAME (',' NAME)*
/// nonlocal_stmt: 'nonlocal' NAME (',' NAME)*
/// assert_stmt: 'assert' test [',' test]
/// 
/// compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt | with_stmt | funcdef | classdef | decorated | async_stmt
/// async_stmt: ASYNC (funcdef | with_stmt | for_stmt)
/// if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':' suite]
/// while_stmt: 'while' test ':' suite ['else' ':' suite]
/// for_stmt: 'for' exprlist 'in' testlist ':' suite ['else' ':' suite]
/// try_stmt: ('try' ':' suite
///            ((except_clause ':' suite)+
///             ['else' ':' suite]
///             ['finally' ':' suite] |
///            'finally' ':' suite))
/// with_stmt: 'with' with_item (',' with_item)*  ':' suite
/// with_item: test ['as' expr]
/// # NB compile.c makes sure that the default except clause is last
/// except_clause: 'except' [test ['as' NAME]]
/// suite: simple_stmt | NEWLINE INDENT stmt+ DEDENT
/// 
/// test: or_test ['if' or_test 'else' test] | lambdef
/// test_nocond: or_test | lambdef_nocond
/// lambdef: 'lambda' [varargslist] ':' test
/// lambdef_nocond: 'lambda' [varargslist] ':' test_nocond
/// or_test: and_test ('or' and_test)*
/// and_test: not_test ('and' not_test)*
/// not_test: 'not' not_test | comparison
/// comparison: expr (comp_op expr)*
/// # <> isn't actually a valid comparison operator in Python. It's here for the
/// # sake of a __future__ import described in PEP 401 (which really works :-)
/// comp_op: '<'|'>'|'=='|'>='|'<='|'<>'|'!='|'in'|'not' 'in'|'is'|'is' 'not'
/// star_expr: '*' expr
/// expr: xor_expr ('|' xor_expr)*
/// xor_expr: and_expr ('^' and_expr)*
/// and_expr: shift_expr ('&' shift_expr)*
/// shift_expr: arith_expr (('<<'|'>>') arith_expr)*
/// arith_expr: term (('+'|'-') term)*
/// term: factor (('*'|'@'|'/'|'%'|'//') factor)*
/// factor: ('+'|'-'|'~') factor | power
/// power: atom_expr ['**' factor]
/// atom_expr: [AWAIT] atom trailer*
/// atom: ('(' [yield_expr|testlist_comp] ')' |
///        '[' [testlist_comp] ']' |
///        '{' [dictorsetmaker] '}' |
///        NAME | NUMBER | STRING+ | '...' | 'None' | 'True' | 'False')
/// testlist_comp: (test|star_expr) ( comp_for | (',' (test|star_expr))* [','] )
/// trailer: '(' [arglist] ')' | '[' subscriptlist ']' | '.' NAME
/// subscriptlist: subscript (',' subscript)* [',']
/// subscript: test | [test] ':' [test] [sliceop]
/// sliceop: ':' [test]
/// exprlist: (expr|star_expr) (',' (expr|star_expr))* [',']
/// testlist: test (',' test)* [',']
/// dictorsetmaker: ( ((test ':' test | '**' expr)
///                    (comp_for | (',' (test ':' test | '**' expr))* [','])) |
///                   ((test | star_expr)
///                    (comp_for | (',' (test | star_expr))* [','])) )
/// 
/// classdef: 'class' NAME ['(' [arglist] ')'] ':' suite
/// 
/// arglist: argument (',' argument)*  [',']
/// 
/// # The reason that keywords are test nodes instead of NAME is that using NAME
/// # results in an ambiguity. ast.c makes sure it's a NAME.
/// # "test '=' test" is really "keyword '=' test", but we have no such token.
/// # These need to be in a single rule to avoid grammar that is ambiguous
/// # to our LL(1) parser. Even though 'test' includes '*expr' in star_expr,
/// # we explicitly match '*' here, too, to give it proper precedence.
/// # Illegal combinations and orderings are blocked in ast.c:
/// # multiple (test comp_for) arguments are blocked; keyword unpackings
/// # that precede iterable unpackings are blocked; etc.
/// argument: ( test [comp_for] |
///             test '=' test |
///             '**' test |
///             '*' test )
/// 
/// comp_iter: comp_for | comp_if
/// comp_for: [ASYNC] 'for' exprlist 'in' or_test [comp_iter]
/// comp_if: 'if' test_nocond [comp_iter]
/// 
/// # not used in grammar, but may appear in "node" passed from Parser to Compiler
/// encoding_decl: NAME
/// 
/// yield_expr: 'yield' [yield_arg]
/// yield_arg: 'from' test | testlist
/// ```
/// 
pub struct PythonGrammar;