Enable API's that consume &str to retrieve the text string from any LoadSource source while tracking the origin.

Terminology

This crate uses some terminology to help in disambiguation:

• "text" - an &str to be "processed" by application code; in contrast to &str used for other purposes such as naming the origin of a "text" or used in error messages.
• "source" - a [Source] value which tracks both a text and the name of its origin.

Example: [Parsable]

Suppose we have a config file parser which parses a configuration into a Config struct. We want to be able to either parse strings in memory or load and parse config files from disk, with error messages indicating the source:

use indoc::indoc; // For cleanly formatting test assertions.
use source_text::Parsable;

#[derive(Debug)]
pub struct Config {
    // ...
}

impl Parsable for Config {
    fn parse_text(text: &str) -> anyhow::Result<Self> {
        if text.is_empty() {
            Err(anyhow::Error::msg("empty input\n"))
        } else {
            todo!("implement an `&str` parser...");
        }
    }
}

let err1 = Config::parse_source("").err().unwrap();

assert_eq!(
    format!("{:?}", err1).trim_end(),
    indoc! {
    r#"
       Error in <input>:

       Caused by:
           empty input
    "#
    }.trim_end()
);

let configpath = std::path::Path::new("/__this_path_should_not_exist__");
let err2 = Config::parse_source(configpath).err().unwrap();

assert_eq!(
    format!("{:?}", err2).trim_end(),
    indoc! { r#"
        Error in "/__this_path_should_not_exist__":

        Caused by:
            No such file or directory (os error 2)
    "# }.trim_end(),
);

Example: process_text

If [Parsable] does not fit your usage, you can wrap any fn(&str) -> anyhow::Result<T> with [process_text]:

use indoc::indoc; // For cleanly formatting test assertions.

fn count_lines<S>(source: S) -> anyhow::Result<usize>
    where S: source_text::LoadSource,
{
    source_text::process_text(source, |text: &str| {
        Ok(text.lines().count())
    })
}

fn main() {
    let linecount = count_lines("Hello\nWorld!").unwrap();
    assert_eq!(2, linecount);

    let path = std::path::Path::new("/__this_path_should_not_exist__");
    let err = count_lines(path).err().unwrap();

    assert_eq!(
        format!("{:?}", err).trim_end(),
        indoc! { r#"
            Error in "/__this_path_should_not_exist__":

            Caused by:
                No such file or directory (os error 2)
        "# }.trim_end(),
    );
}