scansion-rs/README.md

Scansion-rs

Reimplementation of the Scansion project in Rust.

License

SPDX: MPL-2.0. See LICENSE file.

Parsing support

Language features are defined here:
https://matthewwild.co.uk/projects/scansion/usage/script-basics/

This library supports parsing the following:

• Metadata
  Lines starting with # at the beginning of the file. All metadata lines are optional. If a single line is found it's set as the title, the second lines is set as the description. Lines starting with ## right below will be added as tags. A description is not needed for tags to be added.
  • title: optional
  • description: optional
  • tags: optional
• Client
  • Attributes
    Following lines beginning with at least a tab (\t) character, in the form attr: value, and ending with a newline (\n). Any line that matches this format will be parsed and will be discarded if it doesn't match an actual client attribute.
    • jid: Expects a bare jid or a full jid. Will be converted to jid::Jid.
    • password
    • custom_host
    • custom_port: Expect a u16
• Actions
  • 'connects'
  • 'disconnects'
  • 'sends:' / 'receives:'
    • A block of lines each starting with a tab (\t) after the action will be converted to a minidom::Element.
  • receives: nothing as the absence of received stanza.
• Variables in attributes
  • Bare Jid (${louise's JID})
  • Full Jid (${louise's full JID})
• Ignoring attribute values: {scansion:any}
• Comments
  Optional lines starting with a # or // and ending with a newline (\n). They get discarded in the output

ScanElement

ScanElement is a wrapper to minidom::Element that reimplements PartialEq. Most checks will happen in there, variables in attributes will also be read at this time.

PartialEq is only implemented for Element as it wouldn't make sense to compare two ScanElements.

This interface may change in the future as it doesn't allow returning a Result (errors may happen when parsing variables: missing from context, etc.). Currently when a referenced client doesn't exist in context, the comparison fails. If no context has been specified, comparison will go on, skipping variable handling.

minidom::Element requires every element to be namespaced and ScanElement has no special treatment for this. Be sure to include namespaces in your Elements. You may want to use Element::from_reader_with_prefixes.

Namespaced attributes aren't yet handled by minidom so scansion:strict also isn't treated in any special way.

Text nodes that aren't the unique child of an element and containing only whitespace are considered insignificant, and removed from the comparison.

Reporting bugs

Everything that's supported by upstream should be supported by this library, as long as it concerns parsing.