From e1fd22b305e8bd94f79c98b7475bd482f8a16139 Mon Sep 17 00:00:00 2001 From: Milo Moisson Date: Wed, 14 Aug 2024 10:37:41 +0200 Subject: [PATCH 1/2] docs: fix formatting --- src/lib.rs | 155 +++++++++++++++++++++++--------------------------- src/macros.rs | 19 +++---- 2 files changed, 79 insertions(+), 95 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 456c6a5ab..fa6002f2b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -13,19 +13,19 @@ //! use handlebars::Handlebars; //! //! # fn main() { -//! // create the handlebars registry -//! let mut handlebars = Handlebars::new(); -//! -//! // register the template. The template string will be verified and compiled. -//! let source = "hello {{world}}"; -//! assert!(handlebars.register_template_string("t1", source).is_ok()); -//! -//! // Prepare some data. -//! // -//! // The data type should implements `serde::Serialize` -//! let mut data = BTreeMap::new(); -//! data.insert("world".to_string(), "世界!".to_string()); -//! assert_eq!(handlebars.render("t1", &data).unwrap(), "hello 世界!"); +//! // create the handlebars registry +//! let mut handlebars = Handlebars::new(); +//! +//! // register the template. The template string will be verified and compiled. +//! let source = "hello {{world}}"; +//! assert!(handlebars.register_template_string("t1", source).is_ok()); +//! +//! // Prepare some data. +//! // +//! // The data type should implements `serde::Serialize` +//! let mut data = BTreeMap::new(); +//! data.insert("world".to_string(), "世界!".to_string()); +//! assert_eq!(handlebars.render("t1", &data).unwrap(), "hello 世界!"); //! # } //! ``` //! @@ -126,15 +126,13 @@ //! Templates are created from `String`s and registered to `Handlebars` with a name. //! //! ``` -//! # extern crate handlebars; -//! //! use handlebars::Handlebars; //! //! # fn main() { -//! let mut handlebars = Handlebars::new(); -//! let source = "hello {{world}}"; +//! let mut handlebars = Handlebars::new(); +//! let source = "hello {{world}}"; //! -//! assert!(handlebars.register_template_string("t1", source).is_ok()) +//! assert!(handlebars.register_template_string("t1", source).is_ok()) //! # } //! ``` //! @@ -147,17 +145,16 @@ //! without registration. //! //! ``` -//! # use std::error::Error; //! use handlebars::Handlebars; //! use std::collections::BTreeMap; //! -//! # fn main() -> Result<(), Box> { -//! let mut handlebars = Handlebars::new(); -//! let source = "hello {{world}}"; +//! # fn main() -> Result<(), Box> { +//! let mut handlebars = Handlebars::new(); +//! let source = "hello {{world}}"; //! -//! let mut data = BTreeMap::new(); -//! data.insert("world".to_string(), "世界!".to_string()); -//! assert_eq!(handlebars.render_template(source, &data)?, "hello 世界!".to_owned()); +//! let mut data = BTreeMap::new(); +//! data.insert("world".to_string(), "世界!".to_string()); +//! assert_eq!(handlebars.render_template(source, &data)?, "hello 世界!".to_owned()); //! # Ok(()) //! # } //! ``` @@ -179,62 +176,53 @@ //! You can use default `render` function to render a template into `String`. From 0.9, there's `render_to_write` to render text into anything of `std::io::Write`. //! //! ``` -//! # use std::error::Error; -//! # #[macro_use] -//! # extern crate serde_derive; -//! # extern crate handlebars; -//! //! use handlebars::Handlebars; //! -//! #[derive(Serialize)] +//! #[derive(serde::Serialize)] //! struct Person { //! name: String, //! age: i16, //! } //! -//! # fn main() -> Result<(), Box> { -//! let source = "Hello, {{name}}"; -//! -//! let mut handlebars = Handlebars::new(); -//! assert!(handlebars.register_template_string("hello", source).is_ok()); +//! # fn main() -> Result<(), Box> { +//! let source = "Hello, {{name}}"; //! +//! let mut handlebars = Handlebars::new(); +//! assert!(handlebars.register_template_string("hello", source).is_ok()); //! -//! let data = Person { -//! name: "Ning Sun".to_string(), -//! age: 27 -//! }; -//! assert_eq!(handlebars.render("hello", &data)?, "Hello, Ning Sun".to_owned()); +//! let data = Person { +//! name: "Ning Sun".to_string(), +//! age: 27 +//! }; +//! assert_eq!(handlebars.render("hello", &data)?, "Hello, Ning Sun".to_owned()); //! # Ok(()) //! # } -//! # //! ``` //! //! Or if you don't need the template to be cached or referenced by other ones, you can //! simply render it without registering. //! //! ``` -//! # use std::error::Error; -//! # #[macro_use] -//! # extern crate serde_derive; -//! # extern crate handlebars; //! use handlebars::Handlebars; -//! # #[derive(Serialize)] +//! # #[derive(serde::Serialize)] //! # struct Person { //! # name: String, //! # age: i16, //! # } //! -//! # fn main() -> Result<(), Box> { -//! let source = "Hello, {{name}}"; +//! # fn main() -> Result<(), Box> { +//! let source = "Hello, {{name}}"; //! -//! let mut handlebars = Handlebars::new(); +//! let mut handlebars = Handlebars::new(); //! -//! let data = Person { -//! name: "Ning Sun".to_string(), -//! age: 27 -//! }; -//! assert_eq!(handlebars.render_template("Hello, {{name}}", &data)?, -//! "Hello, Ning Sun".to_owned()); +//! let data = Person { +//! name: "Ning Sun".to_string(), +//! age: 27 +//! }; +//! assert_eq!( +//! handlebars.render_template("Hello, {{name}}", &data)?, +//! "Hello, Ning Sun".to_owned() +//! ); //! # Ok(()) //! # } //! ``` @@ -249,7 +237,6 @@ //! //! ``` //! use std::io::Write; -//! # use std::error::Error; //! use handlebars::*; //! //! // implement by a structure impls HelperDef @@ -276,27 +263,28 @@ //! } //! //! -//! # fn main() -> Result<(), Box> { -//! let mut handlebars = Handlebars::new(); -//! handlebars.register_helper("simple-helper", Box::new(SimpleHelper)); -//! handlebars.register_helper("another-simple-helper", Box::new(another_simple_helper)); -//! // via closure -//! handlebars.register_helper("closure-helper", -//! Box::new(|h: &Helper, r: &Handlebars, _: &Context, rc: &mut RenderContext, out: &mut dyn Output| -> HelperResult { -//! let param = -//! h.param(0).ok_or(RenderErrorReason::ParamNotFoundForIndex("closure-helper", 0))?; -//! -//! out.write("3rd helper: ")?; -//! out.write(param.value().render().as_ref())?; -//! Ok(()) -//! })); -//! -//! let tpl = "{{simple-helper 1}}\n{{another-simple-helper 2}}\n{{closure-helper 3}}"; -//! assert_eq!(handlebars.render_template(tpl, &())?, -//! "1st helper: 1\n2nd helper: 2\n3rd helper: 3".to_owned()); +//! # fn main() -> Result<(), Box> { +//! let mut handlebars = Handlebars::new(); +//! handlebars.register_helper("simple-helper", Box::new(SimpleHelper)); +//! handlebars.register_helper("another-simple-helper", Box::new(another_simple_helper)); +//! // via closure +//! handlebars.register_helper("closure-helper", +//! Box::new(|h: &Helper, r: &Handlebars, _: &Context, rc: &mut RenderContext, out: &mut dyn Output| -> HelperResult { +//! let param = +//! h.param(0).ok_or(RenderErrorReason::ParamNotFoundForIndex("closure-helper", 0))?; +//! +//! out.write("3rd helper: ")?; +//! out.write(param.value().render().as_ref())?; +//! Ok(()) +//! })); +//! +//! let tpl = "{{simple-helper 1}}\n{{another-simple-helper 2}}\n{{closure-helper 3}}"; +//! assert_eq!( +//! handlebars.render_template(tpl, &())?, +//! "1st helper: 1\n2nd helper: 2\n3rd helper: 3".to_owned() +//! ); //! # Ok(()) //! # } -//! //! ``` //! //! Data available to helper can be found in [Helper](struct.Helper.html). And there are more @@ -371,17 +359,16 @@ //! //! ``` //! # #[cfg(feature = "string_helpers")] { -//! # use std::error::Error; -//! # extern crate handlebars; //! use handlebars::Handlebars; //! -//! # fn main() -> Result<(), Box> { -//! -//! let mut handlebars = Handlebars::new(); +//! # fn main() -> Result<(), Box> { +//! let mut handlebars = Handlebars::new(); //! -//! let data = serde_json::json!({"value": "lower camel case"}); -//! assert_eq!(handlebars.render_template("This is {{lowerCamelCase value}}", &data)?, -//! "This is lowerCamelCase".to_owned()); +//! let data = serde_json::json!({"value": "lower camel case"}); +//! assert_eq!( +//! handlebars.render_template("This is {{lowerCamelCase value}}", &data)?, +//! "This is lowerCamelCase".to_owned() +//! ); //! # Ok(()) //! # } //! # } diff --git a/src/macros.rs b/src/macros.rs index 7483ad99d..f33cccf39 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -13,27 +13,24 @@ /// # Examples /// /// ```rust -/// #[macro_use] extern crate handlebars; -/// #[macro_use] extern crate serde_json; -/// +/// # use handlebars::{handlebars_helper, Handlebars}; +/// # use serde_json::json; /// handlebars_helper!(is_above_10: |x: u64| x > 10); /// handlebars_helper!(is_above: |x: u64, { compare: u64 = 10 }| x > compare); /// -/// # fn main() { -/// # -/// let mut handlebars = handlebars::Handlebars::new(); +/// # fn main() -> Result<(), Box> { +/// let mut handlebars = Handlebars::new(); /// handlebars.register_helper("is-above-10", Box::new(is_above_10)); /// handlebars.register_helper("is-above", Box::new(is_above)); /// /// let result = handlebars -/// .render_template("{{#if (is-above-10 12)}}great!{{else}}okay{{/if}}", &json!({})) -/// .unwrap(); +/// .render_template("{{#if (is-above-10 12)}}great!{{else}}okay{{/if}}", &json!({}))?; /// assert_eq!(&result, "great!"); +/// /// let result2 = handlebars -/// .render_template("{{#if (is-above 12 compare=10)}}great!{{else}}okay{{/if}}", &json!({})) -/// .unwrap(); +/// .render_template("{{#if (is-above 12 compare=10)}}great!{{else}}okay{{/if}}", &json!({}))?; /// assert_eq!(&result2, "great!"); -/// # } +/// # Ok(()) } /// ``` #[macro_export] From c10a0287cc37c012b5c4265e6e53451a4d06d8c1 Mon Sep 17 00:00:00 2001 From: Milo Moisson Date: Wed, 14 Aug 2024 10:57:20 +0200 Subject: [PATCH 2/2] docs: other issue --- src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index fa6002f2b..9a560cffb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -229,7 +229,7 @@ //! //! #### Escaping //! -//! As per the handlebars spec, output using `{{expression}}` is escaped by default (to be precise, the characters `&"<>'`=_` are replaced by their respective html / xml entities). However, since the use cases of a rust template engine are probably a bit more diverse than those of a JavaScript one, this implementation allows the user to supply a custom escape function to be used instead. For more information see the `EscapeFn` type and `Handlebars::register_escape_fn()` method. In particular, `no_escape()` can be used as the escape function if no escaping at all should be performed. +//! As per the handlebars spec, output using `{{expression}}` is escaped by default (to be precise, the characters ``&"<>'`=_`` are replaced by their respective html / xml entities). However, since the use cases of a rust template engine are probably a bit more diverse than those of a JavaScript one, this implementation allows the user to supply a custom escape function to be used instead. For more information see the `EscapeFn` type and `Handlebars::register_escape_fn()` method. In particular, `no_escape()` can be used as the escape function if no escaping at all should be performed. //! //! ### Custom Helper //!