[][src]Crate idioma

As Rust developers we deeply care about safety and error handling - our programs are fast and reliable. However, users never make it easy for us: they misunderstand instructions and break things. When we catch them doing something they shouldn't be doing, we let them know (usually) with an error message.

Every command line tool prints handy messages to stdout from time to time, and to do so, requires a function or two. I noticed that whenever I start a new project I tend to copy the util.rs that contains those display functions from my last project. That is simply no good.

It means that my error messages

  • differ in style (since I regularly alter code in that util file);
  • don't look like idiomatic Rust messages;
  • require that COPY + PASTE operation for every new project.

And I strongly believe that I am not alone in this. Take a look at this code by brain-lang:

macro_rules! exit_with_error(
    ($($arg:tt)*) => { {
        use std::process;
        eprintln!($($arg)*);
        process::exit(1);
    } }
);

As you can see, they wrote this macro right next to the main function and it is the same problem that I have with my util file.

The idioma library solves all these problems forever. Here's how.

In your Cargo.toml file.

[dependencies]
idioma = "*"

Include in any Rust file.

extern crate idioma;

Use within a function.

use idioma::*;
fn foo(i: i32) {
    if i != 42 {
        error("Your taste is appalling.").exit(1);
    }
}

Structs

Text

Text is the main type that gets thrown around between functions and methods. It is basically a String, but it had to be made into a separate struct so that it would be possible to impl some things for it.

Functions

custom

Allows you to create and print messages with custom labels. Essentially, allows you to write your own functions like error, info, etc. that we already have here.

debug

Debug your code with style.

error

Returns a bright-red error message that draws attention.

exit_if_error

Somethimes you get a Result and you want to continue execution as normal if case it's Ok or exit if it's Err. This function allows you to do precisely that.

info

Returns a neutral info message.

into

Use into to turn any Result type with a displayable error into Result<O, idioma::Error>. This will allow you to use all methods and functions defined for idioma::Error without having to explicitly wrap errors from other libraries yourself.

success

Returns a green and shiny success message.

warning

Displays a warning.

Type Definitions

Error

Error type is an alias of the Text type that we use to denote errors specifically. The fact that this is an alias also means that it has access to all the methods that Text has.