My Little Procedural Macro

Chris Wong

What is a procedural macro?

A procedural macro extends the syntax of Rust

Parser

Source Code

Binary

* Type checking, optimization, etc.

MAGIC^*

Procedural macro

Procedural macros are everywhere!

• Serde (serialization)
• Diesel (databases)
• Rocket (web framework)
• ...
• Maud

What is maud?

Maud is a macro for writing HTML

A macro for writing HTML

use maud::html;�let best_pony = "Pinkie Pie";�let page = html! {� p {� "Hello, " (best_pony)� }�};

println!("{}", page.into_string());

A macro for writing HTML

$ cargo run

<p>Hello, Pinkie Pie</p>

Low overhead

{

let __output = String::new();

__output.push_str("<p>Hello, ");

best_pony.render_to(&mut output);

__output.push_str("</p>");

::maud::PreEscaped(__output)

}

Static type checking

use maud::html;�let best_pony = "Pinkie Pie";�let page = html! {� p {� "Hello, " (best_pone)� }�};

println!("{}", page.into_string());

Static type checking

error[E0425]: cannot find value `best_pone` in this scope

--> maud_test/src/main.rs:5:20

|

5 | "Hello, " (best_pone)

| ^^^^^^^^^ did you mean `best_pony`?

How it all started

Hamlet (Haskell)

Slim (Ruby)

Razor (C#)

??? (Rust)

How to write a successful Rust library

1. Take an existing idea from another language
2. Rewrite it in Rust
3. …
4. Profit!

Developing on Rust Nightly

Bleeding edge!

• Maud 0.1 was released Jan 2015
• Rust 1.0 was released May 2015
• Proc macro API was (and for the most part still is) unstable
• The build still breaks every month (was: every few days)

Rolling with the punches

• Schedule a daily build using Travis CI
• Research Rust commit history, blame, PRs
• Subscribe to relevant tracking issues

Keeping it simple?

Don’t go crazy with the syntax

• Put distinguishing markers at the beginning
• e.g. the let statement in Rust
• Use delimiters () [] {} as much as possible
• Rust parses these automatically

^foo.bar.baz

{{ foo.bar.baz }}

(foo.bar.baz)

https://www.deviantart.com/dipi11/art/Pinkie-Pie-in-Thought-421240604

https://www.deviantart.com/luckreza8/art/Mlp-Fim-pinkie-pie-how-do-you-think-vector-573248347

Don’t fear the heap

• Box, String, Vec aren’t evil
• Zero-allocation code can be hard to read
• Sometimes, allocations can make code faster!

fn article<'r>(

title: &'r str,

content: &'r str,

) -> impl RenderOnce + 'r {

// ...

}

https://www.deviantart.com/spyro4287/art/Pinkie-Pie-Scared-544318678

Implementation details

Use an abstract syntax tree (AST)

Even if you think you don’t need it

You’ll thank yourself later

Keep the spans

• These tell the compiler where a syntax fragment came from
• This improves compiler errors
• Also avoids weird scoping issues

error: duplicate attribute `href`

--> maud/tests/basic_syntax.rs:13:15

|

13 | html! { a href="foo.html" href="bar.html" {} }

| ^^^^^^^^^^^^^^^

|

note: `href` is duplicated here

--> maud/tests/basic_syntax.rs:13:31

|

13 | html! { a href="foo.html" href="bar.html" {} }

| ^^^^^^^^^^^^^^^

Where to next?

Where to next?

• More diagnostics!
• Invalid/non-standard elements and attributes
• rel="noopener"
• Work on stable Rust?

Thanks for listening!

https://github.com/lfairy/maud