1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
// This module is only a chapter of the documentation. //! This module describes how to configure and use Rust Compiled Templates. //! //! Ructe compiles your templates to rust code that should be compiled with //! your other rust code, so it needs to be called before compiling. //! Assuming you use [cargo](http://doc.crates.io/), it can be done like //! this: //! //! First, specify a build script and ructe as a build dependency in //! `Cargo.toml`: //! //! ```toml //! build = "src/build.rs" //! //! [build-dependencies] //! ructe = "^0.3" //! ``` //! //! Then, in the build script, compile all templates found in the templates //! directory and put the output where cargo tells it to: //! //! ```rust,no_run //! extern crate ructe; //! //! use ructe::compile_templates; //! use std::env; //! use std::path::PathBuf; //! //! fn main() { //! let out_dir = PathBuf::from(env::var("OUT_DIR").unwrap()); //! let in_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap()) //! .join("templates"); //! compile_templates(&in_dir, &out_dir).expect("compile templates"); //! } //! ``` //! //! And finally, include and use the generated code in your code. //! The file `templates.rs` will contain `mod templates { ... }`, //! so I just include it in my `main.rs`: //! //! ```rust,ignore //! include!(concat!(env!("OUT_DIR"), "/templates.rs")); //! ``` //! //! When calling a template, the arguments declared in the template will be //! prepended by a `Write` argument to write the output to. //! It can be a `Vec<u8>` as a buffer or for testing, or an actual output //! destination. //! The return value of a template is `std::io::Result<()>`, which should be //! `Ok(())` unless writing to the destination fails. //! //! ``` //! #[test] //! fn test_hello() { //! let mut buf = Vec::new(); //! templates::hello(&mut buf, "World").unwrap(); //! assert_eq!(buf, b"<h1>Hello World!</h1>\n"); //! } //! ``` //! //! # Optional features //! //! Ructe has some options that can be enabled from `Cargo.toml`. //! //! * `sass` -- Compile sass and include the compiled css as static assets. //! * `mime02` -- Static files know their mime types, compatible with //! version 0.2.x of the `mime` crate. //! * `mime03` -- Static files know their mime types, compatible with //! version 0.3.x of the `mime` crate. //! //! The `mime02` and `mime03` features are mutually exclusive and //! requires a dependency on a matching version of `mime`. //! Any of them can be combined with the `sass` feature. //! //! ```toml //! build = "src/build.rs" //! //! [build-dependencies] //! ructe = { version = "^0.3", features = ["sass", "mime02"] //! //! [dependencies] //! mime = "0.2.6" //! ``` #![allow(non_snake_case)]