| 1 |
|
| 2 |
|
| 3 |
<html> |
| 4 |
<head> |
| 5 |
<title>parser</title> |
| 6 |
<link rel="stylesheet" href="doc.css" type="text/css"/> |
| 7 |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> |
| 8 |
</head> |
| 9 |
<body> |
| 10 |
|
| 11 |
<div id="container"> |
| 12 |
|
| 13 |
<div id="product"> |
| 14 |
<p/> |
| 15 |
<div id="product_logo"> |
| 16 |
<a href="http://www.lua.org"> <img alt="Lua logo" src="lua.gif"/> </a> |
| 17 |
</div> |
| 18 |
<div id="product_name"><big><strong>parser</strong></big></div> |
| 19 |
<div id="product_description"> Lua 5.1 parser </div> |
| 20 |
<br/> |
| 21 |
|
| 22 |
<div id="product_description"> <small><em> <b>Version:</b> 0.1.2 </em></small></div> |
| 23 |
<div id="product_description"> <small><em><b>Generated:</b> November 26, 2007 </em></small> </div> |
| 24 |
|
| 25 |
</div> <!-- id="product" --> |
| 26 |
|
| 27 |
<div id="main"> |
| 28 |
|
| 29 |
<div id="navigation"> |
| 30 |
<h1><a href="index.html">Modules</a></h1> |
| 31 |
<ul> |
| 32 |
<li><a href="grammar.html">grammar</a></li> |
| 33 |
<li><a href="parser.html">parser</a></li> |
| 34 |
<li><a href="scanner.html">scanner</a></li> |
| 35 |
</ul> |
| 36 |
<br/> |
| 37 |
<h1>parser</h1> |
| 38 |
<ul> |
| 39 |
|
| 40 |
<!-- |
| 41 |
<li><a href="#section_Description"> Description </a> |
| 42 |
|
| 43 |
</li> |
| 44 |
--> |
| 45 |
<li><a href="#section_Description"> Description </a> |
| 46 |
</li> |
| 47 |
|
| 48 |
<!-- |
| 49 |
<li><a href="#section_Dependencies"> Dependencies </a> |
| 50 |
|
| 51 |
</li> |
| 52 |
--> |
| 53 |
<li><a href="#section_Dependencies"> Dependencies </a> |
| 54 |
</li> |
| 55 |
|
| 56 |
<!-- |
| 57 |
<li><a href="#section_The_Grammar"> The Grammar </a> |
| 58 |
|
| 59 |
</li> |
| 60 |
--> |
| 61 |
<li><a href="#section_The_Grammar"> The Grammar </a> |
| 62 |
</li> |
| 63 |
|
| 64 |
|
| 65 |
<li><a href="#variables"> Variables </a> |
| 66 |
<ul> |
| 67 |
|
| 68 |
<li><code><a href="#variable_rules"> rules </a></code></li> |
| 69 |
|
| 70 |
</ul> |
| 71 |
</li> |
| 72 |
|
| 73 |
|
| 74 |
<li><a href="#functions"> Functions </a> |
| 75 |
<ul> |
| 76 |
|
| 77 |
<li><code><a href="#function_apply"> apply </a></code></li> |
| 78 |
|
| 79 |
<li><code><a href="#function_check"> check </a></code></li> |
| 80 |
|
| 81 |
</ul> |
| 82 |
</li> |
| 83 |
|
| 84 |
|
| 85 |
</ul> |
| 86 |
</div> <!-- id="navigation" --> |
| 87 |
|
| 88 |
<div id="content"> |
| 89 |
|
| 90 |
|
| 91 |
|
| 92 |
<p/> |
| 93 |
|
| 94 |
|
| 95 |
<p/> |
| 96 |
<h1><a name="section_Description"></a>Description</h1> |
| 97 |
<p/> |
| 98 |
Pairing with <a href="scanner.html">scanner</a>, this module exports Lua 5.1's syntactic rules as a grammar. |
| 99 |
<p/> |
| 100 |
<h1><a name="section_Dependencies"></a>Dependencies</h1> |
| 101 |
<ul> |
| 102 |
<li><a href="http://www.inf.puc-rio.br/~roberto/lpeg.html">LPeg</a>; </li> |
| 103 |
<li><a href="grammar.html">grammar</a>; and </li> |
| 104 |
<li><a href="scanner.html">scanner</a>.</li></ul> |
| 105 |
<p/> |
| 106 |
<h1><a name="section_The_Grammar"></a>The Grammar</h1> |
| 107 |
<p/> |
| 108 |
The <a href="#variable_rules">rules</a> variable implements the official <a href="http://www.lua.org/manual/5.1/manual.html#8">Lua 5.1 grammar</a>. It includes all keyword and symbol rules in <a href="scanner.html">scanner</a>, as well as the <code>CHUNK</code> rule, which matches a complete Lua source file. |
| 109 |
<p/> |
| 110 |
<a href="#variable_rules">rules</a> is a table with <a href="http://www.inf.puc-rio.br/~roberto/lpeg.html#grammar">open references</a>, not yet a LPeg pattern; to create a pattern, it must be given to <code><a href="http://www.inf.puc-rio.br/~roberto/lpeg.html#lpeg">lpeg.P</a></code>. This is done to enable users to modify the grammar to suit their particular needs. <a href="grammar.html">grammar</a> provides a small API for this purpose. |
| 111 |
<p/> |
| 112 |
The code below shows the Lua 5.1 grammar in LPeg, minus spacing issues. |
| 113 |
<p/> |
| 114 |
The following convention is used for rule names:<ul> |
| 115 |
<li><strong>TOKENRULE</strong>: token rules (which represent terminals) are in upper case when applicable (ex. <code>+, WHILE, NIL, ..., THEN, {, ==</code>).</li> |
| 116 |
<li><strong>GrammarRule</strong>: the main grammar rules (non-terminals): Examples are <code>Chunk</code>, <code>FuncName</code>, <code>BinOp</code>, and <code>TableConstructor</code>.</li> |
| 117 |
<li><strong>_GrammarRule</strong>: subdivisions of the main rules, introduced to ease captures. Examples are <code>_SimpleExp</code>, <code>_PrefixExpParens</code> and <code>_FieldExp</code>.</li> |
| 118 |
<li><strong>METARULE</strong>: grammar rules with a special semantic meaning, to be used for capturing in later modules, like <code>BOF</code>, <code>EOF</code> and <code>EPSILON</code>.</li></ul> |
| 119 |
<p/> |
| 120 |
<pre class="example"> |
| 121 |
rules = { |
| 122 |
<font color="#808080"> -- See peculiarities below</font> |
| 123 |
IGNORED = scanner.IGNORED <font color="#808080"> -- used as spacing, not depicted below</font> |
| 124 |
EPSILON = <b>lpeg.P</b>(<font color="#0000FF"><b>true</b></font>) |
| 125 |
EOF = scanner.EOF <font color="#808080"> -- end of file</font> |
| 126 |
BOF = scanner.BOF <font color="#808080"> -- beginning of file</font> |
| 127 |
Name = ID |
| 128 |
|
| 129 |
<font color="#808080"> -- Default initial rule</font> |
| 130 |
[<font color="#B00000"><i>1</i></font>] = CHUNK |
| 131 |
CHUNK = scanner.BANG^-<font color="#B00000"><i>1</i></font> * Block |
| 132 |
|
| 133 |
Chunk = (Stat * <font color="#008000">';'</font>^-<font color="#B00000"><i>1</i></font>)^<font color="#B00000"><i>0</i></font> * (LastStat * <font color="#008000">';'</font>^-<font color="#B00000"><i>1</i></font>)^-<font color="#B00000"><i>1</i></font> |
| 134 |
Block = Chunk |
| 135 |
|
| 136 |
<font color="#808080"> -- STATEMENTS</font> |
| 137 |
Stat = Assign + FunctionCall + Do + While + Repeat + If |
| 138 |
+ NumericFor + GenericFor + GlobalFunction + LocalFunction |
| 139 |
+ LocalAssign |
| 140 |
Assign = VarList * <font color="#008000">'='</font> * ExpList |
| 141 |
Do = <font color="#008000">'do'</font> * Block * <font color="#008000">'end'</font> |
| 142 |
While = <font color="#008000">'while'</font> * Exp * <font color="#008000">'do'</font> * Block * <font color="#008000">'end'</font> |
| 143 |
Repeat = <font color="#008000">'repeat'</font> * Block * <font color="#008000">'until'</font> * Exp |
| 144 |
If = <font color="#008000">'if'</font> * Exp * <font color="#008000">'then'</font> * Block |
| 145 |
* (<font color="#008000">'elseif'</font> * Exp * <font color="#008000">'then'</font> * Block)^<font color="#B00000"><i>0</i></font> |
| 146 |
* ((<font color="#008000">'else'</font> * Block) + EPSILON) |
| 147 |
* <font color="#008000">'end'</font> |
| 148 |
NumericFor = <font color="#008000">'for'</font> * Name * <font color="#008000">'='</font> |
| 149 |
* Exp * <font color="#008000">','</font> * Exp * ((<font color="#008000">','</font> * Exp) + EPSILON) |
| 150 |
* <font color="#008000">'do'</font> * Block * <font color="#008000">'end'</font> |
| 151 |
GenericFor = <font color="#008000">'for'</font> * NameList * <font color="#008000">'in'</font> * ExpList * <font color="#008000">'do'</font> * Block * <font color="#008000">'end'</font> |
| 152 |
GlobalFunction = <font color="#008000">'function'</font> * FuncName * FuncBody |
| 153 |
LocalFunction = <font color="#008000">'local'</font> * <font color="#008000">'function'</font> * Name * FuncBody |
| 154 |
LocalAssign = <font color="#008000">'local'</font> * NameList * (<font color="#008000">'='</font> * ExpList)^-<font color="#B00000"><i>1</i></font> |
| 155 |
LastStat = <font color="#008000">'return'</font> * ExpList^-<font color="#B00000"><i>1</i></font> |
| 156 |
+ <font color="#008000">'break'</font> |
| 157 |
|
| 158 |
<font color="#808080"> -- LISTS</font> |
| 159 |
VarList = Var * (<font color="#008000">','</font> * Var)^<font color="#B00000"><i>0</i></font> |
| 160 |
NameList = Name * (<font color="#008000">','</font> * Name)^<font color="#B00000"><i>0</i></font> |
| 161 |
ExpList = Exp * (<font color="#008000">','</font> * Exp)^<font color="#B00000"><i>0</i></font> |
| 162 |
|
| 163 |
<font color="#808080"> -- EXPRESSIONS</font> |
| 164 |
Exp = _SimpleExp * (BinOp * _SimpleExp)^<font color="#B00000"><i>0</i></font> |
| 165 |
_SimpleExp = <font color="#008000">'nil'</font> + <font color="#008000">'false'</font> + <font color="#008000">'true'</font> + Number + String + <font color="#008000">'...'</font> + Function |
| 166 |
+ _PrefixExp + TableConstructor + (UnOp * _SimpleExp) |
| 167 |
_PrefixExp = ( Name a Var |
| 168 |
+ _PrefixExpParens only an expression |
| 169 |
) * ( |
| 170 |
_PrefixExpSquare a Var |
| 171 |
+ _PrefixExpDot a Var |
| 172 |
+ _PrefixExpArgs a FunctionCall |
| 173 |
+ _PrefixExpColon a FunctionCall |
| 174 |
) ^ <font color="#B00000"><i>0</i></font> |
| 175 |
|
| 176 |
<font color="#808080"> -- Extra rules for semantic actions:</font> |
| 177 |
_PrefixExpParens = <font color="#008000">'('</font> * Exp * <font color="#008000">')'</font> |
| 178 |
_PrefixExpSquare = <font color="#008000">'['</font> * Exp * <font color="#008000">']'</font> |
| 179 |
_PrefixExpDot = <font color="#008000">'.'</font> * ID |
| 180 |
_PrefixExpArgs = Args |
| 181 |
_PrefixExpColon = <font color="#008000">':'</font> * ID * _PrefixExpArgs |
| 182 |
|
| 183 |
<font color="#808080"> -- These rules use an internal trick to be distingished from _PrefixExp</font> |
| 184 |
Var = _PrefixExp |
| 185 |
FunctionCall = _PrefixExp |
| 186 |
|
| 187 |
<font color="#808080"> -- FUNCTIONS</font> |
| 188 |
Function = <font color="#008000">'function'</font> * FuncBody |
| 189 |
FuncBody = <font color="#008000">'('</font> * (ParList+EPSILON) * <font color="#008000">')'</font> * Block * <font color="#008000">'end'</font> |
| 190 |
FuncName = Name * _PrefixExpDot^<font color="#B00000"><i>0</i></font> * ((<font color="#008000">':'</font> * ID)+EPSILON) |
| 191 |
Args = <font color="#008000">'('</font> * (ExpList+EPSILON) * <font color="#008000">')'</font> |
| 192 |
+ TableConstructor + String |
| 193 |
ParList = NameList * (<font color="#008000">','</font> * <font color="#008000">'...'</font>)^-<font color="#B00000"><i>1</i></font> |
| 194 |
+ <font color="#008000">'...'</font> |
| 195 |
|
| 196 |
<font color="#808080"> -- TABLES</font> |
| 197 |
TableConstructor = <font color="#008000">'{'</font> * (FieldList+EPSILON) * <font color="#008000">'}'</font> |
| 198 |
FieldList = Field * (FieldSep * Field)^<font color="#B00000"><i>0</i></font> * FieldSep^-<font color="#B00000"><i>1</i></font> |
| 199 |
FieldSep = <font color="#008000">','</font> + <font color="#008000">';'</font> |
| 200 |
|
| 201 |
<font color="#808080"> -- Extra rules for semantic actions:</font> |
| 202 |
_FieldSquare = <font color="#008000">'['</font> * Exp * <font color="#008000">']'</font> * <font color="#008000">'='</font> * Exp |
| 203 |
_FieldID = ID * <font color="#008000">'='</font> * Exp |
| 204 |
_FieldExp = Exp |
| 205 |
|
| 206 |
<font color="#808080"> -- OPERATORS</font> |
| 207 |
BinOp = <font color="#008000">'+'</font> + <font color="#008000">'-'</font> + <font color="#008000">'*'</font> + <font color="#008000">'/'</font> + <font color="#008000">'^'</font> + <font color="#008000">'%'</font> + <font color="#008000">'..'</font> |
| 208 |
+ <font color="#008000">'<'</font> + <font color="#008000">'<='</font> + <font color="#008000">'>'</font> + <font color="#008000">'>='</font> + <font color="#008000">'=='</font> + <font color="#008000">'~='</font> |
| 209 |
+ <font color="#008000">'and'</font> + <font color="#008000">'or'</font> |
| 210 |
UnOp = <font color="#008000">'-'</font> + <font color="#008000">'not'</font> + <font color="#008000">'#'</font> |
| 211 |
|
| 212 |
<font color="#808080"> -- ...plus scanner's keywords and symbols</font> |
| 213 |
} |
| 214 |
</pre> |
| 215 |
<p/> |
| 216 |
The implementation has certain peculiarities that merit clarification: |
| 217 |
<ul> |
| 218 |
<li>Spacing is matched only between two tokens in a rule, never at the beginning or the end of a rule.</li></ul> |
| 219 |
<ul> |
| 220 |
<li><code>EPSILON</code> matches the empty string, which means that it always succeeds without consuming input. Although <code>rule + EPSILON</code> can be changed to <code>rule^-1</code> without any loss of syntactic power, <code>EPSILON</code> was introduced in the parser due to it's usefulness as a placeholder for captures.</li></ul> |
| 221 |
<ul> |
| 222 |
<li><code>BOF</code> and <code>EOF</code> are rules used to mark the bounds of a parsing match, and are useful for semantic actions.</li></ul> |
| 223 |
<ul> |
| 224 |
<li><code>Name</code> versus <code>ID</code>: the official Lua grammar doesn't distinguish between them, as their syntax is exactly the same (Lua identifiers). But semantically <code>Name</code> is a variable identifier, and <code>ID</code> is used with different meanings in <code>_FieldID</code>, <code>FuncName</code>, <code>_PrefixExpColon</code> and <code>_PrefixExpDot</code>.</li></ul> |
| 225 |
<ul> |
| 226 |
<li>In Lua's <a href="http://www.lua.org/manual/5.1/manual.html#8">original extended BNF grammar</a>, <code>Var</code> and <code>FunctionCall</code> are defined using left recursion, which is unavailable in PEGs. In this implementation, the problem was solved by modifying the PEG rules to eliminate the left recursion, and by setting some markers (with some LPeg chicanery) to ensure the proper pattern is being used.</li></ul> |
| 227 |
<p/> |
| 228 |
<p/> |
| 229 |
|
| 230 |
|
| 231 |
|
| 232 |
<hr/> |
| 233 |
<h1><a name="variables"></a> Variables </h1> |
| 234 |
<table border="0" width="95%"> |
| 235 |
|
| 236 |
<tr> |
| 237 |
<a name="variable_rules"></a> |
| 238 |
<td> <pre class="example"><big><strong>rules</strong></big> = <small>table</small> </pre> </td> |
| 239 |
<td> <br/> |
| 240 |
A table holding the Lua 5.1 grammar. See <a href="#section_The_Grammar">The Grammar</a> for an extended explanation. |
| 241 |
<p/> |
| 242 |
</td> |
| 243 |
</tr> |
| 244 |
|
| 245 |
</table> |
| 246 |
|
| 247 |
|
| 248 |
|
| 249 |
<hr/> |
| 250 |
<h1><a name="functions"></a> Functions </h1> |
| 251 |
<table border="0" width="95%"> |
| 252 |
|
| 253 |
<tr> |
| 254 |
<!-- <td> <pre class="example"><big><strong><a href="#functions_apply">apply</a></strong></big> (extraRules, captures)</pre> </td> --> |
| 255 |
<td> <code><big><strong> <a href="#function_apply">apply</a></strong></big> (extraRules, captures) </code> </td> |
| 256 |
<td> Uses <a href="grammar.html#function_apply">grammar.apply</a> to return a new grammar, with <code>captures</code> and extra rules. <a href="#variable_rules">rules</a> stays unmodified. </td> |
| 257 |
</tr> |
| 258 |
|
| 259 |
<tr> |
| 260 |
<!-- <td> <pre class="example"><big><strong><a href="#functions_check">check</a></strong></big> (input)</pre> </td> --> |
| 261 |
<td> <code><big><strong> <a href="#function_check">check</a></strong></big> (input) </code> </td> |
| 262 |
<td> Checks if <code>input</code> is valid Lua source code. </td> |
| 263 |
</tr> |
| 264 |
|
| 265 |
</table> |
| 266 |
|
| 267 |
|
| 268 |
<p/><a name="function_apply"></a> |
| 269 |
<hr/><code><big>apply (extraRules, captures)</big></code> |
| 270 |
<ul>Uses <a href="grammar.html#function_apply">grammar.apply</a> to return a new grammar, with <code>captures</code> and extra rules. <a href="#variable_rules">rules</a> stays unmodified. |
| 271 |
<p/> |
| 272 |
<strong>Parameters:</strong><ul> |
| 273 |
<li><code>extraRules</code>: optional, the new and modified rules. See <a href="grammar.html#function_apply">grammar.apply</a> for the accepted format.</li> |
| 274 |
<li><code>captures</code>: optional, the desired captures. See <a href="grammar.html#function_apply">grammar.apply</a> for the accepted format.</li></ul> |
| 275 |
<p/> |
| 276 |
<strong>Returns:</strong><ul> |
| 277 |
<li>the extended grammar.</li></ul></ul> |
| 278 |
|
| 279 |
<p/><a name="function_check"></a> |
| 280 |
<hr/><code><big>check (input)</big></code> |
| 281 |
<ul>Checks if <code>input</code> is valid Lua source code. |
| 282 |
<p/> |
| 283 |
<strong>Parameters:</strong><ul> |
| 284 |
<li><code>input</code>: a string containing Lua source code.</li></ul> |
| 285 |
<p/> |
| 286 |
<strong>Returns:</strong><ul> |
| 287 |
<li><code>true</code>, if <code>input</code> is valid Lua source code, or <code>false</code> and an error message if the matching fails.</li></ul></ul> |
| 288 |
|
| 289 |
<hr/> |
| 290 |
|
| 291 |
|
| 292 |
|
| 293 |
|
| 294 |
</div> <!-- id="content" --> |
| 295 |
</div> <!-- id="main" --> |
| 296 |
</div> <!-- id="container" --> |
| 297 |
</body> |
| 298 |
</html> |