Rename CtxError to NeuErr and implement colored format

Author: Flix

Cargo.lock

@@ -17,13 +17,16 @@ exclude = ["/.github"]
 default = ["std", "send", "sync"]
 # Use the standard library.
 # Provides interaction with `ExitCode` termination.
-std = []
+std = ["yansi?/std", "yansi?/detect-tty", "yansi?/detect-env"]
 # Error types must be `Send`.
 send = []
 # Error types must be `Sync`.
 sync = ["send"]
+# Enable colored error formatting. See `yansi` create documentation on how to control enable/disable colors.
+colors = ["dep:yansi"]
 
 [dependencies]
+yansi = { version = "1.0.1", optional = true, default-features = false, features = ["alloc"] }
 
 [dev-dependencies]
 regex = { version = "1.12.2", default-features = false, features = ["unicode", "perf"] }

Cargo.toml

@@ -71,6 +71,18 @@ command = "cargo"
 args = ["clippy", "--workspace", "--all-targets", "--no-default-features", "--features", "std,send,sync", "--", "-D", "warnings"]
 dependencies = ["install-rust-toolchain"]
 
+[tasks.clippy-colors]
+install_crate = false
+command = "cargo"
+args = ["clippy", "--workspace", "--all-targets", "--features", "colors", "--", "-D", "warnings"]
+dependencies = ["install-rust-toolchain"]
+
+[tasks.clippy-colors-no-std]
+install_crate = false
+command = "cargo"
+args = ["clippy", "--workspace", "--all-targets", "--no-default-features", "--features", "colors", "--", "-D", "warnings"]
+dependencies = ["install-rust-toolchain"]
+
 [tasks.clippy-all]
 install_crate = false
 command = "cargo"
@@ -86,6 +98,8 @@ dependencies = [
 	"clippy-no-send-sync",
 	"clippy-send",
 	"clippy-send-sync",
+	"clippy-colors",
+	"clippy-colors-no-std",
 	"clippy-all",
 ]
 

Makefile.toml

@@ -19,6 +19,8 @@ An error handling library designed to be:
 - Works with std and no-std, but requires a global allocator. [See example](examples/embedded-no-std.rs).
 - Compatible with non-Send/Sync environments, but also with Send/Sync environments (per feature flag).
 - Out of the box source error chaining.
+- No dependencies by default. Optional features may lead to some dependencies.
+- No `unsafe` used (yet?).
 
 ## Why a new (German: neuer) error library?
 
