Topiary

https://topiary.tweag.io/book
Admin
Topiary is a universal formatter engine for simple languages built on Tree-sitter that allows...
Tokens:32,401
Snippets:496
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Topiary with Nix

Source: https://topiary.tweag.io/book/print.html

Install Topiary using Nix if you are not using flakes.

```bash
nix-shell -p topiary
```

--------------------------------

### Install Topiary with Nix Environment (No Flakes)

Source: https://topiary.tweag.io/book/getting-started/installation/package-managers.html

Install Topiary using the traditional Nix environment command. Note: Use nixos.topiary on NixOS. This command installs Topiary into your user profile.

```bash
# Or, without flakes:
nix-env -iA nixpkgs.topiary
```

--------------------------------

### Install Topiary with Home Manager

Source: https://topiary.tweag.io/book/print.html

Install Topiary for your user using Home Manager by adding it to your home.nix file.

```nix
home.packages = with pkgs; [
  topiary
];
```

--------------------------------

### Install Topiary with Home Manager

Source: https://topiary.tweag.io/book/getting-started/installation/package-managers.html

Install Topiary using Home Manager for user-specific package management. Add Topiary to your home.nix configuration.

```nix
home.packages = with pkgs;
  [ topiary ];
```

--------------------------------

### Install Topiary using Nix Profile

Source: https://topiary.tweag.io/book/print.html

Install Topiary using the Nix package manager, either with flakes or without. Note the NixOS specific command.

```bash
# Using flakes:
nix profile install nixpkgs#topiary

# Or, without flakes:
# (Note: Use nixos.topiary on NixOS)
nix-env -iA nixpkgs.topiary
```

--------------------------------

### Install Topiary CLI with Cargo

Source: https://topiary.tweag.io/book/getting-started/installation/package-managers.html

Install the Topiary CLI using the Rust package manager, Cargo. Ensure you have Rust and Cargo installed.

```bash
cargo install topiary-cli
```

--------------------------------

### Install Topiary with Nix Profile (Flakes)

Source: https://topiary.tweag.io/book/getting-started/installation/package-managers.html

Install Topiary using Nix flakes. This command adds Topiary to your user profile, making it available in your environment.

```bash
# Using flakes:
nix profile install nixpkgs#topiary
```

--------------------------------

### Install Topiary from AUR

Source: https://topiary.tweag.io/book/getting-started/installation/package-managers.html

Install Topiary from the Arch User Repository (AUR) using an AUR helper like `yay`. This is for Arch Linux users.

```bash
yay -S topiary
```

--------------------------------

### Install Topiary with OPAM

Source: https://topiary.tweag.io/book/getting-started/installation/package-managers.html

Install Topiary using OPAM, the OCaml package manager, for formatting OCaml code. This is useful for OCaml development workflows.

```bash
opam install topiary
```

--------------------------------

### Topiary Output Example

Source: https://topiary.tweag.io/book/cli/usage/index.html

The resulting output after running the format command on JSON input.

```json
{ "foo": "bar" }
```

--------------------------------

### Install Topiary with Homebrew

Source: https://topiary.tweag.io/book/getting-started/installation/package-managers.html

Install Topiary using Homebrew, the package manager for macOS and Linux. This command adds Topiary to your system.

```bash
brew install topiary
```

--------------------------------

### Install Topiary on NixOS

Source: https://topiary.tweag.io/book/print.html

Add Topiary to your system packages on NixOS by including it in your configuration.nix file.

```nix
environment.systemPackages = with pkgs; [
  topiary
];
```

--------------------------------

### JSON Input Example

Source: https://topiary.tweag.io/book/reference/capture-names/vertical-spacing.html

This JSON demonstrates single-line and multi-line contexts for testing Topiary's formatting queries.

```json
{
  "single-line": [1, 2, 3, 4],
  "multi-line": [
    1, 2,
    3
    , 4
  ]
}
```

--------------------------------

### Example JSON Input

Source: https://topiary.tweag.io/book/print.html

Sample JSON structure used to demonstrate line break formatting contexts.

```json
__
{
  "single-line": [1, 2, 3, 4],
  "multi-line": [
    1, 2,
    3
    , 4
  ]
}
```

--------------------------------

### Tree-sitter Query Rules

Source: https://topiary.tweag.io/book/guides/suggested-workflow.html

Examples of Tree-sitter query patterns for formatting nodes.

```lisp
(type_constructor_path) @append_space
```

```lisp
(
  (type_constructor_path) @append_space
  .
  (type_constructor_path)
)
```

```lisp
(constructed_type
  (_) @append_space
  .
  (_)
)
```

--------------------------------

### Basic Query Example

Source: https://topiary.tweag.io/book/print.html

A simple query pattern that captures a comma and any subsequent node.

```scm
__
(
  "," @append_space
  .
  (_)
)
```

--------------------------------

### Debugging query matches

Source: https://topiary.tweag.io/book/reference/capture-names/general.html

