Crate unilang

Expand description

§Module :: unilang

Zero-overhead command framework with compile-time command registration

unilang processes command definitions at compile-time, generating optimized static command registries with O(1) lookups (~80ns), zero runtime overhead, and SIMD-accelerated parsing. Commands are defined in YAML (default), JSON, or Rust DSL; the build system auto-discovers and validates them before your binary ships.

§Features

50x faster command resolution — static PHF map vs runtime HashMap (~80ns vs ~4,000ns)
Compile-time validation — all command definitions checked before deployment
SIMD parsing — 4-25x parsing performance improvement
Multiple definition styles — YAML, JSON, Rust DSL (builder or const fn)
Multi-file aggregation — auto-discover commands across files with conflict detection
Hybrid mode — static base + runtime plugins in one registry
Built-in REPL — interactive shell with history, completion, secure input
CLI aggregation — unify multiple tools under one interface with namespace isolation

§Installation

[dependencies]
unilang = "0.49"

The default configuration enables multi-YAML build-time static registration (Approach #2 — recommended for 95% of users).

§Minimal Example

Create unilang.commands.yaml:

- name: ".greet"
  description: "Greeting command"
  arguments:
    - name: "name"
      kind: "String"
      attributes:
        optional: true
        default: "World"

Use it in src/main.rs:

use unilang::prelude::*;

include!( concat!( env!( "OUT_DIR" ), "/static_commands.rs" ) );

fn main() -> Result< (), unilang::Error >
{
  let registry = StaticCommandRegistry::from_commands( &STATIC_COMMANDS );
  let pipeline = Pipeline::new( registry );
  let result = pipeline.process_command_simple( ".greet name::Alice" );
  println!( "{}", result.outputs[ 0 ].content );
  Ok( () )
}

cargo run  # Builds, generates static registry, runs

§Parameter Syntax

Named parameters use name::value — double colon is required. The :: operator activates value context, preserving special characters (/, ., #, ?) until whitespace:

.greet name::Alice
.run   file::./examples/plan.md          # file paths — fully supported
.fetch url::https://example.com/path     # URLs — fully supported
.find  pattern::"multi word value"       # spaces → quote the value

Single colon (name:value) is not valid syntax and produces a parse error. See docs/parameter_syntax.md for the full reference.

§Documentation

Document	Contents
docs/quick_start.md	Step-by-step setup guide
docs/parameter_syntax.md	`::` operator, value context, file paths, quoting
docs/cli_definition_approaches.md	All 21 approaches (YAML/JSON/DSL, build/runtime)
docs/cli_aggregation.md	CLI aggregation with namespace isolation
docs/migration.md	Runtime → build-time migration (50x speedup)
docs/troubleshooting.md	Common errors and solutions
docs/features.md	Full feature tracking table
docs/optimization_guide.md	Performance tuning guidelines
docs/phf_reexport.md	PHF re-export for `static_registry` users
spec/	Requirements and specification
examples/	Runnable examples with learning path

§Approach Selection

#	Approach	Feature Flag	Default	Lookup
2	Multi-YAML → Build-time static	`approach_yaml_multi_build`	✅	~80ns
1	Single YAML → Build-time static	`approach_yaml_single_build`	❌	~80ns
3	YAML → Runtime loading	`approach_yaml_runtime`	❌	~4,200ns
4–6	JSON variants (same as 1–3)	`approach_json_*`	❌	80/4,200ns
7	Rust DSL builder API	(always available)	✅	~4,200ns
8	Rust DSL const fn static	`approach_rust_dsl_const`	❌	~80ns
18	Hybrid (static + runtime)	`approach_hybrid`	❌	Mixed

See docs/cli_definition_approaches.md for all 21 approaches.

§Design Rules Compliance Notice

CRITICAL: This codebase must follow strict design rules. Before making changes, review:

$PRO/genai/code/rules/code_design.rulebook.md - Core design patterns and architecture rules
$PRO/genai/code/rules/code_style.rulebook.md - Code formatting and style requirements

Key Rules Summary:

Testing: All tests MUST be in tests/ directory, NOT in src/ as mod tests
Benchmarking: Use benchkit framework ONLY - no custom timing code in tests
Performance Tests: NEVER mix benchmarks with unit tests - separate concerns
Test Documentation: Every test file MUST have Test Matrix documentation
Directory Structure: tests/ for tests, benches/ for benchmarks (if using benchkit)

Common Violations to Avoid: ❌ Custom std::time::Instant timing code in test files ❌ Performance/benchmark tests in tests/ directory ❌ Missing file-level documentation with Test Matrix in test files ❌ Using anything other than benchkit for performance measurement

§Feature Flags

Unilang supports multiple feature flags to customize functionality and dependencies:

§Core Features

enabled - Core functionality (included in default)
full - All features enabled for maximum functionality

§REPL Features

repl - Basic REPL functionality with standard I/O
- Provides interactive command execution
- Basic command history tracking
- Cross-platform compatibility
- No additional dependencies
enhanced_repl ⭐ Enabled by Default - Advanced REPL with rustyline integration
- Enables: All features from repl plus:
- Arrow Key Navigation: ↑/↓ for command history browsing
- Tab Auto-completion: Command and argument completion
- Interactive Prompts: Secure password input with masking
- Session Persistence: History saved across sessions
- Terminal Detection: Auto-fallback to basic REPL in non-interactive environments
- Dependencies: rustyline, std::io::IsTerminal

§Performance Features

simd - SIMD optimizations for parsing and JSON processing
- Enables: simd-json (4-25x faster JSON), SIMD string operations
- Automatic: Included in default for maximum performance
- Disable with: cargo build --no-default-features --features enabled

§Optional Features

on_unknown_suggest - Fuzzy command suggestions (requires textdistance)

Note: Benchmarking tools are available in the separate unilang_benchmarks workspace crate

§Usage Examples

Basic REPL (minimal dependencies):

[dependencies]
unilang = { version = "0.10", features = ["repl"] }

Default (Enhanced REPL included):

[dependencies]
unilang = "0.10"  # Enhanced REPL enabled by default

Performance-optimized CLI:

[dependencies]
unilang = { version = "0.10", features = ["enhanced_repl", "simd", "on_unknown_suggest"] }

Embedded/minimal:

[dependencies]
unilang = { version = "0.10", default-features = false, features = ["enabled"] }

§Feature Compatibility

enhanced_repl automatically includes repl
full includes all features except development-only ones
All features work together without conflicts
Enhanced REPL gracefully falls back to basic REPL when needed

Re-exports§

pub use super::private::TypeAnalyzer;
pub use super::private::TypeHint;
pub use super::private::Severity;
pub use super::private::HintGenerator;
pub use super::aggregator;
pub use super::builder;
pub use super::type_analyzer;
pub use super::hint_generator;
pub use super::private::TypeAnalyzer;
pub use super::private::TypeHint;
pub use super::private::Severity;
pub use super::private::HintGenerator;
pub use unilang_parser as parser;
pub use phf;
pub use super::prelude::*;
pub use super::prelude::*;

Modules§

build_helpers: Build-time helper utilities for type analysis and hint generation. Provides tools for detecting type issues in YAML command definitions during build. Requires feature: yaml_parser Build-time helper utilities for static registry generation
command_validation: Command validation utilities. Command registration validation and utilities.
config_extraction: Config value extraction utilities. Generic extractors for HashMap<String, (JsonValue, S)> config maps. Requires feature: json_parser
data: Core data structures and types.
error: Error handling utilities.
exposed: Exposed namespace of the module.
help: Help generation system.
interner: String interning system for performance optimization. String Interning System
interpreter: Command execution interpreter.
loader: Configuration loading from YAML/JSON. Functions gated by yaml_parser and json_parser features.
multi_yaml: Multi-YAML build system for compile-time aggregation. Requires feature: multi_file Multi-YAML Build System and Ergonomic Aggregation APIs
orphan: Orphan namespace of the module.
own: Own namespace of the module.
pipeline: High-level pipeline API.
prelude: Prelude to use essentials: use my_module ::prelude :: *.
registry: Command registry management. Some functions gated by approach features.
semantic: Semantic analysis and validation.
simd_json_parser: SIMD-optimized JSON parsing for 4-25x performance improvements. Requires features: simd-json AND json_parser
simd_tokenizer: SIMD-optimized tokenization for 3-6x performance improvements. SIMD-optimized tokenization for high-performance string processing.
static_data: Static data structures for compile-time commands. Requires feature: static_registry
types: Value types and type system.
validation_core: Core validation logic shared between runtime and build.rs. This module can be included in build.rs via include!() since it has no dependencies. Core validation logic shared between runtime and build.rs.

Structs§

AggregationConfig: Re-export key aggregator types Re-export key aggregator types Configuration for multi-YAML aggregation
ArgumentAttributes: Holds attributes and configuration for a specific argument within a command.
ArgumentDefinition: Defines an argument within a command, including its name, type, and constraints.
BatchResult: Result of processing multiple commands through the pipeline.
CliBuilder: Re-export key builder types Re-export key builder types Ergonomic CLI builder for simple and complex aggregation scenarios
CliConfig: Re-export key builder types Re-export key builder types Global CLI configuration
CommandDefinition: Type-safe command definition with validated newtypes and private fields.
CommandDefinitionBuilder: Type-state builder for CommandDefinition that enforces required fields at compile time.
CommandName: A validated command name that guarantees the dot prefix convention.
CommandRegistry: Runtime command registration. Consider compile-time alternatives for better performance. Runtime command registration. Consider compile-time alternatives for better performance. Runtime command registration. Consider compile-time alternatives for better performance.
CommandRegistryBuilder: A builder for constructing CommandRegistry instances with a fluent API.
CommandResult: Result of processing a single command through the pipeline.
ConditionalModule: Re-export key builder types Re-export key builder types Conditional module based on feature flags
ConflictReport: Re-export key aggregator types Re-export key aggregator types Report of detected conflicts
DynamicCommandMap: Optimized dynamic command storage with intelligent caching
DynamicModule: Re-export key builder types Re-export key builder types Dynamic YAML module configuration for ergonomic APIs
EnvConfigParser: Re-export key aggregator types Re-export key aggregator types Environment variable configuration parser
ErrorData: Represents an error that occurred during command execution
ExecutionContext: The execution context for a command.
FastJsonValue: Performance-optimized JSON value for applications that need maximum parsing speed with minimal allocations.
HelpDisplayOptions: Global configuration for help output display.
HelpGenerator: Generates help information for commands.
InternerStats: Statistics about the string interner’s current state.
Interpreter: The interpreter for Unilang commands.
ModuleConfig: Re-export key aggregator types Re-export key aggregator types Configuration for a single module
MultiYamlAggregator: Re-export key aggregator types Re-export key aggregator types Multi-YAML aggregation system for compile-time command processing
Namespace: Represents a namespace within the command system.
NamespaceIsolation: Re-export key aggregator types Re-export key aggregator types Namespace isolation configuration
NamespaceType: A validated namespace that guarantees correct naming conventions.
NotSet: Marker type indicating a required field has not been set.
OutputData: Represents the output of a successfully executed command.
PerformanceMetrics: Performance metrics for command registry operations.
Pipeline: A high-level pipeline processor that combines parsing, semantic analysis, and execution.
SIMDJsonParser: High-performance JSON parser using SIMD optimizations.
SIMDTokenizer: SIMD-optimized tokenizer for splitting strings by delimiters. SIMD-optimized tokenizer for splitting strings by delimiters.
SemanticAnalyzer: The semantic analyzer, responsible for validating the parsed program.
Set: Marker type indicating a required field has been set.
StaticArgumentAttributes: Static, const-compatible version of ArgumentAttributes.
StaticArgumentDefinition: Static, const-compatible version of ArgumentDefinition.
StaticCommandDefinition: Static, const-compatible version of CommandDefinition.
StaticCommandMap: Wrapper for static command maps with zero-overhead compile-time lookup.
StaticCommandRegistry: High-performance static command registry with zero-cost compile-time lookup. High-performance static command registry with zero-cost compile-time lookup. High-performance static command registry with zero-cost compile-time lookup.
StaticModule: Re-export key builder types Re-export key builder types Static module configuration for ergonomic APIs
StringInterner: Thread-safe string interner that caches strings and returns ’static references.
TypeError: An error that can occur during type parsing or validation.
VerifiedCommand: Represents a command that has been verified against the command registry.
VersionType: A validated version string.

Enums§

AggregationMode: Re-export key builder types Re-export key builder types Ergonomic CLI aggregation modes
CommandStatus: Command status indicating lifecycle stage and availability.
ConflictResolutionStrategy: Re-export key aggregator types Re-export key aggregator types Conflict resolution strategies for handling duplicate commands
ConflictType: Re-export key aggregator types Re-export key aggregator types Types of conflicts that can be detected
Error: The main error type for the Unilang framework.
ErrorCode: Standard error codes for command execution failures
HelpVerbosity: Help verbosity levels controlling output detail.
Kind: Represents the data type and structure of an argument or value.
ModuleSource: Re-export key builder types Re-export key builder types Module source type for aggregation
RegistryMode: Registry operation mode for hybrid command lookup optimization
StaticKind: Static, const-compatible version of Kind.
StaticValidationRule: Static, const-compatible version of ValidationRule.
UnilangError: Structured error types for better API consistency and error handling.
ValidationRule: Validation rule for argument values.
Value: Represents a parsed and validated value of a specific kind.

Traits§

CommandRegistryTrait: Common trait for command registries to enable interoperability.

Functions§

aggregate_cli_complex: Re-export key aggregator types Re-export key aggregator types More complex aggregate_cli simulation
aggregate_cli_simple: Re-export key aggregator types Re-export key aggregator types Convenience function for zero-boilerplate static aggregation (aggregate_cli! macro simulation)
compute_full_name_core: Computes full command name from namespace and name.
create_aggregated_registry: Re-export key aggregator types Re-export key aggregator types Runtime multi-YAML aggregation with environment variable support.
extract_bool: Extract bool value from config.
extract_f64: Extract f64 value from config.
extract_i32: Extract i32 value from config.
extract_i64: Extract i64 value from config.
extract_string: Extract String value from config.
extract_string_array: Extract array of strings from config.
extract_u8: Extract u8 value from config.
extract_u16: Extract u16 value from config.
extract_u32: Extract u32 value from config.
extract_u64: Extract u64 value from config.
global_interner: Returns a reference to the global string interner instance.
intern: Convenience function to intern a string using the global interner.
intern_command_name: Convenience function to intern command names using the global interner.
is_help_command: Checks if command name ends with “.help” suffix.
is_simd_enabled: Returns true if SIMD optimizations are available and enabled. Returns true if SIMD optimizations are available and enabled.
load_command_definitions_from_json_str: Loads command definitions from a JSON string.
load_command_definitions_from_yaml_str: Loads command definitions from a YAML string.
make_help_command_name: Builds help command name from command name.
parse_cargo_metadata: Re-export key aggregator types Re-export key aggregator types Parse Cargo.toml metadata for build configuration
parse_value: Parses a raw string input into a Value based on the specified Kind.
process_single_command: Convenience function to process a single command with a registry.
resolve_routine_link: Resolves a routine link string to a CommandRoutine.
simd_support_info: CPU feature detection for SIMD optimization selection. CPU feature detection for SIMD optimization selection.
validate_command_definition_core: Validates a complete command definition at build time.
validate_command_for_registration: Validates entire command definition for registration.
validate_command_name: Validates command name follows dot-prefix naming convention.
validate_command_name_core: Validates command name follows dot-prefix naming convention.
validate_full_name_core: Validates the full name (namespace + name combination).
validate_namespace: Validates namespace follows dot-prefix naming convention.
validate_namespace_core: Validates namespace follows dot-prefix naming convention.
validate_parameter_storage_types: Validates parameter storage types match their multiple attribute.
validate_single_command: Convenience function to validate a single command with a registry.
validate_version_core: Validates version string is non-empty.

Type Aliases§

CommandRoutine: Type alias for a command routine. A routine takes a VerifiedCommand and an ExecutionContext, and returns a Result of OutputData or ErrorData.
ConfigMap: Type alias for configuration maps with any source type.

Crate unilang

Crate unilang Copy item path

§Module :: unilang

§Features

§Installation

§Minimal Example

§Parameter Syntax

§Documentation

§Approach Selection

§Design Rules Compliance Notice

§Feature Flags

§Core Features

§REPL Features

§Performance Features

§Optional Features

§Usage Examples

§Feature Compatibility

Re-exports§

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate unilang