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. This library 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 MXP standard (above). 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 [Element]s, custom [Entity]s, and user-defined [LineTag]s. 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.