Examples showing log output and the use of the #query_name! predicate for easier debugging.

```text
[2024-10-08T15:48:13Z INFO  topiary_core::tree_sitter] Processing match: LocalQueryMatch { pattern_index: 17, captures: [ {Node "," (1,3) - (1,4)} ] } at location (286,1)
```

```Tree-sitter
(
  "," @append_space
  .
  (_)
)
```

```Tree-sitter
(
  "," @append_space
  .
  (_)

  (#query_name! "comma spacing")
)
```

```text
[2024-10-08T15:48:13Z INFO  topiary_core::tree_sitter] Processing match of query "comma spacing": LocalQueryMatch { pattern_index: 17, captures: [ {Node "," (1,3) - (1,4)} ] } at location (286,1)
```

--------------------------------

### Source shell completion script

Source: https://topiary.tweag.io/book/print.html

Example of sourcing the generated completion script in a Bash session.

```bash
source <(topiary completion)
```

--------------------------------

### Format Standard Input with Language and Query

Source: https://topiary.tweag.io/book/print.html

Example of formatting standard input when input files are not provided. Requires specifying the `--language` and optionally the `--query` arguments.

```bash
some_command | topiary format --language LANGUAGE
```

--------------------------------

### JSON Formatting Queries

Source: https://topiary.tweag.io/book/print.html

Example queries applying indentation and line break captures to JSON structures.

```query
__
(object . "{" @append_hardline @append_indent_start)
(object "}" @prepend_hardline @prepend_indent_end .)
(object (pair) @prepend_hardline)
(pair . _ ":" @append_hardline)

(array "," @LINEBREAK)
```

--------------------------------

### Install Topiary on NixOS

Source: https://topiary.tweag.io/book/getting-started/installation/package-managers.html

Add Topiary to your system packages on NixOS by including it in your configuration.nix file. This ensures Topiary is available globally.

```nix
environment.systemPackages = with pkgs;
  [ topiary ];
```

--------------------------------

### Correct Query Example for Commands

Source: https://topiary.tweag.io/book/getting-started/on-tree-sitter.html

This query correctly handles command arguments, including string arguments, by using a general pattern for pairs of nodes under the 'command' node. It assumes formatting is only needed for commands.

```scm
; Correct query (if we ignore everything besides commands)
; Results in: command arg1 arg2
; Handles string arguments: command "arg1" arg2
(command
  (_) @append_space
  .
  (_)
)
```

--------------------------------

### Define Indentation Start Markers

Source: https://topiary.tweag.io/book/print.html

Use these captures to trigger indentation before or after matched nodes.

```query
__
; Start an indented block after these
[
  "begin"
  "else"
  "then"
  "{"
] @append_indent_start
```

--------------------------------

### Apply @prepend_empty_softline to dots

Source: https://topiary.tweag.io/book/print.html

Starts new lines for each dot in multi-line constructs.

```lisp
__
; Put an empty softline before dots, so that in multi-line constructs we start
; new lines for each dot.
(_
  "." @prepend_empty_softline
)
```

--------------------------------

### Topiary @prepend_hardline Example

Source: https://topiary.tweag.io/book/reference/capture-names/vertical-spacing.html

Demonstrates @prepend_hardline, which adds a line break before each delimiter, regardless of context.

```topiary
(array "," @prepend_hardline)
```

--------------------------------

### View hash mismatch error

Source: https://topiary.tweag.io/book/print.html

Example of the error output when a missing or incorrect nixHash is provided.

```text
evaluation warning: Language `nickel`: no nixHash provided - using dummy value
error: hash mismatch in fixed-output derivation '/nix/store/jgny7ll7plh7rfdnvdpgcb82kd51aiyx-tree-sitter-nickel-43433d8.drv':
         specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
            got:    sha256-9Ei0uy+eGK9oiH7y2KIhB1E88SRzGnZinqECT3kYTVE=
error: 1 dependencies of derivation '/nix/store/0q20rk8l4g0n5fzr0w45agxx0j9qy65v-nickel-grammar-43433d8477b24cd13acaac20a66deda49b7e2547.drv' failed to build
error: 1 dependencies of derivation '/nix/store/s5phxykjyzqay7gc33hc6f8kw4ndba25-languages-prefetched.json.drv' failed to build
error: 1 dependencies of derivation '/nix/store/5w15p3b3xfw5nd6mxz58ln09v10kvf8v-languages-prefetched.ncl.drv' failed to build
error: 1 dependencies of derivation '/nix/store/7zzyha67jw09kc37valp28bp5h6i7dka-topiary-0.6.0.drv' failed to build
```

--------------------------------

### Define Indentation Start

Source: https://topiary.tweag.io/book/reference/capture-names/indentation.html

Use these capture groups to trigger an increase in indentation level for subsequent lines.

```scm
; Start an indented block after these
[
  "begin"
  "else"
  "then"
  "{"
] @append_indent_start
```

