Getting Started with Alterant

Installing Alterant

Alterant is available as a Ruby gem. We recommend installing Alterant using RubyGems with the following command: gem install alterant Once installed, you should be able to check Alterant version alterant version

Basics

Alterant is very simple to use. Configuration file (YAML or JSON) comes in, a Javascript “modifier” is applied to it to modify it and the output is generated in YAML or JSON format.

Writing your first modifier script

Modifiers are written in Javascript. While the language is Javascript, only the base JS libraries are available (no file access, no IO control) to allow potentially unsafe scripts run on a CI server for example. There are a few helpers provided by Alterant to help with writing modifiers. The first one is $. $ is the input document that’s passed into Alterant. Let’s see it in an example:

foo:
  bar: ham

Let’s save this as input.yml.

With the above YAML used as input, $ will be the entire document. This means $.foo.bar will be ham. Now let’s make a change to the document:

$.foo.bar = "eggs"

Save the above script as my_mod.js.

Now, you can apply the modifier to the input:

$ alterant modify --in input.yml --modifier my_mod.js
---
foo:
  bar: eggs

As you can see, the input configuration file is loaded into a Javascript object called $ and given to your modifier script. By the end of the process, Alterant converts $ into a YAML file and writes the output.

A second example

Using the previous input, let’s write a modifier to add a new node to the foo array:

$.foo.push({ fuzz: "fish" })

This will generate this output:

foo:
  bar: ham
  fuzz: fish

There is a lot more you can do with Alterant, see some examples, or jump right into learning about Alterant CLI.