bashkit 0.4.0__tar.gz → 0.4.1__tar.gz

{bashkit-0.4.0 → bashkit-0.4.1}/Cargo.lock

@@ -345,7 +345,7 @@ checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 
 [[package]]
 name = "bashkit"
-version = "0.4.0"
+version = "0.4.1"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -393,7 +393,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-bench"
-version = "0.4.0"
+version = "0.4.1"
 dependencies = [
  "anyhow",
  "bashkit",
@@ -407,7 +407,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-cli"
-version = "0.4.0"
+version = "0.4.1"
 dependencies = [
  "anyhow",
  "bashkit",
@@ -423,7 +423,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-eval"
-version = "0.4.0"
+version = "0.4.1"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -440,7 +440,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-js"
-version = "0.4.0"
+version = "0.4.1"
 dependencies = [
  "bashkit",
  "napi",
@@ -453,7 +453,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-python"
-version = "0.4.0"
+version = "0.4.1"
 dependencies = [
  "bashkit",
  "num-bigint",

{bashkit-0.4.0 → bashkit-0.4.1}/Cargo.toml

@@ -7,7 +7,7 @@ resolver = "2"
 members = ["crates/*"]
 
 [workspace.package]
-version = "0.4.0"
+version = "0.4.1"
 edition = "2024"
 license = "MIT"
 authors = ["Everruns"]

{bashkit-0.4.0 → bashkit-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bashkit
-Version: 0.4.0
+Version: 0.4.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

bashkit-0.4.1/crates/bashkit/docs/clap-builtins.md

@@ -0,0 +1,151 @@
+# Clap Builtins
+
+`ClapBuiltin` lets Rust applications define custom Bashkit commands with
+`#[derive(clap::Parser)]` argument structs. Handlers receive a
+`BashkitContext` that captures stdout, stderr, and exit code for the virtual
+shell. The feature is enabled by default through `clap-builtins`.
+
+Disable it for a smaller library dependency surface:
+
+```toml
+[dependencies]
+bashkit = { version = "0.3", default-features = false }
+```
+
+Enable it explicitly when default features are off:
+
+```toml
+[dependencies]
+bashkit = { version = "0.3", default-features = false, features = ["clap-builtins"] }
+```
+
+## Basic Usage
+
+```rust
+use bashkit::clap::Parser;
+use bashkit::{Bash, BashkitContext, ClapBuiltin, async_trait};
+
+#[derive(Parser)]
+#[command(name = "greet", about = "Print a greeting")]
+struct GreetArgs {
+    #[arg(short, long, default_value = "World")]
+    name: String,
+
+    #[arg(short, long)]
+    shout: bool,
+}
+
+struct Greet;
+
+#[async_trait]
+impl ClapBuiltin for Greet {
+    type Args = GreetArgs;
+
+    async fn execute_clap(
+        &self,
+        args: Self::Args,
+        ctx: &mut BashkitContext<'_>,
+    ) -> bashkit::Result<()> {
+        let greeting = format!("Hello, {}!", args.name);
+        let greeting = if args.shout {
+            greeting.to_uppercase()
+        } else {
+            greeting
+        };
+        ctx.write_stdout(format!("{greeting}\n"));
+        Ok(())
+    }
+}
+
+#[tokio::main]
+async fn main() -> bashkit::Result<()> {
+    let mut bash = Bash::builder().builtin("greet", Box::new(Greet)).build();
+
+    let result = bash.exec("greet --name Alice --shout").await?;
+    assert_eq!(result.stdout, "HELLO, ALICE!\n");
+
+    let help = bash.exec("greet --help").await?;
+    assert_eq!(help.exit_code, 0);
+    assert!(help.stdout.contains("Usage: greet"));
+    assert!(help.stderr.is_empty());
+
+    let error = bash.exec("greet --unknown").await?;
+    assert_eq!(error.exit_code, 2);
+    assert!(error.stderr.contains("unexpected argument"));
+    Ok(())
+}
+```
+
+## Subcommands
+
+Use normal clap subcommands for nested command surfaces.
+
+```rust
+use bashkit::clap::{Parser, Subcommand};
+use bashkit::{Bash, BashkitContext, ClapBuiltin, async_trait};
+
+#[derive(Parser)]
+#[command(name = "math")]
+struct MathArgs {
+    #[command(subcommand)]
+    command: MathCommand,
+}
+
+#[derive(Subcommand)]
+enum MathCommand {
+    Add { left: i64, right: i64 },
+    StdinLen,
+}
+
+struct Math;
+
+#[async_trait]
+impl ClapBuiltin for Math {
+    type Args = MathArgs;
+
+    async fn execute_clap(
+        &self,
+        args: Self::Args,
+        ctx: &mut BashkitContext<'_>,
+    ) -> bashkit::Result<()> {
+        let value = match args.command {
+            MathCommand::Add { left, right } => left + right,
+            MathCommand::StdinLen => ctx.stdin().unwrap_or("").len() as i64,
+        };
+        ctx.write_stdout(format!("{value}\n"));
+        Ok(())
+    }
+}
+
+#[tokio::main]
+async fn main() -> bashkit::Result<()> {
+    let mut bash = Bash::builder().builtin("math", Box::new(Math)).build();
+
+    let sum = bash.exec("math add 20 22").await?;
+    assert_eq!(sum.stdout, "42\n");
+
+    let stdin_len = bash.exec("printf abc | math stdin-len").await?;
+    assert_eq!(stdin_len.stdout, "3\n");
+    Ok(())
+}
+```
+
+## Behavior
+
+- The clap parser receives only the command arguments, not the shell command
+  name from the script.
+- `BashkitContext::write_stdout()` and `write_stderr()` append virtual command
+  output; direct `println!`/`eprintln!` writes to the host process instead.
+- Set non-zero command status with `ctx.set_exit_code(code)` or
+  `ctx.fail(message, code)`.
+- `--help` and `--version` return exit code `0` with clap output on stdout.
+- Parse failures return clap's exit code, usually `2`, with diagnostics on
+  stderr.
+- Diagnostics are capped at 1 KB so custom builtins keep Bashkit's builtin
+  error-output safety guarantees.
+
+## See Also
+
+- [`crates/bashkit/examples/clap_builtin.rs`](../crates/bashkit/examples/clap_builtin.rs)
+- [`crates/bashkit/examples/clap_builtin_subcommands.rs`](../crates/bashkit/examples/clap_builtin_subcommands.rs)
+- [`crates/bashkit/docs/custom_builtins.md`](../crates/bashkit/docs/custom_builtins.md)

{bashkit-0.4.0 → bashkit-0.4.1}/crates/bashkit/src/lib.rs

@@ -2795,7 +2795,7 @@ pub mod custom_builtins_guide {}
 ///
 /// **Related:** [`ClapBuiltin`], [`BashkitContext`], [`BashBuilder::builtin`], [`custom_builtins_guide`]
 #[cfg(feature = "clap-builtins")]
-#[doc = include_str!("../../../docs/clap-builtins.md")]
+#[doc = include_str!("../docs/clap-builtins.md")]
 pub mod clap_builtins_guide {}
 
 /// Bash compatibility scorecard.