# Pre > Advanced Preprocessor Latest version **2.0.0-rc2.2** (published 2016-05-30) · MIT license · 0 weekly downloads ## Install ```sh npm install Pre pnpm add Pre yarn add Pre bun add Pre ``` Provides the command `pre`. ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 2.0.0-rc2.2 | | Published | 2016-05-30 | | First published | 2016-05-28 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 4 | | Known vulnerabilities | 0 (+1 in 1 direct dependencies) | | Install scripts | no | | Author | Mikhail Yurasov | | Maintainers | mym___ | ## Links - npm: https://www.npmjs.com/package/Pre - Repository: https://github.com/myurasov/Pre - Homepage: https://github.com/myurasov/Pre#readme - Issues: https://github.com/myurasov/Pre/issues - npm.io page: https://npm.io/package/Pre ## Dependencies (4) - [jsep](https://npm.io/package/jsep.md) 0.3.0 - [clone](https://npm.io/package/clone.md) 1.0.2 - [github](https://npm.io/package/github.md) 0.2.4 - [request](https://npm.io/package/request.md) 2.71.0 ## Recent versions - 2.0.0-rc2.2 (latest) — 2016-05-30 - 0.0.1-dev — 2016-05-28 ## README

_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](#syntax) - [Directives](#directives) - [@set](#@set) - [@macro](#@macro) - [@include](#@include) - [Macro](#macro) - [Local Files](#local-files) - [Remote Files](#remote-files) - [From GitHub](#from-github) - [Authentication](#authentication) - [@include once](#@include-once) - [@{...} (inline expressions/macros)](#@-inline-expressionsmacros) - [@while](#@while) - [@repeat](#@repeat) - [@if – @elseif – @else](#@if-%E2%80%93-@elseif-%E2%80%93-@else) - [@error](#@error) - [Filters](#filters) - [Expressions](#expressions) - [Types](#types) - [Operators](#operators) - [Member Expressions](#member-expressions) - [Conditional Expressions](#conditional-expressions) - [Variables](#variables) - [\_\_LINE\_\_](#%5C_%5C_line%5C_%5C_) - [\_\_FILE\_\_](#%5C_%5C_file%5C_%5C_) - [\_\_PATH\_\_](#%5C_%5C_path%5C_%5C_) - [loop](#loop) - [Functions](#functions) - [Comments](#comments) - [Usage](#usage) - [Testing](#testing) - [License](#license) - [Author](#author)
[![Build Status](https://travis-ci.org/myurasov/Pre.svg?branch=develop)](https://travis-ci.org/myurasov/Pre)
# 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 - 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 GitHub

@include "github:<user>/<repo>/<path>[@<ref>]"

Where: - `user` – user/organization name - `repo` – repository name - `ref` – git reference (branch name or tag, defaults to _master_) Examples: - Head of the default branch

  @include "github:electricimp/Promise/Promise.class.nut"

- Head of the _develop_ branch

  @include "github:electricimp/Promise/Promise.class.nut@develop"

- Tag _v2.0.0_:

  @include "github:electricimp/Promise/Promise.class.nut@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](https://github.com/settings/tokens)_ **or** _password_ (which is less secure and not recommended). More info on how to provide those parameters is in [usage](#usage) section. ### @include once

@include once <source:expression>

Acts the same as @include but has no effect if _source_ has already been included. Macros are always included. ### @{...} (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. ``` ### @while While-loop. [loop](#loop) variable is available in `@while` loops.

@while <test:expression>
  // 0-based iteration counter: @{loop.index}
  // 1-based iteration counter: @{loop.iteration}
@endwhile

_@endwhile can be replaced with @end._ [Example](#loop) ### @repeat Loop that repeats a certain number of iterations. [loop](#loop) variable is available in `@repeat` loops.

@repeat <times:expression>
  // 0-based iteration counter: @{loop.index}
  // 1-based iteration counter: @{loop.iteration}
@endrepeat

_@endrepeat can be replaced with @end._ Example:

@repeat 3
  loop.iteration: @{loop.iteration}
@end

outputs: ``` loop.iteration: 1 loop.iteration: 2 loop.iteration: 3 ``` ### @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

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

@{<expression> | <filter>}

which is equivalent to:

@{<filter>(<expression>)}

Example:

// include external HTML to a string
a = "@{include('index.html')|escape}"

// include external binary file to a base64-encoded string
b = "@{include('file.bin')|base64}"

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

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__}!

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

@set myvar = 12

@while myvar > 9
  @set myvar = myvar - 1
  var: @{myvar}
  loop.index: @{loop.index}
@end

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:

@ something about platform #1
@set PLATFORM "platform1"

# Usage _Please note that Pre requires Node.js 4.0 and above._ - As _npm_ library: ```sh npm i --save Pre ``` then ```js const Pre = require('Pre'); const pre = new Pre(); // (optional) provide GitHub credentials pre.machine.readers.github.username = ""; pre.machine.readers.github.token = ""; const output = pre.machine.execute(`@include "${inputFile}"`); ``` - As CLI: _Pre_ provides `prprcss` command when installed globally:

  npm i -g Pre
  pre [-D<variable> <value>...] [-l] [--github-user <usename> --github-token <token>] [-l] <input_file>

where: * `-l` – generate line control statements * -D<variable> <value> – define a variable * --github-user – GitHub username * --github-token – GitHub [personal access token](https://github.com/settings/tokens) or password (not recommended) # Testing ``` SPEC_LOGLEVEL= \ SPEC_GITHUB_USERNAME= \ SPEC_GITHUB_TOKEN= \ npm test ``` # License [MIT](./LICENSE). _Pre_ is a fork of Electric Imp's _Builder_ licensed under MIT. # Author _Mikhail Yurasov _ --- _Source: https://npm.io/package/Pre · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._