truce_utils/
lib.rs

1#![forbid(unsafe_code)]
2
3//! Dependency-free utilities shared across the truce workspace.
4//!
5//! - [`cast`] - numeric-cast helpers for the audio-plugin → host FFI
6//!   boundary (`usize` ↔ `u32` length casts, host `f64` ↔ DSP `f32`,
7//!   discrete-index ↔ normalized).
8//! - [`midi`] - MIDI value-domain normalize / denormalize between
9//!   wire-native integers and `f32` ranges, plus the spec's MIDI 1.0
10//!   ↔ MIDI 2.0 bit-replication bridges.
11//! - [`shell_sidecar`] - sidecar-file path resolution shared by
12//!   `cargo-truce` (writes the sidecar at install-time) and the
13//!   `truce::plugin!` macro (reads it at runtime to locate the logic
14//!   dylib for hot-reload).
15//! - [`slugify`] - ASCII-safe filesystem / IRI slug used by the LV2
16//!   staging path and runtime bundle-name derivation.
17//! - [`safe_filename`] - case-preserving sanitizer for plugin
18//!   display names used as path components (`{name}.aaxplugin`,
19//!   `{name}.vst3`, etc.). Replaces filesystem-reserved characters
20//!   without lowercasing or collapsing words.
21//!
22//! `truce-core` re-exports the modules above so consumers that pull
23//! `truce-core` don't need a second dependency. Crates that want to
24//! avoid `truce-core`'s `truce-params` chain (notably `cargo-truce`)
25//! depend on `truce-utils` directly.
26
27pub mod cast;
28pub mod midi;
29pub mod shell_sidecar;
30
31/// Slug a plugin's display name into a lowercase, hyphenated,
32/// ASCII-safe identifier suitable for filesystem paths, LV2 bundle
33/// names, and IRI components.
34///
35/// Rules: ASCII alphanumerics pass through lowercased; every other
36/// character (including runs of them) collapses to a single `-`;
37/// leading and trailing dashes are trimmed.
38#[must_use]
39pub fn slugify(name: &str) -> String {
40    let mut out = String::with_capacity(name.len());
41    let mut prev_dash = false;
42    for c in name.chars() {
43        if c.is_ascii_alphanumeric() {
44            out.push(c.to_ascii_lowercase());
45            prev_dash = false;
46        } else if !prev_dash {
47            out.push('-');
48            prev_dash = true;
49        }
50    }
51    out.trim_matches('-').to_string()
52}
53
54/// Sanitize a plugin's display name into a filesystem-safe form,
55/// preserving case and spaces. Use this whenever the name is going
56/// to land in a path component (`{name}.aaxplugin`, `{name}.vst3`,
57/// the executable inside an AAX `Contents/MacOS/`, etc.). The
58/// in-Info.plist / in-host-browser display name should keep using
59/// the raw `name` so users still see "Truce Dry/Wet" in their DAW.
60///
61/// Replacements:
62/// - POSIX path separator `/`, Windows path separator `\`, NTFS /
63///   HFS path-reserved chars `:<>"|?*`, NUL and ASCII control chars
64///   → `-`.
65/// - Leading and trailing whitespace + ASCII dots stripped (Windows
66///   forbids trailing dots / spaces; trimming both keeps behaviour
67///   identical across platforms).
68/// - Runs of `-` collapsed to a single `-` so `Dry//Wet` doesn't
69///   produce `Dry--Wet`.
70#[must_use]
71pub fn safe_filename(name: &str) -> String {
72    let mut out = String::with_capacity(name.len());
73    let mut prev_dash = false;
74    for c in name.chars() {
75        let reserved = matches!(c, '/' | '\\' | ':' | '<' | '>' | '"' | '|' | '?' | '*')
76            || c == '\0'
77            || c.is_control();
78        if reserved {
79            if !prev_dash {
80                out.push('-');
81                prev_dash = true;
82            }
83        } else {
84            out.push(c);
85            prev_dash = false;
86        }
87    }
88    out.trim_matches(|c: char| c.is_whitespace() || c == '.' || c == '-')
89        .to_string()
90}
91
92#[cfg(test)]
93mod slugify_tests {
94    use super::slugify;
95
96    #[test]
97    fn slugify_basic() {
98        assert_eq!(slugify("My Plugin"), "my-plugin");
99        assert_eq!(slugify("Hello!! World"), "hello-world");
100        assert_eq!(slugify("--leading and trailing--"), "leading-and-trailing");
101        assert_eq!(slugify("ABC123"), "abc123");
102        assert_eq!(slugify(""), "");
103    }
104}
105
106#[cfg(test)]
107mod safe_filename_tests {
108    use super::safe_filename;
109
110    #[test]
111    fn replaces_path_separators() {
112        assert_eq!(safe_filename("Truce Dry/Wet"), "Truce Dry-Wet");
113        assert_eq!(safe_filename(r"Foo\Bar"), "Foo-Bar");
114    }
115
116    #[test]
117    fn replaces_windows_reserved() {
118        assert_eq!(safe_filename(r#"a:b<c>d"e|f?g*h"#), "a-b-c-d-e-f-g-h");
119    }
120
121    #[test]
122    fn collapses_runs_of_replacements() {
123        assert_eq!(safe_filename("Dry//Wet"), "Dry-Wet");
124        assert_eq!(safe_filename("A//B\\\\C"), "A-B-C");
125    }
126
127    #[test]
128    fn preserves_case_and_spaces() {
129        assert_eq!(safe_filename("Truce DryWet"), "Truce DryWet");
130        assert_eq!(safe_filename("ALL CAPS"), "ALL CAPS");
131    }
132
133    #[test]
134    fn trims_whitespace_and_dots() {
135        assert_eq!(safe_filename("  Foo  "), "Foo");
136        assert_eq!(safe_filename(".hidden."), "hidden");
137        assert_eq!(safe_filename(" . . trim . . "), "trim");
138    }
139
140    #[test]
141    fn empty_in_empty_out() {
142        assert_eq!(safe_filename(""), "");
143        assert_eq!(safe_filename("///"), "");
144    }
145}
truce_utils/lib.rs

truce_utils/
lib.rs