@@ -44,7 +46,7 @@ provided_attachments!(
 );
 
 fn do_something_internal() -> Result<()> {
-  Err(CtxError::new("Error occurred internally")
+  Err(NeuErr::new("Error occurred internally")
     .attach(Retryable::No))
 }
 
@@ -68,6 +70,20 @@ fn main() {
 
 Run `cargo add neuer-error` to add the library to your project.
 
+## Comparisons
+
+### Anyhow / Eyre
+
+- `NeuErr` provides a meechanism to discover and retrieve multiple items of typed context information, while `anyhow` can `downcast` to its source error types only.
+- `NeuErr` captures source locations instead of backtraces by default, which is more efficient and works without debug info. I personally also find it easier to read.
+
+### Thiserror / Snafu
+
+- `NeuErr` is a single error type for all errors, so no need for boilerplate, better ergonomics, but less type safety and flexibility.
+- `NeuErr` captures source location automatically, which `thiserror` does not and `snafu` does only when you add the location field to every error variant.
+- `NeuErr` prints the full (source) error chain already.
+- `NeuErr` does not have procedural macros.
+
 ## Development
 
 If you want to contribute or have questions, feel free to open issues :)

README.md

@@ -14,11 +14,11 @@ use ::core::{
 	ptr::null_mut,
 	sync::atomic::{AtomicUsize, Ordering},
 };
-use ::neuer_error::{CtxError, Result, traits::*};
+use ::neuer_error::{NeuErr, Result, traits::*};
 
 
 fn self_test() -> Result<()> {
-	Err(CtxError::new("Memory error"))
+	Err(NeuErr::new("Memory error"))
 }
 
 fn boot_up() -> Result<()> {

examples/embedded-no-std.rs

@@ -8,15 +8,15 @@
 
 use ::neuer_error::Result;
 
-use self::library::CtxErrorAttachments;
+use self::library::NeuErrAttachments;
 
 /// Library creators need to think about what information would be interesting for humans and what
 /// machine information is necessary to handle errors programmatically.
 ///
 /// When providing attachments, library authors should make use of the `provided_attachments!`
 /// macro!
 mod library {
-	use ::neuer_error::{CtxError, Result, provided_attachments, traits::*};
+	use ::neuer_error::{NeuErr, Result, provided_attachments, traits::*};
 
 	/// Kinds of errors that are interesting to match on for library users.
 	/// If it is only interesting to humans, it can be iin the context instead.
@@ -44,7 +44,7 @@ mod library {
 
 	/// Implement your errors while attaching machine-targeted information.
 	fn do_something_internal() -> Result<()> {
-		Err(CtxError::new("Error occurred internally")
+		Err(NeuErr::new("Error occurred internally")
 			.attach(ErrorKind::InvalidInput)
 			.attach(Retryable::No))
 	}

examples/library.rs

@@ -6,7 +6,7 @@
 	reason = "Example"
 )]
 
-use ::neuer_error::{CtxError, Result, provided_attachments, traits::*};
+use ::neuer_error::{NeuErr, Result, provided_attachments, traits::*};
 
 /// The usual error message contains code file locations, so it is not always suitable for UI
 /// errors. We can simply attach user friendly messages to the errors and still keep debuggable
@@ -23,7 +23,7 @@ provided_attachments!(
 struct MyUser;
 
 fn fetch_user() -> Result<MyUser> {
-	Err(CtxError::new("Failed!").attach(UserErrorMessage("Invalid user ID 5".to_owned())))
+	Err(NeuErr::new("Failed!").attach(UserErrorMessage("Invalid user ID 5".to_owned())))
 }
 
 fn save_user(_user: MyUser) -> Result<()> {

examples/non-dev-user.rs

@@ -6,25 +6,25 @@
 	reason = "Example"
 )]
 
-use ::neuer_error::{CtxError, Result, traits::*};
+use ::neuer_error::{NeuErr, Result, traits::*};
 use ::std::process::ExitCode;
 
 fn ensure_project_validity() -> Result<()> {
 	Ok(())
 }
 
 fn call_preprocessor() -> Result<()> {
-	Err(CtxError::new("Binary gcc not found"))
+	Err(NeuErr::new("Binary gcc not found"))
 }
 
 fn compile_my_code() -> Result<()> {
-	ensure_project_validity().context("project must be valid for compiling")?;
-	call_preprocessor().context("preprocessor failed")?;
+	ensure_project_validity().context("Project must be valid for compiling")?;
+	call_preprocessor().context("Üreprocessor failed")?;
 	Ok(())
 }
 
 fn lint() -> Result<()> {
-	Err(CtxError::new("Warning: something is deprecated").attach_override(ExitCode::SUCCESS))
+	Err(NeuErr::new("Warning: something is deprecated").attach_override(ExitCode::SUCCESS))
 }
 
 // Returning the error will automatically use the attached ExitCode or assume failure.

examples/tool-cli.rs

@@ -6,7 +6,7 @@
 	reason = "Example"
 )]
 
-use ::neuer_error::{CtxError, Result, traits::*};
+use ::neuer_error::{NeuErr, Result, traits::*};
 
 struct UserData {
 	id: u64,
@@ -15,14 +15,14 @@ struct UserData {
 }
 
 fn validate_id(id: u64) -> Result<()> {
-	if id == 0 { Err(CtxError::new("ID must be non-zero")) } else { Ok(()) }
+	if id == 0 { Err(NeuErr::new("ID must be non-zero")) } else { Ok(()) }
 }
 
 fn validate_name(name: &str) -> Result<()> {
 	if name.trim().is_empty() {
-		Err(CtxError::new("Name must not be empty"))
+		Err(NeuErr::new("Name must not be empty"))
 	} else if !name.chars().all(|c| c.is_alphabetic()) {
-		Err(CtxError::new("Name must only contain alphabetic characters"))
+		Err(NeuErr::new("Name must only contain alphabetic characters"))
 	} else {
 		Ok(())
 	}
@@ -35,19 +35,19 @@ struct User {
 }
 
 impl User {
-	fn new(data: UserData) -> Result<Self, Vec<CtxError>> {
+	fn new(data: UserData) -> Result<Self, Vec<NeuErr>> {
 		let mut errors = Vec::new();
 		let UserData { id, name, balance } = data;
 
 		validate_id(id).or_collect(&mut errors);
 		validate_name(&name).or_collect(&mut errors);
 
 		if balance < 0 {
-			errors.push(CtxError::new("Cannot create new user with debt"));
+			errors.push(NeuErr::new("Cannot create new user with debt"));
 		}
 
 		if id == 3 {
-			errors.push(CtxError::new(format!("User {id} ({name}) already exists")));
+			errors.push(NeuErr::new(format!("User {id} ({name}) already exists")));
 		}
 
 		let user = User { id, name, balance };

examples/validation.rs

@@ -6,7 +6,7 @@
 	reason = "Example"
 )]
 
-use ::neuer_error::{CtxError, Result, provided_attachments, traits::*};
+use ::neuer_error::{NeuErr, Result, provided_attachments, traits::*};
 use ::std::time::Duration;
 
 /// Mark errors	whether they can be retried and/or were already retried.
@@ -41,15 +41,15 @@ fn fetch_data(user: &str) -> Result<()> {
 			std::io::ErrorKind::NetworkDown => ErrorStatus::Temporary,
 			_ => ErrorStatus::Permanent,
 		})
-		.context_with(|| format!("failed fetching data for user {user}"))?;
+		.context_with(|| format!("Failed fetching data for user {user}"))?;
 
 	// Alternative 2.
 	do_request(request).map_err(|err| {
 		let status = match err.kind() {
 			std::io::ErrorKind::NetworkDown => ErrorStatus::Temporary,
 			_ => ErrorStatus::Permanent,
 		};
-		CtxError::new_with_source(format!("failed fetching data for user {user}"), err)
+		NeuErr::new_with_source(format!("Failed fetching data for user {user}"), err)
 			.attach_override(status)
 	})
 }