Crate shrub_core 

The shell itself: the Shell type and everything that runs a script, for programs that embed shrub or build a front end on it.

shrub-core sits between shrub_parser, which turns text into a syntax tree, and the crates that add builtins or a line editor on top. It owns variables, expansion, redirection, jobs, traps, and programmable completion. It has no line editor or prompt drawing of its own.

Quick start

Build a Shell with Shell::builder, then run text with Shell::run_string. The shell keeps its variables, functions, and working directory between calls.

use shrub_core::{Error, Shell, SourceInfo};

let mut shell = Shell::builder().build().await?;

let result = shell
    .run_string(
        "name=world; greet() { echo \"Hello, $1!\"; }; greet \"$name\"",
        &SourceInfo::default(),
        &shell.default_exec_params(),
    )
    .await?;

assert!(result.is_success());
assert_eq!(shell.env_str("name").as_deref(), Some("world"));

A failed parse or an error the shell cannot continue past comes back as Error. A command that exits non-zero is not an error: it is an ExecutionResult whose exit code you inspect.

Builtins

A new shell has no builtins registered. Add them while building, with ShellBuilder::builtin, or later with Shell::register_builtin. Use builtins::builtin to register a type that implements builtins::Command, or builtins::simple_builtin for a builtins::SimpleCommand. The shrub-builtins crate registers the standard set this way.

Customizing a shell

Shell is generic over ShellExtensions, which swaps in parts of the shell’s behavior at compile time; today that is how errors are formatted. Create such a shell with Shell::builder_with_extensions.

Parsing

The syntax tree types are re-exported in parser. Shell::parse_string parses with the options the shell currently has set.

Cargo features

Feature	Effect
serde	Implements Serialize and Deserialize for the syntax tree and other data types, through the same feature of shrub-parser.
experimental-parser	Makes the winnow-based parser available through parser::ParserImpl, by enabling shrub-parser’s winnow-parser feature.

Re-exports

pub use commands::CommandArg;

pub use commands::ExecutionContext;

pub use error::BuiltinError;

pub use error::Error;

pub use error::ErrorKind;

pub use extensions::ShellExtensions;

pub use results::ExecutionControlFlow;

pub use results::ExecutionExitCode;

pub use results::ExecutionResult;

pub use results::ExecutionSpawnResult;

pub use sourceinfo::SourceInfo;

pub use variables::ShellValue;

pub use variables::ShellVariable;

Modules

arithmetic

Arithmetic evaluation

builtins

Facilities for implementing and managing builtins

callstack

Call stack representations.

commands

Command execution

completion

Implements programmable command completion support.

env

Implements a shell variable environment.

error

Error facilities

escape

String escaping utilities

expansion

Word expansion utilities.

extensions

Definition of shell behavior traits and defaults.

functions

Structures for managing function registrations and calls.

history

Facilities for tracking and persisting the shell’s command history.

int_utils

Generic utilities.

interfaces

Exports traits for shell interfaces implemented by callers.

jobs

Job management

namedoptions

Defines shell options.

openfiles

Managing files open within a shell instance.

options

Defines runtime options for the shell.

parser

Re-export parser types used in core definitions.

pathcache

Path cache

pathsearch

Path searching utilities.

patterns

Shell patterns

processes

Process management

results

Encapsulation of execution results.

sourceinfo

Source info.

sys

Platform abstraction facilities

tasks

Tasks the shell runs concurrently with itself.

terminal

Terminal control utilities.

tests

Shell test conditional expressions

timing

Command timing

trace_categories

Trace utilities

traps

Facilities for configuring trap handlers.

variables

Implements variables for a shell environment.

Structs

CreateOptions

Options for creating a new shell.

ExecutionParameters

Parameters for execution.

SavedCommandStatus

Snapshot of the state the last command left behind: $?, PIPESTATUS, and $_.

Shell

Represents an instance of a shell.

ShellBuilder

Builder for Shell

SourcePosition

Represents a position in source text.

SourcePositionOffset

Represents an offset in source text.

SourceSpan

Represents a span within source text.

Enums

ProcessGroupPolicy

Policy for how to manage spawned external processes.

ProfileLoadBehavior

Behavior for loading profile files.

RcLoadBehavior

Behavior for loading rc files.

Traits

ShellBuilderState

Builder’s type state specifies if members are set or not (unset).

ShellState

A dyn-safe trait for constrained access to shell state.

Type Aliases

ShellFd

Type alias for shell file descriptors.