.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Marpa::R2::Scanless::DSL 3pm" .TH Marpa::R2::Scanless::DSL 3pm "2021-01-22" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "Name" .IX Header "Name" Marpa::R2::Scanless::DSL \- The \s-1DSL\s0 for the Scanless interface .SH "Synopsis" .IX Header "Synopsis" .Vb 1 \& use Marpa::R2; \& \& my $grammar = Marpa::R2::Scanless::G\->new( \& { bless_package => \*(AqMy_Nodes\*(Aq, \& source => \e(<<\*(AqEND_OF_SOURCE\*(Aq), \& :default ::= action => [values] bless => ::lhs \& lexeme default = action => [ start, length, value ] \& bless => ::name latm => 1 \& \& :start ::= Script \& Script ::= Expression+ separator => comma \& comma ~ [,] \& Expression ::= \& Number bless => primary \& | \*(Aq(\*(Aq Expression \*(Aq)\*(Aq bless => paren assoc => group \& || Expression \*(Aq**\*(Aq Expression bless => exponentiate assoc => right \& || Expression \*(Aq*\*(Aq Expression bless => multiply \& | Expression \*(Aq/\*(Aq Expression bless => divide \& || Expression \*(Aq+\*(Aq Expression bless => add \& | Expression \*(Aq\-\*(Aq Expression bless => subtract \& \& Number ~ [\ed]+ \& :discard ~ whitespace \& whitespace ~ [\es]+ \& # allow comments \& :discard ~ \& ~ | \& ~ \*(Aq#\*(Aq \& ~ \*(Aq#\*(Aq \& ~ * \& ~ [\ex{A}\ex{B}\ex{C}\ex{D}\ex{2028}\ex{2029}] \& ~ [^\ex{A}\ex{B}\ex{C}\ex{D}\ex{2028}\ex{2029}] \& END_OF_SOURCE \& } \& ); .Ve .SH "About this document" .IX Header "About this document" This is the reference document for the domain-specific language (\s-1DSL\s0) of Marpa's Scanless interface (\s-1SLIF\s0). The \s-1SLIF\s0's \s-1DSL\s0 is an extension of \s-1BNF.\s0 The \s-1SLIF DSL\s0 is used to specify other \&\s-1DSL\s0's, and is therefore a \*(L"meta-DSL\*(R". .SH "The structure of SLIF source strings" .IX Header "The structure of SLIF source strings" The \s-1SLIF\s0 source string consists of a series of rules, pseudo-rules and statements. These are made up of tokens, as described below. Whitespace separates tokens, but is otherwise ignored. .PP A hash ("\f(CW\*(C`#\*(C'\fR") character starts a comment, which continues to the end of the line. Comments are equivalent to whitespace. .SH "L0, G1 and lexemes" .IX Header "L0, G1 and lexemes" In reading this document, it is important to keep in mind the distinction, on one hand, between L0 and G1 rules and, on the other hand, between rules and lexemes. G1 rules have a semantics, which can be specified as described in this document. L0 rules simply recognize symbols in the input. L0 rules do not have a semantics. .PP Top-level L0 rules correspond to a string in the input. The top-level L0 rules are seen by G1 as lexemes, and the string to which a top-level L0 rule corresponds becomes the default value of the lexeme. The L0 grammar can be thought of as similar in behavior to a set of regular expressions with the lexemes being seen as similar to named captures. .PP Lexemes are the symbols which form the interface between G1 and L0. Lexemes, like G1 rules, have a semantics. The semantics of lexemes is specified separately from the semantics of G1 rules, as described below. .SH "Symbol names" .IX Header "Symbol names" Symbol names can be either \*(L"bare\*(R" or enclosed in angle brackets. Bare symbol names must consist entirely of Perl word characters (alphanumerics, plus the underscore). Symbol names are case-sensitive. .PP The angle brackets, if used, serve to \*(L"quote\*(R" the symbol name, and will not be part of the explicit symbol name. .PP If angle brackets are used, symbol names may also contain whitespace, as in .PP .Vb 1 \& .Ve .PP A whitespace sequence inside angle brackets can include any whitespace character that is legal in Perl, including newlines. This allows very long symbol names to be line wrapped, if necessary. .PP Unlike the angle brackets, the whitespace in a bracketed symbol token \&\fBdoes\fR become part of the explicit symbol name, but it does so in a \*(L"normalized\*(R" form. Leading and trailing whitespace in the name is discarded, and all other whitespace sequences are converted to a single \s-1ASCII\s0 space character. This means that .PP .Vb 3 \& < op comma > \& \& < op comma> .Ve .PP and even .PP .Vb 2 \& .Ve .PP will all be regarded as the same symbol name. The explicit form of that symbol name is \f(CW\*(C`\*(C'\fR, except that, again, the angle brackets are for clarity, and are not part of the explicit name. .PP Explicit, reserved and internal symbol names are often displayed between angle brackets, regardless of whether the symbol was originally specified in bracketed form. .PP When a \s-1SLIF\s0 symbol needs to be referred to by name in Perl code, it is the symbol's explicit name that is used. .SH "Single-quoted strings" .IX Header "Single-quoted strings" .Vb 8 \& Expression ::= \& Number bless => primary \& | \*(Aq(\*(Aq Expression \*(Aq)\*(Aq bless => paren assoc => group \& || Expression \*(Aq**\*(Aq Expression bless => exponentiate assoc => right \& || Expression \*(Aq*\*(Aq Expression bless => multiply \& | Expression \*(Aq/\*(Aq Expression bless => divide \& || Expression \*(Aq+\*(Aq Expression bless => add \& | Expression \*(Aq\-\*(Aq Expression bless => subtract .Ve .PP .Vb 1 \& Child ~ \*(AqcHILd\*(Aq:i .Ve .PP Single quotes can be used in prioritized rules to indicate character strings. The characters inside the single quote will be matched in the input, literally and one-for-one. Single-quoted strings can contain any characters with the exception of single quotes and vertical whitespace. .PP Single-quoted strings do not allow \*(L"escaped\*(R" characters. A backslash ("\f(CW\*(C`\e\*(C'\fR") represents itself and has no effect on the interpretation of the next character. If a rule needs to match one of the forbidden characters (single quote or vertical whitespace), it must use a character class. .PP Single-quoted strings are always interpreted at the L0 level, but they may be used in either structural or lexical rules. When a single quoted string is used in a structural rule, Marpa creates a virtual L0 rule on behalf of the application. This is handy, but it does have a real disadvantage \*(-- the name of the virtual rule's \s-1LHS\s0 will be one assigned automatically by Marpa. When tracing and debugging parses and grammars, these virtual \s-1LHS\s0's can be harder for a programmer to interpret. .PP A modifier can appear after the string. It must appear immediately after the string, with no intervening whitespace. Currently only the "\f(CW\*(C`:ic\*(C'\fR\*(L" and \*(R"\f(CW\*(C`:i\*(C'\fR" modifier are availables. These have exactly the same effect \*(-- they make the string match case-insensitive. .SH "Character classes" .IX Header "Character classes" .Vb 1 \& ~ [\ex{A}\ex{B}\ex{C}\ex{D}\ex{2028}\ex{2029}] .Ve .PP .Vb 1 \& word ~ [\ew]:ic + .Ve .PP A character class in square brackets ("\f(CW\*(C`[]\*(C'\fR") can be used in a \s-1RHS\s0 alternative of a prioritized rule, a quantified rule or a discard pseudo-rule. Marpa character classes may contain anything acceptable to Perl, and follow the same escaping conventions as Perl's character classes. .PP Character classes are always interpreted at the L0 level, but they may be used in either structural or lexical rules. When a character class is used in a structural rule, Marpa creates a virtual L0 rule on behalf of the application. This is handy, but it does have a real disadvantage \*(-- the name of the virtual rule's \s-1LHS\s0 will be one assigned automatically by Marpa. When tracing and debugging parses and grammars, these virtual \s-1LHS\s0's can be harder for a programmer to interpret. .PP An implementation note: character classes are interpreted by Perl, but this involves minimal overhead when the parse is of any length. Each character class is passed to Perl to interpret exactly once and the result is memoized in a C language structure for future use. .PP The modifiers allowed after single quoted strings are also allowed allowed after character classes. Modifiers must appear immediately after the closing square bracket, with no intervening whitespace. For more details, see the section on single-quoted strings. .SH "Statements" .IX Header "Statements" The \s-1SLIF DSL\s0 consists of a series of statements. The statements are of three kinds, as indicated by their declarator: .IP "\(bu" 4 G1 rules .Sp The \s-1BNF\s0 operator ("\f(CW\*(C`::=\*(C'\fR"), coming between the \s-1LHS\s0 and the first \s-1RHS\s0 alternative of a rule, indicates that the rule is a G1 rule. .IP "\(bu" 4 L0 rules .Sp The match operator ("\f(CW\*(C`~\*(C'\fR"), coming between the \s-1LHS\s0 and the first \s-1RHS\s0 alternative of a rule, indicates a L0 rule. .IP "\(bu" 4 Global statements .Sp Global statements are signified by the assignment operator ("\f(CW\*(C`=\*(C'\fR"). The location of a statement in the \s-1DSL\s0 source will never affect the result. .PP Rules differ from statements in that the effect of a rule is sometimes lexical \*(-- that is, the effect may vary depending on the position of the rule in the \s-1DSL\s0 source. Some rules are called pseudo-rules. Pseudo-rules do not correspond to \s-1BNF\s0 rules, but instead use the rule format as a convenient way to express other information. .SH "The structure of rules" .IX Header "The structure of rules" Every rule declaration consists of, in order: .IP "\(bu" 4 A left hand side (\s-1LHS\s0). This will be a symbol or a pseudo-symbol. .IP "\(bu" 4 A declaration operator ("\f(CW\*(C`::=\*(C'\fR\*(L" or \*(R"\f(CW\*(C`~\*(C'\fR"). .IP "\(bu" 4 A right side declaration, which contains one or more \s-1RHS\s0 alternatives. Details of the right side declaration vary by the type of rule. For each type of rule, the right side declaration is described in detail below. .SH "RHS alternatives" .IX Header "RHS alternatives" The right side declaration of a rule will often contain one or more \s-1RHS\s0 alternatives. A \s-1RHS\s0 alternative is a series of \s-1RHS\s0 primaries, where a \s-1RHS\s0 primary may be a symbol name, a character class, or a single quoted string. A list of one or more adverbs is often associated with the \&\s-1RHS\s0 alternatives. Each adverb consists of a keyword, the adverb operator ("\f(CW\*(C`=>\*(C'\fR"), and the adverb's value. .PP Within an alternative, primaries may be enclosed in parentheses. A primary enclosed in parentheses is hidden from Marpa's semantics. A set of parentheses may contain more than one primary, in which case the entire sequence of primaries is hidden, as if they had been enclosed in parentheses individually. \&\*(L"Hiding\*(R" primaries in this way can be convenient for primaries whose values the semantics will ignore, perhaps because the value is constant. .PP For example, in the following rule .PP .Vb 1 \& a ::= b (\*(Aq,\*(Aq c) d action => ::first .Ve .PP there is .IP "\(bu" 4 A \s-1LHS,\s0 in this case the symbol "\f(CW\*(C`a\*(C'\fR". .IP "\(bu" 4 A declarator, "\f(CW\*(C`::=\*(C'\fR", which indicates this is a G1 rule. .IP "\(bu" 4 A \s-1RHS\s0 alternative consisting of four \s-1RHS\s0 primaries. The first \s-1RHS\s0 primary is the symbol "\f(CW\*(C`b\*(C'\fR". The second \s-1RHS\s0 primary is a short single-quoted string \f(CW\*(Aq,\*(Aq\fR. The third and fourth \s-1RHS\s0 primaries are symbols: "\f(CW\*(C`c\*(C'\fR\*(L" and \*(R"\f(CW\*(C`d\*(C'\fR\*(L". The parentheses around the second and third \s-1RHS\s0 primaries \*(R"hide" them from the semantics. Marpa's semantics will see this as a rule with only two \s-1RHS\s0 values. .IP "\(bu" 4 The adverb list associated with the \s-1RHS\s0 alternative, consisting of a single adverb. The adverb consists of its keyword "\f(CW\*(C`action\*(C'\fR\*(L", followed by the adverb operator (\*(R"\f(CW\*(C`=>\*(C'\fR\*(L"), and the adverb's value \*(R"\f(CW\*(C`::first\*(C'\fR". .PP The rule in the above example is one of a very common type: a trivial prioritized rule. A prioritized rule is one that contains one or more prioritized \s-1RHS\s0 alternatives. Prioritized rules are the only rules which may contain more than one \s-1RHS\s0 alternative, but even prioritized rules usually have only one \s-1RHS\s0 alternative. If there is only one \s-1RHS\s0 alternative, as in this case, the prioritization is \fBtrivial\fR \*(-- there is only one priority. .SS "Start rule" .IX Subsection "Start rule" .Vb 1 \& :start ::= Script .Ve .PP By default, the start symbol of the grammar is the \s-1LHS\s0 of the first G1 rule. This default can be make explicit or overriden by using an explicit start rule. The \s-1LHS\s0 of this rule is the \f(CW\*(C`:start\*(C'\fR pseudo-symbol. Only one \s-1RHS\s0 alternative is allowed. This \s-1RHS\s0 alternative must contain only one symbol name, and that symbol will be the start symbol of the G1 grammar. No adverbs should be associated with the \s-1RHS\s0 alternative. Start rules must be G1 rules. .SS "Empty rules" .IX Subsection "Empty rules" An empty rule is a rule with an empty \s-1RHS.\s0 The empty \s-1RHS,\s0 technically, is a \s-1RHS\s0 alternative, one with zero \s-1RHS\s0 primaries. The \f(CW\*(C`action\*(C'\fR and \&\f(CW\*(C`bless\*(C'\fR adverbs are allowed for the empty \s-1RHS\s0 alternative, but no others. A empty rule makes its \s-1LHS\s0 symbol a nullable symbol. .SS "Quantified rules" .IX Subsection "Quantified rules" .Vb 1 \& Script ::= Expression+ separator => comma .Ve .PP A quantified rule has only one \s-1RHS\s0 alternative, which is followed by a quantifier. The \s-1RHS\s0 alternative must consist of a single \s-1RHS\s0 primary. This \s-1RHS\s0 primary must be a symbol name or a character class. The quantifer is either a star ("\f(CW\*(C`*\*(C'\fR\*(L"), or a plus sign (\*(R"\f(CW\*(C`+\*(C'\fR") indicating, respectively, that the sequence rule has a minimum length of 0 or 1. .PP Adverbs may be associated with the \s-1RHS\s0 alternative. The adverb list must follow the quantifier. The adverbs allowed are \f(CW\*(C`action\*(C'\fR, \&\f(CW\*(C`bless\*(C'\fR, \&\f(CW\*(C`proper\*(C'\fR and \&\f(CW\*(C`separator\*(C'\fR. .SS "Prioritized rules" .IX Subsection "Prioritized rules" .Vb 8 \& Expression ::= \& Number bless => primary \& | \*(Aq(\*(Aq Expression \*(Aq)\*(Aq bless => paren assoc => group \& || Expression \*(Aq**\*(Aq Expression bless => exponentiate assoc => right \& || Expression \*(Aq*\*(Aq Expression bless => multiply \& | Expression \*(Aq/\*(Aq Expression bless => divide \& || Expression \*(Aq+\*(Aq Expression bless => add \& | Expression \*(Aq\-\*(Aq Expression bless => subtract .Ve .PP A prioritized rule contains a series of one or more \s-1RHS\s0 alternatives, separated by either the alternation operator ("\f(CW\*(C`|\*(C'\fR\*(L") or the loosen operators (\*(R"\f(CW\*(C`||\*(C'\fR"). In a typical grammar, most rules are prioritized rules, but they are often trivially prioritized, consisting of only one \s-1RHS\s0 alternative. For brevity, \s-1RHS\s0 alternatives are often called \fBalternatives\fR. .PP Each alternative may be followed by a list of associated adverbs. The \&\f(CW\*(C`action\*(C'\fR, \&\f(CW\*(C`assoc\*(C'\fR and \&\f(CW\*(C`bless\*(C'\fR adverbs are allowed. .PP The \s-1RHS\s0 alternatives in a prioritized right hand side proceed from tightest (highest) priority to loosest. The double \*(L"or\*(R" symbol ("\f(CW\*(C`||\*(C'\fR\*(L") is the \*(R"loosen\*(L" operator \*(-- the alternatives after it have a looser (lower) priority than the alternatives before it. The single \*(R"or\*(L" symbol (\*(R"\f(CW\*(C`|\*(C'\fR\*(L") is the ordinary \*(R"alternative" operator \*(-- alternatives on each side of it have the same priority. Associativity is specified using adverbs, as described below. .SS "Discard pseudo-rules" .IX Subsection "Discard pseudo-rules" .Vb 1 \& :discard ~ whitespace .Ve .PP A discard pseudo-rule is a rule whose \s-1LHS\s0 is the \f(CW\*(C`:discard\*(C'\fR pseudo-symbol, and which has only one \s-1RHS\s0 alternative. The \s-1RHS\s0 alternative must contain exactly one symbol name, called the \fBdiscarded symbol\fR. Discard pseudo-rules indicate that the discarded symbol is a top-level L0 symbol, but one which is not a lexeme. When a discarded symbol is recognized, it is not passed as a lexeme to the G1 parser, but is (as the name suggests) discarded. Discard pseudo-rules must be L0 rules. No adverbs are allowed. .SS "Default pseudo-rules" .IX Subsection "Default pseudo-rules" .Vb 1 \& :default ::= action => [values] bless => ::lhs .Ve .PP .Vb 1 \& :default ::= action => [lhs, values ] .Ve .PP The purpose of the default pseudo-rule is to change the defaults for rule adverbs. Technically, it has one \s-1RHS\s0 alternative, but this must always contain zero \s-1RHS\s0 primaries. Default pseudo-rules do not affect the defaults for L0 rules or for lexemes. There may be more than one default pseudo-rule. The scope of default pseudo-rules is lexical, applying only to rules that appear afterwards in the \s-1DSL\s0 source. .PP Currently only the \f(CW\*(C`action\*(C'\fR and \f(CW\*(C`bless\*(C'\fR adverbs can be specified in a default pseudo-rule. Each default pseudo-rule creates a completely new set of defaults \*(-- if an adverb is not specified, the default is reset to its implicit value, the value which it had prior to any explicit settings. .SS "Lexeme pseudo-rules" .IX Subsection "Lexeme pseudo-rules" .Vb 1 \& :lexeme ~ priority => 1 .Ve .PP The purpose of the \f(CW\*(C`:lexeme\*(C'\fR pseudo-rule is to allow adverbs to change the treatment of a lexeme. This pseudo-rule always has exactly one \s-1RHS\s0 alternative, and that \s-1RHS\s0 alternative must contain exactly one symbol. This \s-1RHS\s0 symbol identifies the lexeme which the adverbs will affect. The only adverbs allowed in a \f(CW\*(C`:lexeme\*(C'\fR rule are \&\f(CW\*(C`event\*(C'\fR, \&\f(CW\*(C`pause\*(C'\fR, and \&\f(CW\*(C`priority\*(C'\fR. .PP As a side effect, a \f(CW\*(C`:lexeme\*(C'\fR pseudo-rule declares that its \s-1RHS\s0 symbol is expected to be a lexeme. This declaration does not \*(L"force\*(R" lexeme status \*(-- if the symbol does not meet the criteria for a lexeme based on its use in L0 and G1 rules, the result will be a fatal error. Applications may find this ability to \*(L"declare\*(R" lexemes useful for debugging, and for documenting grammars. .SS "Lexeme default statement" .IX Subsection "Lexeme default statement" .Vb 2 \& lexeme default = action => [ start, length, value ] \& bless => ::name latm => .Ve .PP .Vb 1 \& lexeme default = action => [ lhs, value ] .Ve .PP The lexeme default statement changes the defaults for lexeme adverbs. It only changes the defaults for lexemes, and does not affect rules. Only the defaults for the \f(CW\*(C`action\*(C'\fR, \&\f(CW\*(C`bless\*(C'\fR, and \f(CW\*(C`latm\*(C'\fR adverbs can be specified in a lexeme default statement. Only one lexeme default statement is allowed in a grammar. .SS "Named event statement" .IX Subsection "Named event statement" .Vb 1 \& event subtext = completed .Ve .PP .Vb 1 \& event \*(AqA[]\*(Aq = nulled .Ve .PP .Vb 1 \& event \*(Aq^a\*(Aq = predicted A .Ve .PP The named event statement sets up a symbol so that a named event is triggered when some condition occurs at a location. Named events can be defined to occur when a symbol is predicted, when a symbol is completed, or when a symbol is nulled. .PP A \*(L"completed\*(R" event occurs whenever a rule with that symbol on its \s-1LHS\s0 is fully recognized in the parse. (The idea is that \*(L"symbol completion\*(R" occurs when the rule, and therefore its \s-1LHS,\s0 is \*(L"complete\*(R".) For the purpose of \*(L"completed\*(R" events, a nulled symbol is not considered \*(L"complete\*(R", and \*(L"completed\*(R" events will not be triggered for a zero-length instance of a symbol. .PP A \*(L"nulled\*(R" event occurs whenever a zero-length symbol instance is recognized. Null symbols may derive other null symbols, and these derivations may be ambiguous. Ambiguous or not, all such derivations cause \*(L"nulled\*(R" events. Again, nulled events and completed events are mutually exclusive \*(-- a nulled, or zero-length, symbol is not considered \&\*(L"complete\*(R" for this purpose. .PP A \*(L"predicted\*(R" event occurs at any location where a non-zero length symbol would be accepted by the recognizer. It can be thought of as occurring when a symbol is \*(L"expected\*(R". The expectation may or may not come true, depending on future input. Because there is no physical distinction between expecting a zero-length symbol, and actually seeing one, \&\*(L"predicted\*(R" events are not generated for symbols which are only expected in zero-length form. .PP Completed and nulled events may not be defined for symbols that are lexemes, but lexemes are allowed to be predicted events. A predicted event which is a lexeme is different from a lexeme pause. The lexeme pause will not occur unless that the lexeme is actually found in the input. A predicted event, on the other hand, is as the name suggests, only a prediction. The predicted symbol may or not actually be found in the input. .PP The name of an event may be either a bare name, or enclosed in single quotes. A bare event name must be one or more word characters, starting with an alphabetic character. A single quoted event name may contain any character except a single quote or vertical space. The whitespace in single quoted event names is normalized in similar fashion to the normalization of symbol names \*(-- leading and trailing whitespace is removed, and all sequences of internal whitespace are changed to a single \s-1ASCII\s0 space character. Names containing single quotes (which, in any case, are impossible to add using current syntax) are reserved. .PP Named completion events can occur during the the Scanless recognizer's \fBread()\fR, \&\fBresume()\fR, \&\fBlexeme_complete()\fR, and \fBlexeme_read()\fR methods. When they occur in the Scanless recognizer's \fBread()\fR, and \fBresume()\fR methods, they pause internal scanning. Named events may be queried using the Scanless recognizer's \fBevent()\fR method. .SS "Inaccessible symbol statement" .IX Subsection "Inaccessible symbol statement" .Vb 1 \& inaccessible is ok by default .Ve .PP .Vb 1 \& inaccessible is fatal by default .Ve .PP Inaccessible symbols are symbols which cannot be reached from the start symbol. Often, they are the result of an error in grammar writing. But inaccessible symbols can also occur for legitimate reasons \*(-- for example, you may have rules and symbols in grammar intended for future use. .PP The default can be specified or changed with a statement of the form: .PP .Vb 1 \& inaccessible is TREATMENT by default .Ve .PP where \f(CW\*(C`TREATMENT\*(C'\fR is one of \f(CW\*(C`warn\*(C'\fR, \f(CW\*(C`ok\*(C'\fR, or \f(CW\*(C`fatal\*(C'\fR. .PP \&\f(CW\*(C`fatal\*(C'\fR indicates that an inaccessible symbol should be a fatal error. \&\f(CW\*(C`warn\*(C'\fR indicates that Marpa should print a warning message, but proceed with the parse. \&\f(CW\*(C`warn\*(C'\fR is the default. \&\f(CW\*(C`ok\*(C'\fR indicates that the parse should proceed without warning messages. .SH "Ambiguity" .IX Header "Ambiguity" Marpa parses ambiguous grammars and the design of the \s-1SLIF\s0 exploits this. A flexible, but potentially ambiguous, syntax is used. Actual ambiguities are obvious to the human eye, and users will create them, so that the techniques of this section will rarely be needed. .PP If and when an actual ambiguity does occur, an error message reports the ambiguity and its exact location. It will always be possible to disambiguate a \s-1SLIF DSL,\s0 and there will always be more than one way to do this. .SS "Separating statements with semicolons" .IX Subsection "Separating statements with semicolons" .Vb 4 \& :default ::= action => ::array \& quartet ::= a a a a; \& inaccessible is warn by default \& a ~ \*(Aqa\*(Aq .Ve .PP A statement may be terminated with a semicolon ("\f(CW\*(C`;\*(C'\fR"). .SS "Grouping statements in curly braces" .IX Subsection "Grouping statements in curly braces" .Vb 6 \& { \& :default ::= action => ::array \& quartet ::= a a a a \& } \& inaccessible is warn by default \& a ~ \*(Aqa\*(Aq .Ve .PP Statements can be grouped, using curly braces. These do \fBnot\fR create scopes \*(-- the curly braces serve merely to group and to separate groups of statements. .SS "Other ways to disambiguate" .IX Subsection "Other ways to disambiguate" There are many other ways to disambiguate \s-1SLIF\s0 statements. If the ambiguity is between keywords and symbol names, enclosing a symbol name in angle brackets will force it to be treated only as a symbol name. And while it is never necessary, statements can be re-ordered. .SH "Adverbs" .IX Header "Adverbs" Adverbs consist of a keyword, the adverb operator ("\f(CW\*(C`=>\*(C'\fR"), and the adverb's value. The keyword must be one of those described in this section. The adverb's value must be as described for each keyword. .SS "action" .IX Subsection "action" The \f(CW\*(C`action\*(C'\fR adverb is allowed for .IP "\(bu" 4 An \s-1RHS\s0 alternative, in which the action is for the alternative. .IP "\(bu" 4 The default pseudo-rule, in which case the action is for all rules which do not have their own action explicitly specified. .IP "\(bu" 4 The lexeme default statement, in which case the action is for all lexemes. .PP The \f(CW\*(C`action\*(C'\fR adverb is not allowed for L0 rules. The possible values of actions are described, along with other details of the semantics, in a separate document. .SS "assoc" .IX Subsection "assoc" The \f(CW\*(C`assoc\*(C'\fR adverb is only valid in a prioritized rule. Its value must be one of \&\f(CW\*(C`left\*(C'\fR, \&\f(CW\*(C`right\*(C'\fR or \&\f(CW\*(C`group\*(C'\fR. Its effect will be as described below. .SS "bless" .IX Subsection "bless" The \f(CW\*(C`bless\*(C'\fR adverb causes the result of the semantics to be blessed into the class indicated by the value of the adverb. Details of its use may be found in the semantics document. .SS "event" .IX Subsection "event" .Vb 4 \& :lexeme ~ pause => before event => \*(Aqbefore a\*(Aq \& :lexeme ~ pause => after event => \*(Aqafter b\*(Aq \& :lexeme ~ pause => before event => \*(Aqbefore c\*(Aq \& :lexeme ~ pause => after event => \*(Aqafter d\*(Aq .Ve .PP The \f(CW\*(C`event\*(C'\fR adverb applies only to lexemes and is only allowed in a \f(CW\*(C`:lexeme\*(C'\fR pseudo-rule. It turns a lexeme's pause into a named event, using the name specified as its value. Applications are encouraged to turn all lexeme pause's into named events, using the \f(CW\*(C`event\*(C'\fR adverb. The allowed event names are as described for the named event statement. .PP It is a fatal error to specify the \f(CW\*(C`event\*(C'\fR adverb if the \f(CW\*(C`pause\*(C'\fR adverb is not also specified. .SS "forgiving" .IX Subsection "forgiving" .Vb 1 \& :lexeme ~ forgiving => 1 .Ve .PP The forgiving adverb is a synonym for the \f(CW\*(C`latm\*(C'\fR adverb. .SS "latm" .IX Subsection "latm" .Vb 1 \& :lexeme ~ value latm => 1 .Ve .PP The \f(CW\*(C`latm\*(C'\fR adverb applies only to lexemes and is only allowed in a \f(CW\*(C`:lexeme\*(C'\fR pseudo-rule and a \f(CW\*(C`lexeme default\*(C'\fR statement. Its value is a boolean. If the boolean is set it indicates that a token is \s-1LATM. A\s0 value of 1 is recommended, which indicates that a token is \s-1LATM.\s0 The default value is 0, for reasons of backward compatibility. .PP \&\s-1LATM\s0 means \*(L"longest acceptable tokens match\*(R". In this, the lexer find those tokens that are the longest that would be accepted by the G1 grammar. There may be more than one such \*(L"longest\*(R" acceptable token, in which case, the lexing will be ambiguous, and the parse will use all of the matching tokens. .PP The alternative to \s-1LATM,\s0 and the default, is the \*(L"longest tokens match\*(R" (\s-1LTM\s0) discipline. \&\s-1LTM\s0 is similar to \s-1LATM,\s0 except that it takes no account of whether a token would be acceptable to the G1 grammar. This makes it possible that \s-1LTM\s0 will find one or more lexemes that are a longest match, and none of them will be acceptable to G1. When that happens, the parse fails with an error message. This failure occurs even if shorter lexemes would have been found using \s-1LATM,\s0 lexemes which would have been acceptable to the G1 grammar. This means that matching succeeds more often under \s-1LATM\s0 than under \s-1LTM.\s0 .PP Intuitively, \s-1LATM\s0 is a longest tokens match that considers context, while \s-1LTM\s0 is a longest tokens match that ignores context. \&\s-1LATM\s0 is usually preferable. Usually if \s-1LATM\s0 is chosen, a parse will want to use the a \f(CW\*(C`lexeme default\*(C'\fR statement and use \s-1LATM\s0 globally. It is possible to use \s-1LATM\s0 adverb on a lexeme by lexeme basis. When that is done, the lexemes marked \&\s-1LATM\s0 will match only if acceptable to the G1 grammar, and the lexemes not marked \s-1LATM\s0 will match regardless of their acceptability to the G1 grammar. .PP Whichever token discipline is chosen, all tokens matched will be of the same length. Shorter tokens will not be considered. .PP \&\s-1LTM\s0 is the default for historical reasons. \&\s-1LTM\s0 was the \s-1SLIF\s0's original token matching discipline because it more closely models traditional lexing. Also for historical reasons, \s-1LATM\s0 lexemes are sometimes called \*(L"forgiving\*(R" \*(-- in the original implementation, an \&\s-1LTM\s0 search was always done for all lexemes, and \s-1LATM\s0 was implemented by \*(L"forgiving\*(R" rejection by the G1 grammar, and backing up over the input to find acceptable lexemes. Marpa now does \s-1LATM\s0 far more efficiently \*(-- the G1 grammar indicates to the lexer, in advance, which lexemes are acceptable, and the lexer searches only for those. .SS "name" .IX Subsection "name" .Vb 3 \& start ::= number1 number2 name => top \& number1 ::= name => \*(Aqnumber 1\*(Aq \& number2 ::= name => \*(Aqnumber 2\*(Aq .Ve .PP The \f(CW\*(C`name\*(C'\fR adverb applies only to rules and rule alternatives. When specified, it defines a name for that rule alternative. .SS "null-ranking" .IX Subsection "null-ranking" .Vb 1 \& S ::= A A A A null\-ranking => high .Ve .PP The \f(CW\*(C`null\-ranking\*(C'\fR adverb applies only to G1 rules (L0 rules do not have a semantics) and is ignored unless the \s-1SLIF\s0 recognizer's \f(CW\*(C`ranking_method\*(C'\fR named argument is set to something other than its default. Some rule alternatives can match the same input in several ways, depending on which symbols are nulled. These different ways of nulling symbols in a rule are called its null variants. The \f(CW\*(C`null\-ranking\*(C'\fR named argument allows the application to control the order in which null variants are returned by the \f(CW\*(C`value()\*(C'\fR method. .PP If \f(CW\*(C`null\-ranking\*(C'\fR is undefined, the order of the null variants will be arbitrary. This is the default, and is acceptable to most applications. For details on using the \&\f(CW\*(C`null\-ranking\*(C'\fR adverb, see the document on parse order. .SS "pause" .IX Subsection "pause" .Vb 4 \& :lexeme ~ pause => before event => \*(Aqbefore a\*(Aq \& :lexeme ~ pause => after event => \*(Aqafter b\*(Aq \& :lexeme ~ pause => before event => \*(Aqbefore c\*(Aq \& :lexeme ~ pause => after event => \*(Aqafter d\*(Aq .Ve .PP The \f(CW\*(C`pause\*(C'\fR adverb applies only to lexemes and is only allowed in a \f(CW\*(C`:lexeme\*(C'\fR pseudo-rule. Pauses take effect during the Scanless recognizer's \fBread()\fR and \fBresume()\fR methods. They cause internal scanning to be suspended, or \*(L"paused\*(R", before or after the specified lexeme. Internal scanning can be resumed with the Scanless recognizer's \fBresume()\fR method. .PP Applications are encouraged to name every lexeme pause using the event adverb. If this is done, lexeme pauses can be queried using the \&\s-1SLIF\s0 recognizer's \&\fBevents()\fR method. Unnamed lexeme pauses must be queried using the \&\s-1SLIF\s0 recognizer's \&\fBpause_lexeme()\fR method. .PP If the value of pause is \f(CW\*(C`before\*(C'\fR, Marpa will \*(L"pause\*(R" internal scanning before that lexeme. No lexemes will be read at that position. .PP If the value of pause is \f(CW\*(C`after\*(C'\fR, all applicable lexemes at that position will be read by G1, and internal scanning will pause immediately afterwards. .PP A lexeme pause event does not occur, and has no effect, if .IP "\(bu" 4 It is deactivated. Deactivation and reactivation of events is done with the \s-1SLIF\s0 recognizer's \&\fBactivate()\fR method .IP "\(bu" 4 The G1 grammar would reject that lexeme at that location. .IP "\(bu" 4 It has a lexeme priority lower than the highest lexeme priority. .IP "\(bu" 4 At the same priority, it has a pause value of \f(CW\*(C`after\*(C'\fR, when another lexeme pause occurs which has a pause value of \f(CW\*(C`before\*(C'\fR. In other words, pausing before a lexeme prevents Marpa from pausing after another lexeme at the same location. .PP Even with the above restrictions, there can be more than one lexeme pause event at a location. The \&\fBpause_lexeme()\fR method will return only one of them, chosen arbitrarily, whereas the \&\fBevents()\fR method will return all of the named events. This is one of the reasons that applications are strongly encouraged to specify a name for every lexeme pause event using the \f(CW\*(C`event\*(C'\fR adverb. .SS "priority" .IX Subsection "priority" The \f(CW\*(C`priority\*(C'\fR adverb is only allowed in a \f(CW\*(C`:lexeme\*(C'\fR pseudo-rule. It sets the lexeme priority for the lexeme. The priority must be an integer, but it may be negative. An increase in numerical value means a higher priority. For example, a priority of 1 is greater than a priority of 0. A priority of 0, in turn, is greater than a priority of \-1. The default priority is zero. .PP Where more than one lexeme can be accepted at a location, the lexeme priority limits the lexemes that will be considered. Only lexemes with the highest priority are considered. If several lexemes have the same priority, all of them will be accepted. .PP The only effect of the lexeme priority is on the choice of lexemes when .IP "\(bu" 4 all of them would be accepted; .IP "\(bu" 4 all started at the same string location; .IP "\(bu" 4 all end at the same string location; and therefore .IP "\(bu" 4 all have the same length. .PP Lexeme priorities only have an effect when lexemes are accepted. The intent of this scheme is to avoid situations where a lexeme with a high priority is rejected, and causes a parse to fail, even though another lower priority lexeme is acceptable and would allow the parse to continue. .PP For example, suppose that "\f(CW\*(C`say\*(C'\fR" can be both a keyword (\f(CW\*(C`\*(C'\fR), and a variable name (\f(CW\*(C`\*(C'\fR). Suppose further that the grammar specifies that \f(CW\*(C`\*(C'\fR has a priority of 1, and \f(CW\*(C`\*(C'\fR is left at the default priority of 0. When L0 finds a occurrence of "\f(CW\*(C`say\*(C'\fR", where both the \f(CW\*(C`say\*(C'\fR keyword and a variable name would be accepted by G1, then only the \f(CW\*(C`say\*(C'\fR keyword is read by G1, because of the priorities. .PP But, suppose instead that the parse is at a location where G1 is not accepting the \f(CW\*(C`\*(C'\fR. Since only lexeme priorites of acceptable lexemes are considered, \&\f(CW\*(C`\*(C'\fR lexeme has the highest priority, and the literal string "\f(CW\*(C`say\*(C'\fR" will be read as a \&\f(CW\*(C`\*(C'\fR token. .SS "proper" .IX Subsection "proper" The \f(CW\*(C`proper\*(C'\fR keyword is only valid for a quantified right side, and its value must be a boolean, in the form of a binary digit (\f(CW0\fR or \f(CW1\fR). It is only relevant is a separator is defined and is 1 if proper separation is required, and 0 if Perl separation is allowed. \&\*(L"Perl separation\*(R" allows a final separator. \&\*(L"Proper separation\*(R" is so called, because it requires that separators be \*(L"proper\*(R" in the sense that they must actually separate sequence items. .SS "rank" .IX Subsection "rank" .Vb 2 \& unspecial ::= (\*(AqI\*(Aq \*(Aqam\*(Aq \*(Aqspecial\*(Aq) words (\*(Aq\-\-\*(Aq \*(AqNOT!\*(Aq \*(Aq;\*(Aq) rank => 1 \& special ::= words (\*(Aq;\*(Aq) rank => \-1 .Ve .PP \&\f(CW\*(C`rank\*(C'\fR is ignored unless the recognizer's \f(CW\*(C`ranking_method\*(C'\fR named argument is set to something other than its default. The range allowed for \f(CW\*(C`rank\*(C'\fR is implementation-defined, but numbers in the range between \-134,217,727 and 134,217,727 will always be allowed. \&\f(CW\*(C`rank\*(C'\fR is 0 by default. For details on using the \&\f(CW\*(C`rank\*(C'\fR named argument, see the document on parse order. .SS "separator" .IX Subsection "separator" The \f(CW\*(C`separator\*(C'\fR keyword is only valid for a quantified right side, and its value must be a single symbol \*(-- either a single symbol name, or a character class. If specified, the separator must separate items of the sequence. A separator may not be nullable. .SH "Precedence" .IX Header "Precedence" Marpa's precedence is a generalization beyond the traditional ideas of precedence. Traditional precedence parsing required the classification of operators as postfix, infix, etc. Marpa's precedence parsing is \s-1NOT\s0 based on the special treatment of operators. .PP For the purpose of precedence, an operand is an occurrence in a \s-1RHS\s0 alternative of the \s-1LHS\s0 symbol. An operator is considered to be anything that is not an operand. The arity of an alternative is the number of operands that it contains. All arities are allowed, from zero to the arbitrary number imposed by system limits such as memory and file size. .PP For example, in the synopsis, the \s-1LHS\s0 symbol is \&\f(CW\*(C`Expression\*(C'\fR. The alternative .PP .Vb 1 \& () Expression () .Ve .PP contains one occurrence of \f(CW\*(C`Expression\*(C'\fR and therefore has an arity of one. The \f(CW\*(C`\*(C'\fR and \f(CW\*(C`\*(C'\fR are considered operators. .PP In the \s-1RHS\s0 alternative .PP .Vb 1 \& Expression () Expression .Ve .PP \&\f(CW\*(C`Expression\*(C'\fR occurs twice, and therefore the arity is 2. \&\f(CW\*(C`\*(C'\fR is considered to be an operator. .PP Because for this purpose an operator is defined as anything that is not an operand, Marpa treats some symbols as operators that would not be considered operators in the traditional approach. For example, in the \s-1RHS\s0 alternative .PP .Vb 1 \& Number .Ve .PP there are no occurrences of \f(CW\*(C`Expression\*(C'\fR, so that the alternative has an arity of zero \*(-- it is nullary. The symbol \f(CW\*(C`Number\*(C'\fR is considered to be an operator. .PP An alternative with arity 0 is nullary. Precedence and associativity are meaningless in this case and will be ignored. .PP An alternative with arity 1 is unary. Precedence will have effect, but left and right associativity will not. .PP An alternative with arity 2 is binary. Precedence will have effect, and left and right associativity will behave in the traditional way. The traditional behavior for binary alternatives is exactly as described next for the \fIN\fR\-ary case. .PP An alternative with an arity of \fIN\fR, where \fIN\fR is 2 or greater, is \fIN\fR\-ary. Precedence will have effect. For left associativity, only the leftmost operand of an \fIN\fR\-ary alternative associates \*(-- operands after the first will have the next-tightest priority level. For right associativity, only the rightmost operand of an \fIN\fR\-ary alternative associates \*(-- all operands except the last will have the next-tightest priority level. .PP Marpa also allows \*(L"group\*(R" associativity. In \*(L"group\*(R" associativity, all operands associate at the loosest (lowest) priority. That is, in an alternative with group associativity, each operand may be a full expression of the kind defined by the prioritized rule. \&\*(L"Group\*(R" associativity is used, for example, in implementing the traditional function of parentheses in Marpa. Group associativity is meaningless for nullary alternatives, and is ignored. .SS "Precedence and ambiguous grammars" .IX Subsection "Precedence and ambiguous grammars" Marpa's generalization of precedence works for all grammars that can be defined by prioritized rules. It is efficient (linear) for all grammars that could be parsed by the traditional precedence parsing methods. Marpa also allows you to define alternatives not allowed by traditional methods. Many of these are useful, and most of the useful ones can be parsed efficiently. .PP Because of the many forms of recursion allowed, it is possible to define highly ambiguous grammars using the precedence mechanism. This can occur even by accident. .PP The user should especially be careful with right hand side alternatives in which all the symbols are operands. These can be useful. For example, an implicit operation can be defined using a binary alternative with no non-operands, and this could implement, for example, the standard notation for concatenation or multiplication. But to do this efficiently requires either avoiding ambiguity, or controlling its use carefully. .PP Marpa does catch the case where an alternative consists only of a single operand \*(-- a \*(L"unit rule\*(R". This causes a fatal error. Unit rules are easy to define by accident in the \s-1SLIF.\s0 The author knows of no practical use for them, and their presence in a grammar is usually unintentional. Note that, in the event an application does find a use for a grammar with unit rules, the \s-1NAIF\s0 and the Thin interface can parse it. .SH "Copyright and License" .IX Header "Copyright and License" .Vb 5 \& Copyright 2014 Jeffrey Kegler \& This file is part of Marpa::R2. Marpa::R2 is free software: you can \& redistribute it and/or modify it under the terms of the GNU Lesser \& General Public License as published by the Free Software Foundation, \& either version 3 of the License, or (at your option) any later version. \& \& Marpa::R2 is distributed in the hope that it will be useful, \& but WITHOUT ANY WARRANTY; without even the implied warranty of \& MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU \& Lesser General Public License for more details. \& \& You should have received a copy of the GNU Lesser \& General Public License along with Marpa::R2. If not, see \& http://www.gnu.org/licenses/. .Ve