Files

undergroundwires 4d7ff7edc5 Add support for pipes in templates #53

The goal is to be able to modify values of variables used in templates.
It enables future functionality such as escaping, inlining etc.

It adds support applying predefined pipes to variables. Pipes
can be applied to variable substitution in with and parameter
substitution expressions. They work in similar way to piping in Unix
where each pipe applied to the compiled result of pipe before.

It adds support for using pipes in `with` and parameter substitution
expressions. It also refactors how their regex is build to reuse more of
the logic by abstracting regex building into a new class.

Finally, it separates and extends documentation for templating.

2021-09-08 18:58:30 +01:00

2.3 KiB

Raw Blame History

Templating

Benefits of templating

Generating scripts by sharing code to increase best-practice usage and maintainability.
Creating self-contained scripts without depending on each other that can be easily shared.
Use of pipes for writing cleaner code and letting pipes do dirty work.

Expressions

Expressions in the language are defined inside mustaches (double brackets, {{ and }}).
Expression syntax is inspired mainly by Go Templates.

Syntax

Parameter substitution

A simple function example:

  function: EchoArgument
  parameters:
    - name: 'argument'
  code: Hello {{ $argument }} !

It would print "Hello world" if it's called in a script as following:

  script: Echo script
  call:
    function: EchoArgument
    parameters:
      argument: World

A function can call other functions such as:

  - 
    function: CallerFunction
    parameters:
      - name: 'value'
    call:
      function: EchoArgument
      parameters:
        argument: {{ $value }}
  -
    function: EchoArgument
    parameters:
      - name: 'argument'
    code: Hello {{ $argument }} !

with

Skips the block if the variable is absent or empty.
Binds its context (.) value of provided argument for the parameter if provided one.
A block is defined as {{ with $parameterName }} Parameter value is {{ . }} here {{ end }}.
The parameters used for with condition should be declared as optional, otherwise with block becomes redundant.

Example:

  function: FunctionThatOutputsConditionally
  parameters:
    - name: 'argument'
      optional: true
  code: |- 
    {{ with $argument }}
      Value is: {{ . }}
    {{ end }}

Pipes

Pipes are set of functions available for handling text in privacy.sexy.
Allows stacking actions one after another also known as "chaining".
Just like Unix pipelines, the concept is simple: each pipeline's output becomes the input of the following pipe.
Pipes are provided and defined by the compiler and consumed by collection files.
Pipes can be combined with parameter substitution and with.
❗ Pipe names must be camelCase without any space or special characters.

2.3 KiB Raw Blame History