--------------------------------

### Use Topiary in Nix Shell (No Flakes)

Source: https://topiary.tweag.io/book/getting-started/installation/package-managers.html

Temporarily add Topiary to your PATH using the standard nix-shell command. This is useful for running Topiary without a permanent installation.

```bash
# Or, without flakes:
nix-shell -p topiary
```

--------------------------------

### Naive Query Example (Incorrect)

Source: https://topiary.tweag.io/book/getting-started/on-tree-sitter.html

This naive query places a space after the command name, leading to arguments coalescing. It does not account for arguments and can break code semantics.

```scm
; Naive query (incorrect; neglects arguments)
; Results in: command arg1arg2
(command_name) @append_space
```

--------------------------------

### Example Log Line with #query_name!

Source: https://topiary.tweag.io/book/print.html

This log line demonstrates how the #query_name! predicate modifies the output to include the query's assigned name, aiding in debugging.

```log
[2024-10-08T15:48:13Z INFO  topiary_core::tree_sitter] Processing match of query "comma spacing": LocalQueryMatch { pattern_index: 17, captures: [ {Node "," (1,3) - (1,4)} ] } at location (286,1)
```

--------------------------------

### Example Log Line without #query_name!

Source: https://topiary.tweag.io/book/print.html

This log line shows the default output when a query matches, indicating the pattern index but not a descriptive name.

```log
[2024-10-08T15:48:13Z INFO  topiary_core::tree_sitter] Processing match: LocalQueryMatch { pattern_index: 17, captures: [ {Node "," (1,3) - (1,4)} ] } at location (286,1)
```

--------------------------------

### Prepending a Delimiter with @prepend_delimiter

Source: https://topiary.tweag.io/book/print.html

This example demonstrates prepending a specified delimiter to a matched node using `@prepend_delimiter` and the `#delimiter!` predicate. This is analogous to prepending a space.

```rust
(_ @prepend_delimiter (#delimiter! "."))
```

--------------------------------

### Debug CST Node Information

Source: https://topiary.tweag.io/book/print.html

Example log output showing Concrete Syntax Tree (CST) node details, including type, location, and name.

```text
[DEBUG atom_collection] CST node:   {Node constructed_type (39, 15) - (39, 42)} - Named: true
[DEBUG atom_collection] CST node:     {Node type_constructor_path (39, 15) - (39, 35)} - Named: true
[DEBUG atom_collection] CST node:       {Node type_constructor (39, 15) - (39, 35)} - Named: true
[DEBUG atom_collection] CST node:     {Node type_constructor_path (39, 36) - (39, 42)} - Named: true
[DEBUG atom_collection] CST node:       {Node type_constructor (39, 36) - (39, 42)} - Named: true

```

--------------------------------

### Bash code example for anchor skipping

Source: https://topiary.tweag.io/book/reference/capture-names/general.html

Illustrates how anchors in Topiary queries can skip over anonymous nodes like ';' and 'then' in Bash code.

```bash
if this; then that; fi
```

--------------------------------

### Identify missing Nix hash via build error

Source: https://topiary.tweag.io/book/cli/configuration.html

Example of the error output when a nixHash is missing or incorrect during compilation.

```text

__
evaluation warning: Language `nickel`: no nixHash provided - using dummy value
error: hash mismatch in fixed-output derivation '/nix/store/jgny7ll7plh7rfdnvdpgcb82kd51aiyx-tree-sitter-nickel-43433d8.drv':
         specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
            got:    sha256-9Ei0uy+eGK9oiH7y2KIhB1E88SRzGnZinqECT3kYTVE=
error: 1 dependencies of derivation '/nix/store/0q20rk8l4g0n5fzr0w45agxx0j9qy65v-nickel-grammar-43433d8477b24cd13acaac20a66deda49b7e2547.drv' failed to build
error: 1 dependencies of derivation '/nix/store/s5phxykjyzqay7gc33hc6f8kw4ndba25-languages-prefetched.json.drv' failed to build
error: 1 dependencies of derivation '/nix/store/5w15p3b3xfw5nd6mxz58ln09v10kvf8v-languages-prefetched.ncl.drv' failed to build
error: 1 dependencies of derivation '/nix/store/7zzyha67jw09kc37valp28bp5h6i7dka-topiary-0.6.0.drv' failed to build

```

--------------------------------

### lib.gitHookBinFor

Source: https://topiary.tweag.io/book/print.html

Exposes the derivation providing `/bin/topiary` in `gitHookFor`. It is meant for clients wanting to get a Git hook but also acquire the same Topiary, for instance to expose it in their environment. See `gitHookFor` for a description of the arguments.

```APIDOC
## `lib.gitHookBinFor`

### Description
This function exposes the derivation providing `/bin/topiary` in `gitHookFor`. It is meant for clients wanting to get a Git hook but also acquire the same Topiary, for instance to expose it in their environment. See `gitHookFor` for a description of the arguments.

### Signature
```
gitHookBinFor : AttrSet -> Derivation
```
```

