xml_sec/sxd_document/

lib.rs

//!
//! ```
//! # #[cfg(not(feature = "embedded"))]
//! # {
//! use sxd_document_no_unsafe::Package;
//! let package = Package::new();
//! let doc = package.as_document();
//!
//! let hello = doc.create_element("hello");
//! hello.set_attribute_value("planet", "Earth");
//! let comment = doc.create_comment("What about other planets?");
//! let text = doc.create_text("Greetings, Earthlings!");
//!
//! hello.append_child(comment);
//! hello.append_child(text);
//! doc.root().append_child(hello);
//! # }
//! ```
//!
//! ### Memory and ownership
//!
//! The `Package` struct is responsible for owning every node in the
//! document. Strings are interned, allowing repeated text to consume
//! less memory. This is very useful for documents containing lots of
//! the same attributes and tag names.
//!
//! The flip side of this decision is that allocated nodes and strings
//! are not deallocated until the entire `Package` is dropped. This is
//! a reasonable decision for two common cases: building up an XML
//! document and reading an XML document. You may wish to perform
//! large modifications to your data *before* creating a document.
//!
//! ### Namespaces, QNames, and Prefixes
//!
//! The names of elements and attributes may use namespaces. XML
//! namespacing uses URIs to uniquely distinguish items with the same
//! local name. A qualified name (`QName`) combines this optional URI
//! with the local name.
//!
//! When an XML document is represented as text, namespaces are given
//! a shorthand reference known as a prefix. Prefix names are
//! non-authoritative, and only the URI can be used to namespace a
//! name.
//!
//! Elements and attributes may specify a *preferred prefix*, which is
//! an indication of what the user would like to be used as a
//! prefix. There are times where the preferred prefix would cause a
//! conflict, and so an autogenerated prefix will be used instead.
//!
//! ### Design decisions
//!
//! Try to leverage the type system as much as possible.

#![deny(rust_2018_idioms)]

#[cfg(not(any(feature = "no-unsafe", feature = "raw-pointer-backend")))]
compile_error!("select either `no-unsafe` or `raw-pointer-backend`");

// Cargo's all-feature verification enables both selectors. Safe precedence keeps that profile
// free of raw pointers; selecting the legacy backend requires disabling default features.

#[cfg(not(feature = "embedded"))]
#[macro_use]
extern crate peresil;

use std::{
    fmt,
    sync::atomic::{AtomicUsize, Ordering},
};

static NEXT_PACKAGE_IDENTITY: AtomicUsize = AtomicUsize::new(1);

fn next_package_identity() -> usize {
    allocate_package_identity(&NEXT_PACKAGE_IDENTITY)
}

fn allocate_package_identity(counter: &AtomicUsize) -> usize {
    let mut current = counter.load(Ordering::Relaxed);
    loop {
        let next = current
            .checked_add(1)
            .expect("document identity space exhausted");
        match counter.compare_exchange_weak(current, next, Ordering::Relaxed, Ordering::Relaxed) {
            Ok(_) => return current,
            Err(observed) => current = observed,
        }
    }
}

#[cfg(test)]
mod identity_tests {
    use super::*;

    #[test]
    fn exhausted_identity_space_does_not_wrap() {
        let counter = AtomicUsize::new(usize::MAX);
        let result = std::panic::catch_unwind(|| allocate_package_identity(&counter));
        assert!(result.is_err());
        assert_eq!(counter.load(Ordering::Relaxed), usize::MAX);
    }

    #[test]
    fn concurrent_allocations_remain_unique() {
        let counter = AtomicUsize::new(1);
        let identities = std::thread::scope(|scope| {
            let workers: Vec<_> = (0..8)
                .map(|_| {
                    scope.spawn(|| {
                        (0..128)
                            .map(|_| allocate_package_identity(&counter))
                            .collect::<Vec<_>>()
                    })
                })
                .collect();
            workers
                .into_iter()
                .flat_map(|worker| worker.join().unwrap())
                .collect::<Vec<_>>()
        });
        let unique: std::collections::HashSet<_> = identities.iter().copied().collect();
        assert_eq!(unique.len(), 8 * 128);
        assert_eq!(counter.load(Ordering::Relaxed), 1 + 8 * 128);
    }
}

