Crate mxp

Expand description

Batteries-included implementation of MXP (MUD eXtension Protocol).

§Description

MXP (MUD eXtension Protocol) is an open communication protocol for MUD servers and clients. The mxp library is a lightweight but robust implementation of the protocol in its entirety. It is geared toward client implementations, but it can also be used for server-side syntax handling.

By default, mxp processes all tags described in the above MXP standard. To restrict which elements your client supports, send a SupportResponse to the MUD server.

§Examples

§Simple parsing

mxp can be used to parse MXP strings directly:

use mxp::{Dimension, FrameAction, FrameLayout};

assert_eq!(
    "<FRAME NAME=Map LEFT=-20c TOP=0 WIDTH=20c HEIGHT=20c>".parse::<mxp::Action>(),
    Ok(mxp::Action::Frame(mxp::Frame {
        name: "Map".into(),
        action: FrameAction::Open,
        title: "Map".into(),
        scrolling: false,
        layout: FrameLayout::External {
            left: Dimension::character_spacing(-20),
            top: Dimension::pixels(0),
            width: Some(Dimension::character_spacing(20)),
            height: Some(Dimension::character_spacing(20)),
            floating: false,
        },
    })),
);

However, this approach lacks the most important aspect of MXP parsing: custom entities and elements. It also has no way to protect secure tags during OPEN line modes. (It’s also inefficient, because it uses owned strings rather than borrowed string slices.) The intended way to use this library is with state management via mxp::State and mxp::ModeState.

§State management

mxp provides state management via mxp::State: the central hub of MXP logic. mxp::State stores custom Elements, custom Entitys, and user-defined LineTags. In this approach, rather than using FromStr to parse tags with owned strings, Tag::parse is used to deserialize tags in-place using borrowed string slices.

Furthermore, mxp::ModeState can be used to handle line modes, as well as retrieving custom elements from user-defined line tags. Rather than being parsed from XML tags like everything else in MXP, modes are set by ANSI escape sequences. For example, to set the MXP mode to 20, server would send <ESC>[20z. As such, it is up to the client to recognize MXP mode changes and apply them with ModeState::set and ModeState::revert.

use std::borrow::Cow;
// Alternatively:
// - `use mxp::node;` for prefixed names, e.g. `node::TagOpen`
// - `use mxp::node::{Tag as TagNode, TagOpen as TagOpenNode};`
use mxp::node::{Tag, TagOpen};

fn handle_element(mxp_state: &mut mxp::State, mut src: &str, secure: bool) -> mxp::Result<()> {
    src = &src[1..src.len() - 1]; // remove < and >
    match Tag::parse(src, secure)? {
        Tag::Definition(definition) => {
            mxp_state.define(definition)?;
        }
        Tag::Open(tag) => {
            handle_open(tag, mxp_state, secure)?;
        }
        Tag::Close(tag) => (),
    }
    Ok(())
}

fn handle_open(tag: TagOpen, mxp_state: &mxp::State, secure: bool) -> mxp::Result<()> {
    match mxp_state.get_component(tag.name, secure)? {
        mxp::Component::AtomicTag(atom) => {
            let action = atom.decode(&tag.arguments, mxp_state)?;
            handle_action(&action);
        }
        mxp::Component::Element(el) => {
            for action in el.decode(&tag.arguments, mxp_state) {
                handle_action(&action?);
            }
        }
    }
    Ok(())
}

fn handle_action(action: &mxp::Action<Cow<str>>) {
    use mxp::Action;

    match action {
        Action::Br => println!(),
        Action::Hr => print!("----"),
        _ => (),
    }
}

let mut mxp_state = mxp::State::with_globals();
let mut mode = mxp::ModeState::new();

mode.set(mxp::Mode::SECURE_ONCE);
let secure = mode.use_secure();
assert!(secure); // Mode must be secure in order to define elements
handle_element(&mut mxp_state, "<!ELEMENT custom '<HR><BR>' EMPTY OPEN>", secure).unwrap();

let secure = mode.use_secure();
assert!(!secure); // SECURE_ONCE reverts back to OPEN mode after use
handle_element(&mut mxp_state, "<custom>", secure).unwrap(); // prints "----\n"

§Server-side usage

All of the types exported by mxp can be serialized to MXP syntax with their Display implementation.

use mxp::entity::EntityKeyword;

let entity = mxp::node::EntityDefinition {
    name: "Guilds",
    value: "Wizards",
    desc: None,
    keywords: EntityKeyword::Publish | EntityKeyword::Add,
};
assert_eq!(entity.to_string(), "<!EN Guilds \"Wizards\" PUBLISH ADD>");

For advanced tag building, see TagBuilder.

§Memory allocation

Tag::parse allocates memory if it parses a custom element definition (as node::ElementDefinition), which needs to use owned strings because custom elements are stored long-term in state. Otherwise, it only allocates memory to parse arguments passed to an opening tag (as node::TagOpen), as described in the next paragraph.

Arguments parsing allocates a Vec<&'a str> and HashMap<&'a str, &'a str> for positional and named arguments respectively. Both use generous size guesses (based on the number of spaces in the string) in order to prevent reallocations. Arguments are ephemeral structs that drop as soon as they are done being used to decode tags.

Tag decoding (via AtomicTag::decode and Element::decode) uses Cows because attributes may contain entities, in which case they must be decoded to owned strings in order to replace entities with their definitions (e.g. replacing "<" with "<"). If the MXP string does not contain entities, no allocations are performed.

Re-exports§

pub use arguments::Arguments;
pub use color::RgbColor;
pub use element::Action;
pub use element::ActionKind;
pub use element::AtomicTag;
pub use element::Element;
pub use element::ParseAs;
pub use entity::Entity;
pub use elements::*;

Modules§

arguments: Arguments and associated types.
color: RgbColor and associated types.
element: Element and associated types.
elements: Atomic elements defined by the MXP standard.
entity: Entity and associated types.
escape: Constants for escape sequences.
node: Typed representations of parsed MXP strings.
responses: Types for generating client responses to MXP queries.

Structs§

Dimension: A measurement of screen space, specified as a pixel amount, a percentage, or an amount of character widths, as determined by the DimensionUnit.
Error: Error encountered during parsing and processing of MXP data.
FlagSet: Reexport from the flagset package.
LineTag: LineTagProperties for a line mode, as well as an Element if one is associated with the current user-defined line mode.
LineTagProperties: Properties defined for a line tag.
Mode: Mode defined by a line tag.
ModeRangeError: The error type returned when a checked conversion from an integral type to Mode fails.
ModeState: State tracker for Mode.
State: A store of MXP state: elements, entities, and line tags.

Enums§

Align: Alignment of an on-screen item.
Component: This struct is created by State::get_component. See its documentation for more.
DimensionUnit: Specifies the units of a Dimension.
ErrorKind: Type associated with an mxp::Error.

Traits§

Decoder: Trait for decoding entities to values.
KeywordFilter: A trait for filtering out keywords from a list of strings.

Functions§

is_valid: If the specified target is valid to use as an MXP identifier or value, returns true. Otherwise, returns false.
validate: If the specified target is valid to use as an MXP identifier or value, returns Ok(()). Otherwise, returns an mxp::Error for the target with the specified error kind.
validate_utf8: Equivalent to str::from_utf8, but returns an mxp::Error instead of a Utf8Error.

Type Aliases§

Result: Type alias for Result<T, mxp::Error>.

Crate mxp

Crate mxp Copy item path

§Description

§Examples

§Simple parsing

§State management

§Server-side usage

§Memory allocation

Re-exports§

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate mxp