Expand description
MDX/MDD parsing and lookup for wodix.
This crate exposes read-only dictionaries and immutable record views. It does not render HTML, execute dictionary scripts, or provide a desktop interface. Format decoders and physical block directories are implementation details; supported types and extension traits are exported from the crate root.
§Decode and look up entries
use wodix::{Mdx, Read};
let bytes = include_bytes!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/data/basic.mdx"));
let dictionary = Mdx::parse(bytes, "example")?;
assert_eq!(dictionary.reader().entries().len(), 6);
assert_eq!(dictionary.lookup("apples")?, vec!["<p>A fruit.</p>".to_owned()]);§Raw bytes and record iteration
Read::read and Read::records return immutable Bytes. Text decoding
via Read::text removes trailing NUL and whitespace; Mdx::lookup also
follows redirects, deduplicates articles and expands MDX stylesheet markers.
These operations intentionally have different semantics.
use wodix::{Read, Reader};
let bytes = include_bytes!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/data/basic.mdx"));
let reader = Reader::parse(bytes, "example")?;
let mut words = Vec::new();
for record in reader.records() {
let (entry, bytes) = record?;
words.push(entry.headword.as_str());
if entry.headword == "apple" {
assert_eq!(bytes.as_ref(), b"<p>A fruit.</p>\0");
}
}
assert_eq!(words, vec!["apple", "apples", "apricot", "banana", "café", "猫"]);§Configure component budgets
Limits is forward-compatible: start from its defaults and change the
fields needed by the caller. Cache residency excludes views retained by the
caller, in-flight decoding and memory-mapped pages; it is not a process RSS cap.
use wodix::{Limits, Read, Reader};
let mut limits = Limits::default();
limits.cache = 0;
let bytes = include_bytes!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/data/basic.mdx"));
let reader = Reader::with_limits(bytes, "example", limits)?;
assert_eq!(reader.text(0)?, "<p>A fruit.</p>");
assert_eq!(reader.cache_stats().resident, 0);§Read-only source identity
Entry ordinals belong to one source; they are not global or persistent IDs. Metadata and entries cannot be changed behind the index or record directory.
use wodix::{Mdx, Read};
let bytes = include_bytes!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/data/basic.mdx"));
let dictionary = Mdx::parse(bytes, "example")?;
dictionary.reader().entries()[0].headword.clear();§File safety and side effects
Owned or borrowed bytes use the safe parsing constructors. Memory-mapped
open operations are explicitly unsafe: backing MDX/MDD files must not be
modified or truncated while the objects exist. Resource directory paths must
also remain stable. Advisory locks alone do not establish these invariants.
Mdx::open may create a derived index cache and lock file and discover MDD
volumes. Cache is available for callers that need explicit cache locations.
Cache schema 3 validates canonical keys/postings before rebuilding the FST;
loading it is not a zero-work binary FST mapping.
§Supported format surface
Version 1.x and 2.x layouts, uncompressed/LZO/zlib blocks, supported key-info
encryption, UTF-8, UTF-16LE, GBK/GB18030 and Big5 are implemented. Unsupported
versions, encodings and encryption modes return typed Error values. HTML
and binary resources remain untrusted application data.
Structs§
- Bytes
- Raw, immutable decompressed record bytes with cheap shared ownership.
- Cache
- A derived cache bound to immutable parsed entries, not source timestamps.
Missing/stale caches are misses; explicit load/save report corruption and I/O errors.
crate::Cache::openwarns and builds directly if cache I/O or publication is unavailable. The.locksidecar is intentionally persistent to preserve its lock inode. Only validated sorted keys and postings are reused; loading reconstructs the FST and checks normalization against the source rather than mapping cached FST nodes. - Cache
Stats - Snapshot of record-block cache ownership and access counters.
- Encryption
- Source encryption bit flags; bit 1 marks encrypted key block metadata.
- Entries
- Original key order, including aliases and duplicate headwords. A failed record advances the iterator just like a successful record.
- Entry
- A headword and its logical position in one source’s record stream.
- Index
- Clones share an immutable index; entry IDs retain source order within each group.
- Limits
- Independent allocation and traversal budgets used by readers and indexes.
- Mdd
- A binary MDD resource source paired with its own immutable key index.
- Mdx
- An MDX article source paired with its own headword index.
- Metadata
- Header metadata decoded from an MDX dictionary or MDD resource source.
- Reader
- Binary MDX/MDD reader backed by any stable byte container.
- Resource
- Resource-path normalization used for MDD key lookup.
- Resources
- Associated local resources and lazily opened MDD volumes.
Enums§
- Encoding
- Text encodings supported by the parser.
- Error
- Typed failures from parsing, record access, searching and cache I/O.
- Query
- Matching operates on normalized headwords; each visit receives every duplicate ID.
- Version
- Numeric layout used by the source file.
Traits§
- Lookup
- Search operations are independent of record decoding and candidate quotas.
- Read
- Read-only dictionary data, independent of source ownership and indexing.
Type Aliases§
- Result
- Library result with an overridable error type for adapters and examples.
- Style
Sheet - Style marker ID mapped to its opening and closing text.