Interpolation

About interpolation

One of the most important features of hyperpotamus is interpolation. Interpolation provides a simple syntax to process the replacement of name/value pairs from the session. The session represents any data that has been provided to or collected throughout the processing of a script. Interpolation is the primary mechanism to interact with that data. Interpolation can be used in the right-hand (value) side of almost any element/property underneath an action element.

As a simple example, let's say that we have a session containing and we want to use those values in an action:

  - set:
      username: pmarkert
      project: hyperpotamus
  - request: 
      url: http://github.com/<% username %>/<% project %>

The string inside of the macro delimiters is the key/path of an item in the session to be output. The interpolation engine also supports nested structures and arrays, so if the session data includes complex objects or arrays, the syntax works as one might expect, for example:

- set:
   user:
     name: John Doe
     address:
       street: 123 Main St.
       street2: Apt #104
       city: Anywhere
       state: ST
       zipcode: 12345
     categories:
       - name: foo
         description: "fooey"
       - name: bar
         description: "bar-ish"
       - name: bat
         description: "batter up"

- print: State is <% user.address.state %> 
- print: Second category's description is <% user.categories.1.description %>.

Pipes

Pipes are a powerful mechanism that can be used to transform/modify the value that a macro outputs. Common uses for pipes include:

• url-encoding a value <% order_id | urlencode %>
• converting a value to proper-case <% name | capcase %>
• returning the length of a string (or array) <% items | length %>

Pipes can be used to parse/format dates, perform arithmetic with numbers, access the "current" element in an array, or many other manipulations. For detailed information, see the pipes reference.

Double-interpolation

Backtick expressions allow interpolation expressions to be evaluated within interpolation expressions. This is useful for passing session context values as pipe parameters or for using session context values as part of the path for a "value-map" in the session data.

Backtick expressions within an interpolation macro are processed first, as if they were a separate interpolation macro. The backtick expression is then replaced with the results of that interpolation and used in the evaluation of the containing macro.

Let's look at an example that uses backtick expressions to perform a value-mapping. We have one object in the session "colors" which represents a mapping between color names and hex code. The expression at the end then uses that mapping to retrieve the hex-code by using the name mapping.

- set:
    color: red
    colors: 
      red: "#FF0000"
      green: "#00FF00"
      blue: "#0000FF"

- print: The hexcode for <% color %> is <% colors.`color` %>

Markup.js

The hyperpotamus interpolation engine uses a customized version of Markup.js (but there is a pull-request pending :). You can read about the processing capabilities of Markup.js on the markup.js project home.

Here are some of the differences in the standard markup-us and the hyperpotamus version:

<% delimiters %>

Markup.js uses {{ delimiters }} to identify macros. hyperpotamus instead uses <% delimiters %>. This is important because the standard {{ }} syntax is often mis-interpreted in YAML files.

Literal values

Hyperpotamus allows for the initial property-path value to be replaced with a literal string value by enclosing it in single (') or double quotes ("). Literals <% "literal value" | capcase %> are useful for processing values with pipes.

Object references

When a Markup.js macro is processed, the final result is converted to a string. Hyperpotamus adds the ability to disable that "string-ification" and to return the final result as the unmodified object value. To indicate an object reference, add a "!" after the opening delimiter such as: <%! user.address %>.