Reuh/candran
1
0
Fork 0
mirror of https://github.com/Reuh/candran.git synced 2025-10-27 17:59:30 +00:00
Code Releases Activity

Candran 0.3.0

Browse source 
* Added @ self alias
* Added short anonymous functions declaration
* Made assignment operators works in every direction, except up, down,
behind and below, because this would be hard to visualize.
* Moved files around.
* Error rewriting.
* Discover the amazing can commandline tool, which includes a fantastic°
REPL and program running abilities.
* Added functions which plagiarize Lua.
* Added 0.1.0 to the version number.
* If you still love pineapple flavored bread, don't hesitate to show
your feelings.

Also, the tests are out of date. Sad.

°: not really.
This commit is contained in:
Étienne Fildadut 2017-08-16 22:33:44 +02:00
parent 2a1e293aa5
commit 4af2b41a0d
17 changed files with 2413 additions and 1865 deletions
Download patch file Download diff file Expand all files Collapse all files

154
README.md
View file

@ -4,11 +4,9 @@ Candran is a dialect of the [Lua 5.3](http://www.lua.org) programming language w
Unlike Moonscript, Candran tries to stay close to the Lua syntax.
Candran code example :
````lua
#import("lib.thing")
#local debug = debug or false
#local debug or= false
local function calculate(toadd=25)
local result = thing.do()
@ -19,11 +17,22 @@ local function calculate(toadd=25)
return result
end
print(calculate())
local a = {
hey = true,
newHop = :(foo, thing)
@hey = thing(foo)
end
}
a:newHop(42, (foo)
return "something " .. foo
end)
````
##### Quick setup
Install LPegLabel (```luarocks install LPegLabel```), download this repository and use Candran through ```canc.lua``` or ```candran.lua```.
#### Quick setup
Install LPegLabel (```luarocks install LPegLabel```), download this repository and use Candran through the scripts in ```bin/``` or use it as a library with the self-contained ```candran.lua```.
The language
------------
@ -53,7 +62,8 @@ The preprocessor has access to the following variables :
### Syntax additions
After the preprocessor is run the Candran code is compiled to Lua. The Candran code adds the folowing syntax to Lua :
##### New assignment operators
##### Assignment operators
* ````var += nb````
* ````var -= nb````
* ````var *= nb````
@ -71,6 +81,10 @@ After the preprocessor is run the Candran code is compiled to Lua. The Candran c
For example, a ````var += nb```` assignment will be compiled into ````var = var + nb````.
All theses operators can also be put right of the assigment operator, in which case ```var =+ nb``` will be compiled into ```var = nb + var```.
If you feel like writing hard to understand code, right and left operator can be used at the same time.
##### Default function parameters
```lua
function foo(bar = "default", other = thing.do())
@ -83,43 +97,87 @@ It is equivalent to doing ```if arg == nil then arg = default end``` for each ar
The default values can be complete Lua expressions, and will be evaluated each time the function is run.
##### @ self aliases
```lua
a = {
foo = "Hoi"
}
function a:hey()
print(@foo) -- Hoi
print(@["foo"]) -- also works
print(@ == self) -- true
end
```
When a variable name is prefied with ```@```, the name will be accessed in ```self```.
When used by itself, ```@``` is an alias for ```self```.
##### Short anonymous function declaration
```lua
a = (arg1, arg2)
print(arg1)
end
b = :(hop)
print(self, hop)
end
```
Anonymous function (functions values) can be created in a more concise way by omitting the ```function``` keyword.
A ```:``` can prefix the parameters paranthesis to automatically add a ```self``` parameter.
Compile targets
---------------
Candran is based on the Lua 5.3 syntax, but can be compiled to both Lua 5.3 and Lua 5.1/LuaJit.
To chose a compile target, either explicitly give ```lua53``` or ```luajit``` as a second argument to ```candran.compile```, or set the ```target``` preprocessor argument when using ```candran.make``` or the command line tools.
To chose a compile target, set the ```target``` option to ```lua53``` (default) or ```luajit``` in the option table when using the library or the command line tools.
Lua 5.3 specific syntax (bitwise operators, integer division) will automatically be translated in valid Lua 5.1 code, using LuaJit's ```bit``` library if necessary.
Lua 5.3 specific syntax (bitwise operators, integer division) will automatically be translated in valid Lua 5.1 code, using LuaJIT's ```bit``` library if necessary.
The library
-----------
### Command-line usage
The library can be used standalone through the ```canc``` utility:
The library can be used standalone through the ```canc``` and ```can``` utility:
* ````lua canc.lua````
* ````canc````
Display the information text (version and basic command-line usage).
* ````lua canc.lua [arguments] filename...````
* ````canc [options] filename...````
Preprocess and compile each _filename_ Candran files, and creates the assiociated ```.lua``` files in the same directories.
_arguments_ is of type ````-somearg -anotherarg thing=somestring other=5 ...````, which will generate a Lua table ```{ somearg = true, anotherarg = true, thing = "somestring", other = 5 }```.
_options_ is of type ````-somearg -anotherarg thing=somestring other=5 ...````, which will generate a Lua table ```{ somearg = true, anotherarg = true, thing = "somestring", other = 5 }```.
You can choose to use another directory where files should be written using the ```dest=destinationDirectory``` argument.
```canc``` can write to the standard output instead of creating files using the ```-print``` argument.
You can choosed to run only the preprocessor or compile using the ```-preprocess``` and ```-compile``` flags.
* example uses :
````lua canc.lua foo.can````
````canc foo.can````
preprocess and compile _foo.can_ and write the result in _foo.lua_.
````lua canc.lua foo.can -verbose -print | lua````
````canc foo.can -verbose -print | lua````
preprocess _foo.can_ with _verbose_ set to _true_, compile it and execute it.
* ```can```
Start a simplisitic Candran REPL.
* ````canc [options] filename````
Preprocess, compile and run _filename_ using the options provided.
This will automatically register the Candran package searcher so required file will be compiled as they are needed.
This command will use error rewriting if enabled.
### Library usage
Candran can also be used as a Lua library. For example,
````lua
@ -132,14 +190,70 @@ f:close()
local compiled = candran.make(contents, { lang = "fr" })
load(compiled)()
-- or simpler...
candran.dofile("foo.can")
````
Will load Candran, read the file _foo.can_, compile its contents with the argument _lang_ set to _"fr"_, and then execute the result.
The table returned by _require("candran")_ gives you access to :
##### Compiler & preprocessor API
* ````candran.VERSION```` : Candran's version string.
* ````candran.preprocess(code[, args])```` : return the Candran code _code_, preprocessed with _args_ as argument table.
* ````candran.compile(code[, target])```` : return the Candran code compiled to Lua.
* ````candran.make(code[, args])```` : return the Candran code, preprocessed with _args_ as argument table and compilled to Lua.
* ````candran.preprocess(code[, options])```` : return the Candran code _code_, preprocessed with _options_ as options table.
* ````candran.compile(code[, options])```` : return the Candran code compiled to Lua with _options_ as the option table.
* ````candran.make(code[, options])```` : return the Candran code, preprocessed and compiled with _options_ as options table.
##### Code loading helpers
* ```candran.loadfile(filepath, env, options)``` : Candran equivalent to the Lua 5.3's loadfile funtion. Will rewrite errors by default.
* ```candran.load(chunk, chunkname, env, options)``` : Candran equivalent to the Lua 5.3's load funtion. Will rewrite errors by default.
* ```candran.dofile(filepath, options)``` : Candran equivalent to the Lua 5.3's dofile funtion. Will rewrite errors by default.
#### Error rewriting
When using the command-line tools or the code loading helpers, Candran will automatically setup error rewriting: because the code is reformated when
compiled and preprocessed, lines numbers given by Lua in case of error are hardly usable. To fix that, Candran map each line from the compiled file to
the lines from the original file(s), inspired by MoonScript. Errors will be displayed as:
```
example.can:12(5): attempt to call a nil value (global 'iWantAnError')
```
12 is the line number in the original Candran file, and 5 is the line number in the compiled file.
If you are using the preprocessor ```import()``` function, the source Candran file and destination Lua file might not have the same name. In this case, the error will be:
```
example.can:12(final.lua:5): attempt to call a nil value (global 'iWantAnError')
```
* ```candran.messageHandler(message)``` : The error message handler used by Candran. Use it in xpcall to rewrite stacktraces to display Candran source file lines instead of compiled Lua lines.
##### Package searching helpers
Candran comes with a custom package searcher which will automatically find, preprocesses and compile ```.can``` files. If you want to use Candran in your project without worrying about
compiling the files, you can simply call
```lua
require("candran").setup()
```
at the top of your main Lua file. If a Candran is found when you call ```require()```, it will be automatically compiled and loaded. If both a Lua and Candran file match a module name, the Candran
file will be loaded.
* ```candran.searcher(modpath)``` : Candran package searcher function. Use the existing package.path.
* ```candran.setup()``` : Register the Candran package searcher.
##### Available compiler & preprocessor options
You can give arbitrary options which will be gived to the preprocessor, but Candran already provide and uses these with their associated default values:
```lua
target = "lua53" -- Compiler target. "lua53" or "luajit".
indentation = "" -- Character(s) used for indentation in the compiled file.
newline = "\n" -- Character(s) used for newlines in the compiled file.
requirePrefix = "CANDRAN_" -- Prefix used when Candran needs to require an external library to provide some functionality (example: LuaJIT's bit lib when using bitwise operators).
mapLines = true -- If true, compiled files will contain comments at the end of each line indicating the associated line and source file. Needed for error rewriting.
chunkname = "nil" -- The chunkname used when running code using the helper functions and writing the line origin comments. Candran will try to set it to the original filename if it knows it.
rewriteErrors = true -- True to enable error rewriting when loading code using the helper functions. Will wrap the whole code in a xpcall().
```
### Compiling the library
The Candran library itself is written is Candran, so you have to compile it with an already compiled Candran library.
@ -149,9 +263,11 @@ The compiled _candran.lua_ should include every Lua library needed to run it. Yo
This command will use the precompilled version of this repository (candran.lua) to compile _candran.can_ and write the result in _candran.lua_ :
````
lua canc.lua candran.can
canc candran.can
````
The Candran build included in this repository were made using the ```mapLines=false``` options.
You can then run the tests on your build :
````