# tinted-builder-rust

[![Matrix Chat](https://img.shields.io/matrix/tinted-theming:matrix.org)](https://matrix.to/#/#tinted-theming:matrix.org)
[![Crates.io](https://img.shields.io/crates/v/tinted-builder-rust.svg)](https://crates.io/crates/tinted-builder-rust)
[![Tests](https://github.com/tinted-theming/tinted-builder-rust/actions/workflows/ci.yml/badge.svg)](https://github.com/tinted-theming/tinted-builder-rust/actions/workflows/ci.yml)

A builder for [base16] and [base24] templates using the `0.11.1`
[builder specification].

This crate contains a command-line tool to build base16 and base24
templates. It is also a library crate which you can use to directly
build templates within your own Rust application.

## Table of Contents

- [Installation](#installation)
- [Basic usage](#basic-usage)
- [Commands](#commands)
- [Flags](#flags)
- [Builder specification](#builder-specification)
- [Contributing](#contributing)
- [License](#license)

## Installation

**Cargo**

```sh
cargo install tinted-builder-rust
```

**Homebrew**

```sh
brew tap tinted-theming/tinted
brew install tinted-builder-rust
```

**Binaries**

Download the relevant binary from the [repository releases] page.

## Basic Usage

```sh
tinted-builder-rust sync # To sync with latest schemes
tinted-builder-rust build path/to/base16-template
```

## Commands

The following is a table of the available subcommands for the CLI tool (tinted-builder-rust), including the descriptions and any notable arguments.

| Subcommand | Description | Arguments | Example Usage | Flags |
|------------|-------------|-----------|---------------|-------|
| `sync`  | Installs and or updates latest schemes. | - | `tinted-builder-rust sync` | `--quiet` (silence stderr and stdout) |
| `build` | Builds the themes of a template. | `template_path`: Path to template directory. | `tinted-builder-rust build ./path/to/base16-template` | `--quiet` (silence stderr and stdout), `--sync` (equivalent of running `tinted-builder-rust sync` before `tinted-builder-rust build`) |

## Flags

| Flag/Option | Description | Applicable Subcommands | Default Value | Example Usage |
|-------------|-------------|------------------------|---------------|---------------|
| `--schemes-dir` `-s` | Path to local schemes directories.  Used by `build` to find schemes and by `sync` to clone/pull into those paths. | `build`, `sync` | Defaults to `<data-dir>/schemes` | `tinted-builder-rust build . -s /path/one -s /path/two` |
| `--ignore` `-i`   | One or more glob patterns to skip when scanning schemes. Repeat this flag to add multiple ignores. | `build` | - | `tinted-builder-rust build . --ignore "**/LICENSE"` |
| `--data-dir` `-d` | Specifies a custom path for the data directory. | All | Linux: `$XDG_DATA_HOME/tinted-theming/tinted-builder-rust`. macOS: `~/Library/Application\ Support/tinted-theming/tinted-builder-rust` | `tinted-builder-rust sync --data-dir /path/to/custom/data-dir` |
| `--help` `-h` | Displays help information for the subcommand. | All | - | `tinted-builder-rust --help`, `tinted-builder-rust build --help`, etc |
| `--version` `-V` | Shows the version of tinted-builder-rust. | All | - | `tinted-builder-rust --version` |

## List usage

`tinted-builder-rust` supports an `options.list` config property which enables
for accessing a scheme list in a single file.

`template-repo/templates/config.yaml`:

```yaml
some-base16-list:
    filename: "base16-list.md"
    supported-systems: [base16]
    options:
        list: true

some-base24-list:
    filename: "base24-list.md"
    supported-systems: [base24]
    options:
        list: true

list-all:
    filename: "list-all.md"
    supported-systems: [base16, base24]
    options:
        list: true
```

With an example template being `templates/some-base16-list.mustache`:

```text
{{#schemes}}
  {{system}}-{{slug}} (variant: {{variant}})
{{/schemes}}
```

Note: These are unofficial scheme-systems, meaning it's not
part of the Tinted Theming scheme specification.


## Builder specification

tinted-builder-rust implements the `0.11.1` [builder specification]. This
specification details the scheme yaml format or schema as well as the
variables the builder should provide when rendering template mustache
file. Have a look at the [builder specification] document for more
details.

## Contributing

Contributions are welcome! Have a look at [CONTRIBUTING.md] for more
information.

## License

tinted-builder-rust falls under the [GPL-3.0] license. Have a look at the
[LICENSE] file.

[latest schemes repository]: https://github.com/tinted-theming/schemes
[home repository]: https://github.com/tinted-theming/home
[builder specification]: https://github.com/tinted-theming/home/blob/main/builder.md
[base16]: https://github.com/tinted-theming/home/blob/main/styling.md
[base24]: https://github.com/tinted-theming/base24/blob/master/styling.md
[CONTRIBUTING.md]: ../CONTRIBUTING.md
[repository releases]: https://github.com/tinted-theming/tinted-builder-rust/releases/latest
[GPL-3.0]: https://github.com/IQAndreas/markdown-licenses/blob/master/gnu-gpl-v3.0.md
[LICENSE]: ../LICENSE
