ffizer

# Templates Authoring

The documentation is a Work In Progress, feel free to ask details, missing info or to submit content (via Pull Request).

## Rules

- The minimal template is an empty dir.

- a sample template and its expected output (on empty folder) is available at tests/test_1.

- file priority (what file will be used if they have the same destination path)

      existing file
      file with source extension .ffizer.hbs (and no {{...}} in the source file path)
      file with identical source file name (and extension)
      file with {{...}} in the source file path

# A 5 minutes tutorial

1. create the folder with the template

       mkdir my-template
       cd my-template

2. add file that will be copied as is

       cat > file0.txt <<EOF
       I am file0.
       EOF

3. add a template file that will be "rendered" by the handlebars engine

   - the file should have the .ffizer.hbs extension,
   - the extension .ffizer.hbs is removed from the generated filename
   - Handlebars templating language

       cat > file1.txt.ffizer.hbs <<EOF
       I am file1.txt of {{ project }}.
       EOF

4. add a ffizer configuration file (.ffizer.yaml)

   - to list variables
   - to list pattern to ignore

       variables:
         - name: project
           default_value: my-project

       ignores:
         - .git # exclude .git of the template host

5. add a file with a name that will be "rendered" by the handlebars engine

   - the file should have {{ variable }},
   - Handlebars templating language

       cat > '{{ project }}.txt' <<EOF
       I am a fixed content file with rendered file name.
       EOF

# Configuration

The configuration is:

- optionnal
- stored into a yaml file named `.ffizer.yaml` at the root of the template.
- sections (top level entry) of the yaml are optionnals

    variables:
      - name: project
        default_value: my-project

    ignores:
      - .git # exclude .git of the template host

## Sections

### variables

List the variables usable into the `.ffizer.hbs` template file. Variables are defined by:

- `name`: (required) the name of the variable
- `default_value`: a suggested value, the value is a string and support hbs templating
- `ask`: the sentence use to prompt user to set the value of the variable

Variables definition are prompt in the order of the list, and with the prompt defined by `ask` (if defined, else `name`)

    variables:
      - name: project_name
        default_value: "{{ file_name ffizer_dst_folder }}"

### ignores

### imports

# The predefined variables

Some variables are predefined and they can be used into `.ffizer.yaml` into the `ignores` section or `default_value` via handlebars expression.

- `ffizer_dst_folder` contains the value from cli arg `--destination`
- `ffizer_src_rev` contains the value from cli arg `--rev`
- `ffizer_src_uri` contains the value from cli arg `--source`

The following sample combine a helper function `file_name` with `ffizer_dst_folder`.

    variables:
      - name: project_name
        default_value: "{{ file_name ffizer_dst_folder }}"

# Template Helpers / Functions

Helpers extend the template to generate or to transform content. Few helpers are included, but if you need more helpers, ask via an issue or a PR.

To use an helper:

    {{ helper_name argument}}

To chain helpers, use parenthesis:

    {{ to_upper_case (to_singular "Hello foo-bars") }}
    // -> "BAR"

see Handlebars templating language

## String transformation

for the same input: "Hello foo-bars"

helper_name | example out
--- | ---
to_lower_case | "hello foo-bars"
to_upper_case | "HELLO FOO-BARS"
to_camel_case | "helloFooBars"
to_pascal_case | "HelloFooBars"
to_snake_case | "hello_foo_bars"
to_screaming_snake_case | "HELLO_FOO_BARS"
to_kebab_case | "hello-foo-bars"
to_train_case | "Hello-Foo-Bars"
to_sentence_case | "Hello foo bars"
to_title_case | "Hello Foo Bars"
to_class_case | "HelloFooBar"
to_table_case | "hello_foo_bars"
to_plural | "bars"
to_singular | "bar"

## Http content

Helper able to render body response from an http request.

helper_name | usage
--- | ---
http_get | http_get "http://hello/..."
gitignore_io | gitignore_io "rust"

## Path extraction

Helper able to extract (or transform) path (defined as string).

for the same input: "/hello/bar/foo.txt"

helper_name | sample output
--- | ---
file_name | "foo.txt"
parent | "/hello/bar"
extension | "txt"