search

gruntwork-io / boilerplate

A tool for generating files and folders ("boilerplate") from a set of templates
https://www.gruntwork.io
Mozilla Public License 2.0
157 stars 12 forks source link

readme

Boilerplate

Boilerplate is a tool for generating files and folders ("boilerplate") from a set of templates.

Example use cases:

  1. Scaffold out a new repo, folder, or file.
  2. Fill in boilerplate sections in your code files, such as including a legal disclaimer or license at the top of each source file, or updating a version number in a file after each build.
  3. Embed code snippets from actual source files in documentation. Most READMEs have code copy/pasted into them and that code often has syntax errors or goes out of date. Now you can keep those code examples in normal source files which are built & tested, and embed parts of those files dynamically in your docs.

See Introducing Boilerplate for a quick introduction.

Example: creating a new template

Create a folder called website-boilerplate and put a file called boilerplate.yml in it:

variables:
  - name: Title

  - name: WelcomeText
    description: Enter the welcome text for the website

  - name: ShowLogo
    description: Should the website show the logo?
    type: bool
    default: true

This file defines 3 variables: Title, WelcomeText, and ShowLogo. When you run Boilerplate, it will prompt the user for each one.

Next, create an index.html in the website-boilerplate folder that uses these variables using Go Template syntax:

<html>
  <head>
    <title>{{.Title}}</title>
  </head>
  <body>
    <h1>{{.WelcomeText}}</h1>
    {{if .ShowLogo}}<img src="https://github.com/gruntwork-io/boilerplate/raw/master/logo.png">{{end}}
  </body>
</html>

Copy an image into the website-boilerplate folder and call it logo.png.

Finally, run boilerplate, setting the --template-url to website-boilerplate and --output-folder to the path where you want the generated code to go:

boilerplate --template-url /home/ubuntu/website-boilerplate --output-folder /home/ubuntu/website-output

Title

  Enter a value [type: string]: Boilerplate Example

WelcomeText
  Enter the welcome text for the website

  Enter a value [type: string]: Welcome!

ShowLogo
  Should the website show the logo?

  Enter a [type: bool]: true

Generating /home/ubuntu/website-output/index.html
Copying /home/ubuntu/website-output/logo.png

Boilerplate copies any files from the --template-url into the --output-folder, passing them through the Go Template engine along the way. After running the command above, the website-output folder will contain a logo.png (unchanged from the original) and an index.html with the following contents:

<html>
  <head>
    <title>Boilerplate</title>
  </head>
  <body>
    <h1>Welcome!</h1>
    <img src="https://github.com/gruntwork-io/boilerplate/raw/master/logo.png">
  </body>
</html>

You can also run Boilerplate non-interactively, which is great for automation:

boilerplate \
  --template-url /home/ubuntu/website-boilerplate \
  --output-folder /home/ubuntu/website-output \
  --non-interactive \
  --var Title="Boilerplate Example" \
  --var WelcomeText="Welcome!" \
  --var ShowLogo="true"

Generating /home/ubuntu/website-output/index.html
Copying /home/ubuntu/website-output/logo.png

Of course, Boilerplate can be used to generate any type of project, and not just HTML, so check out the examples folder for more examples and the Working with Boilerplate section for full documentation.

Install

Download the latest binary for your OS here.

You can find older versions on the Releases Page.

