mf2_resource/lib.rs
1//! `mf2-resource` — the **W3C Message Resource** container for MessageFormat
2//! 2: a parser, a serializer and the data model, generic over the message
3//! type.
4//!
5//! Unicode defines no file format for MF2; its specification leaves that to
6//! a future message resource specification. Rust MF2 adopts the draft being
7//! written for it, incubated by the W3C i18n WG.
8//!
9//! ```text
10//! # A comment about the file.
11//! @locale en-US
12//! ---
13//!
14//! chat-send = Send
15//!
16//! @param $count - How many people are in the room; a whole number.
17//! users-online =
18//! .input {$count :integer}
19//! .match $count
20//! one {{{$count} user online}}
21//! * {{{$count} users online}}
22//!
23//! [hotkeys]
24//! # → id "hotkeys.release"
25//! release = Release {#kbd}?{/kbd} to close
26//! ```
27//!
28//! # Not part of 1.x's promise
29//!
30//! `mf2-build` and the `mf2` command line read and write `.mf2` files with
31//! this crate; an application never names it. What 2.x promises is the
32//! **file format as `mf2 fmt` writes it** (`docs/versioning.md`), not this
33//! Rust API: it mirrors a draft, and follows the draft as it changes. Its
34//! items are therefore hidden from the documentation.
35//!
36//! | Entry point | Gives |
37//! |---|---|
38//! | `parse` | a `Resource` of MF2 sources as written, plus the syntax errors found |
39//! | `Resource::map_values` | the draft's `Resource<Message>`: the same tree with parsed messages |
40//! | `serialize` / `serialize_with` | canonical source (`mf2 fmt`) |
41//! | `LineIndex` | a byte offset as a line and a column |
42//! | `ValueMap` | a cooked value's offset back to where the file wrote it |
43//!
44//! # The draft is not vendored
45//!
46//! The draft states no license, so nothing is copied from it: this crate
47//! implements a grammar written from the draft at a pinned revision. **Where
48//! the draft and this crate disagree, the draft wins**, and the crate
49//! follows it. The same holds for the JSON shape behind the `serde`
50//! feature.
51//!
52//! `#![no_std]` + `alloc`; never linked into the client wasm.
53//!
54//! # The user guide
55//!
56//! The [Rust MF2 book](https://evancarroll.github.io/rust-mf2/) is the user
57//! guide: how the crates fit together, web and native applications, the
58//! command line, and what 2.x promises.
59//! Its getting-started chapter shows the files this crate
60//! reads, and its versioning chapter what 2.x promises about their format.
61
62#![warn(missing_docs)]
63// docs.rs (`cargo xtask docs-rs`): each feature-gated item says which features it needs.
64#![cfg_attr(docsrs, feature(doc_cfg))]
65#![no_std]
66#![forbid(unsafe_code)]
67
68extern crate alloc;
69
70#[doc(hidden)]
71pub mod code;
72mod diagnostic;
73mod error;
74#[cfg(feature = "serde")]
75mod json;
76mod lines;
77mod model;
78mod parse;
79mod serialize;
80
81#[doc(hidden)]
82pub use diagnostic::Diagnostic;
83#[doc(hidden)]
84pub use error::{Error, Role};
85#[doc(hidden)]
86pub use lines::{LineIndex, Position};
87// Re-exported so that building a resource needs only this crate.
88#[doc(hidden)]
89pub use mf2_model::Span;
90#[doc(hidden)]
91pub use model::{
92 Comment, Detached, Entry, EntryInfo, EntryRef, Head, Id, Meta, Resource, Section, Segment,
93 ValueMap, is_id_char,
94};
95#[doc(hidden)]
96pub use parse::parse;
97#[doc(hidden)]
98pub use serialize::{Style, serialize, serialize_with};