cmakefmt/
lib.rs

1// SPDX-FileCopyrightText: Copyright 2026 Puneet Matharu
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5#![cfg_attr(docsrs, feature(doc_cfg))]
6
7//! `cmakefmt` is a fast, configurable CMake formatter.
8//!
9//! # Quick start
10//!
11//! Format a CMake source string with the default configuration:
12//!
13//! ```
14//! use cmakefmt::{format_source, Config};
15//!
16//! let cmake = "CMAKE_MINIMUM_REQUIRED(VERSION 3.20)\n";
17//! let formatted = format_source(cmake, &Config::default()).unwrap();
18//! assert_eq!(formatted, "cmake_minimum_required(VERSION 3.20)\n");
19//! ```
20//!
21//! To customise formatting, modify [`Config`] fields before passing it in:
22//!
23//! ```
24//! use cmakefmt::{format_source, Config, CaseStyle};
25//!
26//! let mut config = Config::default();
27//! config.line_width = 100;
28//! config.command_case = CaseStyle::Upper;
29//!
30//! let cmake = "target_link_libraries(mylib PUBLIC dep1)\n";
31//! let formatted = format_source(cmake, &config).unwrap();
32//! assert_eq!(formatted, "TARGET_LINK_LIBRARIES(mylib PUBLIC dep1)\n");
33//! ```
34//!
35//! # Organisation
36//!
37//! | Module | Purpose |
38//! |--------|---------|
39//! | [`config`] | Runtime configuration types and config-file loading |
40//! | [`error`] | Error and result types |
41//! | [`formatter`] | Source-to-source formatting pipeline |
42//! | [`parser`] | CMake parser and AST definitions |
43//! | [`spec`] | Built-in and user-extensible command registry |
44//!
45//! # Entry points (re-exported at the crate root)
46//!
47//! | Item | Purpose |
48//! |------|---------|
49//! | [`format_source`] / [`format_source_with_registry`] | Format a source string |
50//! | [`format_parsed_file`] | Format an already-parsed [`parser::ast::File`] |
51//! | [`format_source_with_debug`] / [`format_source_with_registry_debug`] | Format + collect debug decision log |
52//! | [`Config`], [`CommandConfig`], [`PerCommandConfig`] | Runtime configuration |
53//! | [`CaseStyle`], [`DangleAlign`], [`LineEnding`], [`FractionalTabPolicy`] | Config enums |
54//! | [`CommandRegistry`] | Built-in + user-override command specs |
55//! | [`Error`], [`Result`], [`IoResultExt`] | Crate-level error types and the path-context adapter for `io::Result` |
56//!
57//! # Features
58//!
59//! | Feature | Default | Purpose |
60//! |---------|---------|---------|
61//! | `cli` | ✔ | Enables the `cmakefmt` binary plus CLI-oriented public API (`convert_legacy_config_files`, `default_config_template_for`, `generate_json_schema`, `render_effective_config`, `DumpConfigFormat`). Implies `lsp`. |
62//! | `lsp` | ✔ (via `cli`) | Compiles the `lsp::run` Language Server Protocol entry point. |
63//!
64//! The crate also has a separate target path: when compiled for
65//! `wasm32`, `wasm::format` and friends are exposed via
66//! `wasm-bindgen` for the browser playground.
67
68/// Runtime formatter configuration and config-file loading.
69pub mod config;
70/// Shared error types used across parsing, config loading, and formatting.
71pub mod error;
72/// Source-to-source formatting pipeline.
73pub mod formatter;
74/// CMake parser and AST definitions.
75pub mod parser;
76/// Semantic-level normalisation (strip comments, line endings,
77/// keyword casing) used by `--verify` and the idempotency tests.
78pub mod semantic;
79/// Built-in and user-extensible command specification registry.
80pub mod spec;
81
82// Recursive CMake file-discovery helpers used by the CLI.  Not part of the
83// library embedding API; hidden from generated documentation.
84#[cfg(feature = "cli")]
85#[doc(hidden)]
86pub mod files;
87
88// AST / parse-tree dumping helpers used by the `dump` subcommand.
89#[cfg(feature = "cli")]
90#[doc(hidden)]
91pub mod dump;
92
93// LSP server — only compiled when the `lsp` feature is enabled.
94#[cfg(feature = "lsp")]
95#[cfg_attr(docsrs, doc(cfg(feature = "lsp")))]
96pub mod lsp;
97
98// WASM entry point — only compiled for wasm32 targets.
99#[cfg(target_arch = "wasm32")]
100#[cfg_attr(docsrs, doc(cfg(target_arch = "wasm32")))]
101pub mod wasm;
102
103// ── Configuration ────────────────────────────────────────────────────────────
104
105pub use config::{
106    CaseStyle, CommandConfig, Config, ContinuationAlign, DangleAlign, FractionalTabPolicy,
107    LineEnding, PerCommandConfig,
108};
109
110pub use config::default_config_template;
111
112#[cfg(all(not(target_arch = "wasm32"), feature = "cli"))]
113#[cfg_attr(docsrs, doc(cfg(feature = "cli")))]
114pub use config::{
115    convert_legacy_config_files, default_config_template_for, generate_json_schema,
116    render_effective_config, DumpConfigFormat,
117};
118
119// ── Errors ───────────────────────────────────────────────────────────────────
120
121pub use error::{Error, IoResultExt, Result};
122
123// ── Formatting ───────────────────────────────────────────────────────────────
124
125pub use formatter::{
126    format_parsed_file, format_source, format_source_with_debug, format_source_with_registry,
127    format_source_with_registry_debug,
128};
129
130// ── Registry ─────────────────────────────────────────────────────────────────
131
132pub use spec::registry::CommandRegistry;
cmakefmt/lib.rs

cmakefmt/
lib.rs
