diff options
| -rw-r--r-- | askama/src/filters.rs | 14 | ||||
| -rw-r--r-- | askama/src/lib.rs | 14 | ||||
| -rw-r--r-- | askama/src/path.rs | 9 |
3 files changed, 35 insertions, 2 deletions
diff --git a/askama/src/filters.rs b/askama/src/filters.rs index a9fe248..3f6aede 100644 --- a/askama/src/filters.rs +++ b/askama/src/filters.rs @@ -1,9 +1,14 @@ +//! Module for built-in filter functions +//! +//! Contains all the built-in filter functions for use in templates. +//! Currently, there is no way to define filters outside this module. use std::fmt; fn escapable(b: &u8) -> bool { *b == b'<' || *b == b'>' || *b == b'&' } +/// Escapes `&`, `<` and `>` in strings pub fn escape(s: &fmt::Display) -> String { let s = format!("{}", s); let mut found = Vec::new(); @@ -39,12 +44,17 @@ pub fn escape(s: &fmt::Display) -> String { String::from_utf8(res).unwrap() } +/// Alias for the `escape()` filter pub fn e(s: &fmt::Display) -> String { escape(s) } -/// This is actually unused; format filter calls are forwarded directly to -/// the format!() macro in the code generator (see `visit_filter()`). +/// Formats arguments according to the specified format +/// +/// The first argument to this filter must be a string literal (as in normal +/// Rust). All arguments are passed through to the `format!()` +/// [macro](https://doc.rust-lang.org/stable/std/macro.format.html) by +/// the Askama code generator. pub fn format() { } #[cfg(test)] diff --git a/askama/src/lib.rs b/askama/src/lib.rs index aa21eed..73313b7 100644 --- a/askama/src/lib.rs +++ b/askama/src/lib.rs @@ -2,8 +2,11 @@ extern crate nom; extern crate syn; +/// Main `Template` trait; implementations are generally derived pub trait Template { + /// Renders the template to the given `writer` buffer fn render_to(&self, writer: &mut std::fmt::Write); + /// Helper method which allocates a new `String` and renders into it fn render(&self) -> String { let mut buf = String::new(); self.render_to(&mut buf); @@ -18,11 +21,15 @@ mod path; pub mod filters; pub use path::rerun_if_templates_changed; +// Holds metadata for the template, based on the `template()` attribute. struct TemplateMeta { path: String, print: String, } +// Returns a `TemplateMeta` based on the `template()` attribute data found +// in the parsed struct or enum. Will panic if it does not find the required +// template path, or if the `print` key has an unexpected value. fn get_template_meta(ast: &syn::DeriveInput) -> TemplateMeta { let mut path = None; let mut print = "none".to_string(); @@ -54,6 +61,13 @@ fn get_template_meta(ast: &syn::DeriveInput) -> TemplateMeta { TemplateMeta { path: path.unwrap(), print: print } } +/// Takes a `syn::DeriveInput` and generates source code for it +/// +/// Reads the metadata from the `template()` attribute to get the template +/// metadata, then fetches the source from the filesystem. The source is +/// parsed, and the parse tree is fed to the code generator. Will print +/// the parse tree and/or generated source according to the `print` key's +/// value as passed to the `template()` attribute. pub fn build_template(ast: &syn::DeriveInput) -> String { let meta = get_template_meta(ast); let src = path::get_template_source(&meta.path); diff --git a/askama/src/path.rs b/askama/src/path.rs index 7d75f1b..fb030e5 100644 --- a/askama/src/path.rs +++ b/askama/src/path.rs @@ -33,6 +33,15 @@ fn visit_dirs(dir: &Path, cb: &Fn(&DirEntry)) -> io::Result<()> { Ok(()) } +/// Build script helper to rebuild crates if contained templates have changed +/// +/// Iterates over all files in the template dir (`templates` in +/// `CARGO_MANIFEST_DIR`) and writes a `cargo:rerun-if-changed=` line for each +/// of them to stdout. +/// +/// This helper method can be used in build scripts (`build.rs`) in crates +/// that have templates, to make sure the crate gets rebuilt when template +/// source code changes. pub fn rerun_if_templates_changed() { visit_dirs(&template_dir(), &|e: &DirEntry| { println!("cargo:rerun-if-changed={}", e.path().to_str().unwrap()); |