Enum Error 

pub enum Error {
    EmptyProgramName,
    InvalidProgramName {
        program_name: String,
    },
    MissingHome,
    UnsupportedShell(Shell),
    PathHasNoParent {
        path: PathBuf,
    },
    InvalidTargetPath {
        path: PathBuf,
        reason: &'static str,
    },
    NonUtf8Path {
        path: PathBuf,
    },
    InvalidUtf8File {
        path: PathBuf,
    },
    ManagedBlockMissingEnd {
        path: PathBuf,
        start_marker: String,
        end_marker: String,
    },
    Failure(Box<FailureReport>),
    Io {
        action: &'static str,
        path: PathBuf,
        source: Error,
    },
}

Errors returned by shellcomp operations.

Recoverable operational failures that callers are expected to render are wrapped as Error::Failure with a crate::FailureReport. Lower-level variants represent immediate input validation or filesystem problems.

Variants

EmptyProgramName

The requested program name was empty.

InvalidProgramName

The requested program name contains unsupported path separators or reserved values.

Fields

program_name: String

The rejected program name.

MissingHome

HOME could not be resolved for an operation that requires it.

UnsupportedShell(Shell)

The requested shell is known to the API but not implemented yet.

PathHasNoParent

A target path did not contain a parent directory.

Fields

path: PathBuf

The invalid path.

InvalidTargetPath

A target path failed explicit validation for security or correctness reasons.

Fields

path: PathBuf

The rejected path.

reason: &'static str

Stable reason for failure classification.

NonUtf8Path

A path could not be represented as UTF-8 for shell wiring purposes.

Fields

path: PathBuf

The path that could not be encoded.

InvalidUtf8File

A managed text file contained invalid UTF-8.

Fields

path: PathBuf

The unreadable file path.

ManagedBlockMissingEnd

A managed block start marker was found without its matching end marker.

Fields

path: PathBuf

The file containing the broken managed block.

start_marker: String

The expected start marker.

end_marker: String

The expected end marker.

Failure(Box<FailureReport>)

A structured recoverable failure report intended for callers.

Match this variant when you need stable failure kinds, affected paths, or caller-facing recovery guidance without parsing a display string.

Io

A filesystem operation failed.

Most user-facing operational I/O failures are mapped to Error::Failure by the public APIs. This variant is still exposed because low-level helpers and validation paths may surface it directly.

Fields

action: &'static str

The operation being attempted.

path: PathBuf

The path involved in the operation.

source: Error

The underlying I/O error.

Implementations

impl Error

pub fn error_code(&self) -> &'static str

Returns a stable machine-readable error code.

pub const fn is_retryable(&self) -> bool

Returns whether a retry may succeed with changed environment or timing.

pub fn trace_id(&self) -> Option<u64>

Returns the operation-scoped trace id when this is a structured failure.

pub fn as_failure(&self) -> Option<&FailureReport>

Returns Some when the error is Error::Failure.

pub fn into_failure(self) -> Option<FailureReport>

Converts a Error::Failure into a plain FailureReport.

This is useful when callers need stable, structured failure data and prefer not to branch on internals in each match arm.

pub fn location(&self) -> Option<&Path>

Returns the most relevant filesystem location for this error, when one exists.

For Error::Failure, this returns the report’s primary target_path. Use crate::FailureReport::affected_locations when you need the full set of related paths.

Examples

use shellcomp::Error;

let error = Error::InvalidProgramName {
    program_name: "bad/name".to_owned(),
};

assert_eq!(error.location(), None);

pub fn reason(&self) -> Option<&str>

Returns a human-readable failure reason intended for caller-side rendering.

This is suitable for logs or CLI output, but callers that need stable branching should prefer matching Error::Failure and reading crate::FailureReport::kind.

Examples

use shellcomp::Error;

let error = Error::MissingHome;
assert!(error.reason().is_some());

pub fn next_step(&self) -> Option<&str>

Returns a suggested next step for this error, when one exists.

This is primarily intended for CLI or UI layers that want to surface actionable guidance without inventing shell-specific recovery text themselves.

Examples

use shellcomp::Error;

let error = Error::PathHasNoParent {
    path: "/".into(),
};

assert!(error.next_step().is_some());

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn StdError + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.