Skip to main content

Crate wodix

Crate wodix 

Source
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::open warns and builds directly if cache I/O or publication is unavailable. The .lock sidecar 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.
CacheStats
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.
StyleSheet
Style marker ID mapped to its opening and closing text.