神刀安全网

Builder – Preprocessing language

  • Syntax
    • Directives
      • @set
      • @macro
      • @include
        • Macro
        • Local Files
        • Remote Files
        • From Git Repository
      • @{…} (inline includes)
      • @if – elseif – @else
      • @error
    • Expressions
      • Types
      • Operators
        • Binary
        • Unary
      • Member Expressions
      • Conditional Expressions
      • Variables
        • __LINE__
        • __FILE__
        • __PATH__
      • Functions
    • Comments
  • Usage
  • License

Builder – Preprocessing language

Builder – Preprocessing language

Builder language combines a preprocessor with an expression language and advanced imports.

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 .

Defines a code region that can take it’s own parameters. Macros are declared in a global scope. Macro parameters are only available within the macro scope and override global variables with the same name (but do not affect them).

Macros can be used:

  • via @include directive:

    @include macro(a, b, c)
  • inline:

    @{macro(a, b, c)}

    When macros are used inline:

    • no line control statements are generated for the output inside the macro scope
    • __FILE__ , __LINE__ and __PATH__ variables are bound to the scope where inline inclusion directive appears
    • trailing newline is trimmed from macro output

Examples:

@macro some_macro(a, b, c)   Hello, @{a}!   Roses are @{b},   And violets are @{defined(c) ? c : "of undefined color"}. @end

Then some_macro can be used as:

@include some_macro("username", "red")

which will produce:

Hello, username! Roses are red, And violets are of undefined color. 

The same macro used inline:

[[[ @{some_macro("username", "red", "blue")} ]]]

will ouput:

[[[ Hello, username! Roses are red, And violets are blue. ]]] 

@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

Not yet implemented.

@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@master"
  • 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"

@{…} (inline expressions/macros)

@{<expression>}
@{macro(a, b, c)}

Inserts the value of the enclosed expression or executes a macro.

Example:

@set name "Someone" Hello, @{name}, the result is: @{123 * 456}.

results in the following output:

Hello, Someone, the result is: 56088. 

@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

@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

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' )
  • null
  • true
  • false

Operators

Binary

|| &amp;&amp; == != &lt; &gt; &lt;= &gt;= + – * / %

Unary

+ – !

Member Expressions

  • somevar.member
  • somevar["member"]
  • ([1, 2, 3])[1]

Conditional Expressions

test ? consequent : alternate

Variables

  • Variables defined by @set 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__}!

__PATH__

Absolute path (not including file name) to the file where this variable appears. Contains url for remote includes.

Example:

Hi from file @{__PATH__}!

Functions

  • min(<numbers>)
  • max(<numbers>)
  • abs(<number>)
  • defined(<variable_name>) – returns true if a variable is defined, false otherwise.

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"

Usage

Please note that Builder requires Node.js 4.0 and above.

  • As npm library:

    npm i --save Builder

    then

    const builder = require('Builder'); const output = builder.machine.execute(`@include "${inputFile}"`);
  • As CLI:

    Bullder provides pleasebuild command when installed globally:

    npm i -g Builder pleasebuild [-D<variable> <value>...] [-l] <input_file>

    where:

    • -l – generate line control statements
    • -D<variable> <value> – define a variable

License

MIT

Author

Mikhail Yurasov mikhail@electricimp.com

转载本站任何文章请注明:转载至神刀安全网,谢谢神刀安全网 » Builder – Preprocessing language

分享到:更多 ()

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址