Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
109 lines (77 sloc) 3.46 KB

Creating Custom Templates

Boss templates are extremely easy to write. A basic template consists of the following:

  • A boss.yml config file
  • One or more files/directories to copy for new projects

Boss doesn't care what the contents of template files are, as long as it is a readable file. The following is an example python template:

-> python
    `----> @module@/
            `----> @module@.py

    `----> setup.py
    `----> setup.cfg
    `----> README
    `----> LICENSE
    `----> boss.yml

In this example, @module@ is a variable defined in the boss.yml config for this template. When calling boss create -t local:python Boss will ask the user to supply a value for @module@, and then when files/directories are copied that value will be replace at every occurrence of @module@ both in file/directory names as well as file contents.

Note that in the future we do plan to support alternative templating languages such as Mustache or Jinja2, but at this time the initial goal was simplicity and ease of use.

Boss Template Configuration Files

Currently Boss only supports a boss.json or boss.yml configuration file which is in the JSON or Yaml format respectively. The following is an example Yaml configuration file:

variables:
    version: Version
    module: Python Module Name
    class_prefix: Python Class Prefix
    project: Project Name
    description: Project Description
    creator: Project Creator
    email: Project Creator Email
    url: Project URL
    license: Project License

external_files:
    .gitignore: https://raw.github.com/github/gitignore/master/Python.gitignore
    LICENSE: https://raw.github.com/datafolklabs/license/master/@license@

The variables setting is a list of key/value pairs. The first item in the list is the variable that is set, and the second is the question as presented to the user for input.

The external_files is also a list of key/value pairs, and is optional. These are files that are pulled down externally. The first item in the external file definition is the destination path where that file should be saved to. The second is the remote URL to pull the contents from. In the above example we use external files to pull down a current .gitignore file from Github, as well as a LICENSE file for the given license if it exists.

Working with Variables

Boss treats all variables as strings. Therefore, it supports string operations during the replacement process. For example, if I had a variable of foo, then in my templates I would reference that variable as @foo@. If the value of @foo@ were bar for example, I could do things like:

  • @foo.capitalize@ => Bar
  • @foo.upper@ => BAR
  • @foo.lower@ => bar
  • @foo.title@ = Bar

These simple string operations are commonly used throughout templates. That said, don't get carried away ... Boss doesn't intend to be a robust templating language, but rather a facility to easily build and copy templates for new projects.

Delimiters

The default delimiters are ['@', '@']. In some cases, this might not work for your template. You can change this in your boss.yml or boss.json config:

delimiters: ['%', '%']

Or:

delimiters: ['{{', '}}']