Skip to main content

Debugging a program

A mistake in a Hypershell program or its wiring is a compile error, and the raw compiler output for one spans every layer of wiring between the context, the type the program runs on, and the part that failed. Hypershell is a shell-scripting language whose programs are Rust types, built with Context-Generic Programming (CGP), a Rust library whose wiring selects the implementation behind each trait. This guide shows the common mistakes, each with the code that triggers it, the root cause cargo cgp check reports, and the fix. Each output below comes from compiling the program against cargo-cgp built from its current source, sometimes through a check_components! and sometimes at the handle call, and is trimmed to its headline and root cause. Long type paths are abridged with an ellipsis, and the dependency chain the tool prints below the root cause is left out. cargo cgp check leads with the root cause for the classes it recognizes, and the tool does not yet reshape every class.

Check first, then read the root cause​

Put the program in a check_components! before reading any error, and read the result with cargo cgp check. A failure reported at the handle call often carries no root cause at all: the missing-field mistake below, reported at its call site, produces only headlines about the pipeline's combinators. Through a check, the same mistake names its cause. The check is keyed on the program and its input:

use cgp::extra::handler::HandlerComponent;

check_components! {
#[check_trait(CheckHypershellCli)]
HypershellCli {
HandlerComponent: (Program, Vec<u8>),
}
}

Below the root cause, cargo cgp check prints the chain of lookups that led to it, one line per step, which follows the walk on the assembly page. Read it from the bottom: the last line is the part that failed. Each step names the table it looked in, so the chain shows whether the failure is in the context, in a bundle, or in an input dispatcher. The codes in brackets are listed on the error codes page.

A context lacks a field​

A FieldArg names a field the context does not have. Here HypershellCli, which has no fields, runs a program that reads name:

pub type Program = hypershell! {
SimpleExec<StaticArg<"echo">, WithArgs[StaticArg<"Hello,">, FieldArg<"name">]>
| StreamToStdout
};
error[E0277]: [CGP-E001] missing field `name` on `HypershellCli`
= note: root cause: [CGP-E110] missing field `name` on `HypershellCli`

The chain runs through the pipeline, SimpleExec, the command's argument list, and the extractor for FieldArg<"name">. Fix: run the program on a context with the field, deriving HasField, as hello_name does. The same error names http_client when an HTTP program runs on a context without a client.

A stage cannot accept the previous stage's output​

The input type of a stage is the previous stage's output, and the error takes one of two forms, depending on whether the stage has an input dispatcher.

A stage without a dispatcher reports the unmet bound. SimpleExec needs bytes, and a streaming stage produces a stream:

pub type Program = hypershell! {
StreamingExec<StaticArg<"echo">, WithStaticArgs["hello"]>
| SimpleExec<StaticArg<"wc">, WithStaticArgs["-c"]>
| StreamToStdout
};
error[E0277]: [CGP-E001] the trait bound `…::TokioAsyncReadStream<…::ChildOutputStream>: AsRef<[u8]>` is not satisfied
= note: root cause: [CGP-E117] the trait bound `…::TokioAsyncReadStream<…::ChildOutputStream>: AsRef<[u8]>` is not satisfied

Fix: insert StreamToBytes between the two stages. With it, the program compiles and prints 6, the byte count of hello and its newline.

A stage with a dispatcher reports the entry it lacks. Removing BytesToHex from http_checksum_native leaves the raw digest flowing into StreamToStdout:

pub type Program = hypershell! {
StreamingHttpRequest<GetMethod, FieldArg<"url">, WithHeaders[ ]>
| Checksum<Sha256>
| StreamToStdout
};
error[E0277]: [CGP-E001] missing entry for `@HandlerComponent.StreamToStdout.GenericArray<u8, …>` in provider `hypershell_tokio_components::providers::async_read::HandleToTokioAsyncRead`
= note: root cause: [CGP-E114] missing entry for `@HandlerComponent.StreamToStdout.GenericArray<u8, …>` in provider `hypershell_tokio_components::providers::async_read::HandleToTokioAsyncRead`

The path names the syntax and then the input type, which is exactly what the dispatcher could not match; see streams and input dispatch. Fix: convert the value into one of the types the dispatcher accepts, here with BytesToHex. The same form appears for an input the caller passes: StreamingExec given a &'static str reports a missing @HandlerComponent.StreamingExec<…>.&str entry, and the fix is to pass a String or a Vec<u8>.

A syntax has no route​

A syntax that no route reaches fails at the missing route, even when a provider for it exists. Checksum has a provider in the hash crate, but HypershellNamespace does not route it, so a program using it fails on HypershellCli:

