Skip to content

About

A Rust DSL for shell-script-like programs, built with Context-Generic Programming (CGP): each pipeline is a Rust type, and the context that runs it acts as its interpreter.

Topics

Resources

Stars

52 stars

Watchers

1 watching

Forks

Repository files navigation

Crates.io Docs.rs License Tests

Hypershell

Hypershell is a small language for writing shell-script-like programs in Rust, built with Context-Generic Programming (CGP), a language extension for Rust with pluggable trait implementations at compile-time. A Hypershell program is a Rust type, and the context that runs it is its interpreter: a type whose wiring chooses how each piece of the program behaves. So both the language's syntax and its meaning can be extended without editing the crates that define them.

Hypershell is an experimental proof of concept. It shows how CGP builds a modular language in Rust, and it is not meant to replace a shell.

Project page · Examples · CGP quickstart · Introduction post

A program that is a type

This is the smallest Hypershell program. It runs echo hello world! and prints the output:

use hypershell::prelude::*;

pub type Program = hypershell! {
        SimpleExec<
            StaticArg<"echo">,
            WithStaticArgs["hello", "world!"],
        >
    |   StreamToStdout
};

#[tokio::main]
async fn main() -> Result<(), Error> {
    HypershellCli
        .handle(PhantomData::<Program>, Vec::new())
        .await?;

    Ok(())
}

Program is a type alias, not a value. Each piece of it, such as SimpleExec or StreamToStdout, is an empty struct that says nothing about how it runs, and the hypershell! macro only rewrites the shell-like surface into that type: the | becomes a pipeline, the brackets a type-level list, and each string a type-level string.

Running the program is one handle call on a context. HypershellCli is the context here, and this is its entire definition:

pub struct HypershellCli;

delegate_components! {
    HypershellCli {
        namespace HypershellNamespace;
    }
}

The one line joins HypershellNamespace, which routes each piece of syntax to the implementation, or provider, that interprets it. The compiler resolves every choice while it type-checks the program, so the call compiles to direct calls to those providers, with no interpreter running at run time. A context of your own can join the same namespace, add fields that a program reads, such as a URL, or join a namespace that extends the language with new syntax.

Installation

Add hypershell, cgp, and an async runtime to your Cargo.toml:

[dependencies]
cgp = "0.8.0"
hypershell = "0.2.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

The hypershell! macro expects hypershell::prelude::* in scope, and its expansion names the cgp crate, so a program's crate depends on both.

The library crates build on stable Rust, and so does a small program such as the one above. Large programs can need nightly Rust with the next-generation trait solver. On stable Rust 1.98.1, the repository's two compare examples, which nest whole programs inside others, grew rustc to about 7 GB while type-checking and were stopped; on nightly with -Z next-solver=globally, a fresh check of one of them took about 9 seconds and 460 MB. A crate with programs of that size can copy the repository's rust-toolchain.toml and .cargo/config.toml, which select a dated nightly and turn the solver on.

The crates

Hypershell is split into crates by backend, so a program compiles only the libraries it uses:

The two extensions are not part of HypershellNamespace, so a program that uses them joins an extended namespace or wires them on its context, as the examples show. The unpublished hypershell-examples crate holds the examples below.

Examples

Each example is a runnable program, run from the repository's root with cargo run -p hypershell-examples --example <name>. Most need the network and a few common command-line tools.

  • hello.rs: runs echo hello world! through SimpleExec.
  • hello_name.rs: passes a value from a field of the context to a shell command with FieldArg.
  • http_checksum_cli.rs: fetches a URL with curl and pipes the output to sha256sum and cut as streaming commands.
  • http_checksum_client.rs: fetches the URL with the native HTTP client, then pipes the response through the same commands.
  • http_checksum_native.rs: the same checksum in native stages, from a language extended with Checksum.
  • nix_manual.rs: combines a native HTTP request with external command-line tools.
  • save_webpage.rs: downloads a webpage as a stream and writes it to a file.
  • github_issues.rs: calls a JSON web API and decodes the result into a Rust type.
  • rust_playground.rs: sends a Rust snippet to the Rust Playground API as JSON and decodes the response.
  • bluesky.rs: connects to the Bluesky firehose through nix-shell and websocat, then filters the stream with grep.
  • bluesky_websocket.rs: the same firehose, with native WebSockets added to the language.
  • compare_and_branch.rs and parallel_compare.rs: compare the outputs of pipelines and branch on the result, with syntax the examples crate adds.

Status and costs

Hypershell is a demonstration, and these are the costs to weigh first:

  • Large programs need nightly. As Installation describes, the library and small programs build on stable Rust, and programs that nest others deeply can need nightly with the new trait solver.
  • Programs are fixed at compile time. A program is a type, so it cannot be loaded or changed while the application runs. Values a program needs at run time, such as a URL, come from fields of its context.
  • Error messages are long. A mistake in a program is a compile error, and the compiler's raw message lists every step it took before it failed. Checking the program with check_components! and reading the error with cargo cgp check helps: cargo cgp check leads with the root cause for the classes it recognizes, and the tool does not yet reshape every class.
  • It is lightly tested. Its value is as a worked example rather than a tool for production, and the limitations page describes where the design stops and when a shell script or plain Rust fits better.

Building

These are the commands CI runs:

cargo build --workspace --all-targets
cargo test --workspace

The workspace pins nightly-2026-11-16 in rust-toolchain.toml, because .cargo/config.toml turns on the next-generation trait solver with -Z next-solver=globally, so cargo selects that nightly in the repository. Contributors and agents start from AGENTS.md, which names these checks.

Learn more

The project page explains Hypershell: its examples as short tutorials, the design one idea at a time, and guides to writing and debugging a program. For CGP itself, start with the quickstart, then the tutorials and the concepts, and the type-level DSLs page explains the technique behind Hypershell with a smaller language. The CGP knowledge base records the project in depth for contributors and agents.

About

A Rust DSL for shell-script-like programs, built with Context-Generic Programming (CGP): each pipeline is a Rust type, and the context that runs it acts as its interpreter.

Topics

Resources

Stars

52 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages