taplo.toml

Overview

The taplo.toml file is a configuration file used to define formatting and linting rules specifically for TOML files within a project. It sets global include patterns for which files to process, and provides detailed formatting rules and key reorder policies, especially tailored for Rust project manifest files such as Cargo.toml. The file primarily focuses on controlling how arrays and keys are ordered, how inline tables are expanded, and which files or sections these rules apply to.

Configuration Details

Global Include Pattern

include = ["**/*.toml"]

• Specifies a glob pattern to include all TOML files recursively.

• This ensures the formatting and rules apply to every .toml file in the project directory hierarchy.

Formatting Section

[formatting]
reorder_arrays = false
indent_string = "    "

• reorder_arrays (boolean): Controls whether arrays should be reordered during formatting. Set to false to preserve the original order.

• indent_string (string): Specifies the indentation string used for nested elements, here defined as four spaces (" ").

• The comment references a future fix in Taplo, indicating that the indentation string setting is currently a workaround.

Rule Definitions

The file contains multiple [[rule]] tables, each defining specific formatting rules that apply conditionally based on the file path or keys.

Rule 1: For All Cargo.toml Files

[[rule]]
include = ["**/Cargo.toml"]
formatting.inline_table_expand = false

• Applies to all Cargo.toml files anywhere in the project.

• Controls the formatting of inline tables, disabling their expansion (inline_table_expand = false), meaning inline tables remain compact rather than expanded to multiple lines.

Rule 2: For Dependencies Sections in Cargo.toml

[[rule]]
include = ["**/Cargo.toml"]
keys = ["dependencies", "*-dependencies", "workspace.dependencies"]
[rule.formatting]
reorder_keys = true

• Targets dependency sections within Cargo.toml files, including any keys matching "dependencies", wildcard *-dependencies (e.g., dev-dependencies, build-dependencies), and "workspace.dependencies".

• Enables reordering of keys (reorder_keys = true) within these sections to maintain a consistent, sorted order for dependencies.

Rule 3: For Root Cargo.toml Workspace Members

[[rule]]
include = ["Cargo.toml"]
keys = ["workspace", "members"]
formatting.reorder_arrays = true

• Applies specifically to the root Cargo.toml file (not in subdirectories).

• Targets the workspace and members keys, which typically define the workspace configuration and member crates.

• Enables reordering of arrays (reorder_arrays = true) for these keys, ensuring that workspace members are sorted.

Implementation Details and Algorithms

• The file uses conditional rules based on the file path (include) and TOML key scopes (keys) to selectively apply formatting rules.

• The use of glob patterns allows flexible matching of files across directory structures.

• The reordering features (reorder_keys, reorder_arrays) imply that the formatter parses TOML sections and applies sorting algorithms to keys or array elements to enforce consistency.

• The indentation string setting influences the whitespace used during formatting, critical for human-readable TOML files.

• The inline table expansion setting manages how nested tables are represented, affecting readability and compactness.

Interaction with Other Parts of the System

• This file configures Taplo, a TOML linter and formatter tool, dictating how it formats TOML files in the project.

• It specifically tunes the formatting of Cargo.toml files, which are essential for Rust project dependency management and workspace configuration.

• By defining rules for dependency sections and workspace members, it ensures that other tools or developers working with the Rust project see a consistent and orderly manifest.

• The global inclusion of all .toml files implies that this configuration also standardizes formatting for any other TOML files in the project, not just Rust manifests.

Usage Examples

• When the formatter runs, it will process all .toml files and:

  • Leave array orders as-is unless specifically overridden (e.g., workspace.members arrays).

  • Keep inline tables compact in Cargo.toml.

  • Sort keys alphabetically within dependency tables to improve readability.

  • Indent nested tables with four spaces.

Example: Dependency Section Before and After Formatting

Before:

[dependencies]
serde = "1.0"
rand = "0.8"

After (with reorder_keys = true):

[dependencies]
rand = "0.8"
serde = "1.0"

Example: Workspace Members Array Before and After Formatting

Before:

[workspace]
members = [
    "crate-b",
    "crate-a"
]

After (with reorder_arrays = true):

[workspace]
members = [
    "crate-a",
    "crate-b"
]

Visual Diagram

flowchart TD
A[Global Include: "**/*.toml"] --> B[Formatting Settings]
B --> B1[reorder_arrays: false]
B --> B2[indent_string: "    "]
A --> C[Rule 1: Cargo.toml]
C --> C1[inline_table_expand: false]
A --> D[Rule 2: Cargo.toml Dependencies]
D --> D1[keys: dependencies, *-dependencies, workspace.dependencies]
D --> D2[reorder_keys: true]
A --> E[Rule 3: Root Cargo.toml Workspace]
E --> E1[keys: workspace, members]
E --> E2[reorder_arrays: true]

This diagram shows the hierarchical structure of the global inclusion and the three main rule sets with their respective formatting configurations.