Crate macro_railroad

A library to generate syntax diagrams for Rust macros.

let src = r#"macro_rules! vec {
                 ( $ elem : expr ; $ n : expr ) => { ... };
                 ( $ ( $ x : expr ) , * ) => { ... };
                 ( $ ( $ x : expr , ) * ) => { ... };
             }
"#;
let dia = macro_railroad::to_diagram(&src).expect("Failed to parse");
assert!(dia.starts_with("<svg"));

Diagrams are generated directly from code:

1. Parsing the macro_rules!()-block.
2. Converting the parser-tree into an intermediate representation and applying transformations as desired.
3. Converting the intermediate representation into a railroad::Diagram. Adding CSS to control the graphical representation.
4. Outputting the final SVG.

let src = r#"macro_rules! vec {
                 ( $ elem : expr ; $ n : expr ) => { ... };
                 ( $ ( $ x : expr ) , * ) => { ... };
                 ( $ ( $ x : expr , ) * ) => { ... };
             }
"#;

let parsed = macro_railroad::parser::parse(&src).expect("Failed to parse");

let mut ir: macro_railroad::lowering::MacroRules = parsed.into();
// Remove `__impl`--rules, which we consider macro-internal here.
ir.remove_internal();
// Fold common parts in the macro-syntax, making the diagram easier to understand.
ir.foldcommontails();
// Remove superfluous elements left from parsing and transforming.
ir.normalize();

// Create a diagram, add a legend
let mut dia = macro_railroad::diagram::into_diagram(ir, true);
dia.add_default_css();

assert!(dia.to_string().starts_with("<svg"));

Re-exports

pub extern crate syn;

pub use railroad;

Modules

diagram

Transform a lowering::MacroRules-tree into a railroad::Diagram

lowering

Intermediate representation of a MacroRules and it’s transformations.

parser

Parses a raw macro_rules!-string.

Functions

to_diagram

Create a syntax diagram as an SVG from the given macro_rules!-source.