pub type Program = hypershell! {
StreamingExec<StaticArg<"cat">, WithStaticArgs["Cargo.toml"]>
| Checksum<Sha256>
};
error[E0277]: [CGP-E001] missing wiring for `PathCons<…>` on `HypershellCli`
= note: root cause: [CGP-E113] missing wiring for `PathCons<…>` on `HypershellCli`

The message names the route as the type-level path the lookup follows, PathCons<…>, with the Checksum segment inside it. WebSocket fails the same way on such a context. Fix: add the route, either on a namespace that inherits HypershellNamespace, as http_checksum_native joins, or as an entry beside the context's namespace statement, as bluesky_websocket adds.

A raised error type has no route​

A provider raises an error type the namespace does not know. This custom stage raises TooLong when its input is longer than 16 bytes:

use cgp::extra::handler::Handler;
use hypershell::namespaces::HypershellNamespace;
use hypershell::prelude::*;

pub struct CheckLength;

#[derive(Debug)]
pub struct TooLong;

#[cgp_impl(new HandleCheckLength)]
#[uses(CanRaiseError<TooLong>)]
#[use_type(HasErrorType.Error)]
impl<Input> Handler<CheckLength, Input>
where
Input: Send + AsRef<[u8]>,
{
type Output = Input;

async fn handle(&self, _code: PhantomData<CheckLength>, input: Input) -> Result<Input, Error> {
if input.as_ref().len() > 16 {
return Err(Self::raise_error(TooLong));
}
Ok(input)
}
}

pub struct App;

delegate_components! {
App {
namespace HypershellNamespace;
@cgp.extra.handler.HandlerComponent.CheckLength: HandleCheckLength,
}
}
error[E0277]: [CGP-E001] missing wiring for `@cgp.core.error.ErrorRaiserComponent.TooLong` on `App`
= note: root cause: [CGP-E113] missing wiring for `@cgp.core.error.ErrorRaiserComponent.TooLong` on `App`

The provider requires the context to raise TooLong into its error type, and HypershellNamespace routes only the error types the base language raises. Fix: route the new type to a way of converting it, beside the namespace statement:

@cgp.core.error.ErrorRaiserComponent.TooLong: DebugAnyhowError,

DebugAnyhowError, from cgp_error_anyhow, formats any Debug value into the anyhow::Error the namespace uses, and RaiseAnyhowError converts a type that implements std::error::Error. The path names ErrorRaiserComponent, so it must be imported from cgp::core::error. The idea behind the routes is CGP's modular error handling.

A routed provider does not implement Handler​

A route that exists can still lead to a provider of the wrong kind, as when a syntax is routed straight to a synchronous Computer provider. Here App routes a custom Shout syntax to ShoutText:

use cgp::extra::handler::Computer;

pub struct Shout;

#[cgp_impl(new ShoutText)]
impl<Code> Computer<Code, String> {
type Output = String;

fn compute(&self, _code: PhantomData<Code>, input: String) -> String {
input.to_uppercase()
}
}

delegate_components! {
App {
namespace HypershellNamespace;
@cgp.extra.handler.HandlerComponent.Shout: ShoutText,
}
}
error[E0277]: [CGP-E001] `ShoutText` is not a provider of `Handler`
= note: root cause: [CGP-E115] `ShoutText` is not a provider of `Handler`

Fix: lift the provider into a handler, as Promote<PromoteAsync<ShoutText>>, with both imported from cgp::extra::handler. PromoteAsync makes the synchronous computer an asynchronous one, and Promote makes that a Handler. Hypershell wires its own ConvertTo syntax the same way.

Rebinding a syntax conflicts​

An entry for a syntax the namespace already routes conflicts with the namespace:

delegate_components! {
MyApp {
namespace HypershellNamespace;
@cgp.extra.handler.HandlerComponent.<Path, Args> SimpleExec<Path, Args>: FakeSimpleExec,
}
}
error[E0119]: [CGP-E011] conflicting wiring: `MyApp` wires `@cgp.extra.handler.HandlerComponent.SimpleExec<Path, Args>`, which `HypershellNamespace` already covers

A namespace that inherits HypershellNamespace and binds the same path fails in the same way. Fix: there is no wiring-only fix, because a namespace's bindings cannot be overridden. Choose the provider in the program instead, with Use<FakeSimpleExec, SimpleExec<…>>, which runs the named provider for that one stage, or write a namespace of your own that routes every syntax itself. The namespaces page explains why a shared namespace's choices cannot be overridden.

The macro cannot find its names​

A program written with hypershell! can fail with "cannot find macro Product in this scope" or "cannot find type Pipe in this scope". The message comes from the macro rather than from the wiring, and does not mention CGP. It means the prelude is not imported: the macro writes Pipe, Product!, and Symbol! without qualifying them, so they must be in scope. Fix: import hypershell::prelude::*.

Where to go next​


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.