Struct CommandRegistry 

pub struct CommandRegistry { /* private fields */ }

Registry of known CMake command specifications used to guide formatting.

The registry describes the argument structure of each command — positional slots, keyword sections, flags, and per-form layout hints — so the formatter can group and wrap arguments correctly.

Two-tier model

The built-in registry covers the full CMake standard library. User override files (TOML or YAML) can extend or modify any entry without replacing the whole registry.

Getting a registry

Situation	Recommended call
No customisation needed	CommandRegistry::builtins — lazily initialised singleton, cheapest
Fresh owned copy	CommandRegistry::load — allocates every call
Merge with user override file	CommandRegistry::from_builtins_and_overrides
Owned copy without overrides	CommandRegistry::from_builtins_and_overrides with None::<&Path> (equivalent to load())

Implementations

impl CommandRegistry

pub fn load() -> Result<Self>

Load the embedded built-in registry from builtins.yaml.

Returns a fresh owned CommandRegistry on every call. Prefer CommandRegistry::builtins when you only need a read-only reference — it initialises once and amortises the parse cost across all callers.

pub fn builtins() -> &'static Self

Return the lazily initialised built-in registry singleton.

The registry is parsed exactly once on first call; subsequent calls return a &'static reference at zero cost. Use CommandRegistry::load if you need an owned, mutable copy.

pub fn from_builtins_and_overrides( path: Option<impl AsRef<Path>>, ) -> Result<Self>

Available on non-WebAssembly and crate feature cli only.

Load the embedded built-ins and optionally merge a user override file.

pub fn merge_toml_overrides(&mut self, toml_source: &str) -> Result<()>

Merge TOML-formatted command spec overrides from a string.

Examples

use cmakefmt::CommandRegistry;

let mut registry = CommandRegistry::load().unwrap();
registry.merge_toml_overrides(r#"
    [commands.my_add_test]
    pargs = 0
    flags = ["VERBOSE"]

    [commands.my_add_test.kwargs.NAME]
    nargs = 1

    [commands.my_add_test.kwargs.SOURCES]
    nargs = "+"
"#).unwrap();

Errors

Returns Error::Formatter with an unstructured parse error string. For structured line/column diagnostics, use CommandRegistry::merge_override_str or CommandRegistry::merge_override_file which return Error::Spec.

pub fn merge_yaml_overrides(&mut self, yaml_source: &str) -> Result<()>

Merge YAML-formatted command spec overrides from a string.

Examples

use cmakefmt::CommandRegistry;

let mut registry = CommandRegistry::load().unwrap();
registry.merge_yaml_overrides("
commands:
  my_add_test:
    pargs: 0
    flags: [VERBOSE]
    kwargs:
      NAME:
        nargs: 1
      SOURCES:
        nargs: \"+\"
").unwrap();

Errors

Returns Error::Formatter with an unstructured parse error string. For structured line/column diagnostics, use CommandRegistry::merge_override_file which returns Error::Spec.

pub fn merge_override_file(&mut self, path: &Path) -> Result<()>

Available on crate feature cli only.

Merge a supported user override file from disk into the registry.

Errors

Deserialisation failures are reported as Error::Spec with structured crate::error::FileParseError metadata including 1-based line and column numbers — suitable for surfacing to editors and IDE integrations. I/O failures are reported as Error::Io.

pub fn merge_override_str( &mut self, source: &str, path: impl Into<PathBuf>, ) -> Result<()>

Available on crate feature cli only.

Merge TOML override contents into the registry.

Errors

Like merge_override_file, parse failures are reported as Error::Spec with structured line/column metadata — unlike merge_toml_overrides, which returns an unstructured Error::Formatter.

pub fn get(&self, command_name: &str) -> &CommandSpec

Get the command spec for command_name, falling back to a permissive default when the command is unknown.

The fallback is a CommandSpec::Single with pargs = ZeroOrMore, no kwargs, and no flags — i.e. “format as generically as possible, treat every token as a positional argument”. This lets user-defined commands format sensibly without requiring every project to author a spec override.

pub fn contains(&self, command_name: &str) -> bool

Return true when the command has a known spec (built-in or user-defined).

pub fn contains_builtin(&self, command_name: &str) -> bool

Return true when the command is present in the built-in registry.

pub fn audited_cmake_version(&self) -> &str

Report the upstream CMake version the built-in spec was last audited against. The return value is a SemVer-style string (e.g. "4.3.1") sourced from the [metadata] block in src/spec/builtins.yaml. Useful for tooling that wants to surface “cmakefmt knows about CMake X.Y” to end users.

pub fn builtin_command_names(&self) -> impl Iterator<Item = &str>

Iterate over the names of every built-in command in the registry. Yields the lowercase canonical form; user-merged override commands are excluded. Intended for tooling that wants to introspect the spec surface (e.g. cmakefmt dump spec-coverage).

Trait Implementations

impl Clone for CommandRegistry

fn clone(&self) -> CommandRegistry

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CommandRegistry

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.