Crate format_serde_error

Serde error messages for humans.

Format serde errors in a way to make it obvious where the error in the source file was.

Example:

use format_serde_error::SerdeError;

#[derive(Debug, serde::Serialize, serde::Deserialize)]
struct Config {
    values: Vec<String>,
}

fn parse_config() -> Result<Config, anyhow::Error> {
  let config_str = "values:
  - 'first'
  - 'second'
  - third:";

  let config = serde_yaml::from_str::<Config>(config_str)
    .map_err(|err| SerdeError::new(config_str.to_string(), err))?;

  Ok(config)
}

The output will be:

Error:
   | values:
   |   - 'first'
   |   - 'second'
 4 |   - third:
   |           ^ values[2]: invalid type: map, expected a string at line 4 column 10

Context Behavior

By default the crate will show preceding and following lines (default CONTEXT_LINES_DEFAULT).

By default the crate will also shorten long lines if needed and only show a certain amount of context instead (default CONTEXT_CHARACTERS_DEFAULT). A long line means that the line is longer than context_characters * 2 + 1. Which means that a long line is longer than the context that should be shown on either side of the error plus the error itself.

To change the behavior there are the following functions:

• set_default_contextualize: Enable or disable contextualization. When false the crate will show no context lines and keep the error line as is even if its very long. This can also be changed for a single error using SerdeError::set_contextualize.

• set_default_context_lines: Set the amount of context lines that should be shown. For example if the amount of context is set to 5 the crate will print 5 lines before the error and 5 lines after the error if possible. This can also be changed for a single error using SerdeError::set_context_lines.

• set_default_context_characters: Set the amount of characters shown before and after a error when a line is shortened. For example if the amount of context ist set to 30 the create will print 30 characters before the error column and 30 characters after the error column if possible. This can also be changed for a single error using SerdeError::set_context_characters.

Crate Features

serde_yaml

Enabled by default: yes

Enables support for errors emitted by serde_yaml. Enables the implementation to convert serde_yaml::Error to SerdeError using the From trait. Also extends the ErrorTypes enum by ErrorTypes::Yaml.

serde_json

Enabled by default: yes

Enables support for errors emitted by serde_json. Enables the implementation to convert serde_json::Error to SerdeError using the From trait. Also extends the ErrorTypes enum by ErrorTypes::Json.

colored

Enabled by default: yes

Enables support for color output to a terminal using the colored crate. Also enables the functions always_color, never_color, set_coloring_mode, use_environment and the enum ColoringMode which allow changing the behavior of colored.

graphemes_support

Enabled by default: yes

Enables proper support for grapheme cluster when contextualizing long error lines. Without this feature the crate will just split the line using std::str::Chars. This can mean that certain error messages won’t get formatted properly when a string contains unicode grapheme clusters. You can check the test test::context_long_line::graphemes_string for an example.

Structs

SerdeError

Struct for formatting the error together with the source file to give a nicer output.

Enums

ColoringMode

Different behaviors for the crate to allow overriding the colored output behaviors. Creating the environment variable NO_COLOR (value is not relevant) will disable all coloring. There is also some detection going on to decide what kind of terminal type is used and if coloring should be used or not. See colored::control for more information.

ErrorTypes

Contains the error that will be used by SerdeError to format the output. For this to work the error needs to support emitting the line and column of the error. We are implementing Into for some common types. If a error type is not implemented yet the ErrorTypes::Custom can be used instead.

Constants

CONTEXTUALIZE_DEFAULT

If the output should be contextualized or not.

CONTEXT_CHARACTERS_DEFAULT

Amount of characters to show before and after the column containing the error.

CONTEXT_LINES_DEFAULT

Amount of lines to show before and after the line containing the error.

Functions

always_color

Set coloring mode to never use color in the output (ColoringMode::NeverColor).

get_default_context_characters

Get the current default amount of context characters shown. Default amount of context is CONTEXT_CHARACTERS_DEFAULT.

get_default_context_lines

Get the current default amount of context lines shown. Default amount of context is CONTEXT_LINES_DEFAULT.

get_default_contextualize

Get the current default if contextualization should be enabled or not. Default value is CONTEXTUALIZE_DEFAULT.

never_color

Set coloring mode to always use color in the output (ColoringMode::AlwaysColor).

set_coloring_mode

Change coloring mode across the library. See ColoringMode for more information. By default the library will detect if the output should use color or not ColoringMode::UseEnvironment.

set_default_context_characters

Set the default amount of context characters shown. Default amount of context is CONTEXT_CHARACTERS_DEFAULT. If you want to change the amount context shown for a single error use SerdeError::set_context_characters instead.

set_default_context_lines

Set the default amount of context lines shown. Default amount of context is CONTEXT_LINES_DEFAULT. If you want to change the amount of context shown for a single error use SerdeError::set_context_lines instead.

set_default_contextualize

Set the default if contextualization should be enabled or not. Default value is CONTEXTUALIZE_DEFAULT. If you want to change the amount of context shown for a single error use SerdeError::set_contextualize instead.

use_environment

Set coloring mode detect if color should be used in the output or not (ColoringMode::UseEnvironment).