📜 Cirious Codex Derive

Declarative CLI & Configuration Framework for the Cirious Ecosystem

Robust, type-safe, and high-performance argument parsing built on procedural macros.

📖 Overview

Cirious Codex Derive replaces complex, third-party CLI parsing crates with a custom, high-performance macro engine.

⚙️ Supported Attributes

⚡ Quick Start

use cirious_codex_derive::{CodexCommand, CodexParser};

// 1. Define global arguments that will be injected into every command
#[derive(Debug, Clone)]
pub struct GlobalArgs {
  pub verbose: bool,
  pub config_path: Option<String>,
}

// 2. Define a trait to access these global arguments (required by the derive)
pub trait CodexCommand {
  fn global_args(&self) -> &GlobalArgs;
}

// 3. Derive CodexParser and CodexCommand
#[derive(CodexParser, CodexCommand, Debug)]
pub struct AuthConfig {
  // 3a. Global Arguments Field (Must be named 'global')
  pub global: GlobalArgs,

  // 3b. Define a Command
  // 'aliase' = short flag (e.g., /p)
  // 'command' = long flag (e.g., /port)
  // 'default_value' = fallback if argument is missing
  #[codex(aliase = "p", command = "port", default_value = "3000")]
  pub port: u16,

  #[codex(aliase = "c", command = "config", default_value = "./config.toml")]
  pub config_path: String,
}

fn main() {
  // 4. Parse arguments (returns the struct directly)
  let config = AuthConfig::parse_cli(None);

  println!("Server port: {}", config.port);
  println!("Config path: {}", config.config_path);

  if config.global.verbose {
    println!("Verbose mode enabled");
  }
}

Run it:

# Using short flags
$ cargo run -- /p 8080 /c ./prod.toml

# Using long flags
$ cargo run -- /port 8080 /config ./prod.toml

# Using defaults (missing flags get filled)
$ cargo run -- /verbose /p 9090

🚧 Development Roadmap

✅ v0.1.0 — Foundation & CLI Core

• Setup proc-macro workspace architecture (syn, quote, proc-macro2).
• Implement foundational traits and attribute parsing logic.
• Develop #[derive(CodexParser)] and #[derive(CodexCommand)] to replace third-party CLI parsing.
• Strict terminal argument validation and custom compilation errors.

✅ v0.2.0 — Subcommands & Globals

• Implement #[derive(CodexSubcommand)] for Enum routing.
• Automatic injection and flattening of GlobalArgs (--config, --verbose).
• Implementation of custom error formatting tailored for the terminal.

🔭 v0.3.0 — Intelligent Developer Experience (DX)

• Fuzzy Suggestion Engine: Implement Levenshtein-based command correction to suggest valid commands upon typos (e.g., "Did you mean /build?").
• Automated Documentation (/help): Develop CodexHelp to automatically generate CLI interface manuals by harvesting doc comments (///) and metadata.
• Custom Validation Hooks: Create an extensible attribute system (e.g., #[codex(validate = "my_func")]) for custom logic like port ranges, path existence, or Regex patterns.
• Performance Optimization: Refactor TokenStream generation and procedural macro expansion to reduce compilation overhead and binary size.
• Exit-Code Idioms: Transition from std::process::exit to idiomatic std::process::ExitCode for better integration with shell scripting pipelines.

📜 License

Licensed under either of the following, at your option:

• MIT License
• Apache License 2.0

Minimalist by design. Consistent in execution.

Engineered by Cirious Studio