📑 Clyjin Templates

Centralized template system to create files and directories.

Installation

Using PIP:

pip install clyjin_templates

Getting Started

Clyjin Templates uses Template Groups in order to define files and directories to be created.

Template Groups are defined using special convention. The central configuration file of any group is spec.yml. The spec defines files and directories to be created in form of nested objects.

An example spec file looks like:

name: my-example
description: example description
vars:
  a:
  b:
  c:
    default: true
templates:
  template_1.py:
  template_2.py:
tree:
  src:
    __init__.py:
      $content: "&template_1.py"
    drivers:
      main.py:
        $content: "&template_2.py"
    local:
      $type: dir
  README.md:
      $content: "some readme text"

Which will produce the following file tree:

.
├── src/
│   ├── __init__.py
│   ├── drivers/
│   │   └── main.py
│   └── local/
│       └── <empty-directory>
└── README.md

Let's consider each field of the spec above.

Name

Name of template group to be associated with, e.g. on CLI calls.

Description

Helper description for template group, displayed e.g. in CLI help messages.

Vars

Variables defined for current template group. Each variable might have a default value and a list of scopes it is available in.

Each var becomes available to be set via CLI on template group call. For our example above, the call with all vars defined might look like:

clyjin templates my-example "a=10,b='hello, world!',c=false"

Note that we could omitted c=false, since we defined a default value for it in the spec.yml. Although, it would result in an error for other non-default variables.

Templates

Template files defined to be referenced for this template group.

For file nodes (see below), in $content field you can point to a template object to be rendered into the file.

Tree

File tree generated by this template group. Consists of nodes. The nodes can be of two types - file or directory.

Directory node is any spec's tree node with at least one subnode, or an empty directory with $type: dir explicitly set. Other empty nodes (without subnodes or other fields) are considered as empty files by default.

File node is an empty spec's tree node or any node with $type: file set explicitly. File nodes have special field $content which defines what string will be pasted inside it on creation. The content field can have either a direct string (simply written in spec.yml file), absolute or relative (to working directory) path to template file, or pointer to in-spec defined template. In our example latter is used in form of $content: "&template_1.py".

Add a template group

In order to make your template group available in the CLI, you need to register it:

clyjin templates.add
# or
clyjin templates.add path/to/working/directory

Which will automatically search for spec.yml in the working directory and then for referenced there template files. For our example it would be:

.
├── spec.yml
├── template_1.py.mako
└── template_2.py.mako

All files will be copied to Clyjin system directory for the plugin.

Alternatively, you can explicitly define name of spec file:

clyjin templates.register -c another-spec-name.yml

Invoke a template group

In order to create files and directories out of previously registered template group you need:

clyjin templates <your-template-name> -d path/to/output/directory

In our example case, we can output our registered example in some current directory:

clyjin templates my-example

This will output rendered contents of our chosen template group in current or chosen (with -d option) directory.