5. Built‐ins, Helpers, and Settings - SuperCuber/dotter GitHub Wiki

Variables

Dotter automatically defines the built-in variable dotter, that is a mapping with the following keys:

  • dotter.packages - a mapping between the package name and the value true of the selected packages, intended to be used like {{#if dotter.packages.my_package}} (this will evaluate to false for packages that aren't enabled)
  • dotter.files - a mapping between the source and target of each deployed file
  • dotter.os - either windows or unix, use something like {{#if (eq dotter.os "unix")}}
  • dotter.current_dir - contains the absolute path to the directory Dotter was ran from (usually the root of the repository)

Helpers

Handlebars supports "helper" functions to transform and operate on variables. Dotter has several built-in helpers.

Built-in helpers

  • Ones defined by Handlebars itself
  • math - used like {{math font_size "*" 2}}.
    Executed by meval-rs.
  • include_template - used to include the contents of another file. If the file is a template, it is also rendered.
  • is_executable - used to check whether a program is able to be executed.
    Use with an if statement: {{#if (is_executable "cargo")}}
  • command_success - runs the command and checks if it exited successfully.
    Use with an if statement: {{#if (command_success "test 5 = 5")}}
  • command_output - runs the command and inserts the output into the template.
    Use like so: {{command_output "cargo --help"}}
  • All the helpers from handlebars_misc_helpers

Custom

The Rust implementation of Handlebars supports custom helpers written in the scripting language rhai.

To define one yourself, add it in the optional [helpers] section in global.toml in the form of script_name = "script_file_location".
The ones I currently use will be in the helpers folder of my dotfiles - you can use them as examples.

Settings

Dotter allows you to configure some global settings.

  • default_target_type: symbolic or template or automatic. Defaults to automatic

Sets the default target type for any package files that don't explicity set a target type.

In global.toml:

[settings]
default_target_type = "symbolic"

[nvim]
depends = []

[nvim.files]
nvim = "~/.config/nvim" # Does not attempt to detect anymore, will always be symbolic