preserves/implementations/rust/preserves/src/value/text/mod.rs

//! Implements the Preserves [human-oriented text
//! syntax](https://preserves.dev/preserves-text.html).
//!
//! The main entry points for reading are functions [iovalue_from_str],
//! [annotated_iovalue_from_str], [from_str], and [annotated_from_str].
//!
//! The main entry points for writing are [TextWriter::encode_iovalue] and
//! [TextWriter::encode].
//!
//! # Summary of Text Syntax
#![doc = include_str!("../../../doc/cheatsheet-text-plaintext.md")]

pub mod reader;
pub mod writer;

pub use reader::TextReader;
pub use reader::ToplevelWhitespaceMode;
pub use writer::TextWriter;

use crate::value::reader::BytesBinarySource;

use std::io;

use super::{DomainParse, IOValue, IOValueDomainCodec, NestedValue, Reader, ViaCodec};

/// Reads a value from the given string using the text syntax, discarding annotations.
pub fn from_str<N: NestedValue, Dec: DomainParse<N::Embedded>>(
    s: &str,
    decode_embedded: Dec,
) -> io::Result<N> {
    TextReader::new(&mut BytesBinarySource::new(s.as_bytes()), decode_embedded).demand_next(false)
}

/// Reads an [IOValue] from the given string using the text syntax, discarding annotations.
pub fn iovalue_from_str(s: &str) -> io::Result<IOValue> {
    from_str(s, ViaCodec::new(IOValueDomainCodec))
}

/// As [from_str], but includes annotations.
pub fn annotated_from_str<N: NestedValue, Dec: DomainParse<N::Embedded>>(
    s: &str,
    decode_embedded: Dec,
) -> io::Result<N> {
    TextReader::new(&mut BytesBinarySource::new(s.as_bytes()), decode_embedded).demand_next(true)
}

/// As [iovalue_from_str], but includes annotations.
pub fn annotated_iovalue_from_str(s: &str) -> io::Result<IOValue> {
    annotated_from_str(s, ViaCodec::new(IOValueDomainCodec))
}