Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Error Handling

All fallible functions in rust-meth-lib return rust_meth_lib::Result<T>, a type alias over a single [RustMethError] enum. This makes it easy to propagate errors with ? in your own code, and to convert them into your application’s own error type when you need custom messages or behaviour.

RustMethError variants

VariantCause
RustAnalyzerNotFoundrust-analyzer not on PATH or in rustup component directory
TypeNotFoundThe probed type doesn’t exist or isn’t in scope
FeatureGatedType exists but requires a feature flag not enabled in the probe
Timeoutrust-analyzer failed to respond within the retry budget
IoOS or filesystem error
JsonJSON serialization or deserialization failure
UnexpectedResponseShapeStructurally valid JSON but missing expected fields
RecvExhaustedMessage loop hit its limit without matching a response

Custom error types

The most common embedding pattern is wrapping RustMethError in your own thiserror enum. Since RustMethError implements std::error::Error, it converts with ? directly, but a manual From impl lets you intercept specific variants for custom messages before falling through to a generic wrapper for everything else.

The example below intercepts RustAnalyzerNotFound and TypeNotFound to give actionable error messages, while passing everything else through as a generic QueryFailed.

custom_error.rs

use rust_meth_lib::analyzer::{find_rust_analyzer, query_methods};
use rust_meth_lib::error::RustMethError;

// -- Your application's error type --

#[derive(Debug, thiserror::Error)]
enum AppError {
    /// rust-analyzer isn't installed, give a helpful message.
    #[error("rust-analyzer not found. Install it with: rustup component add rust-analyzer")]
    RustAnalyzerMissing,

    /// The type the user asked about doesn't exist.
    #[error(
        "Unknown type `{type_name}`. Check the spelling and that any required crate is listed in deps."
    )]
    UnknownType { type_name: String },

    /// Anything else from the library becomes a generic query failure.
    #[error("LSP query failed: {0}")]
    QueryFailed(RustMethError),
}

// -- Conversion --
//
// We can't use `#[from]` for everything because we want to intercept specific
// variants. Instead, write a manual `From` impl that matches the cases we care
// about and falls through to the generic wrapper for everything else.

impl From<RustMethError> for AppError {
    fn from(err: RustMethError) -> Self {
        match err {
            RustMethError::RustAnalyzerNotFound => Self::RustAnalyzerMissing,
            RustMethError::TypeNotFound { type_name, .. } => Self::UnknownType { type_name },
            other => Self::QueryFailed(other),
        }
    }
}

// -- Application logic --

fn lookup(type_name: &str) -> Result<(), AppError> {
    // find_rust_analyzer() returns RustMethError::RustAnalyzerNotFound on
    // failure, which our From impl converts to AppError::RustAnalyzerMissing.
    let ra_path = find_rust_analyzer()?;

    // query_methods() returns RustMethError::TypeNotFound for bad type names,
    // which our From impl converts to AppError::UnknownType.
    let methods = query_methods(type_name, &ra_path, None)?;

    println!("{type_name}: {} methods", methods.len());
    for m in methods.iter().take(5) {
        println!("  {}", m.name);
    }
    if methods.len() > 5 {
        println!("  ...and {} more", methods.len() - 5);
    }
    Ok(())
}

fn main() {
    // Use a type that will succeed.
    match lookup("Vec<u8>") {
        Ok(()) => {}
        Err(e) => eprintln!("error: {e}"),
    }

    println!();

    // Use a type that will fail with `TypeNotFound`, demonstrates the
    // custom error message path.
    match lookup("NonExistentType") {
        Ok(()) => {}
        Err(AppError::UnknownType { type_name }) => {
            eprintln!("Type not found: `{type_name}`");
            eprintln!("Tip: check spelling, or pass deps for third-party crates.");
        }
        Err(e) => eprintln!("error: {e}"),
    }
}

Output

Vec<u8>: 229 methods
  align_to
  align_to_mut
  allocator
  append
  array_windows
  ...and 224 more

Type not found: `NonExistentType`
Tip: check spelling, or pass deps for third-party crates.