Struct Input

Source

pub struct Input { /* private fields */ }

Available on crate features input-toml or input-yaml only.

Expand description

A named text, ready to parse and validate.

The name is usually the file’s path, and appears in every problem. Build one with Input::new_with_format for text in memory, or Input::open for a file. With input-yaml, Input::new and Input::read build a YAML one.

Implementations§

Source §

impl Input

Source

pub fn new(name: impl Into<String>, text: impl Into<String>) -> Self

Available on crate feature input-yaml only.

A YAML input from text already in memory, whatever the extension of name. Set another format with Input::format.

Source

pub fn new_with_format( name: impl Into<String>, text: impl Into<String>, format: Format, ) -> Self

An input of format from text already in memory, whatever the extension of name. It needs only format’s feature, so a build without YAML builds text in memory with it.

Source

pub fn read(path: &Path) -> Result<Self, InputError>

Available on crate feature input-yaml only.

Read a YAML file, named by its path, whatever its extension.

§Errors

An InputError with the I/O failure.

Source

pub fn open(path: &Path) -> Result<Self, InputError>

Read a file and take its Format from its extension, as Format::of does. The extension is checked before the file is read.

§Errors

An InputError for an extension Format::of refuses, or with the I/O failure.

Source

pub fn format(self, format: Format) -> Self

Set how the text is written, over what the constructor took.

Source

pub fn name(&self) -> &str

The name given at construction, usually the file’s path.

Source

pub fn text(&self) -> &str

The text as read, unchanged.

Source

pub fn frontmatter(&self) -> Option<(Self, &str)>

Available on crate feature input-yaml only.

Split YAML frontmatter from a Markdown body.

The frontmatter is the text between a first line of --- and the next line of ---. It is YAML whatever this input’s format, and problems in it keep the line numbers of the whole file. The second item is the body after the closing line. Returns None when the text does not start with a --- line, or never closes it.

Source

pub fn limits(self, limits: Limits) -> Self

Override limits for this input alone, above every other tier. See Limits for the order.

Source

pub fn parse<T: DeserializeOwned>(&self) -> Result<T, InputError>

Parse the text into T, without validating it.

In YAML only true and false are booleans, and a duplicate key or a merge key (<<) is refused. In TOML the format itself refuses a duplicate key.

The text must fit the limits in force, decided field by field through the tiers Limits lists. TOML reads only max_reader_input_bytes, max_depth, and max_nodes, because the other fields name YAML syntax.

§Errors

An InputError with the parser’s problem and its line. A limit problem names the limit, its value, and where to raise it, or, without input-yaml, that the tool sets it.

Source

pub fn check<T: Validate + ?Sized>( &self, value: &T, context: &T::Context, ) -> Result<(), InputError>

Available on crate feature validate only.

Validate a parsed value against context.

Each of garde’s problems lands on the line of the field it names, or of its nearest written ancestor. The place comes from the parts of garde’s path through Input::place, so a key that holds a . is found as one key. Problem::field is garde’s printed path, for display only.

§Errors

An InputError with every problem garde reports.

Source

pub fn place(&self, path: &FieldPath) -> Option<Place>

Where path is written in the text, or where its nearest written ancestor is.

The line counts the whole file, so a frontmatter input adds the lines before it. A path the text lacks gives the place of the last step that exists, and a caller that needs an exact hit compares the result with the place of the path’s parent. None when the text does not parse.

None too when the text goes past the limits in force, as Input::parse would refuse it, so placing never parses a text the limits keep out. A YAML input checks max_reader_input_bytes, max_depth and max_nodes before it hands the text to yamled, which has no budget. A TOML input checks max_reader_input_bytes, and the parse of its tree is the one Input::parse does first.

A YAML input parses its text for the first placing and keeps the result, so Input::check and later calls read one document. A TOML input parses its text on each call.

use ctl_core::input::{FieldPath, Input};

let input = Input::new("app.yaml", "files:\n  'docs/**/*.md':\n    label: ''\n");
let path = FieldPath::root()
    .key("files")
    .key("docs/**/*.md")
    .key("label");
let at = input.place(&path).map(|at| (at.line, at.column));
assert_eq!(at, Some((3, 12)));