--------------------------------

### Topiary @prepend_empty_softline Example

Source: https://topiary.tweag.io/book/reference/capture-names/vertical-spacing.html

Illustrates @prepend_empty_softline. In single-line context, it consumes whitespace; in multi-line, it adds a line break before the delimiter.

```topiary
(array "," @prepend_empty_softline)
```

--------------------------------

### Attempt to append space (will not work)

Source: https://topiary.tweag.io/book/reference/capture-names/general.html

This example shows an incorrect way to append a space, illustrating that capture names must precede the node they modify.

```scm
@append_space (infix_operator)
```

--------------------------------

### Set Up Input and Expected Output for C Tests

Source: https://topiary.tweag.io/book/guides/adding-a-new-language.html

Creates sample input and expected output files for C code to be used in Topiary's I/O tester.

```bash
echo 'void main ();' > topiary-cli/tests/samples/input/clang.c
echo 'voidmain();' > topiary-cli/tests/samples/expected/clang.c
```

--------------------------------

### Enter Topiary Development Shell

Source: https://topiary.tweag.io/book/getting-started/installation/building-from-source.html

Initializes the environment with all required dependencies and variables.

```bash
nix develop
```

--------------------------------

### Naive and Improved Tree-sitter Queries for Bash Commands

Source: https://topiary.tweag.io/book/print.html

These examples show different Tree-sitter queries for formatting Bash commands. The naive query is incorrect as it coalesces arguments. Improved queries attempt to handle arguments but can be too specific or fail in certain cases. The correct query uses a general pattern to ensure spacing between command components.

```treesitter_query
; Naive query (incorrect; neglects arguments)
; Results in: command arg1arg2
(command_name) @append_space
```

```treesitter_query
; Improved queries (incorrect; too specific)
; Results in: command arg1 arg2
; Failure mode if the first argument is a string: command "arg1"arg2
(command
  (command_name) @append_space
)

(command
  (word) @append_space
)
```

```treesitter_query
; Correct query (if we ignore everything besides commands)
; Results in: command arg1 arg2
; Handles string arguments: command "arg1" arg2
(command
  (_) @append_space
  .
  (_)
)
```

--------------------------------

### Run Topiary from Source

Source: https://topiary.tweag.io/book/cli/usage/index.html

Execute Topiary using Cargo or Nix build tools.

```bash
echo '{"foo":"bar"}' | cargo run -- format --language json
echo '{"foo":"bar"}' | nix run . -- format --language json
```

--------------------------------

### Improved but Specific Query Examples (Incorrect)

Source: https://topiary.tweag.io/book/getting-started/on-tree-sitter.html

These improved queries attempt to account for arguments but are too specific. They fail when the first argument is a string, demonstrating a tight coupling to specific use-cases.

```scm
; Improved queries (incorrect; too specific)
; Results in: command arg1 arg2
; Failure mode if the first argument is a string: command "arg1"arg2
(command
  (command_name) @append_space
)

(command
  (word) @append_space
)
```

--------------------------------

### Topiary CLI Help Output

Source: https://topiary.tweag.io/book/print.html

Lists all available subcommands and options for the Topiary CLI. Use `topiary --help` for a general overview and subcommand-specific help for detailed usage.

```bash
topiary --help
```

--------------------------------

### Run Topiary Format via Nix

Source: https://topiary.tweag.io/book/print.html

Shows how to execute the Topiary `format` subcommand using Nix, useful for reproducible builds and environments.

```bash
echo '{"foo":"bar"}' | nix run . -- format --language json
```

--------------------------------

### Build Topiary with Nix

Source: https://topiary.tweag.io/book/getting-started/installation/building-from-source.html

Standard build command for Nix users with flakes enabled.

```bash
nix build
```

--------------------------------

### Wrap Topiary with Configuration

Source: https://topiary.tweag.io/book/reference/nix.html

Produces an executable running topiary with a specific configuration. The resulting binary does not accept additional -C arguments.

```nix
wrapWithConfig : Derivation -> TopiaryConfig -> Derivation
```

```nix
wrapWithConfigFile : Derivation -> File -> Derivation
```

--------------------------------

### Display configuration sources

Source: https://topiary.tweag.io/book/cli/configuration.html

Command to list all detected configuration sources and their status.

```bash
$ topiary config show-sources
```

--------------------------------

### Configuration command usage

Source: https://topiary.tweag.io/book/print.html

Displays the help and usage options for the config subcommand.

```text
Usage: topiary config [OPTIONS] [COMMAND]
```

--------------------------------

### CST Node Debug Output

Source: https://topiary.tweag.io/book/guides/suggested-workflow.html

Example of the CST node structure output during debugging.