/// Node and edge counts used to reserve storage before projecting into this DOM.
#[derive(Debug, Clone, Copy, Default)]
pub struct StorageRequirements {
    pub roots: usize,
    pub elements: usize,
    pub attributes: usize,
    pub texts: usize,
    pub comments: usize,
    pub processing_instructions: usize,
    pub child_edges: usize,
    pub namespace_bindings: usize,
    pub interned_strings: usize,
    pub string_bytes: usize,
}

/// Conservative heap-storage estimate for one projected document.
#[must_use]
pub fn estimated_storage_bytes(requirements: StorageRequirements) -> usize {
    raw::estimated_storage_bytes(requirements)
}

mod lazy_hash_map;
pub(crate) mod str;
mod str_ext;

#[cfg(not(feature = "no-unsafe"))]
pub mod dom;
#[cfg(not(feature = "no-unsafe"))]
mod raw;
#[cfg(not(feature = "no-unsafe"))]
pub(crate) mod string_pool;
#[cfg(not(feature = "no-unsafe"))]
#[doc(hidden)]
pub mod thindom;
#[cfg(not(feature = "no-unsafe"))]
pub mod writer;

#[cfg(feature = "no-unsafe")]
#[path = "raw_no_unsafe.rs"]
mod raw;
#[cfg(feature = "no-unsafe")]
#[path = "string_pool_no_unsafe.rs"]
pub(crate) mod string_pool;
#[cfg(feature = "no-unsafe")]
pub use string_pool::InternedString;
#[cfg(feature = "no-unsafe")]
#[path = "dom_no_unsafe.rs"]
pub mod dom;
#[cfg(feature = "no-unsafe")]
#[path = "thindom_no_unsafe.rs"]
#[doc(hidden)]
pub mod thindom;
#[cfg(feature = "no-unsafe")]
#[path = "writer_no_unsafe.rs"]
pub mod writer;

pub mod parser;

#[cfg(not(feature = "no-unsafe"))]
#[cfg(feature = "__internal_expose_string_pool")]
pub mod __internal {
    pub use super::string_pool::StringPool;
}

#[cfg(feature = "no-unsafe")]
#[cfg(feature = "__internal_expose_string_pool")]
pub mod __internal {
    pub use super::string_pool::StringPool;
}

pub use crate::str::XmlChar;
#[cfg(feature = "embedded")]
pub use crate::{as_opt_str, as_qname, as_str, to_ns_str};

#[cfg(not(feature = "no-unsafe"))]
#[macro_export]
macro_rules! as_str {
    ($e:expr) => {
        $e
    };
}

#[cfg(not(feature = "no-unsafe"))]
#[macro_export]
macro_rules! as_opt_str {
    ($e:expr) => {
        $e
    };
}

#[cfg(not(feature = "no-unsafe"))]
#[macro_export]
macro_rules! as_qname {
    ($e:expr) => {
        $e
    };
}

#[cfg(feature = "no-unsafe")]
#[macro_export]
macro_rules! as_str {
    ($e:expr) => {
        &*$e
    };
}

#[cfg(feature = "no-unsafe")]
#[macro_export]
macro_rules! as_opt_str {
    ($e:expr) => {
        $e.as_deref()
    };
}

#[cfg(feature = "no-unsafe")]
#[macro_export]
macro_rules! as_qname {
    ($e:expr) => {
        $e.get()
    };
}

#[cfg(not(feature = "no-unsafe"))]
#[macro_export]
macro_rules! to_ns_str {
    ($e:expr) => {
        $e
    };
}

#[cfg(feature = "no-unsafe")]
#[macro_export]
macro_rules! to_ns_str {
    ($e:expr) => {
        ($e).to_owned()
    };
}

/// String type used for namespace prefix/URI storage.
/// `&'d str` in default mode, `String` in no-unsafe mode.
#[cfg(not(feature = "no-unsafe"))]
pub type NsStr<'d> = &'d str;
/// String type used for namespace prefix/URI storage.
/// `&'d str` in default mode, `String` in no-unsafe mode.
#[cfg(feature = "no-unsafe")]
///
/// The lifetime is intentionally retained so cfg-independent generic code has one public type
/// signature; owned storage does not borrow from `'d` in this mode.
pub type NsStr<'d> = String;

