prprcssr
v2.0.0-rc1
Published
Preprocessor
Downloads
4
Readme
Advanced preprocessing language.
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 namerepo
– repository nameref
– 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.
@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 counterloop.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 Prprcssr requires Node.js 4.0 and above.
As npm library:
npm i --save Prprcssr
then
const Prprcssr = require('prprcssr'); const pp = new Prprcssr(); // (optional) provide GitHub credentials pp.machine.readers.github.username = "<usename>"; pp.machine.readers.github.token = "<personal access token>"; const output = pp.machine.execute(`@include "${inputFile}"`);
As CLI:
Prprcssr 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
Author
Mikhail Yurasov [email protected]