Struct IoError

#[non_exhaustive]
pub struct IoError {
    pub kind: ErrorKind,
    pub span: Span,
    pub path: Option<PathBuf>,
    pub additional_context: Option<AdditionalContext>,
    pub location: Option<String>,
}

Represents an I/O error in the ShellError::Io variant.

This is the central I/O error for the ShellError::Io variant. It represents all I/O errors by encapsulating ErrorKind, an extension of std::io::ErrorKind. The span indicates where the error occurred in user-provided code. If the error is not tied to user-provided code, the location refers to the precise point in the Rust code where the error originated. The optional path provides the file or directory involved in the error. If ErrorKind alone doesn’t provide enough detail, additional context can be added to clarify the issue.

For handling user input errors (e.g., commands), prefer using new. Alternatively, use the factory method to simplify error creation in repeated contexts. For internal errors, use new_internal to include the location in Rust code where the error originated.

Examples

User Input Error

use std::path::PathBuf;

let path = PathBuf::from("/some/missing/file");
let error = IoError::new(
    std::io::ErrorKind::NotFound,
    span,
    path
);
println!("Error: {:?}", error);

Internal Error

let error = IoError::new_internal(
    std::io::ErrorKind::UnexpectedEof,
    "Failed to read data from buffer",
    nu_protocol::location!()
);
println!("Error: {:?}", error);

Using the Factory Method

use std::path::PathBuf;

let path = PathBuf::from("/some/file");
let from_io_error = IoError::factory(span, Some(path.as_path()));

let content = std::fs::read_to_string(&path).map_err(from_io_error)?;

ShellErrorBridge

The ShellErrorBridge struct is used to contain a ShellError inside a std::io::Error. This allows seamless transfer of ShellError instances where std::io::Error is expected. When a ShellError needs to be packed into an I/O context, use this bridge. Similarly, when handling an I/O error that is expected to contain a ShellError, use the bridge to unpack it.

This approach ensures clarity about where such container transfers occur. All other I/O errors should be handled using the provided constructors for IoError. This way, the code explicitly indicates when and where a ShellError transfer might happen.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

kind: ErrorKind

The type of the underlying I/O error.

std::io::ErrorKind provides detailed context about the type of I/O error that occurred and is part of std::io::Error. If a kind cannot be represented by it, consider adding a new variant to ErrorKind.

Only in very rare cases should std::io::ErrorKind::Other be used, make sure you provide additional_context to get useful errors in these cases.

span: Span

The source location of the error.

path: Option<PathBuf>

The path related to the I/O error, if applicable.

Many I/O errors involve a file or directory path, but operating system error messages often don’t include the specific path. Setting this to Some allows users to see which path caused the error.

additional_context: Option<AdditionalContext>

Additional details to provide more context about the error.

Only set this field if it adds meaningful context. If ErrorKind already contains all the necessary information, leave this as None.

location: Option<String>

The precise location in the Rust code where the error originated.

This field is particularly useful for debugging errors that stem from the Rust implementation rather than user-provided Nushell code. The original Location is converted to a string to more easily report the error attributing the location.

This value is only used if span is Span::unknown() as most of the time we want to refer to user code than the Rust code.

Implementations

impl IoError

pub fn new( kind: impl Into<ErrorKind>, span: Span, path: impl Into<Option<PathBuf>>, ) -> IoError

Creates a new IoError with the given kind, span, and optional path.

This constructor should be used in all cases where the combination of the error kind, span, and path provides enough information to describe the error clearly. For example, errors like “File not found” or “Permission denied” are typically self-explanatory when paired with the file path and the location in user-provided Nushell code (span).

Constraints

If span is unknown, use:

• new_internal if no path is available.
• new_internal_with_path if a path is available.

pub fn new_with_additional_context( kind: impl Into<ErrorKind>, span: Span, path: impl Into<Option<PathBuf>>, additional_context: impl ToString, ) -> IoError

Creates a new IoError with additional context.

