Advanced General-Purpose Preprocessor

🐝 Direct includes from Github (versioned) and URLs

🐧 Flexible syntax (macros, loops, expressions, etc.)

🍄 Asset filters (escape, base64, custom)

🐠 Automatic un-indentation of nested blocks

🐥 Line control statements generation

🐸 Available as cli or as npm library

🐼 Extensible and embeddable via JS API

• Syntax
  • Directives
    • @set
    • @macro
    • @include
      • Macro
      • Local Files
      • Remote Files
      • From GitHub
      • Authentication
    • @include once
    • @{...} (inline expressions/macros)
    • @while
    • @repeat
    • @if – @elseif – @else
    • @error
  • Filters
  • Expressions
    • Types
    • Operators
    • Member Expressions
    • Conditional Expressions
    • Variables
      • __LINE__
      • __FILE__
      • __PATH__
      • loop
    • Functions
  • Comments
• Usage
• Testing
• License
• Author

Syntax

Directives

Directives start with @ symbol.

@set

Assigns a value of an expression to a variable.

Variables are defined in a global context.

Example:

Sets SOMEVAR to 1:

@macro

@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:

• inline:

  When macros are used inline:

  • no line control statements are generated for the output inside the macro scope
  • trailing newline is trimmed from macro output

Examples:

Then some_macro can be used as:

which will produce:

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

The same macro used inline:

will ouput:

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

@include

Includes local file, external source or a macro.

Macro

Local Files

Remote Files

From GitHub

Where:

• user – user/organization name
• repo – repository name
• ref – git reference (branch name or tag, defaults to master)

Examples:

• Head of the default branch

• Head of the develop branch

• Tag v2.0.0:

Authentication

When using GitHub includes, authentication is optional, however:

• with authentication GitHub API provides much higher rate limits
• to access private repositories authentication is required

Apart from GitHub username you need to provide either a personal access token or password (which is less secure and not recommended). More info on how to provide those parameters is in usage section.

@include once

Acts the same as @include but has no effect if source has already been included. Macros are always included.

@{...} (inline expressions/macros)

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

Example:

results in the following output:

Hello, Someone, the result is: 56088.

@while

While-loop. loop variable is available in @while loops.

@endwhile can be replaced with @end.

Example

@repeat

Loop that repeats a certain number of iterations. loop variable is available in @repeat loops.

@endrepeat can be replaced with @end.

Example:

outputs:

  loop.iteration: 1
  loop.iteration: 2
  loop.iteration: 3

@if – @elseif – @else

Conditional directive.

@endif can be replaced with @end.

Example:

@error

Emits an error.

Example:

Filters

"Filter" | operator allows to pass a value through any of supported functions.

which is equivalent to:

Example:

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

|| && == != < > <= >= + - * / %

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:

__FILE__

Name of the file in which this variable appears.

Example:

__PATH__

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

Example:

loop

Defined inside @while and @repeat loops.

Contains information about the current loop:

• loop.index – 0-indexed iteration counter
• loop.iteration – 1-indexed iteration counter

Example:

outputs:

myvar: 11
loop.index: 0
myvar: 10
loop.index: 1
myvar: 9
loop.index: 2

Functions

• defined(<variable_name>) – returns true if a variable is defined, false otherwise.
• include(<source>) – includes external source
• escape(<value>) – escapes special characters in string (\b, \f, \n, \r, \t, \, ', ")
• base64(<value>) – encodes value as base64
• min(<numbers>)
• max(<numbers>)
• abs(<number>)

Comments

Lines starting with @ followed by space or a line break are treated as comments and not added to the output.

Example:

Usage

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

• As npm library:

  npm i --save Pre

  then

  const Pre = require('Pre');
  
  const pre = new Pre();
  
  // (optional) provide GitHub credentials
  pre.machine.readers.github.username = "<usename>";
  pre.machine.readers.github.token = "<personal access token>";
  
  const output = pre.machine.execute(`@include "${inputFile}"`);

• As CLI:

  Pre provides prprcss command when installed globally:

  where:

  • -l – generate line control statements
  • -D<variable> <value> – define a variable
  • --github-user – GitHub username
  • --github-token – GitHub personal access token or password (not recommended)

Testing

SPEC_LOGLEVEL=<debug|info|warning|error> \
SPEC_GITHUB_USERNAME=<GitHub username> \
SPEC_GITHUB_TOKEN=<GitHub password/access token> \
npm test

License

MIT. Pre is a fork of Electric Imp's Builder licensed under MIT.

Author

Mikhail Yurasov [email protected]