pub(crate) static XML_NS_PREFIX: &str = "xml";
pub(crate) static XML_NS_URI: &str = "http://www.w3.org/XML/1998/namespace";

/// A prefixed name. This represents what is found in the string form
/// of an XML document, and does not apply any namespace mapping.
#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct PrefixedName<'a> {
    prefix: Option<&'a str>,
    local_part: &'a str,
}

impl<'a> PrefixedName<'a> {
    /// Create a `PrefixedName` without a prefix
    pub fn new(local_part: &str) -> PrefixedName<'_> {
        PrefixedName::with_prefix(None, local_part)
    }

    /// Create a `PrefixedName` without an optional prefix
    pub fn with_prefix(prefix: Option<&'a str>, local_part: &'a str) -> PrefixedName<'a> {
        PrefixedName { prefix, local_part }
    }

    pub fn prefix(&self) -> Option<&str> {
        self.prefix
    }
    pub fn local_part(&self) -> &str {
        self.local_part
    }
}

/// A namespace-qualified name. This represents the name of an element
/// or attribute *after* the prefix has been mapped to a specific
/// namespace.
#[derive(Debug, Copy, Clone, PartialEq)]
pub struct QName<'s> {
    namespace_uri: Option<&'s str>,
    local_part: &'s str,
}

impl<'s> QName<'s> {
    /// Create a `QName` without a namespace
    pub fn new(local_part: &'s str) -> QName<'s> {
        QName::with_namespace_uri(None, local_part)
    }

    /// Create a `QName` with an optional namespace
    pub fn with_namespace_uri(namespace_uri: Option<&'s str>, local_part: &'s str) -> QName<'s> {
        QName {
            namespace_uri,
            local_part,
        }
    }

    pub fn namespace_uri(&self) -> Option<&'s str> {
        self.namespace_uri
    }
    pub fn local_part(&self) -> &'s str {
        self.local_part
    }
}

impl<'s> From<(&'s str, &'s str)> for QName<'s> {
    fn from(v: (&'s str, &'s str)) -> QName<'s> {
        QName {
            namespace_uri: Some(v.0),
            local_part: v.1,
        }
    }
}

impl<'s> From<&'s str> for QName<'s> {
    fn from(v: &'s str) -> QName<'s> {
        QName {
            namespace_uri: None,
            local_part: v,
        }
    }
}

/// The main entrypoint to an XML document
///
/// This is an opaque structure that stores the internal details of
/// the XML document. Modify the document via `as_document`.
pub struct Package {
    identity: usize,
    storage: raw::Storage,
    connections: raw::Connections,
}

impl Default for Package {
    fn default() -> Package {
        let s = raw::Storage::new();
        let root = s.create_root();
        Package {
            identity: next_package_identity(),
            storage: s,
            connections: raw::Connections::new(root),
        }
    }
}

impl Package {
    pub fn new() -> Package {
        Self::default()
    }

    pub fn as_document(&self) -> dom::Document<'_> {
        dom::Document::new(self.identity, &self.storage, &self.connections)
    }

    #[doc(hidden)]
    pub fn as_thin_document(&self) -> (thindom::Storage<'_>, thindom::Connections<'_>) {
        // The returned handles borrow this Package, so its address is a stable runtime brand
        // for rejecting nodes created by a different arena before index or pointer access.
        let identity = std::ptr::from_ref(self).addr();
        let s = thindom::Storage::new(&self.storage, identity);
        #[cfg(not(feature = "no-unsafe"))]
        let c = thindom::Connections::new(&self.connections, identity);
        #[cfg(feature = "no-unsafe")]
        let c = thindom::Connections::new(&self.connections, &self.storage, identity);
        (s, c)
    }
}

impl PartialEq for Package {
    fn eq(&self, other: &Package) -> bool {
        std::ptr::eq(self, other)
    }
}

impl fmt::Debug for Package {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "Package")
    }
}