Builder language combines a preprocessor with an expression language and advanced imports.
Please note that the works is in-progress and published for preview purposes only.
Syntax
Directives
Directives start with @ symbol.
@set
@set <variable:identifier> <value:expression>
@set <variable:identifier> = <value:expression>
Assigns a value of an expression to a variable.
Variables are defined in a global context.
Example:
Sets SOMEVAR to 1:
@set SOMEVAR min(1, 2, 3)
@macro
@macro <name>(<arguments>) <body> @endmacro
@endmacro can be replaced with @end.
Declares a block of code that can take parameters and can be used with an @include statement. Once declared, macros are available from anywhere.
Variables declared as macro argumentys are only available within the macro scope and override global variables with the same name (but do not change them).
Example:
@macro some_macro(a, b, c)
Hello, @{a}!
Roses are @{b},
And violets are @{defined(c) ? c : "of undefiend color"}.
@end
Then some_macro can be used as:
@include some_macro("username", 123)
which will produce:
Hello, username!
Roses are red,
And violets are of undefiend color.
@if – @elseif – @else
Conditional directive.
@if // consequent code @elseif <test:expression> // else if #1 code // ...more elseifs... @else // alternate code @endif
@endif can be replaced with @end.
Example:
@if __FILE__ == 'abc.ext' // include something @elseif __FILE__ == 'def.ext' // include something else @else // something completely different @endif
@{...} (inline expressions)
@{<expression>}
Inserts the value of the enclosed expression.
Example:
@set name "Someone"
Hello, @{name}, the result is: @{123 * 456}.
results in the following output:
Hello, Someone, the result is: 56088.
@error
@error <message:expression>
Emits an error.
Example:
@if PLATFORM == "platform1" // platform 1 code @elseif PLATFORM == "platform2" // platform 2 code @elseif PLATFORM == "platform3" // platform 3 code @else @error "Platform is " + PLATFORM + " is unsupported" @endif
@include
Includes local file, external source or a macro.
@include <source:expression>
Macro
@include some_macro("username", 123)
Local Files
@include "somefile.ext"
Remote Files
@include "http://example.com/file.ext"
@include "https://example.com/file.ext"
From Git Repository
@include "<repository_url>.git/<path>/<to>/<file>@<ref>"
For example, importing file from GitHub looks like:
-
Head of the default branch
@include "https://github.com/electricimp/Builder.git/README.md"
-
Head of the master branch
@include "https://github.com/electricimp/Builder.git/README.md
-
Tag v1.2.3:
@include "https://github.com/electricimp/Builder.git/README.md@v1.2.3"
-
Latest available tag
@include "https://github.com/electricimp/Builder.git/README.md@latest"
Expressions
Directives that have parameters allow usage of expression syntax.
For example:
@include <source:expression>@set <variable:identifier> <value:expression>@if <condition:expression>@elseif <condition:expression>@{<expression>}(inline expressions)
Types
The following types are supported in expressions:
- numbers (eg:
1,1E6,1e-6,1.567) - strings (eg:
"abc",'abc') nulltruefalse
Operators
Binary
|| && == != < > <= >= + - * / %
Unary
+ - !
Member Expressions
somevar.membersomevar["member"]([1, 2, 3])[1]
Conditional Expressions
test ? consequent : alternate
Variables
- Variables defined by
<b>@set</b>statements are available in expressions. - Undefined variables are evaluated as
null. - Variable names can contain
$,_, latin letters and digits and can start only with a non-digit.
__LINE__
Line number (relative to the file in which this variable appears).
Example:
Hi from line @{__LINE__}!
__FILE__
Name of the file in which this variable appears.
Example:
Hi from file @{__FILE__}!
Functions
min(<numbers>)max(<numbers>)abs(<number>)defined(<variable_name>)– returnstrueif a variable is defined,falseotherwise.
Comments
Lines starting with @ followed by space or a line break are treated as comments and not added to the output.
Example:
@ something about platform #1 @set PLATFORM "platform1"
License
MIT
Author
Mikhail Yurasov mikhail@electricimp.com