candran/README.md

Candran

Candran is a dialect of the Lua 5.3 programming language which compiles to Lua 5.3 and Lua 5.1/LuaJit. It adds a preprocessor and several useful syntax additions.

Unlike Moonscript, Candran tries to stay close to the Lua syntax.

Candran code example :

#import("lib.thing")
#local debug = debug or false

local function calculate(toadd=25)
	local result = thing.do()
	result += toadd
    #if debug then
        print("Did something")
    #end
	return result
end

print(calculate())

Quick setup

Install LPegLabel (luarocks install LPegLabel), download this repository and use Candran through canc.lua or candran.lua.

The language

Preprocessor

Before compiling, Candran's preprocessor is run. It execute every line starting with a # (ignoring whitespace) as Candran code. For example,

#if lang == "fr" then
	print("Bonjour")
#else
	print("Hello")
#end

Will output print("Bonjour") or print("Hello") depending of the "lang" argument passed to the preprocessor.

The preprocessor has access to the following variables :

• candran : the Candran library table.
• output : the current preprocessor output string.
• import(module[, [args, autoRequire]]) : a function which import a module. This is equivalent to use require(module) in the Candran code, except the module will be embedded in the current file. args is an optional preprocessor arguments table for the imported module (current preprocessor arguments will be inherited). autoRequire (boolean, default true) indicate if the module should be automaticaly loaded in a local variable or not. If true, the local variable will have the name of the module.
• include(filename) : a function which copy the contents of the file filename to the output.
• write(...) : write to the preprocessor output. For example, #print("hello()") will output hello() in the final file.
• placeholder(name) : if the variable name is defined in the preprocessor environement, its content will be inserted here.
• ... : each arguments passed to the preprocessor is directly available.
• and every standard Lua library.

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

• var += nb
• var -= nb
• var *= nb
• var /= nb
• var //= nb
• var ^= nb
• var %= nb
• var ..= str
• var and= str
• var or= str
• var &= nb
• var |= nb
• var <<= nb
• var >>= nb

For example, a var += nb assignment will be compiled into var = var + nb.

Default function parameters

function foo(bar = "default", other = thing.do())
    -- stuff
end

If an argument isn't provided or nil when the function is called, it will be automatically set to a default value.

It is equivalent to doing if arg == nil then arg = default end for each argument at the start of the function.

The default values can be complete Lua expressions, and will be evaluated each time the function is run.

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.

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:

• lua canc.lua

  Display the information text (version and basic command-line usage).

• lua canc.lua [arguments] 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 }.

  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.

  • example uses :

    lua canc.lua foo.can

    preprocess and compile foo.can and write the result in foo.lua.

    lua canc.lua foo.can -verbose -print | lua

    preprocess foo.can with verbose set to true, compile it and execute it.

Library usage

Candran can also be used as a Lua library. For example,

local candran = require("candran")

local f = io.open("foo.can")
local contents = f:read("*a")
f:close()

local compiled = candran.make(contents, { lang = "fr" })

load(compiled)()

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 :

• 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.

Compiling the library

The Candran library itself is written is Candran, so you have to compile it with an already compiled Candran library.

The compiled candran.lua should include every Lua library needed to run it. You will still need to install LPegLabel.

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

You can then run the tests on your build :

cd tests
lua test.lua ../candran.lua