libxml_rs/

lib.rs

//! libxml-rs: Custodial native-Rust reimplementation of libxml2 and libxslt
//!
//! This is not an XML crate. This is not an XSLT crate. This is not a wrapper.
//! This is a forensic reconstruction of the observable behavior of the libxml2 + libxslt
//! ecosystem across its historical lifetime, implemented in native Rust.
//!
//! # Architecture
//!
//! The crate is organized into semantic modules corresponding to real ownership boundaries:
//!
//! - `abi` - C ABI compatibility layer: types, structs, constants, exports, callbacks, allocator, ownership, versioning
//! - `xml` - libxml2 implementation: parser, SAX, tree, entities, namespaces, DTD, validation, reader, writer, encoding, I/O, catalog, URI, XPath, XPointer, XInclude, RELAX NG, schemas, Schematron, C14N, HTML, regex, automata, dictionary, hash, list, debug, globals, threads, errors, memory
//! - `xslt` - libxslt implementation: stylesheet, compiler, transform, templates, patterns, variables, parameters, keys, attributes, namespace_alias, whitespace, sorting, numbering, documents, imports, extensions, serialization, security, errors
//! - `exslt` - EXSLT modules: common, math, sets, strings, dynamic, functions, dates
//! - `compatibility` - Historical profiles, quirks, platform-specific behavior
//! - `bin` - CLI tools: xmllint, xmlcatalog, xsltproc
//!
//! # Safety
//!
//! This crate uses `unsafe` only where fundamentally required for C ABI export, raw-pointer
//! compatibility, foreign allocator interoperability, public C structure layout, callbacks,
//! variadic compatibility, OS interfaces, and dynamic-loader interaction.
//!
//! Every unsafe block documents:
//! - What must be true
//! - Who establishes it
//! - How long it remains true
//! - Which oracle/parity court exercises the assumption
//! - What would constitute violation

#![deny(unconditional_recursion, unused_lifetimes, while_true)]
// Lint policy, sealed at 11.1-Z. This crate is a C-ABI mirror of
// libxml2/libxslt; the hot lint surface is raw-pointer plumbing and
// C-signal integer casts that are *deliberate* parity decisions (e.g.
// `i32` -> `usize` mirrors what upstream C does; rewriting cast_sign_loss
// sites with `try_from().unwrap()` would introduce panics that do not
// exist in the oracle). Consequently:
//
//   - `clippy::all` plus the rustc doc lints is the enforced gate and is
//     kept clean: `cargo clippy --all-targets --all-features -- -D warnings`
//     passes at the 11.1-Z seal (every remaining unsafe fn carries a
//     `# Safety` section; missing_docs is allowed only on the C-header
//     mirror modules structs.rs/types.rs, where the C headers are the
//     canonical documentation, matching bindgen's default).
//   - `clippy::pedantic`/`clippy::nursery` are NOT gated. clippy documents
//     pedantic as "opinionated" and nursery as "experimental"; their two
//     largest families here (ptr_as_ptr ~4.5k and cast_* ~1.6k instances
//     in the lib) are inherent to the ABI-mirror domain, so enforcing them
//     would force either semantically-worse code or thousands of per-site
//     `#[allow]` attributes. They were enabled-but-dirty since crate
//     inception; the seal converts the policy to what is actually enforced.
//   - `clippy::missing_inline_in_public_items` is not gated: the
//     `#[no_mangle] extern "C"` export surface cannot be inlined across
//     the FFI boundary, making the lint noise on ~500 exports.
#![warn(
    missing_docs,
    missing_debug_implementations,
    clippy::all,
    clippy::cargo,
    clippy::missing_const_for_fn
)]
#![allow(
    // The C-API ports declare every out-parameter with a NULL/0 initializer
    // mirroring upstream C (`xmlXPathObjectPtr obj = NULL;`); Rust flags the
    // dead initializer as unused_assignments, which is deliberate parity
    // structure (it keeps the port textually aligned with upstream for
    // archaeology/diff review), not a bug.
    unused_assignments,
    clippy::module_name_repetitions,
    clippy::multiple_crate_versions,
    clippy::too_many_lines,
    clippy::type_complexity,
    // C ABI type names must mirror the upstream headers verbatim; the
    // `xml...` acronym spellings are the exported API, so renames that
    // clippy suggests would break the ABI/API mirror. Likewise the
    // non_snake_case locals/parameters mirror upstream C variable names
    // (e.g. `pubID`, `SystemID`, `mallocFunc`) to keep the ports textually
    // aligned with the archaeology source for diff review.
    clippy::upper_case_acronyms,
    non_camel_case_types,
    non_snake_case,
    // The internal safe wrapper API (dictionary/list/hash/tree/errors
    // helpers) null-checks raw pointers before dereferencing them,
    // mirroring upstream's NULL-tolerant C functions; the wrappers are the
    // crate's safe facade, and marking them `unsafe` would push unsafe
    // blocks into every caller. The C ABI exports that deref are declared
    // `unsafe extern "C"` and carry `# Safety` sections.
    clippy::not_unsafe_ptr_arg_deref,
)]

// Public ABI compatibility layer
pub mod abi;

// libxml2 implementation
pub mod xml;

// libxslt implementation
pub mod xslt;

// EXSLT implementation
pub mod exslt;

// Compatibility profiles and historical behavior
pub mod compatibility;

// Binary entry points are defined as [[bin]] targets in Cargo.toml.
// They are NOT library modules — they depend on libxml_rs as a library.
// See src/bin/xmllint.rs, src/bin/xmlcatalog.rs, src/bin/xsltproc.rs

// Phase 0: ABI re-exports will be populated when types are defined.
// The `allow(unused_imports)` is intentional — these will be used in Phase 1+.
#[allow(unused_imports)]
use abi::allocator::*;
#[allow(unused_imports)]
use abi::callbacks::*;
#[allow(unused_imports)]
use abi::constants::*;
#[allow(unused_imports)]
use abi::ownership::*;
#[allow(unused_imports)]
use abi::structs::*;
#[allow(unused_imports)]
use abi::types::*;
#[allow(unused_imports)]
use abi::versioning::*;

// Internal modules (not part of public C ABI)
mod internal;

// Property-based fuzzing smoke targets (proptest, runs in `cargo test`).
#[cfg(test)]
mod fuzz;

/// The full version string of the libxml-rs crate (from Cargo.toml).
pub const LIBXML_RS_VERSION: &str = env!("CARGO_PKG_VERSION");

/// Major version number of libxml-rs.
pub const LIBXML_RS_VERSION_MAJOR: u32 = 0;

/// Minor version number of libxml-rs.
pub const LIBXML_RS_VERSION_MINOR: u32 = 1;

/// Micro version (patch) number of libxml-rs.
pub const LIBXML_RS_VERSION_MICRO: u32 = 0;