```text
[DEBUG atom_collection] CST node:   {Node constructed_type (39, 15) - (39, 42)} - Named: true
[DEBUG atom_collection] CST node:     {Node type_constructor_path (39, 15) - (39, 35)} - Named: true
[DEBUG atom_collection] CST node:       {Node type_constructor (39, 15) - (39, 35)} - Named: true
[DEBUG atom_collection] CST node:     {Node type_constructor_path (39, 36) - (39, 42)} - Named: true
[DEBUG atom_collection] CST node:       {Node type_constructor (39, 36) - (39, 42)} - Named: true
```

--------------------------------

### Build Topiary CLI with Nixpkgs

Source: https://topiary.tweag.io/book/getting-started/installation/building-from-source.html

Builds the CLI package using grammars pinned by the flake.

```bash
nix build .#topiary-cli-nix
```

--------------------------------

### Display Topiary Configuration Sources

Source: https://topiary.tweag.io/book/print.html

This command displays the configuration sources Topiary is using, including any detected 'languages.ncl' files or 'queries' directories.

```bash
$ topiary config show-sources
```

```text
╭───────────┬──────────────────────────────────────────────────────┬───────────────┬─────────╮
│ source    │ path                                                 │ languages.ncl │ queries │
├───────────┼──────────────────────────────────────────────────────┼───────────────┼─────────┤
│ workspace │ /Users/USER_NAME/Documents/rust/topiary/.topiary     │ ✗             │ ✗       │
├───────────┼──────────────────────────────────────────────────────┼───────────────┼─────────┤
│ unix-home │ /Users/USER_NAME/.config/topiary                     │ ✓             │ ✓       │
├───────────┼──────────────────────────────────────────────────────┼───────────────┼─────────┤
│ OS        │ /Users/USER_NAME/Library/Application Support/topiary │ ✗             │ ✗       │
├───────────┼──────────────────────────────────────────────────────┼───────────────┼─────────┤
│ built-in  │ <built-in>                                           │ ✓             │ ✓       │
╰───────────┴──────────────────────────────────────────────────────┴───────────────┴─────────╯
```

--------------------------------

### Run Topiary Format via Cargo

Source: https://topiary.tweag.io/book/print.html

Demonstrates how to run the Topiary `format` subcommand using Cargo, suitable for development from source.

```bash
echo '{"foo":"bar"}' | cargo run -- format --language json
```

--------------------------------

### Topiary @append_hardline Example

Source: https://topiary.tweag.io/book/reference/capture-names/vertical-spacing.html

Demonstrates @append_hardline, which adds a line break after each delimiter, regardless of context.

```topiary
(array "," @append_hardline)
```

--------------------------------

### OCaml Code Snippet

Source: https://topiary.tweag.io/book/reference/capture-names/scopes.html

A simple OCaml tuple expression used as an example for CST analysis.

```OCaml
(1,2,
3)
```

--------------------------------

### Generate performance flamegraph

Source: https://topiary.tweag.io/book/guides/contributing.html

Generates a flamegraph SVG to analyze performance, requiring the flamegraph tool to be installed.

```bash
CARGO_PROFILE_RELEASE_DEBUG=true \
cargo flamegraph -p topiary-cli -- \
  format --language ocaml \
  < topiary-cli/tests/samples/input/ocaml.ml \
  > /dev/null
```

--------------------------------

### Correct Standard Input Redirection

Source: https://topiary.tweag.io/book/print.html

Demonstrates the correct way to pipe input to Topiary format using standard input redirection.

```bash
# Do this instead
some_command | topiary format --language LANGUAGE
```

--------------------------------

### Define Custom Scope

Source: https://topiary.tweag.io/book/reference/capture-names/scopes.html

Example of defining a custom scope using capture names and the scope_id predicate.

```Tree-sitter
(parenthesized_expression
  "(" @append_begin_scope
  ")" @prepend_end_scope

  (#scope_id! "tuple")
)
```

--------------------------------

### Configuration Management

Source: https://topiary.tweag.io/book/reference/nix.html

Functions for prefetching language sources and managing default Topiary configurations.

```APIDOC
## lib.prefetchLanguages

### Description
Returns a Topiary configuration with language sources replaced by prefetched and precompiled versions. Requires `nixHash` for all sources.

## lib.prefetchLanguagesFile

### Description
Expects a path to a Nickel file and produces a path to a JSON file with prefetched language sources.

## lib.defaultConfig

### Description
Returns the default Topiary configuration as a Nix value.

## lib.defaultConfigPrefetched

### Description
Returns the default configuration with all language grammars pointing to prefetched Nix store paths.
```

--------------------------------

### Override specific configuration field

Source: https://topiary.tweag.io/book/cli/configuration.html

Example of overriding only the indentation setting for Bash using the force operator.

```nickel
{
  languages = {
    bash = {
      indent | force = "    ",
    },
  },
}
```

--------------------------------

### Topiary Format Subcommand Help

Source: https://topiary.tweag.io/book/print.html

Displays the help information for the `topiary format` subcommand, detailing its options and arguments.

