2020-06-13 23:29:45 -04:00
|
|
|
//! Sailfish is a simple, small, and extremely fast template engine for Rust.
|
|
|
|
//! Before reading this reference,
|
|
|
|
//! I recommend reading [User guide](https://sailfish.netlify.app/en/).
|
|
|
|
//!
|
|
|
|
//! This crate contains utilities for rendering sailfish template.
|
|
|
|
//! If you want to use sailfish templates, import `sailfish-macros` crate and use
|
|
|
|
//! derive macro `#[derive(TemplateOnce)]` or `#[derive(Template)]`.
|
|
|
|
//!
|
|
|
|
//! In most cases you don't need to care about the `runtime` module in this crate, but
|
|
|
|
//! if you want to render custom data inside templates, you must implement
|
|
|
|
//! `runtime::Render` trait for that type.
|
|
|
|
//!
|
|
|
|
//! ```ignore
|
|
|
|
//! use sailfish::TemplateOnce;
|
|
|
|
//!
|
|
|
|
//! #[derive(TemplateOnce)]
|
|
|
|
//! #[template(path = "hello.stpl")]
|
|
|
|
//! struct HelloTemplate {
|
|
|
|
//! messages: Vec<String>
|
|
|
|
//! }
|
|
|
|
//!
|
|
|
|
//! fn main() {
|
|
|
|
//! let ctx = HelloTemplate {
|
|
|
|
//! messages: vec!["foo".to_string(), "bar".to_string()]
|
|
|
|
//! };
|
|
|
|
//!
|
|
|
|
//! println!("{}", ctx.render_once().unwrap());
|
|
|
|
//! }
|
|
|
|
//! ```
|
|
|
|
|
2020-06-13 13:47:20 -04:00
|
|
|
#![doc(
|
2020-06-13 13:50:24 -04:00
|
|
|
html_logo_url = "https://raw.githubusercontent.com/Kogia-sima/sailfish/master/resources/icon.png"
|
2020-06-13 13:47:20 -04:00
|
|
|
)]
|
2020-06-18 03:32:07 -04:00
|
|
|
#![cfg_attr(sailfish_nightly, feature(core_intrinsics))]
|
2020-06-13 13:47:20 -04:00
|
|
|
|
2020-06-04 16:39:33 -04:00
|
|
|
pub mod runtime;
|
|
|
|
|
2020-12-16 04:34:26 -05:00
|
|
|
use runtime::Buffer;
|
2020-06-04 16:39:33 -04:00
|
|
|
pub use runtime::{RenderError, RenderResult};
|
2020-12-15 23:35:37 -05:00
|
|
|
#[cfg(feature = "derive")]
|
|
|
|
pub use sailfish_macros::TemplateOnce;
|
2020-06-04 16:39:33 -04:00
|
|
|
|
2020-06-06 06:16:08 -04:00
|
|
|
/// Template that can be rendered with consuming itself.
|
2020-06-18 05:35:39 -04:00
|
|
|
pub trait TemplateOnce: Sized {
|
2020-06-19 02:36:42 -04:00
|
|
|
/// Render the template and return the rendering result as `RenderResult`
|
|
|
|
///
|
2020-07-11 04:10:23 -04:00
|
|
|
/// This method never returns `Err`, unless you explicitly return RenderError
|
|
|
|
/// inside templates
|
2020-12-16 04:34:26 -05:00
|
|
|
///
|
|
|
|
/// When you use `render_once` method, total rendered size will be cached, and at
|
|
|
|
/// the next time, buffer will be pre-allocated based on the cached length.
|
|
|
|
///
|
|
|
|
/// If you don't want this behaviour, you can use `render_once_to` method instead.
|
|
|
|
fn render_once(self) -> runtime::RenderResult;
|
2020-06-18 05:35:39 -04:00
|
|
|
|
2020-06-19 02:36:42 -04:00
|
|
|
/// Render the template and append the result to `buf`.
|
2020-07-11 04:10:23 -04:00
|
|
|
///
|
|
|
|
/// This method never returns `Err`, unless you explicitly return RenderError
|
|
|
|
/// inside templates
|
2020-12-16 04:34:26 -05:00
|
|
|
///
|
|
|
|
/// ```
|
|
|
|
/// use sailfish::{RenderError, TemplateOnce};
|
|
|
|
/// use sailfish::runtime::Buffer;
|
|
|
|
///
|
|
|
|
/// # pub struct HelloTemplate {
|
|
|
|
/// # messages: Vec<String>,
|
|
|
|
/// # }
|
|
|
|
/// #
|
|
|
|
/// # impl TemplateOnce for HelloTemplate {
|
|
|
|
/// # fn render_once(self) -> Result<String, RenderError> {
|
|
|
|
/// # Ok(String::new())
|
|
|
|
/// # }
|
|
|
|
/// #
|
|
|
|
/// # fn render_once_to(self, buf: &mut Buffer) -> Result<(), RenderError> {
|
|
|
|
/// # Ok(())
|
|
|
|
/// # }
|
|
|
|
/// # }
|
|
|
|
/// #
|
|
|
|
/// let tpl = HelloTemplate {
|
|
|
|
/// messages: vec!["foo".to_string()]
|
|
|
|
/// };
|
|
|
|
///
|
|
|
|
/// // custom pre-allocation
|
|
|
|
/// let mut buffer = Buffer::with_capacity(100);
|
|
|
|
/// tpl.render_once_to(&mut buffer).unwrap();
|
|
|
|
/// ```
|
|
|
|
fn render_once_to(self, buf: &mut Buffer) -> Result<(), RenderError>;
|
2020-06-04 16:39:33 -04:00
|
|
|
}
|
|
|
|
|
2020-07-11 04:10:23 -04:00
|
|
|
/// Work in Progress
|
2020-06-04 16:39:33 -04:00
|
|
|
pub trait Template {
|
2020-06-06 06:16:08 -04:00
|
|
|
fn render(&self) -> runtime::RenderResult;
|
2020-06-04 16:39:33 -04:00
|
|
|
}
|