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,
        persistent: 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,
        },
    })),
);

Although useful for development, this approach lacks support for the most important aspect of MXP: defining custom entities and elements. (It’s also inefficient, because it uses owned strings rather than borrowed string slices.) Instead, production environments should make use of mxp’s state management system, provided by mxp::State and mxp::ModeState.

§State management

mxp::State stores definitions for custom Elements, Entitys, and LineTags. Once the state receives a definition, it can be used in all subsequent parses. With this approach, rather than using FromStr to parse tags into owned strings, Tag::parse is used to deserialize tags in-place using borrowed string slices.

Unlike everything else in MXP, which uses XML syntax, line modes are set by ANSI escape sequences. For example, to set the MXP mode to 20, the MUD 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};

// Handler function for receiving tags from the MUD server. A tag is anything surrounded by
// `<` and `>`. The `secure` flag indicates whether the current line mode is secure.
fn handle_tag(mxp_state: &mut mxp::State, mut src: &str, secure: bool) -> mxp::Result<()> {
    src = &src[1..src.len() - 1]; // strip < and > from the source
    match Tag::parse(src, secure)? {
        Tag::Definition(definition) => { // <!...>
            mxp_state.define(definition)?;
        }
        Tag::Open(tag) => { // <...>
            handle_open(tag, mxp_state, secure)?; // see below
        }
        Tag::Close(tag) => (), // </...>
    }
    Ok(())
}


// Handler function for receiving an opening tag. Called by `handle_tag`.
fn handle_open(tag: TagOpen, mxp_state: &mxp::State, secure: bool) -> mxp::Result<()> {
    match mxp_state.get_component(tag.name, secure)? {
        // server sent a standard, atomic tag, such as <a> or <br>
        mxp::Component::AtomicTag(atom) => {
            let action = atom.decode(&tag.arguments, mxp_state)?;
            handle_action(&action);
        }
        // server sent a previously-defined custom element
        mxp::Component::Element(el) => {
            for action in el.decode(&tag.arguments, mxp_state) {
                handle_action(&action?);
            }
        }
    }
    Ok(())
}

// Handler function for applying the action of an atomic tag.
// This is where the actual client logic takes place.
fn handle_action(action: &mxp::Action<Cow<str>>) {
    use mxp::Action;

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

// initialize state
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); // line mode is secure, so elements may be defined
handle_tag(&mut mxp_state, "<!ELEMENT MyEl '<HR><BR>' EMPTY OPEN>", secure).unwrap();
// The <MyEl> element has now been defined, and can be used in subsequent parses.

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

§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), and most MXP tags do not have arguments, so no allocation occurs.

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::AttributeList;
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.

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