16 unstable releases (3 breaking)
0.4.1 | May 1, 2021 |
---|---|
0.4.0 | Mar 11, 2021 |
0.3.0 | Jan 12, 2021 |
0.2.10 | Nov 19, 2020 |
0.2.7 | Jul 15, 2020 |
#152 in Template engine
49 downloads per month
Used in 2 crates
53KB
834 lines
guidon
guidon performs templating based on handlebars templating system.
Usage
Files to be handles needs to have an .hbs
extension. Folders and files names can be templatized too : {{folder/subfolder}}
The entry point is the Guidon structure.
Basic init
let mut guidon = Guidon::new(PathBuf::from("path/to/template/dir"));
let mut vars = BTreeMap::new();
vars.insert("key1".to_string(), "value1".to_string());
guidon.variables(vars);
guidon.apply_template("path/to/destination").unwrap();
With this initialization:
- guidon will use the vars map to find substitution values.
- guidon will parse the directory
path/to/template/dir/template
- the result will be written in
path/to/destination
TryNew init
guidon implements a TryNew trait to initialize from a dir or a git repo
TryNew from path
let mut guidon = Guidon::try_new("path/to/template/dir").unwrap();
With this initialization:
- guidon will init the substitution variables from
path/to/template/dir/variables.toml
- guidon will parse the directory
path/to/template/dir/template
let mut guidon = Guidon::try_new("path/to/template/dir/my_vars.toml").unwrap();
With this initialization:
- guidon will init the substitution variables from
path/to/template/dir/my_vars.toml
- guidon will parse the directory
path/to/template/dir
TryNew from CustomTemplate
Guidon can be provided with specific template file and directory to parse.
let custom = CustomTemplate {
dir_path: Path::new("path/to/template/dir"),
template_path: Path::new("path/to/my_vars.toml")
};
let mut guidon = Guidon::try_new(custom);
TryNew from git repo
let git = GitOptions::builder()
.repo("url/to/repo")
.build()
.unwrap();
let mut guidon = Guidon::try_new(git);
With this initialization
- guidon will clone the repo to a temporary directory
- guidon will init the substitutions variables from
tmp/dir/template.toml
- when applying template, guidon will parse the directory
tmp/dir/template
The git repo url could be in the form :
http[s]://[user[:password]]@uri/repo[.git]
where user and password must be part of the urlgit@uri:repo.git
. The key used must be loaded in an ssh-agent instance
Template variables
The configuration file is structured as follows :
# Key value pairs for template substitution
[variables]
test1 = "test 1"
test2 = "test 2"
Helpers
replace
. It's simply replace a string by another in the value.Tell me: {{replace my_var everybody world}}
withmy_var="Hello everybody !
will render asTell me: Hello world !
.append
. Simply append a string to the value.Tell me: {{append my_var "and everybody !"}}
withmy_var="Hello world"
will render asTell me: Hello world and everybody !
.prepend
. Prepend a string to the value.Tell me: {{prepend my_var "Sure, "}}
withmy_var="hello world"
will render asTell me: Sure, hello world
.up
: Uppercase the valuelow
: Lowercase the valuedefault
: default to given value if input is null or emptyTell me: {{default my_var "Oops"}}
withmy_var
not defined will render asTell me: Oops
encrypt
: Encrypt the data. The key must be provideddecrypt
: Decrypt the data
encrypt and decrypt helpers are provide with the
crypto
feature.
Callbacks
guidon offers the possiblity to provide two callbacks :
- a variables callback to operate on the variables before applying the template
- a render callback, which is called if a missing value is detected while rendering the template.
These callbacks could be use for user interaction, or default behaviour.
Variable callback
In this example, the callback will add " cb"
to every value.
let cb = |h: &mut BTreeMap<String, String>| {
h.iter_mut().for_each(|(_, v)| *v +=" cb");
};
let mut guidon = Guidon::new(PathBuf::from("template/path"));
guidon.set_variables_callback(cb);
Render callback
In this example, the callback will replace any missing value by the key concatenated with "-cb"
// this callback will add `-cb` to the key as a value
let cb = |h: String| {
let mut s = h.clone();
s.push_str("-cb");
s
};
let mut guidon = Guidon::new(PathBuf::from("template/path"));
guidon.set_render_callback(cb);
File and Directory names
Filnames and directory can also be templatized.
Super-{{my_var}}-content.txt
will render as Super-boring-content.txt
given my_var="boring"
.
If the content of the file is templatized, we have Super-{{my_var}}-content.txt.hbs
.//!
Logs
guidon uses the log facade.
License
This project is licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in guidon by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Generated with cargo readme
Dependencies
~4.5–7MB
~175K SLoC