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.current_dir - contains the absolute path to the directory Dotter was ran from (usually the root of the repository)
  • DEPRECATED dotter.os - either windows or unix, use something like {{#if (eq dotter.os "unix")}}
  • dotter.unix, dotter.windows, dotter.macos, dotter.linux - boolean value depending on your platform. unix is true for linux and macos platforms.

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