Manifest

A manifest has a name, version and set of variables. A sample manifest looks like this:

{
  "name": "bash_script",
  "version": "1.0.0",
  "metadata": {
    "app_archetype": {
      "version": "1.0.1"
    }
  },
  "variables": {
    "script_name": {
      "type": "string",
      "description": "Name of script"
    },
    "script_description": {
      "type": "string",
      "description": "Short sentence describing purpose of the script"
    }
  }
}

For a manifest to be valid, it must include all of the following keys:

• name should be a unique name that identifies a manifest for you
• version should be the version of the template
• metadata.app_archetype is information about the manifest for the app archetype gem. metadata.app_archetype.version is required, and must be less than the version of the currently installed gem.
• variables is an array of variable objects that specifies variables to be available to the template.

Variables

The variables entry on the manifest should be an array of objects that specify variables available to the template. The entry should look like this:

"variables": {
    "script_name": {
      "type": "string",
      "description": "Name of script"
    },
    "script_description": {
      "type": "string",
      "description": "Short sentence describing purpose of the script"
    }
  }

Defining a Variable

Each variable object definition supports the following keys:

• type - The expected type of the variable. Can be string, boolean, integer or map
• description - a quick description that will be shown to the user when prompting for the value
• default - an optional default that the user can choose by pressing enter when prompted
• value - hard coded value for the variable. This will not prompt the user.

As a general rule, the user will be prompted for an input on each variable unless a value is specified.

Generator Functions for Values

Generator functions can be used within the value field of the variable definition. This is useful for generating data to be inserted into filenames and template documents.

Some examples of generator functions are:

• this_year - renders the current year in YYYY format
• timestamp_now - renders the current time as a timestamp
• timestamp_utc_now - renders the current utc time as a timestamp
• random_string - renders a random string of letters and numbers up to 256 characters long

See Generator Functions for a complete list and more detail of supported generator functions.

Generator functions are called using the following syntax:

#[[function_name]], [[arg1]], [[arg2]] ...

For example to generate a 10 character random string you would specify a variable like this:

{
  "variables": [
    {
      "name": "ten_char_random_string",
      "description": "Example of a generator function call",
      "value": "#random_string, 10"
    }
  ]
}

Using a Variable

Variables can be used in file names as well as within .hbs and .erb files within the template.

Within a Filename

If you want to use the value of a variable in a filename you need to use handlebars syntax in the file name this:

01_{{script_name}}.rb

Within a Document

Variables can be used in .hbs documents using handlebars syntax (similar to filenames). Observe the usage in the following examples, which is a README.md document using the script_name and script_description example from above.

# {{script_name}}

{{ script_description }}

They can also be used in .erb files within the template like this:

# <%= script_name >

<%= script_description >

Variable Helper Functions

AppArchetype extends variables with additional functions that can be used to further parse the string that is rendered into filenames and documents. This can be useful when the filename must be of a specific case or a value requires a random string be generated.

To use a helper function, call the method on the end of the string like this:

01_{{script_name.snake_case}}

Some examples of helper functions:

• snake_case - converts a string like Some Thing to some_thing
• dash_case - converts a string like some_thing or Some Thing to some-thing
• camel_case - converts a string like Some Thing to SomeThing
• pluralize - attempts to make a singular word a plural (i.e. cake to cakes)
• singularize - attempts to mkae a plural word a singular (i.e. things to thing)

These functions can be chained together as well like:

01_{{script_name.pluralize.camel_case}}

See Helper Functions for a complete list and more detail of supported helper functions.

Jsonnet Support

If plain ol’ JSON isn’t quite enough for you - manifests can also be expressed in jsonnet language. This permits you to use functions and objects to generate your template manifest. All manifest.json/manifest.jsonnet files will be parsed as you might expect.

See https://jsonnet.org/ for more jsonnet documentation