Writing a program
This guide is for writing Hypershell programs rather than extending the language: how to choose the context, which is the type a program runs on, and then how to feed the program its values, make its stages agree, and check it before running it. Hypershell is a shell-scripting language whose programs are Rust types, built with Context-Generic Programming (CGP), a Rust library that lets an application choose an implementation. The examples show each step in a running program.
Start from the prelude and a context
Import hypershell::prelude::*, and run the program on HypershellCli if it reads no runtime
values. The prelude brings the syntax, the hypershell! macro and the names its output uses,
CanHandle, PhantomData, and the error type. Run the program with handle, inside a Tokio
runtime:
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(())
}
Import the prelude rather than the macro alone. The macro's output names Pipe, Product!, and
Symbol! without qualifying them, so a file without them in scope fails with "cannot find macro
Product in this scope". Use HypershellHttp instead of HypershellCli when the program makes
HTTP requests and reads no other value; it carries the http_client field those requests need.
Read runtime values from a custom context
A value a program needs at run time lives in a field of the context, and the program names the
field. A program is a type, so it cannot hold a URL or a name. Define a struct with the fields,
derive HasField, and join HypershellNamespace:
use hypershell::namespaces::HypershellNamespace;
use hypershell::prelude::*;
#[derive(HasField)]
pub struct MyApp {
pub http_client: reqwest::Client,
pub url: String,
}
delegate_components! {
MyApp {
namespace HypershellNamespace;
}
}
Name the client field http_client, since the namespace reads the HTTP client from a field of
exactly that name. Then reach the fields from the program with the argument syntax:
FieldArg<"name">— one value, formatted withDisplay, wherever an argument is expected.FieldArgs<"args">— every item of an iterable field, as a command's whole argument list.JoinArgs[…]— several arguments joined into one. For a URL or a header it concatenates them, and for a command path or a file path it joins them as path segments.UrlEncodeArg<…>— a value percent-encoded for a URL. Use it inside theJoinArgsthat builds the URL.
Choose simple or streaming stages
Use a simple stage when the data is small or a command must finish before the next one starts, and
a streaming stage for large data or concurrent processes. SimpleExec and SimpleHttpRequest
collect the whole output and produce bytes. StreamingExec and StreamingHttpRequest produce a
stream at once, and consecutive streaming stages run at the same time, as in a shell.
The choice changes when a failure is reported. SimpleExec fails as soon as its command exits with
a failure status, reporting its standard error. StreamingExec reports the same failure when its
output stream ends, so the stage reading the stream fails with it, after any output the command
wrote has flowed through the stages in between.
Make adjacent stages agree
Each stage's output is the next stage's input, and a stage accepts only the input types its wiring lists. Most stages accept bytes or any kind of stream, so they chain freely. Three boundaries need an adapter:
- A streaming stage before a simple stage — insert
StreamToBytes, as inStreamingExec<…> | StreamToBytes | SimpleExec<…>. - An HTTP or WebSocket stream before
StreamToBytesorStreamToString— insertToTokioAsyncRead, imported fromhypershell_tokio_components::dsl. - Raw bytes to print as text —
BytesToStringdecodes UTF-8, andBytesToHexencodes bytes such as a digest.
The full table of what each stage accepts and produces is on the streams and input dispatch page.
Pass the right input
The input argument is the first stage's input, and its type must be one the first stage accepts. The common cases are:
Vec::<u8>::new()for a program whose first stage runs a command or sends a request with an empty body.()for a program starting withReadFile, which accepts nothing else.- A Rust value for a program starting with
EncodeJson.
When a program fails to compile, the errors reported at the handle call show some of their types
as unresolved _, whether the input is written Vec::new() or Vec::<u8>::new(). Checking the
program, as the last section shows, avoids them.
The program's output type is computed from its last stage, so handle on a program ending in
DecodeJson<Vec<Issue>> returns a Vec<Issue> with no conversion.
Check the program before running it
Assert that a context can run a program with
check_components!, keyed on the program and its
input. The check forces the whole resolution where it is written, and a failure there carries a
root cause:
use cgp::extra::handler::HandlerComponent;
check_components! {
#[check_trait(CheckMyApp)]
MyApp {
HandlerComponent: (Program, Vec<u8>),
}
}
One check can list several programs, or several inputs, as an array:
HandlerComponent: [(Hello, Vec<u8>), (Cat, ())]. Read failures with
cargo cgp check; the debugging guide shows the common
ones. A failure reported at the handle call itself often carries no root cause, which is the
practical reason to check. cargo cgp check leads with the root cause for the classes it
recognizes, and the tool does not yet reshape every class.
Build large programs with nightly and the new trait solver
A small program builds on stable Rust in a crate of its own. The Hypershell repository pins nightly
Rust and passes -Z next-solver=globally to the compiler, and a crate of your own whose programs
nest sub-programs should do the same. On stable Rust the simpler programs type-check, but the
largest examples exhausted memory while type-checking; see
crate layout.
Where to go next
- Debugging: the common mistakes, with the error each one produces and its fix.
hello_name: a custom context and a check, in a running program.
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the project's source. See How AI is used in this project.