stache/ruby/

mod.rs

extern crate regex;

use regex::Regex;
use std::collections::HashSet;
use std::io::{self, Write};

use super::{Compile, Name, ParseError, Path, Statement, Template};
use self::runtime::RUNTIME;

mod runtime;

/// A program is the final result of Mustache AST to Ruby extension source
/// translation that is presented to the main compiler driver for output.
///
/// It contains all external rendering functions generated by the translator,
/// which are exposed to Ruby code after the extension is compiled.
#[derive(Debug)]
pub struct Program {
    global: Scope,
}

impl Program {
    fn new() -> Self {
        Program { global: Scope::new(Name::new("global")) }
    }

    fn merge(&mut self, scope: Scope) -> &mut Self {
        self.global.merge(scope);
        self
    }
}

impl Compile for Program {
    /// Writes the final translated source code to an output buffer.
    ///
    /// This emits fully-formed Ruby extension source code that may be input
    /// into a mkmf build process, creating a dynamically loadable shared
    /// object file.
    fn emit(&self, buf: &mut Write) -> io::Result<()> {
        // Emit runtime preamble.
        writeln!(buf, "{}", RUNTIME)?;

        // Emit function declarations.
        for fun in &self.global.functions {
            writeln!(buf, "{};", fun.decl)?;
        }

        writeln!(buf, "")?;

        // Emit function definitions.
        for fun in &self.global.functions {
            fun.emit(buf)?
        }

        // Emit main function.
        write!(buf,
               r#"void Init_stache() {{
                      VALUE Stache = rb_define_module("Stache");
                      VALUE Templates = rb_define_class_under(Stache, "Templates", rb_cObject);
                 "#)?;

        for fun in &self.global.functions {
            if let Some(ref export) = fun.export {
                writeln!(buf,
                         "rb_define_method(Templates, \"{}\", {}, 1);",
                         export,
                         fun.name)?;
            }
        }

        // Emit cached constants.
        writeln!(buf,
                 r#"rb_require("cgi");
                    cCGI = rb_const_get(rb_cObject, rb_intern("CGI"));
                    id_escape_html = rb_intern("escapeHTML");
                    id_key_p = rb_intern("key?");
                    id_to_s = rb_intern("to_s");
                 "#)?;

        writeln!(buf, "}}")
    }
}

/// A store for functions created by the translation process of an input
/// template to source code output.
///
/// Scopes have name generators that are used in function naming, providing a
/// stable name that other scopes may rely on for partial template function
/// calls.
///
/// After each template is translated into a scope they are merged into a
/// Program's global scope for final output.
#[derive(Debug)]
struct Scope {
    name: Name,
    functions: Vec<Function>,
}

impl Scope {
    fn new(name: Name) -> Self {
        Scope {
            name: name,
            functions: Vec::new(),
        }
    }

    /// Combines this scope's function definitions with another's.
    fn merge(&mut self, mut other: Scope) -> &mut Self {
        self.functions.append(&mut other.functions);
        self
    }

    /// Advances the scope's name generator to the next unique identifier. This
    /// should be called before descending another level in the recursive
    /// tree translation process.
    fn next(&mut self) -> &mut Self {
        self.name.next();
        self
    }

    /// Adds a function to this scope.
    fn register(&mut self, fun: Function) {
        self.functions.push(fun);
    }
}

#[derive(Debug)]
struct Function {
    name: String,
    decl: String,
    body: Vec<String>,
    export: Option<String>,
}

impl Function {
    fn emit(&self, buf: &mut Write) -> io::Result<()> {
        writeln!(buf, "{} {{", self.decl)?;
        for node in &self.body {
            writeln!(buf, "{}", node)?;
        }
        writeln!(buf, "}}\n")
    }
}

/// Recursively walks the AST, translating Mustache statement tree nodes into
/// the corresponding Ruby extension source code.
///
/// Sections are extracted into top-level functions paired with a function
/// call at the location the section appeared in the template. Partials are
/// similarly translated into a function call which is expected to be provided
/// by another template in the final tree.
fn transform(scope: &mut Scope, node: &Statement) -> Option<String> {
    match *node {
        Statement::Program(ref block) => {
            let id = scope.name.id();

            // Build private render function.
            let children = block.statements
                .iter()
                .filter_map(|stmt| transform(scope.next(), stmt))
                .collect();

            let internal = Function {
                name: format!("render_{}", id),
                decl: format!("static void render_{}(VALUE buf, VALUE stack)", id),
                body: children,
                export: None,
            };

            // Build public template function.
            let body = format!("VALUE buf = rb_str_buf_new(0);
                                VALUE stack = rb_ary_new_from_args(1, context);
                                render_{}(buf, stack);
                                return buf;",
                               id);
            let external = Function {
                name: format!("{}_template", id),
                decl: format!("static VALUE {}_template(VALUE self, VALUE context)", id),
                body: vec![body],
                export: Some(id),
            };

            scope.register(internal);
            scope.register(external);

            None
        }
        Statement::Section(ref path, ref block) => {
            let children = block.statements
                .iter()
                .filter_map(|stmt| transform(scope.next(), stmt))
                .collect();

            let fun = Function {
                name: format!("section_{}", scope.name),
                decl: format!("static void section_{}(VALUE buf, VALUE stack)", scope.name),
                body: children,
                export: None,
            };

            let call = format!("{{ {} section(buf, stack, path, {}); }}",
                               path_ary(path),
                               fun.name);

            scope.register(fun);
            Some(call)
        }
        Statement::Inverted(ref path, ref block) => {
            let children = block.statements
                .iter()
                .filter_map(|stmt| transform(scope.next(), stmt))
                .collect();

            let fun = Function {
                name: format!("section_{}", scope.name),
                decl: format!("static void section_{}(VALUE buf, VALUE stack)", scope.name),
                body: children,
                export: None,
            };

            let call = format!("{{ {} inverted(buf, stack, path, {}); }}",
                               path_ary(path),
                               fun.name);

            scope.register(fun);
            Some(call)
        }
        Statement::Partial(ref name) => {
            let name = Name::new(name);
            Some(format!("render_{}(buf, stack);", name.id()))
        }
        Statement::Comment(_) => None,
        Statement::Content(ref text) => {
            let text = clean(text);
            Some(format!("rb_str_cat_cstr(buf, \"{}\");", text))
        }
        Statement::Variable(ref path) => {
            let path = path_ary(path);
            Some(format!("{{ {} append_value(buf, stack, path, true); }}", path))
        }
        Statement::Html(ref path) => {
            let path = path_ary(path);
            Some(format!("{{ {} append_value(buf, stack, path, false); }}", path))
        }
    }
}

/// Transforms the AST of each parsed template into a source code tree
/// and links each template together into a single executable program.
pub fn link(templates: &Vec<Template>) -> Result<Program, ParseError> {
    validate(templates)?;

    let mut program = Program::new();
    templates.iter()
        .map(|template| {
            let mut scope = Scope::new(template.name());
            transform(&mut scope, &template.tree);
            scope
        })
        .fold(&mut program, |program, scope| program.merge(scope));

    Ok(program)
}

/// Ensures all templates may be linked together into an executable.
///
/// This method checks that all partial template paths are provided by
/// another template. For example, a `{{>include/header}}` partial invocation
/// must be provided by an `include/header.mustache` template file.
///
/// Partials can be considered function calls, so the function must be defined.
fn validate(templates: &Vec<Template>) -> Result<(), ParseError> {
    let all: HashSet<_> = templates.iter().map(|temp| &temp.name).collect();

    for template in templates {
        let names: HashSet<_> = template.tree.partials().into_iter().collect();
        let missing = &names - &all;
        if !missing.is_empty() {
            let name = missing.into_iter().next().unwrap();
            return Err(ParseError::UnknownPartial(name.clone(), template.path.clone()));
        }
    }

    Ok(())
}

/// Replaces string literal characters considered invalid inside a cstr with
/// their escaped counterparts.
fn clean(text: &str) -> String {
    let re = Regex::new(r"\r").unwrap();
    let value = re.replace_all(text, "\\r");

    let re = Regex::new(r"\n").unwrap();
    let value = re.replace_all(&value, "\\n");

    let re = Regex::new(r#"["]"#).unwrap();
    re.replace_all(&value, "\\\"")
}

/// Transforms a Mustache variable key path into the source code to build a
/// Ruby array. At runtime, each key in the array is recursively processed to
/// find the replacement text for a Mustache expression.
fn path_ary(path: &Path) -> String {
    let args = path.keys
        .iter()
        .map(|key| format!("rb_str_new_cstr(\"{}\")", key))
        .collect::<Vec<String>>()
        .join(", ");

    format!("VALUE path = rb_ary_new_from_args({}, {});",
            path.keys.len(),
            args)
}

#[cfg(test)]
mod tests {
    use super::{link, transform, Scope};
    use super::super::{Name, ParseError, Statement, Template};
    use std::path::{Path, PathBuf};

    #[test]
    fn validates_valid_partial_reference() {
        let base = PathBuf::from("app/templates");
        let path = PathBuf::from("app/templates/machines/robots.mustache");
        let tree = Statement::Partial(String::from("machines/robot"));
        let master = Template::new(&base, path, tree);

        let path = PathBuf::from("app/templates/machines/robot.mustache");
        let tree = Statement::Content(String::from("hubot"));
        let detail = Template::new(&base, path, tree);

        let templates = vec![master, detail];
        match link(&templates) {
            Ok(_) => (),
            Err(e) => panic!("Must link valid partials: {}", e),
        }
    }

    #[test]
    fn validates_invalid_partial_reference() {
        let base = PathBuf::from("app/templates");
        let path = PathBuf::from("app/templates/machines/robots.mustache");
        let tree = Statement::Partial(String::from("machines/unknown"));
        let master = Template::new(&base, path, tree);

        let path = PathBuf::from("app/templates/machines/robot.mustache");
        let tree = Statement::Content(String::from("hubot"));
        let detail = Template::new(&base, path, tree);

        let templates = vec![master, detail];
        match link(&templates) {
            Err(ParseError::UnknownPartial(ref name, ref path)) => {
                assert_eq!("machines/unknown", name);
                assert_eq!(Path::new("app/templates/machines/robots.mustache"), path);
            }
            _ => panic!("Must enforce partial references"),
        }
    }

    #[test]
    fn transforms_tree_into_functions() {
        let text = "
            {{> includes/header }}
            <ul>
                {{# robots}}
                    <li>{{ name.first }}</li>
                {{/ robots}}
                {{^ robots}}
                    {{! else clause }}
                    No robots
                {{/ robots}}
            </ul>
            {{> includes/footer }}
            {{{ unescaped.html }}}
        ";

        match Statement::parse(text) {
            Ok(tree) => {
                let mut scope = Scope::new(Name::new("machines/robot"));
                transform(&mut scope, &tree);

                // One for each section, private render, and exported template function.
                let names: Vec<_> = scope.functions.iter().map(|fun| &fun.name).collect();
                assert_eq!(vec!["section_machines_robot7",
                                "section_machines_robot12",
                                "render_machines_robot",
                                "machines_robot_template"],
                           names);

                // Single exported function name.
                let exports: Vec<_> =
                    scope.functions.iter().filter_map(|fun| fun.export.as_ref()).collect();
                assert_eq!(vec!["machines_robot"], exports);
            }
            Err(e) => panic!("Failed to parse tree: {}", e),
        }
    }
}