clyjin-templates 0.1.0
Creates files and directories using templates
Requires Python: >=3.11,<4.0

# 📑 Clyjin Templates

Centralized template system to create files and directories.

## Installation

Using PIP:
```sh
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:
```yaml
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:
```sh
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:
```sh
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](https://github.com/ryzhovalex/clyjin)
system directory for the plugin.

Alternatively, you can explicitly define name of spec file:
```sh
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:
```sh
clyjin templates <your-template-name> -d path/to/output/directory
```

In our example case, we can output our registered example in some current
directory:
```sh
clyjin templates my-example
```

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