Use this constructor when the error kind, span, and path are not sufficient to fully explain the error, and additional context can provide meaningful details. Avoid redundant context (e.g., “Permission denied” for an error kind of ErrorKind::PermissionDenied).

Constraints

If span is unknown, use:

• new_internal if no path is available.
• new_internal_with_path if a path is available.

pub fn new_internal( kind: impl Into<ErrorKind>, additional_context: impl ToString, location: Location, ) -> IoError

Creates a new IoError for internal I/O errors without a user-provided span or path.

This constructor is intended for internal errors in the Rust implementation that still need to be reported to the end user. Since these errors are not tied to user-provided Nushell code, they generally have no meaningful span or path.

Instead, these errors provide:

• additional_context: Details about what went wrong internally.
• location: The location in the Rust code where the error occurred, allowing us to trace and debug the issue. Use the nu_protocol::location! macro to generate the location information.

Examples

use nu_protocol::shell_error::io::IoError;

let error = IoError::new_internal(
    std::io::ErrorKind::UnexpectedEof,
    "Failed to read from buffer",
    nu_protocol::location!(),
);

pub fn new_internal_with_path( kind: impl Into<ErrorKind>, additional_context: impl ToString, location: Location, path: PathBuf, ) -> IoError

Creates a new IoError for internal I/O errors with a specific path.

This constructor is similar to new_internal but also includes a file or directory path relevant to the error. Use this function in rare cases where an internal error involves a specific path, and the combination of path and additional context is helpful.

Examples

use std::path::PathBuf;
use nu_protocol::shell_error::io::IoError;

let error = IoError::new_internal_with_path(
    std::io::ErrorKind::NotFound,
    "Could not find special file",
    nu_protocol::location!(),
    PathBuf::from("/some/file"),
);

pub fn factory<'p, P>(span: Span, path: P) -> impl Fn(Error) + use<'p, P>

where P: Into<Option<&'p Path>>,

Creates a factory closure for constructing IoError instances from std::io::Error values.

This method is particularly useful when you need to handle multiple I/O errors which all take the same span and path. Instead of calling .map_err(|err| IoError::new(err.kind(), span, path)) every time, you can create the factory closure once and pass that into .map_err.

Trait Implementations

impl Clone for IoError

fn clone(&self) -> IoError

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for IoError

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

Formats the value using the given formatter.

impl Diagnostic for IoError

fn code<'a>(&'a self) -> Option<Box<dyn Display + 'a>>

Unique diagnostic code that can be used to look up more information about this Diagnostic. Ideally also globally unique, and documented in the toplevel crate’s documentation for easy searching. Rust path format (foo::bar::baz) is recommended, but more classic codes like E0123 or enums will work just fine.

fn help<'a>(&'a self) -> Option<Box<dyn Display + 'a>>

Additional help text related to this Diagnostic. Do you have any advice for the poor soul who’s just run into this issue?

fn labels(&self) -> Option<Box<dyn Iterator<Item = LabeledSpan> + '_>>

Labels to apply to this Diagnostic’s Diagnostic::source_code

fn diagnostic_source(&self) -> Option<&dyn Diagnostic>

The cause of the error.

fn source_code(&self) -> Option<&dyn SourceCode>

Source code to apply this Diagnostic’s Diagnostic::labels to.

fn severity(&self) -> Option<Severity>

Diagnostic severity. This may be used by ReportHandlers to change the display format of this diagnostic.

fn url<'a>(&'a self) -> Option<Box<dyn Display + 'a>>

URL to visit for a more detailed explanation/help about this Diagnostic.

fn related<'a>( &'a self, ) -> Option<Box<dyn Iterator<Item = &'a dyn Diagnostic> + 'a>>

Additional related Diagnostics.

impl Display for IoError

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

Formats the value using the given formatter.

impl Error for IoError

fn source(&self) -> Option<&(dyn Error + '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.

impl From<IoError> for ShellError

fn from(value: IoError) -> ShellError

Converts to this type from the input type.

impl PartialEq for IoError

fn eq(&self, other: &IoError) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for IoError