36 releases

0.3.16 Aug 24, 2018
0.3.15 Jul 16, 2018
0.3.14 Jun 23, 2018
0.3.6 Jan 13, 2018
0.1.3 Dec 31, 2016

#6 in Web programming

Download history 1886/week @ 2018-06-01 2019/week @ 2018-06-08 2106/week @ 2018-06-15 1987/week @ 2018-06-22 3190/week @ 2018-06-29 2762/week @ 2018-07-06 2656/week @ 2018-07-13 2337/week @ 2018-07-20 2335/week @ 2018-07-27 2596/week @ 2018-08-03 2942/week @ 2018-08-10 1856/week @ 2018-08-17 1639/week @ 2018-08-24

10,103 downloads per month
Used in 39 crates (38 directly)

MIT/Apache

698KB
10K SLoC


lib.rs:

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
  • options
  • catch

The grammar for all route attributes, including route, get, put, post, delete, head, patch, and options 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 catch attribute is:

 catch := INTEGER
 

A use of the catch attribute looks like:

 #[catch(404)]

Custom Derives

This crate implements the following custom derives:

  • FromForm

FromForm

The FromForm derive can be applied to structures with named fields:

 #[derive(FromForm)]
 struct MyStruct {
     field: usize,
     other: String
 }

Each field's type is required to implement FromFormValue. The derive accepts one field attribute: form, with the following syntax:

 form := 'field' '=' '"' IDENT '"'

 IDENT := valid identifier, as defined by Rust
 

When applied, the attribute looks as follows:

 #[derive(FromForm)]
 struct MyStruct {
     field: usize,
     #[form(field = "renamed_field")]
     other: String
 }

The derive generates an implementation for the FromForm trait. The implementation parses a form whose field names match the field names of the structure on which the derive was applied. Each field's value is parsed with the FromFormValue implementation of the field's type. The FromForm implementation succeeds only when all of the field parses succeed.

The form field attribute can be used to direct that a different incoming field name is expected. In this case, the attribute's field name is used instead of the structure's field name when parsing a form.

Procedural Macros

This crate implements the following procedural macros:

  • routes
  • catchers

The syntax for routes! and catchers! 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

Dependencies

~13MB
~406K SLoC