```bash
topiary format --help
```

--------------------------------

### Display Topiary CLI Help

Source: https://topiary.tweag.io/book/cli/usage/index.html

View available subcommands and options for the Topiary CLI.

```text
CLI app for Topiary, the universal code formatter.

Usage: topiary [OPTIONS] <COMMAND>

Commands:
  format         Format inputs
  visualise      Visualise the input's Tree-sitter parse tree
  config         Print the current configuration
  prefetch       Prefetch languages in the configuration
  coverage       Checks how much of the tree-sitter query is used
  check-grammar  Check if an input parses to the respective Tree-sitter grammar
  completion     Generate shell completion script
  help           Print this message or the help of the given subcommand(s)

Options:
  -C, --configuration <CONFIGURATION>  Configuration file [env: TOPIARY_CONFIG_FILE]
  -M, --merge-configuration            Enable merging for configuration files
  -v, --verbose...                     Logging verbosity (increased per occurrence)
  -h, --help                           Print help
  -V, --version                        Print version
```

--------------------------------

### Override language configuration

Source: https://topiary.tweag.io/book/cli/configuration.html

Example of overriding the entire Bash configuration using the force operator in a Nickel file.

```nickel
{
  languages = {
    # Alternatively, use `priority 1`, rather than `force`
    bash | force = {
      extensions = [ "sh" ],
      indent = "    ",
    },
  },
}
```

--------------------------------

### Configure a Git-based grammar source

Source: https://topiary.tweag.io/book/cli/configuration.html

Specify a remote Git repository for Topiary to fetch and build the grammar automatically.

```nickel

__
nickel = {
  extensions = ["ncl"],
  grammar.source.git = {
    git = "https://github.com/nickel-lang/tree-sitter-nickel",
    rev = "43433d8477b24cd13acaac20a66deda49b7e2547",
  },
},

```

--------------------------------

### Append Space Example

Source: https://topiary.tweag.io/book/print.html

Appends a space to the matched node using the @append_space capture. This is equivalent to @append_delimiter with a space.

```Topiary Query
(
  (infix_operator)
  "if"
  ":"
) @append_space
```

--------------------------------

### Topiary @prepend_spaced_softline Example

Source: https://topiary.tweag.io/book/reference/capture-names/vertical-spacing.html

Shows @prepend_spaced_softline. Adds a space before the delimiter in single-line context and a line break in multi-line context.

```topiary
(array "," @prepend_spaced_softline)
```

--------------------------------

### Test Initial Formatting of C Code

Source: https://topiary.tweag.io/book/guides/adding-a-new-language.html

Tests Topiary's ability to format C code. Without formatting queries, this results in mangled output and requires the --skip-idempotence flag.

```bash
$ echo 'void main();' | cargo run -- format -s --language clang
voidmain();
```

--------------------------------

### Prefetch languages command usage

Source: https://topiary.tweag.io/book/print.html

Displays the help and usage options for the prefetch subcommand.

```text
Usage: topiary prefetch [OPTIONS] [LANGUAGE]
```

--------------------------------

### Topiary @append_spaced_softline Example

Source: https://topiary.tweag.io/book/reference/capture-names/vertical-spacing.html

Demonstrates @append_spaced_softline. Adds a space after the delimiter in single-line context and a line break in multi-line context.

```topiary
(array "," @append_spaced_softline)
```

--------------------------------

### Topiary @append_empty_softline Example

Source: https://topiary.tweag.io/book/reference/capture-names/vertical-spacing.html

Shows @append_empty_softline. In single-line context, it consumes whitespace; in multi-line, it adds a line break after the delimiter.

```topiary
(array "," @append_empty_softline)
```

--------------------------------

### Prefetch Language Configurations

Source: https://topiary.tweag.io/book/reference/nix.html

Replaces language sources with prefetched and precompiled versions. Requires a nixHash for all sources.

```nix
prefetchLanguages : TopiaryConfig -> TopiaryConfig
```

```nix
prefetchLanguagesFile : File -> File
```

--------------------------------

### Create Empty Query File for Clang

Source: https://topiary.tweag.io/book/guides/adding-a-new-language.html

Initializes an empty query file for the C language, which will later contain formatting rules.

```bash
touch topiary-queries/queries/clang.scm
```

--------------------------------

### Anchor Behavior with Anonymous Nodes

Source: https://topiary.tweag.io/book/print.html

Explains how anchors skip over anonymous nodes that interpose terminals, using a Bash example.

```Bash
if this; then that; fi
```

```Topiary Query
(if_statement
  (_)  ; will match "this"
  .
  (_)  ; will match "that"
)
```

--------------------------------

### Prefetch Languages with Topiary CLI

Source: https://topiary.tweag.io/book/cli/usage/prefetch.html

Use this command to prefetch Tree-sitter grammars. If no language is specified, all configured languages will be prefetched. Options include forcing re-fetching and specifying a configuration file.

