sxd_document_no_unsafe/

lib.rs

//!
//! ```
//! 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)]

#[macro_use]
extern crate peresil;

use std::fmt;

mod lazy_hash_map;
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"))]
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"]
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(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")]
pub type NsStr<'d> = String;

static XML_NS_PREFIX: &str = "xml";
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 {
    storage: raw::Storage,
    connections: raw::Connections,
}

impl Default for Package {
    fn default() -> Package {
        let s = raw::Storage::new();
        let root = s.create_root();
        Package {
            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.storage, &self.connections)
    }

    #[doc(hidden)]
    pub fn as_thin_document(&self) -> (thindom::Storage<'_>, thindom::Connections<'_>) {
        let s = thindom::Storage::new(&self.storage);
        #[cfg(not(feature = "no-unsafe"))]
        let c = thindom::Connections::new(&self.connections);
        #[cfg(feature = "no-unsafe")]
        let c = thindom::Connections::new(&self.connections, &self.storage);
        (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")
    }
}