Debian Codegraph @

doc/parser.html

raw
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">'&lt;'</font> + <font color="#008000">'&lt;='</font> + <font color="#008000">'&gt;'</font> + <font color="#008000">'&gt;='</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>