rocket_codegen 0.1.6

Code generation for the Rocket web framework.

Rocket - Code Generation

This crate implements the code generation portions of Rocket. This includes custom derives, custom attributes, and procedural macros. The documentation here is purely technical. The code generation facilities are documented thoroughly in the Rocket programming guide.

Custom Attributes

This crate implements the following custom attributes:

  • route
  • get
  • put
  • post
  • delete
  • head
  • patch
  • error

The grammar for all route attributes, including route, get, put, post, delete, head, and patch, is defined as:

route := METHOD? '(' ('path' '=')? path (',' kv_param)* ')'

path := URI_SEG
      | DYNAMIC_PARAM
      | '?' DYNAMIC_PARAM
      | path '/' path
      (string literal)

kv_param := 'rank' '=' INTEGER
          | 'format' '=' STRING
          | 'data' '=' DYNAMIC_PARAM

INTEGER := isize, as defined by Rust
STRING := UTF-8 string literal, as defined by Rust
IDENT := Valid identifier, as defined by Rust

URI_SEG := Valid HTTP URI Segment
DYNAMIC_PARAM := '<' IDENT '..'? '>' (string literal)

Note that the route attribute takes a method as its first argument, while the remaining do not. That is, route looks like:

#[route(GET, path = "/hello")]

while the equivalent using get looks like:

#[get("/hello")]

The syntax for the error attribute is:

error := INTEGER

Custom Derives

This crate implements the following custom derives:

  • FromForm

Procedural Macros

This crate implements the following procedural macros:

  • routes
  • errors

The syntax for both of these is defined as:

macro := PATH (',' macro)*

PATH := a path, as defined by Rust

Debugging Codegen

When the ROCKET_CODEGEN_DEBUG environment variable is set, this crate logs the items it has generated to the console at compile-time. For example, you might run the following to build a Rocket application with codegen logging enabled:

ROCKET_CODEGEN_DEBUG=1 cargo build