```bash
topiary prefetch [OPTIONS] [LANGUAGE]
```

--------------------------------

### CLI Command: topiary prefetch

Source: https://topiary.tweag.io/book/cli/usage/prefetch.html

The prefetch command downloads and builds Tree-sitter grammars. It can be used to pre-fetch all languages or a specific language.

```APIDOC
## CLI Command: topiary prefetch

### Description
Downloads, builds, and loads Tree-sitter grammars. This is useful for ensuring offline availability and improving startup time.

### Usage
`topiary prefetch [OPTIONS] [LANGUAGE]`

### Arguments
- **LANGUAGE** (string) - Optional - The specific language to fetch. If not provided, all languages defined in the configuration are prefetched.

### Options
- **-f, --force** (flag) - Optional - Re-fetch existing grammars even if they already exist.
- **-C, --configuration** (path) - Optional - Path to the configuration file. Can also be set via the TOPIARY_CONFIG_FILE environment variable.
- **-M, --merge-configuration** (flag) - Optional - Enable merging for configuration files.
- **-v, --verbose** (count) - Optional - Increase logging verbosity (can be used multiple times).
- **-h, --help** (flag) - Optional - Print help information.
```

--------------------------------

### Topiary visualise command usage

Source: https://topiary.tweag.io/book/cli/usage/visualise.html

Displays the command-line interface help and available options for the visualise subcommand.

```text
Usage: topiary visualise [OPTIONS] <--language <LANGUAGE>|FILE>
```

--------------------------------

### Appending a Delimiter with @append_delimiter

Source: https://topiary.tweag.io/book/print.html

This example shows how to append a specified delimiter to a matched node using `@append_delimiter` and the `#delimiter!` predicate. This is a generalization of appending a space.

```rust
(_ @append_delimiter (#delimiter! ","))
```

--------------------------------

### Prepend Antispace Example

Source: https://topiary.tweag.io/book/print.html

Removes all horizontal whitespace from the beginning of a node using @prepend_antispace. Useful for juxtaposing tokens without extra spaces.

```Topiary Query
[
  ","
  ";"
  ":"
  "."
] @prepend_antispace
```

--------------------------------

### Build Topiary with Cargo

Source: https://topiary.tweag.io/book/getting-started/installation/building-from-source.html

Standard Rust build command for environments with dependencies pre-configured.

```bash
cargo build
```

--------------------------------

### Shell completion command usage

Source: https://topiary.tweag.io/book/print.html

Displays the help and usage options for the completion subcommand.

```text
Usage: topiary completion [OPTIONS] [SHELL]
```

--------------------------------

### lib.gitHookBin

Source: https://topiary.tweag.io/book/print.html

Provides a Git hook with Topiary binary. Same as `gitHookBinFor {}`.

```APIDOC
## `lib.gitHookBin`

### Signature
```
gitHookBin : Derivation
```

### Description
Same as `gitHookBinFor {}`.
```

--------------------------------

### Run Topiary Input/Output Tester

Source: https://topiary.tweag.io/book/print.html

Executes the input_output_tester for a specific language feature without default features.

```bash
cargo test \
  --no-default-features \
  -F mylanguage \
  -p topiary-cli \
  input_output_tester \
  -- --nocapture

```

--------------------------------

### Run Topiary CLI with Docker

Source: https://topiary.tweag.io/book/getting-started/installation/package-managers.html

Execute the Topiary CLI within a Docker container to format JSON input. Use Docker bind mounts to format files on disk.

```bash
docker run --rm -i ghcr.io/topiary/topiary format -l json <<< '{"foo":123}'
```

--------------------------------

### Topiary @prepend_input_softline Example

Source: https://topiary.tweag.io/book/reference/capture-names/vertical-spacing.html

Demonstrates @prepend_input_softline. Adds a space before the delimiter in single-line context. In multi-line context, adds a line break only if the original input had a line break before the delimiter.

```topiary
(array "," @prepend_input_softline)
```

--------------------------------

### Topiary @append_input_softline Example

Source: https://topiary.tweag.io/book/reference/capture-names/vertical-spacing.html

Illustrates @append_input_softline. Adds a space after the delimiter in single-line context. In multi-line context, adds a line break only if the original input had a line break after the delimiter.

```topiary
(array "," @append_input_softline)
```

--------------------------------

### Git Hook with Topiary Binary Configuration

Source: https://topiary.tweag.io/book/print.html

Provides a default derivation for a Git hook that includes the Topiary binary. It is equivalent to calling gitHookBinFor with empty arguments.

```nix
__
gitHookBin : Derivation

```

--------------------------------

### Configure Nix hash for grammar

Source: https://topiary.tweag.io/book/cli/configuration.html

Include a nixHash for Git sources to enable pre-fetching in Nix derivations.