Features

  1. Interactive mode: Boilerplate interactively prompts the user for a set of variables defined in a boilerplate.yml file and makes those variables available to your project templates during copying.
  2. Non-interactive mode: Variables can also be set non-interactively, via command-line options, so that Boilerplate can be used in automated settings (e.g. during automated tests).
  3. Flexible templating: Boilerplate uses Go Template for templating, which gives you the ability to do formatting, conditionals, loops, and call out to Go functions. It also includes helpers for common tasks such as loading the contents of another file.
  4. Variable types: Boilerplate variables support types, so you have first-class support for strings, ints, bools,
  5. Validations: Boilerplate provides a set of validations for a given variable that user input must satisfy.
  6. Variable presentation order: Boilerplate allows you to define the relative presentation order of a set of variables. lists, maps, and enums.
  7. Scripting: Need more power than static templates and variables? Boilerplate includes several hooks that allow you to run arbitrary scripts.
  8. Cross-platform: Boilerplate is easy to install (it's a standalone binary) and works on all major platforms (Mac, Linux, Windows).

Working with boilerplate

When you run Boilerplate, it performs the following steps:

  1. Read the boilerplate.yml file in the folder specified by the --template-url option to find all defined varaibles.
  2. Gather values for the variables from any --var and --var-file options that were passed in and prompting the user for the rest (unless the --non-interactive flag is specified).
  3. Copy each file from --template-url to --output-folder, running each non-binary file through the Go Template engine with the map of variables as the data structure.

Learn more about boilerplate in the following sections:

  1. Boilerplate command line options
  2. The boilerplate.yml file
  3. Variables
  4. Dependencies
  5. Hooks
  6. Skip Files
  7. Templates
  8. Validations
  9. Variable Ordering
  10. Alternative Template Engines (EXPERIMENTAL)
  11. Template helpers
  12. Deprecated helpers
  13. Partials

Boilerplate command line options

The boilerplate binary supports the following options:

Some examples:

Generate a project in ~/output from the templates in ~/templates:

boilerplate --template-url ~/templates --output-folder ~/output

Generate a project in ~/output from the templates in ~/templates, using variables passed in via the command line:

boilerplate --template-url ~/templates --output-folder ~/output --var "Title=Boilerplate" --var "ShowLogo=false"

Generate a project in ~/output from the templates in ~/templates, using variables read from a file:

boilerplate --template-url ~/templates --output-folder ~/output --var-file vars.yml

Generate a project in ~/output from the templates in this repo's include example dir, using variables read from a file:

boilerplate --template-url "git@github.com:gruntwork-io/boilerplate.git//examples/for-learning-and-testing/include?ref=master" --output-folder ~/output --var-file vars.yml

The boilerplate.yml file

The boilerplate.yml file is used to configure boilerplate. The file is optional. If you don't specify it, you can still use Go templating in your templates so long as you specify the --missing-config-action ignore option, but no variables or dependencies will be available.

boilerplate.yml uses the following syntax:

required_version: <VERSION_CONSTRAINT>

variables:
  - name: <NAME>
    description: <DESCRIPTION>
    type: <TYPE>
    options:
      - <CHOICE>
      - <CHOICE>
    default: <DEFAULT>
    reference: <NAME>

dependencies:
  - name: <DEPENDENCY_NAME>
    template-url: <FOLDER>
    output-folder: <FOLDER>
    skip: <CONDITION>
    dont-inherit-variables: <BOOLEAN>
    for_each: <LIST>
    for_each_reference: <NAME>
    variables:
      - name: <NAME>
        description: <DESCRIPTION>
        type: <TYPE>
        default: <DEFAULT>

hooks:
  before:
    - command: <CMD>
      args:
        - <ARG>
      env:
        <KEY>: <VALUE>
      skip: <CONDITION>
  after:
    - command: <CMD>
      args:
        - <ARG>
      env:
        <KEY>: <VALUE>
      skip: <CONDITION>

partials:
  - <GLOB>
  - <GLOB>

Here's an example:

variables:
  - name: Description
    description: Enter the description of this template

  - name: Version
    description: Enter the version number that will be used by the docs dependency

  - name: Title
    description: Enter the title for the dependencies example

  - name: WelcomeText
    description: Enter the welcome text used by the website dependency

  - name: ShowLogo
    description: Should the webiste show the logo (true or false)?
    type: bool
    default: true

dependencies:
  - name: docs
    template-url: ../docs
    output-folder: ./docs
    variables:
      - name: Title
        description: Enter the title of the docs page

  - name: website
    template-url: ../website
    output-folder: ./website
    variables:
      - name: Title
        description: Enter the title of the website

skip_files:
  - path: .ignore-me
  - path: subfolder/README.md
    if: {{ not .ShowLogo }}

engines:
  - path: subfolder/foo.json.jsonnet
    template_engine: jsonnet

partials:
  - ../html/*.html
  - ../css/*.css
  - ../other/somefile.html

Required Version: A version constraint string in the same format as Terraform that can be used to specify what versions of Boilerplate are supported by the config.

Variables: A list of objects (i.e. dictionaries) that define variables. Each variable may contain the following keys:

See the Variables section for more info.

Dependencies: A list of objects (i.e. dictionaries) that define other boilerplate templates to execute before executing the current one. Each dependency may contain the following keys:

See the Dependencies section for more info.

Partials: Use partials to include reusable templates. Partials are defined using a list of glob patterns.

See the Partials section for more info.

Skip Files: Use skip_files to specify files in the template folder that should not be rendered. The path field is the relative path from the template folder root (where the boilerplate.yml file is defined) of the file that should be excluded. You can conditionally skip the file using the if field, which should either be a YAML boolean value (true or false), or Go templating syntax (which can use the boilerplate variables) that evaluates to the string values "true" or "false".

See the Skip Files section for more info.

Engines: Use engines to specify files in the template folder that should be rendered with an alternative templating engine. The path field is the relative path from the template folder root (where the boilerplate.yml file is defined) of the file that should use the alternative template engine.

See the Alternative Template Engines (EXPERIMENTAL) section for more info.

Hooks: Boilerplate provides hooks to execute arbitrary shell commands. There are two types of hooks:

See the Hooks section for more info.

Variables

You must provide a value for every variable defined in boilerplate.yml, or project generation will fail. There are four ways to provide a value for a variable:

  1. --var option(s) you pass in when calling boilerplate. Example: boilerplate --var Title=Boilerplate --var ShowLogo=false. To specify a complex type like a map or a list on the command-line, use YAML syntax (preferably the shorthand variety to keep it a one-liner). For example --var foo='{key: "value"}' --var bar='["a", "b", "c"]'. If you want to specify the value of a variable for a specific dependency, use the <DEPENDENCY_NAME>.<VARIABLE_NAME> syntax. For example: boilerplate --var Description='Welcome to my home page!' --var about.Description='About Us' --var ShowLogo=false.

  2. --var-file option(s) you pass in when calling boilerplate. Example: boilerplate --var-file vars.yml. The vars file must be a simple YAML file that defines key, value pairs, where the key is the name of a variable (or <DEPENDENCY_NAME>.<VARIABLE_NAME> for a variable in a dependency) and the value is the value to set for that variable. Example:

    Title: Boilerplate
ShowLogo: false
Description: Welcome to my home page!
about.Description: Welcome to my home page!
ExampleOfAMap:
 key1: value1
 key2: value2
ExampleOfAList:
 - value1
 - value2
  3. Manual input. If no value is specified via the --var or --var-file flags, Boilerplate will interactively prompt the user to provide a value. Note that the --non-interactive flag disables this functionality.
  4. Defaults defined in boilerplate.yml. The final fallback is the optional default that you can include as part of the variable definition in boilerplate.yml.

Note that variables can reference other variables using Go templating syntax:

variables:
  - name: Foo
    default: foo

  - name: Bar
    default: "{{ .Foo }}-bar"

If you rendered {{ .Bar }} with the variables above, you would get foo-bar. Note that this will always return a string. If you want to reference another variable of a non-string type (e.g. a list), use the reference keyword:

variables:
  - name: Foo
    type: list
    default:
      - 1
      - 2
      - 3

  - name: Bar
    type: list
    reference: Foo

In the example above, the Bar variable will be set to the same (list) value as Foo.

Dependencies

Specifying dependencies within your boilerplate.yml files allows you to chain multiple boilerplate templates together. This allows you to create more complicated projects from simpler pieces.

Note the following:

Hooks

You can specify hooks in boilerplate.yml to tell Boilerplate to execute arbitrary shell commands.

Note the following:

Skip Files

You can specify files that should be excluded from the rendered output using the skip_files section in boilerplate.yml. This is most useful when you have templates that need to conditionally exclude files from the rendered folder list.

The skip_files section is a list of objects with the fields path, not_path, and if, where one of path or not_path is required. When path is set, all files that match the path attribute will be skipped, while when not_path is set, all files that DO NOT match the not_path attribute are skipped (in other words, only paths that match not_path are kept).

if can be used to conditionally skip a file from the template folder, and it defaults to true. That is, when if is omitted, the file at the path is always excluded from the output. Note that path and not_path are always the relative path from the template root.

All three attributes (path, not_path, and if) support Go templating syntax with access to boilerplate variables and template helpers.

Consider the following boilerplate template folder:

.
├── boilerplate.yml
├── BOILERPLATE_README.md
└── docs
    ├── README_WITH_ENCRYPTION.md
    └── README_WITHOUT_ENCRYPTION.md

Suppose that you wanted to conditionally select which README to render based on some variable. You can use skip_files to implement this logic:

variables:
  - name: UseEncryption
    type: bool

skip_files:
  - path: "BOILERPLATE_README.md"
  - path: "docs/README_WITH_ENCRYPTION.md"
    if: "{{ not .UseEncryption }}"
  - path: "docs/README_WITHOUT_ENCRYPTION.md"
    if: "{{ .UseEncryption }}"
  - not_path: "docs/**/*"
    if: "{{ .DocsOnly }}"

This will:

For a more concise specification, you can use glob syntax in the path to match multiple paths in one entry:

skip_files:
  - path: "docs/**/*"

Templates

Boilerplate puts all the variables into a Go map where the key is the name of the variable and the value is what the user provided. It then starts copying files from the --template-url into the --output-folder, passing each non-binary file through the Go Template engine, with the variable map as a data structure.

For example, if you had a variable called Title in your boilerplate.yml file, then you could access that variable in any of your templates using the syntax {{.Title}}. You can also use Go template syntax to do if-statements, for loops, and use the provided template helpers.

You can even use Go template syntax and boilerplate variables in the names of your files and folders. For example, if you were using boilerplate to generate a Java project, your template folder could contain the path com/{{.PackageName}}/MyFactory.java. If you run boilerplate against this template folder and enter "gruntwork" as the PackageName, you'd end up with the file com/gruntwork/MyFactory.java.

Validations

Boilerplate allows you to specify a set of validations when defining a variable. When a user is prompted for a variable that has validations defined, their input must pass all defined validations. If the user's input does not pass all validations, they'll be presented with real-time feedback on exactly which rules their submission is failing. Once a user's submission passes all defined validations, Boilerplate will accept their submitted value.

Here's an example prompt for a variable with validations that shows how invalid submissions are handled:

Example Boilerplate real-time validation

Here's an example demonstating how to specify validations when defining your variables:

variables:
  - name: CompanyName
    description: Enter the name of your organization.
    default: ""
    type: string
    validations:
      - required
      - length-5-22
      - alphanumeric

This boilerplate.yml snippet defines a variable, CompanyName which:

Currently supported validations

Boilerplate uses the go-ozzo/ozzo-validation library. The following validations are currently supported:

Variable Ordering

Boilerplate allows you to define the relative order in which a set of variables should be presented to the user when prompting for human input.

Here's an example demonstrating how to define the relative order of a set of variables:

variables:
  - name: WebsiteURL
    order: 0
    description: Enter the URL to your homepage
 - name: ImagePath:
   order: 1
   description: Enter the full filepath to your logo image
 - name: ProfileName
   order: 2
   description: Enter the display name for your user

Alternative Template Engines (EXPERIMENTAL)

Boilerplate has experimental support for the following alternative template engines:

To specify an alternative template engine, you can use the engines directive to provide a path glob that matches the files that should be fed through the alternative engine. For example, the following boilerplate configuration makes it so that any file with the .jsonnet extension will be fed through the jsonnet template engine:

engines:
  - path: "**/*.jsonnet"
    template_engine: jsonnet

Note that alternative template engines are currently only supported for processing individual files, and can not be used for parsing boilerplate directives in the config file or directory names.

See below for more information on each of the template engines supported:

IMPORTANT: Support for template helpers are limited to the go templating engine at this time. Some limited functions may be available depending on the template engine. See the information for the templating engine to know which functions are supported.

Jsonnet

Jsonnet is a data template engine optimized for generating json data. Unlike go templating, jsonnet has many features that make it more friendly to write such as:

When boilerplate processes jsonnet templates, the variables are passed through as a Top Level Argument under the name boilerplateVars. This means that every jsonnet template must be defined in a way to handle the TLA argument. For example:

function(boilerplateVars) {
  person: {
    name: boilerplateVars.Name,
  },
}

Boilerplate will also make available the following helpers as external variables:

While the jsonnet template engine does not support the boilerplate helper functions, it does have access to the Jsonnet standard library. You can also import any libsonnet library in your jsonnet template, including those installed with jsonnet-bundlery.

Note that to ensure you can have editor assistance while modifying jsonnet files, the jsonnet template engine in boilerplate will strip the extension suffix .jsonnet from the output file path. E.g., if your template folder contained:

.
├── boilerplate.yml
└── data.json.jsonnet

The output folder will be:

.
└── data.json

Template helpers

Your templates have access to all the standard functionality in Go Template, including conditionals, loops, and functions.

Additionally, boilerplate ships with sprig (version 3.2.1), the standard library of template functions. You can view all the functions available in sprig here. Note that there are some differences for some functions due to backwards compatibility. Take a look at Deprecated helpers.

Boilerplate also includes several custom helpers that you can access that enhance the functionality of sprig:

Deprecated helpers

These helpers are deprecated. They are currently available for backwards compatibility, but may be removed in future versions. Please use the alternative supported forms listed in the description.

The following functions overlap with sprig, but have different functionality. There is an equivalent function listed above under a different name. These point to the boilerplate implementations for backwards compatibility. Please migrate to using the new naming scheme, as they will be updated to use the sprig versions in future versions of boilerplate.

Partials

Partials help to keep templates DRY. Using partials, you can define templates in external files, and then use those templates over and over again in other templates. Partials are common among templating engines, such as in Hugo.

Let's start with a simple example. In an HTML document, we might want to have a common set of meta tags to reuse throughout our site:

<html>
  <head>
    <meta charset="UTF-8">
    <meta name="author" content="Gruntwork">
  </head>
  <body>
    <h1>Welcome to this page!</h1>
    <img src="https://github.com/gruntwork-io/boilerplate/raw/master/logo.png">
  </body>
</html>

Rather than add these tags in a <head> section within each and every file, we could define a partial, then reuse it throughout the site.

We define the header in partials/header.html:

{{ define "header" }}
  <head>
    <meta charset="UTF-8">
    <meta name="author" content="Gruntwork">
  </head>
{{ end }}

Then we set up the structure in templates/boilerplate.yml:

partials:
  - ../partials/*.html

In templates/page.html:

<html>
{{ template "header" }}
  <body>
    <h1>Welcome to this page!</h1>
    <img src="https://github.com/gruntwork-io/boilerplate/raw/master/logo.png">
  </body>
</html>

The contents of the header template will be rendered within page.html and any other page in which we call the header partial.

Let's see a slightly more involved example.

<html>
  <head>
    <title>Welcome!</title>
  </head>
  <body>
    <h1>Welcome to this page!</h1>
    <img src="https://github.com/gruntwork-io/boilerplate/raw/master/logo.png">
  </body>
</html>

The example above shows the HTML for a web page, with a title, a welcome message, and a logo. Now, if we wanted to have another page showing a different title and body, we'd have to duplicate all of that content.

In the example below, we'll create a partial that represents the basic layout of the site, then reuse that layout for each page. First, we create a directory structure to keep everything organized:

.
├── partials
│   └── layout.html
└── template
    ├── about
    │   ├── about.html
    │   └── boilerplate.yml
    └── root
        ├── boilerplate.yml
        └── index.html

In partials/layout.html, we create the basic page layout:

{{ define "basic_layout" }}
<html>
  <head>
    <title>{{ .Title }}</title>
  </head>
  <body>
    {{ template "body" . }}
  </body>
</html>
{{ end }}

Now, in each of the pages on the site, we can reuse this layout. For example, from the site's root, we want the welcome page. We create the boilerplate.yml first:

partials:
  - ../../partials/*.html

variables:
  - name: Title
    description: A title for the page.
    default: "Welcome!"

Now we can use the layout within our index.html:

{{- define "body" -}}
    <h1>This is index.html.</h1>
    <img src="https://github.com/gruntwork-io/boilerplate/raw/master/logo.png">
{{- end -}}
{{- template "basic_layout" . -}}

When we run boilerplate, basic_layout template will be rendered with the contents of the index.html. Then we can use the same layout for the about page, with its corresponding boilerplate.yml.

Contents of about/boilerplate.yml:

partials:
  - ../../partials/*.html

variables:
  - name: Title
    description: A title for the page.
    default: "About"

about/about.html:

{{- define "body" -}}
    <h1>This is about.html.</h1>
{{- end -}}
{{- template "basic_layout" . -}}

Partials do not need to be located in a magic partials directory. Partials can be located anywhere and referred to using relative paths.

The list of partials is a glob that can match multiple files. The content of all of the files that match the globs will be parsed when rendering the final template. For example, you could match many HTML files at once with:

partials:
  - ../../html/*.html
  - ../../css/*.css

You can use the template definitions from any of the included partials throughout your templates.

You can use Go templating syntax in partial paths. For example, you can define a convenenience variable for a relative path to make the paths slightly easier to read:

variables:
  - name: TemplatesRoot
    description: A convenience variable identify the relative path to the root of the templates directory.
    default: ../../../../
partials:
  - "{{ .TemplatesRoot }}/html/*.html"
  - "{{ .TemplatesRoot }}/css/*.css"

Alternative project generators

Before creating Boilerplate, we tried a number of other project generators, but none of them met all of our requirements. We list these alternatives below as a thank you to the creators of those projects for inspiring many of the ideas in Boilerplate and so you can try out other projects if Boilerplate doesn't work for you:

License

This code is released under the Mozilla Public License Version 2.0. Please see LICENSE and NOTICE for more details.

Copyright © 2016 Gruntwork, Inc.