<div align="center">
# 📜 Cirious Codex Derive
### Declarative CLI & Configuration Framework for the Cirious Ecosystem
Robust, type-safe, and high-performance argument parsing built on procedural macros.
[](https://github.com/cirious-studio/cirious_codex_derive/actions/workflows/ci.yml) [](https://crates.io/crates/cirious_codex_derive) [](https://docs.rs/cirious_codex_derive) [](https://www.rust-lang.org/) [](#-license)
</div>
---
## 📖 Overview
**`Cirious Codex Derive`** replaces complex, third-party CLI parsing crates with a custom, high-performance macro engine.
---
### ⚙️ Supported Attributes
| Attribute | Type | Description |
| :--- | :--- | :--- |
| `aliase` | `String` | Short flag (e.g., `"p"` becomes `/p`) |
| `command` | `String` | Long flag (e.g., `"port"` becomes `/port`) |
| `default_value`| `String` | Fallback value if the flag is absent |
---
### ⚡ Quick Start
```rust
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:**
```bash
# 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
- [x] Setup `proc-macro` workspace architecture (`syn`, `quote`, `proc-macro2`).
- [x] Implement foundational traits and attribute parsing logic.
- [x] Develop `#[derive(CodexParser)]` and `#[derive(CodexCommand)]` to replace third-party CLI parsing.
- [x] Strict terminal argument validation and custom compilation errors.
### ✅ v0.2.0 — Subcommands & Globals
- [x] Implement `#[derive(CodexSubcommand)]` for Enum routing.
- [x] Automatic injection and flattening of `GlobalArgs` (`--config`, `--verbose`).
- [x] 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
---
<div align="center">
<i>Minimalist by design. Consistent in execution.</i>
**Engineered by Cirious Studio**
</div>