Skip to main content

Format

lex_babel::format

Trait Format 

Source 
pub trait Format: Send + Sync {
    // Required method
    fn name(&self) -> &str;

    // Provided methods
    fn description(&self) -> &str { ... }
    fn file_extensions(&self) -> &[&str] { ... }
    fn supports_parsing(&self) -> bool { ... }
    fn supports_serialization(&self) -> bool { ... }
    fn parse(&self, _source: &str) -> Result<Document, FormatError> { ... }
    fn serialize(&self, _doc: &Document) -> Result<String, FormatError> { ... }
    fn serialize_with_options(
        &self,
        doc: &Document,
        options: &HashMap<String, String>,
    ) -> Result<SerializedDocument, FormatError> { ... }
}
Expand description

Trait for document formats

Implementors provide bidirectional conversion between string representation and Document AST. Formats can support parsing, serialization, or both.

§Round-trip discipline

Implementing both parse and serialize carries an implicit expectation: the format participates in lex-babel’s round-trip test suite, and regressions in either direction are release blockers. If a format only makes sense in one direction (e.g. HTML export with no importer yet, or RFC XML import with no serializer), implement just that direction — don’t add a half-baked counterpart and inherit the round-trip obligation. See the v1 interop tiering for which formats actually carry this expectation — comms/docs/interop-scope.lex in-repo, or https://github.com/lex-fmt/comms/blob/main/docs/interop-scope.lex for readers on docs.rs (the comms directory is a git submodule and won’t be in published crate sources).

§Examples

ⓘ
struct MyFormat;

impl Format for MyFormat {
    fn name(&self) -> &str {
        "my-format"
    }

    fn supports_parsing(&self) -> bool {
        true
    }

    fn supports_serialization(&self) -> bool {
        true
    }

    fn parse(&self, source: &str) -> Result<Document, FormatError> {
        // Parse source to Document
        todo!()
    }

    fn serialize(&self, doc: &Document) -> Result<String, FormatError> {
        // Serialize Document to string
        todo!()
    }
}

Required Methods§

Source

fn name(&self) -> &str

The name of this format (e.g., “lex”, “markdown”, “html”)

Provided Methods§

Source

fn description(&self) -> &str

Optional description of this format

Source

fn file_extensions(&self) -> &[&str]

File extensions associated with this format (e.g., [“lex”], [“md”, “markdown”])

Returns a slice of file extensions without the leading dot. Used for automatic format detection from filenames.

Source

fn supports_parsing(&self) -> bool

Whether this format supports parsing (source → Document)

Source

fn supports_serialization(&self) -> bool

Whether this format supports serialization (Document → source)

Source

fn parse(&self, _source: &str) -> Result<Document, FormatError>

Parse source text into a Document

Default implementation returns NotSupported error. Formats that support parsing should override this method.

Source

fn serialize(&self, _doc: &Document) -> Result<String, FormatError>

Serialize a Document into source text

Default implementation returns NotSupported error. Formats that support serialization should override this method.

Source

fn serialize_with_options( &self, doc: &Document, options: &HashMap<String, String>, ) -> Result<SerializedDocument, FormatError>

Serialize a Document, optionally using extra parameters.

Formats that only emit textual output can rely on the default implementation, which delegates to Format::serialize. Binary formats should override this method to return SerializedDocument::Binary.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§