Scripting

Rust with the ergonomics of a scripting language.

scripting is a professional-grade, high-leverage library designed for staff engineers and SREs who need to build production-ready automation fast. It combines the safety and performance of Rust with a fluent, chained API that rivals Python or Ruby for developer velocity.

---

Key Features

• Fluent API: Chained operations on str, String, and Path via StrExt and PathExt.
• Safety Seams: Built-in DryRunPolicy and AuditBackend for destructive operations.
• Managed Workspaces: Auto-cleaning temporary directories and directory-scoped execution.
• Resilient HTTP: Client with automatic exponential backoff retries and mockable backends.
• Parallel Pipelines: Concurrent shell command execution with rich error reporting.
• Interactive UI: Mandatory dialoguer integration for consistent, beautiful CLI prompts.

---

Quick Start

use scripting::prelude::*;

fn main() {
    // 1. Chained FS & JSON manipulation
    "config.json".p().read().parse_json().dig("api.key").println();

    // 2. Powerful shell interpolation
    let name = "world";
    format!("echo hello {name}").run().println();

    // 3. Resilient Network Calls
    let body = "https://api.github.com/zen".http_get();
    format!("Zen: {body}").println_color(Color::Cyan);
}

---

API Reference by Module

Filesystem (fs)

High-leverage operations that respect safety policies.

"logs".p().mkdir();               // Recursive directory creation
"report.txt".p().read();          // Read file to string (panic-first)
"build".p().rm();                 // Remove file or directory
"config.json".p().exists();       // Path existence check
"src".p().ls().ext("rs");         // Filtered directory listing

Process & Shell (process)

Powerful pipeline building and shell interpolation.

sh!("git commit -m '{msg}'");     // Interpolated shell execution
"ls -l".run();                    // Fluent shell execution
cmd("cat", ["log"]).pipe("grep", ["ERR"]); // Pipeline building
"long_task".background();         // Non-blocking shell execution

JSON & Data (json)

Deep, dot-notation querying inspired by Ruby.

let val = json_str.parse_json();  // Fluid string to JSON
val.dig("metadata.id");           // Deep nested query
val.dig("users.0.name");          // Array indexing

Interactive I/O (io)

Beautiful CLI prompts and colored output.

let name = prompt("Name: ");      // Standard prompt
confirm("Delete?", false);        // [y/N] confirmation
select("Role:", &["Dev", "Ops"]); // Menu selection
"Success".println_color(Color::Green); // Chainable colors

Network (http)

Resilient HTTP client with automatic retries.

"https://api.io".http_get();      // Simple GET (retries enabled)
"url".http_post_json(r#"{"id": 1}"#); // Chained JSON POST
"url".http_download("logo.png");    // Stream to file

Environment & Args (env, arg)

Resilient environment management and ergonomic CLI parsing via pico-args.

let verbose = arg_flag("--verbose"); // Check for flag
let output = arg_value("--output");  // Extract option value
let files = arg_free();              // Get remaining positional args
let home = home();                   // Cross-platform home dir
temp_dir().run_in(|| { ... });       // Scoped workspace execution

Regex (regex)

Streamlined pattern matching and replacement.

"123-456".re_match(r"\d+-\d+");   // Boolean check
"user@mail.com".re_find(r"@\w+"); // Find first match
"v1.2.0".re_replace(r"\d+", "2"); // Single replacement
"a b c".re_replace_all(r"\w", "x"); // Global replacement

---

Architecture: The Safety Seam

The library is built on the principle of Deep Modules. Destructive operations are channeled through a central ScriptPolicy, allowing for global auditing and safety enforcement without changing business logic.

graph TD
    UserScript[User Script] -->|sh! / write / rm| Library[Scripting Library]
    Library -->|Policy Seam| CurrentPolicy{Current Policy}
    CurrentPolicy -->|Live| OS[Operating System]
    CurrentPolicy -->|Dry-Run| Console[Console / Audit Log]
    Library -->|Audit Seam| Auditor[Audit Backend]
    Auditor -->|Log| File[(audit.log)]

Loading

---

Managed Environments

Use Workspace to isolate your script's side effects and ensure cleanup:

let ws = temp_dir(); // Auto-deletes on drop
ws.run_in(|| {
    sh!("git init");
    "README.md".p().write("# New Project");
}).expect("Workspace execution failed");

---

Feature Flags

Feature	Description	Dependencies
http	Resilient HTTP client	ureq
json	Dot-notation JSON querying	serde_json
regex	Streamlined Regex helpers	regex
dotenv	.env file support	dotenvy
hash	SHA256 / MD5 helpers	sha2, md5

---

Production Readiness

• Zero Unsafe: The library is built with forbid(unsafe_code).
• Error Locality: Every failure includes the specific command, path, or URL that caused it.
• Idempotency Focus: Helpers are designed to favor safe, repeatable patterns.
• Mockable: HTTP and Policy backends can be swapped for unit testing your scripts.

---

License

MIT. Build amazing things.