Rename lib to candran

candran/can-parser/README.md

@@ -0,0 +1,127 @@
+lua-parser
+==========
+[![Build Status](https://travis-ci.org/andremm/lua-parser.svg?branch=master)](https://travis-ci.org/andremm/lua-parser)
+
+This is a Lua 5.3 parser written with [LPegLabel](https://github.com/sqmedeiros/lpeglabel) that
+generates an AST in a format that is similar to the one specified by [Metalua](https://github.com/fab13n/metalua-parser).
+The parser uses LPegLabel to provide more specific error messages.
+
+Requirements
+------------
+
+        lua >= 5.1
+        lpeglabel >= 1.0.0
+
+API
+---
+
+The package `lua-parser` has two modules: `lua-parser.parser`
+and `lua-parser.pp`.
+
+The module `lua-parser.parser` implements the function `parser.parse`:
+
+* `parser.parse (subject, filename)`
+
+    Both subject and filename should be strings.
+    It tries to parse subject and returns the AST in case of success.
+    It returns **nil** plus an error message in case of error.
+    In case of error, the parser uses the string filename to build an
+    error message.
+
+The module `lua-parser.pp` implements a pretty printer to the AST and
+a dump function:
+
+* `pp.tostring (ast)`
+
+    It converts the AST to a string and returns this string.
+
+* `pp.print (ast)`
+
+    It converts the AST to a string and prints this string.
+
+* `pp.dump (ast[, i])`
+
+    It dumps the AST to the screen.
+    The parameter **i** sets the indentation level.
+
+AST format
+----------
+
+	block: { stat* }
+
+	stat:
+            `Do{ stat* }
+          | `Set{ {lhs+} {expr+} }                    -- lhs1, lhs2... = e1, e2...
+          | `While{ expr block }                      -- while e do b end
+          | `Repeat{ block expr }                     -- repeat b until e
+          | `If{ (expr block)+ block? }               -- if e1 then b1 [elseif e2 then b2] ... [else bn] end
+          | `Fornum{ ident expr expr expr? block }    -- for ident = e, e[, e] do b end
+          | `Forin{ {ident+} {expr+} block }          -- for i1, i2... in e1, e2... do b end
+          | `Local{ {ident+} {expr+}? }               -- local i1, i2... = e1, e2...
+          | `Localrec{ ident expr }                   -- only used for 'local function'
+          | `Goto{ <string> }                         -- goto str
+          | `Label{ <string> }                        -- ::str::
+          | `Return{ <expr*> }                        -- return e1, e2...
+          | `Break                                    -- break
+          | apply
+
+	expr:
+            `Nil
+          | `Dots
+          | `Boolean{ <boolean> }
+          | `Number{ <number> }
+          | `String{ <string> }
+          | `Function{ { `Id{ <string> }* `Dots? } block }
+          | `Table{ ( `Pair{ expr expr } | expr )* }
+          | `Op{ opid expr expr? }
+          | `Paren{ expr }       -- significant to cut multiple values returns
+          | apply
+          | lhs
+
+	apply:
+             `Call{ expr expr* }
+           | `Invoke{ expr `String{ <string> } expr* }
+
+	lhs: `Id{ <string> } | `Index{ expr expr }
+
+	opid:  -- includes additional operators from Lua 5.3 and all relational operators
+            'add'  | 'sub' | 'mul'  | 'div'
+          | 'idiv' | 'mod' | 'pow'  | 'concat'
+          | 'band' | 'bor' | 'bxor' | 'shl' | 'shr'
+          | 'eq'   | 'ne'  | 'lt'   | 'gt'  | 'le'   | 'ge'
+          | 'and'  | 'or'  | 'unm'  | 'len' | 'bnot' | 'not'
+
+
+Usage
+--------
+
+**Code example for parsing a string:**
+
+
+    local parser = require "lua-parser.parser"
+    local pp = require "lua-parser.pp"
+
+    if #arg ~= 1 then
+        print("Usage: parse.lua <string>")
+        os.exit(1)
+    end
+
+    local ast, error_msg = parser.parse(arg[1], "example.lua")
+    if not ast then
+        print(error_msg)
+        os.exit(1)
+    end
+
+    pp.print(ast)
+    os.exit(0)
+
+**Running the above code example using a string without syntax error:**
+
+    $ lua parse.lua "for i=1, 10 do print(i) end"
+    { `Fornum{ `Id "i", `Number "1", `Number "10", { `Call{ `Id "print", `Id "i" } } } }
+
+**Running the above code example using a string with syntax error:**
+
+    $ lua parse.lua "for i=1, 10 do print(i) "
+    example.lua:1:24: syntax error, expected 'end' to close the for loop
+