template-parser

What for?

This is a template parser, which is designed for the following uses:

1. Generate code based on code.
2. Update a configuration file that contains replaceable variables.
3. Update any file that contains replaceable variables.

For any type of file, you can write the template statements in contents where can be ignored, like comments.
Template parser will replace all variables in Statements.
Statements will be kept if updating file itself, and will be removed if writing to another file.

Install

npm i @yjc/template-parser

Usage

In CLI:

npm run parse file-path [--output=] [--keep-statements] [--comment-start=] [--comment-end=]

Template Language Syntax

Examples:

// var var-name = resource-uri
// var var-obj = resource-uri

// echo line one {{ var-name }} {{ var-obj:key }}
// echo More lines
// echo-end

Some rules:

1. All lines with template statements must be wrapped by comment delimiters.
2. A template statement includes a whole line.

Don't use like:

'Some real content...'; // var a-var = resource-uri

Delimiters

• comment delimiters
• variable delimiters

Tokens

• var
• echo
• echo-end
• .options

Operators

• = ~ Assigning value to a variable.
• : Accessing property value of a variable, or return value from previous action.
• :.. Using variable value as property name.
• | Calling action (function), like piping.

Statements

• var statement
• echo statement
• echo-end statement
• options statement

var statement

var statement reads value, resource data or pack module, and assigns to a variable name.

The following examples are using ##[ and ]## as comment delimiters, in order to show the end of statements clearly.

##[ var var-type var-name = resource-uri ]##
##[ var text a-var ~ ignoring-read-error ]##

Var-Type tells how to parse resource. Var-Type is optional.

Use ~ instead of = if you want to ignore reading error, otherwise any error while reading will break the program.

echo statement, echo-end statement

Continuous echo statements print lines with variables.
echo-end statement tells the end of replacement block.

##[ echo line]##
##[ echo ]##
##[ echo line after an empty line]##
Real content will be written from here,
until "echo-end" statement.

##[ echo-end ]##

In this case, "line 3" will be rewritten, because "line 3" is separated by blank line (not continuous anymore):

##[ echo line 1: echo statements beginning]##
##[ echo line 2: OK, continuous echo statement]##

##[ echo line 3: this line will be rewritten]##
##[ echo-end ]##

Variable Expression

Variables in echo statement or resource uri will be replaced by their values.
Variables are wrapped by variable delimiters.

##[ var string a = Path: {{ process:env:path }} {{ another-var }} ]##
##[ var string key = {{ string-from-a-variable }}]##
##[ var value e = process:env ]

##[ echo line one {{ var-name }} {{ obj:..key }} ]##
##[ echo More lines {{ obj:key0:key1 | pack:action0 | pack:action1 }} ]##
##[ echo Multiple variables to action {{ obj:key | pack:action2 : obj:key2 obj:key3 }} ]##
##[ echo-end ]##

Some rules:

1. Characters allowed in name are: a-z A-Z 0-9 _ . -, no blanks.
2. Use : to get property of variable, NOT ., because . is allowed in name. No blanks around :.
3. Multiple variables are separated by blanks.
4. The statement after each | is an action calling. The first variable is the action (function), all arguments following. Use a single : to access the return value of previous action.
5. The statement before first | means the action of "return the first variable, and ignore others".
6. Use .. before a key to access variable as a property name.

options statement

options statements define customized options.

##[ .options comment-start=##[ comment-end=]## ]##
##[ .options::name=value::other=::boolean-option]##

Some rules:

1. Characters allowed in options name are same as variable name.
2. Characters between .options and first name is separator, can be customized.
3. All characters allowed in separator but characters in name.
4. No blanks around name and =.
5. If an option has not = after it's name, it is a boolean option, and assigned with true.

Details

Resource URI

• http or https url.
• Local file path (related to current file path).
• A value.

Local File Resource Name

File name rule: var-type.file-name.file-type.

Var-Type

• list Parse plain text, return array of each line.
• json JSONP format and inline comments(start with //) are allowed.
• text Return plain text.
• pack Return Node.js module.
• get Execute function and using it's return.
• stat Return http/https response headers, or file stat.
• value Variable expression without delimiters.
• number Will be converted to number.
• string Same as what you write.
• fn For functional variables.

http/https resources using text by default, and pack/get is not available.
For Local file resource, all types are available.

If var-type not declared, get var-type from file name, otherwise use text.

Pack Type

Declare var-type:

exports[`${varType} ${varName}`] = "resource-uri";

Declare get type:

exports[`get ${varName}`] = function () {};

Using context in action:

exports.someValue = 233;
exports.someAction = function (options, ...inputs) {
    return this.someValue * this.someValue;
};

Processing Logic:

1. If var-type declared, loads resource and assigns to result[varName], var-type will be removed from property name.
2. Context of actions is bind to parsed result.
3. get type will be executed at last, means result context is available.

Check demo/resources/pack.*.js for examples.

Built-in Variables

• options In file options, options:input options:output.
• number:* Any number.
• string:* String of a name.
• json
• null undefined true false
• path
• url url:format url:parse url:resolve url:domainToASCII url:domainToUnicode
• env
• process:env(with lowercase names) process:arch process:platform process:node-version process:versions process:release
• Date:new Date:parse Date:UTC Date:now

Functional Variables

Declare a functional variable: var fn .var-name = ... .

• .output Declare output file.
• .ignore If true, do nothing.

Actions

Type of an action: (options: ActionOptions, ...inputs: any[]) => any.

ActionOptions

• indent Blanks in front of line.
• lineBreaks Line breaks characters.

First Line Options

The following options must be written in the first line of options statements.

• comment-start Default: //. The delimiter for comment start.
• comment-end Default: (empty string). The delimiter for comment end.
• escape Default: (undefined). Escaping character. If defined, this option must be written first.
• ignore-head Default: (empty string). Regular expression for ignoring some characters in the head of statement line.
• ignore-tail Default: (empty string). Regular expression for ignoring some characters at the tail of statement line.

Other Options

• var-start Default: {{. The delimiter for variable start.
• var-end Default: }}. The delimiter for variable end.
• no-echo Default: (undefined). If true, remove all contents between echo statement and echo-end statement.

TODO

• Support calling local command as action.