ffizer 0.8.0

ffizer is a files and folders initializer / generator. Create any kind (or part) of project from template.
Documentation

ffizer

Crates.io Crates.io

Project Status: WIP โ€“ Initial development is in progress, but there has not yet been a stable, usable release suitable for the public. Build Status

Crates.io GitHub All Releases

ffizer is a files and folders initializer / generator. Create any kind (or part) of project from template.

keywords: file generator, project template, project scaffolding, quickstart, project initializer, project skeleton

Motivations

Main features

  • project generator as a standalone executable (no shared/system dependencies (so no python + pip + ...))
  • a simple and generic project template (no specialisation to one ecosystem)
  • template as simple as possible, like a
    • copy or clone with file/folder renames without overwrite
    • few search and replace into file
  • template hosted as a local folder on the file system
  • template hosted as a git repository on any host (not only public github)
    • at root of the repository
    • in subfolder of the repository
    • in any revision (branch, tag, commit)
  • template composed of other template
    • composite template are regular standalone template
    • composite template can be apply at root folder
  • a fast enough project generator

Sub features

  • dry mode (usefull to test)
  • chain template generation because fragment of templates can be commons
  • chain commands (eg: 'git init') (like a post-hook)
    • raw command
  • composite template can be apply at root folder
  • composite template include under conditions
  • file / folder ignored under conditions (ignores'item in ffizer.yaml are defined as handlerbar expression)
  • handlebars helpers
    • transform strings (toUpperCase, toLowerCase, Capitelize,...)
    • render content of GET url
    • render content from https://gitignore.io
    • suggestions welcomes ;-)

Limitations

Some of the following limitations could change in the future (depends on gain/loss):

  • no conditionnals file or folder creation
  • no update of existing file or folder
  • no specials features
  • no plugin and not extensible (without change the code)
  • handlebars is the only template language supported (support for other is welcome)

Usages

Install

via github releases

Download the binary for your platform from github releases, then unarchive it and place it your PATH.

via cargo

cargo install ffizer

Run

ffizer 0.8.0
davidB
ffizer is a files and folders initializer / generator. Create any kind (or part) of project from template.

USAGE:
    ffizer [FLAGS] [OPTIONS] --destination <dst_folder> --source <src_uri>

FLAGS:
    -h, --help                      Prints help information
        --offline                   in offline, only local templates or cached templates are used
    -V, --version                   Prints version information
    -v, --verbose                   Verbose mode (-v, -vv (very verbose / level debug), -vvv) print on stderr
        --x-always_default_value    should not ask for valiables values, always use defautl value or empty
                                    (experimental)

OPTIONS:
        --confirm <confirm>             ask confirmation 'never' or 'always' [default: never]
    -d, --destination <dst_folder>      destination folder (created if doesn't exist)
        --source-folder <src_folder>    path of the folder under the source uri to use for template
        --rev <src_rev>                 git revision of the template [default: master]
    -s, --source <src_uri>              uri / path of the template
  • use a local folder as template
    ffizer --source $HOME/my_templates/tmpl0 --destination my_project
    
  • use a remote git repository as template
    ffizer --source https://github.com/davidB/ffizer_demo_template.git --destination my_project
    
    output
    Configure variables
    
    project_name: my_project
    
    
    Plan to execute
    
      - mkdir "my_project/"
      - mkdir "my_project/dir_1"
      - copyraw "my_project/dir_1/file_1_1.txt"
      - mkdir "my_project/dir_2_my_project"
      - copyraw "my_project/dir_2_my_project/file_1_2.txt"
      - copyraw "my_project/file_1.txt"
      - copyrender "my_project/file_2.txt"
      - keep "my_project/file_2.txt"
      - copyrender "my_project/file_3.txt"
      - copyraw "my_project/file_4_my_project.txt"
      - copyrender "my_project/file_5_my_project.txt"
      - copyraw "my_project/file_6.hbs"
    

Create a template

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

    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

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

Pre-defined variables

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

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

The predefined variables are:

  • 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

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"

Templates

Build

cargo test
cargo build --release

Alternatives

Generic

  • Cookiecutter, lot of templates, require python + pip + install dependencies on system (automatic)
  • Cookiecutter โ€” Similar projects
  • sethyuan/fgen: A file generator library to be used to generate project structures, file templates and/or snippets. Templates are based on mustache. require nodejs
  • project_init in rust, use mustache for templating but I have some issues with it (project template creation not obvious, github only) I could contributes but I have incompatible requirements.
  • skeleton, good idea but no template file, more like a script.
  • porteurbars, very similar but I discovered it too late.

Specialized

specialized to a platform, build tool,...