```nickel

__
nickel = {
  extensions = ["ncl"],
  grammar.source.git = {
    git = "https://github.com/nickel-lang/tree-sitter-nickel",
    rev = "43433d8477b24cd13acaac20a66deda49b7e2547",
    nixHash = "sha256-9Ei0uy+eGK9oiH7y2KIhB1E88SRzGnZinqECT3kYTVE=",
  },
},

```

--------------------------------

### Configure a local grammar source

Source: https://topiary.tweag.io/book/cli/configuration.html

Point to a pre-compiled grammar file on the local file system.

```nickel

__
nickel = {
  extensions = ["ncl"],
  grammar.source.path = "/path/to/compiled/grammar/file.so",
},

```

--------------------------------

### Query Order Example: Append Semicolon and Surround with Quotes

Source: https://topiary.tweag.io/book/print.html

Demonstrates how the order of queries can affect the final formatted output. Query A appends a semicolon, and Query B surrounds the word with quotes.

```Topiary Query
; Query A: Append semicolon
(
  (word) @append_delimiter
  .
  ";"? @do_nothing

  (#delimiter! ";")
)

; Query B: Surround with quotes
(
  "\""? @do_nothing
  .
  (word) @prepend_delimiter @append_delimiter
  .
  "\""? @do_nothing

  (#delimiter! "\"")
)
```

--------------------------------

### Access Default Configurations

Source: https://topiary.tweag.io/book/reference/nix.html

Provides access to the default Topiary configuration as a Nix value or file, with optional prefetching.

```nix
defaultConfig : TopiaryConfig
```

```nix
defaultConfigPrefetched
```

```nix
defaultConfigFile : File
```

```nix
defaultConfigFilePrefetched : File
```

--------------------------------

### Configure Feature Flags in Cargo.toml Files

Source: https://topiary.tweag.io/book/guides/adding-a-new-language.html

Enables the 'clang' feature flag across different Cargo.toml files to activate C language support in Topiary.

```toml
experimental = [
  "clang",
]

clang = ["topiary-config/clang", "topiary-queries/clang"]
```

```toml
clang = []

all = [
  "clang",
]
```

```toml
clang = []
```

--------------------------------

### Nix Library Functions

Source: https://topiary.tweag.io/book/print.html

API definitions for managing Topiary configurations and file transformations within Nix.

```nix
fromNickelFile : File -> Any
```

```nix
toJSONFile : Any -> File
```

```nix
prefetchLanguages : TopiaryConfig -> TopiaryConfig
```

```nix
prefetchLanguagesFile : File -> File
```

```nix
defaultConfig : TopiaryConfig
```

```nix
defaultConfigPrefetched
```

```nix
defaultConfigFile : File
```

```nix
defaultConfigFilePrefetched : File
```

```nix
wrapWithConfig : Derivation -> TopiaryConfig -> Derivation
```

```nix
wrapWithConfigFile : Derivation -> File -> Derivation
```

```nix
gitHookFor : AttrSet -> AttrSet
```

--------------------------------

### Incorrect Process Substitution Usage

Source: https://topiary.tweag.io/book/print.html

Illustrates an incorrect method of providing input to Topiary format using process substitution, which is not supported.

```bash
# This won't work
topiary format <(some_command)
```

--------------------------------

### Derivation for Git Hook with Topiary Binary

Source: https://topiary.tweag.io/book/print.html

Exposes the derivation providing \"/bin/topiary\" in gitHookFor. Use when clients need a Git hook and the Topiary binary.

```nix
__
gitHookBinFor : AttrSet -> Derivation

```

--------------------------------

### Specify Git grammar source

Source: https://topiary.tweag.io/book/print.html

Configure Topiary to fetch a grammar from a Git repository.

```nickel
nickel = {
  extensions = ["ncl"],
  grammar.source.git = {
    git = "https://github.com/nickel-lang/tree-sitter-nickel",
    rev = "43433d8477b24cd13acaac20a66deda49b7e2547",
  },
},
```

--------------------------------

### Integrate Topiary with git-hooks.nix

Source: https://topiary.tweag.io/book/getting-started/installation/using-nix.html

Add Topiary as a formatter in your project's pre-commit hooks using the provided lib.gitHook helper.

```nix
pre-commit-check = git-hooks-nix.run {
  hooks = {
    nixfmt.enable = true; ## keep your normal hooks
    ...
    ## Add the following:
    topiary-latest = topiary.lib.${system}.gitHook // { enable = true; };
  };
};
```

--------------------------------

### Integrate C Query Loading in CLI

Source: https://topiary.tweag.io/book/guides/adding-a-new-language.html

Adds a configuration to the `to_query` function in `topiary-cli/src/io.rs` to load the C query file when the 'clang' feature is enabled.

```rust
#![allow(unused)]
fn main() {
fn to_query<T>(name: T) -> CLIResult<QuerySource>

[...] 

        #[cfg(feature = "clang")]
        "clang" => Ok(topiary_queries::clang().into()),
}
}
```
Tokens:
Raw