1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your // option. This file may not be copied, modified, or distributed // except according to those terms. //! ## guidon //! //! guidon performs templating based on [handlebars](https://handlebarsjs.com/) 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](struct.Guidon.html) structure. //! //! ### Basic init //! //! ```rust, no_run //! # use guidon::Guidon; //! # use std::collections::BTreeMap; //! # use std::path::PathBuf; //! //! 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 //! ```rust, no_run //! # use guidon::{Guidon, TryNew}; //! //! 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` //! //! ```rust, no_run //! # use guidon::{Guidon, TryNew}; //! //! 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. //! ```rust, no_run //! # use guidon::{CustomTemplate, Guidon, TryNew}; //! # use std::path::Path; //! 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 //! ```rust, no_run //! # use guidon::{{Guidon, TryNew, GitOptions}}; //! //! 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 url //! * `git@uri:repo.git`. The key used must be loaded in an *ssh-agent* instance //! //! ## Template variables //! The configuration file is structured as follows : //! ```toml //! # Key value pairs for template substitution //! [variables] //! test1 = "test 1" //! test2 = "test 2" //! ``` //! //! ## Helpers //! Several helpers are provided : //! * **replace** : to replace a string by an other in the input `{{replace input "from" "to"}}` //! * **append** : append a string at the end of the input `{{append input "prefix"}}` //! * **prepend** : prepend a string `{{prepend input "suffix"}}` //! * **up** : set input to uppercase `{{up input}}` //! * **down** : set input to lowercase `{{down input}}` //! * **encrypt** : encrypt a string `{{encrypt input}}` //! * **decrypt** : decrypt a string `{{decrypt input}}` //! //! > *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. //! ```rust, no_run //! # use guidon::Guidon; //! # use std::collections::BTreeMap; //! # use std::path::PathBuf; //! 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"` //! ```rust, no_run //! # use guidon::Guidon; //! # use std::collections::BTreeMap; //! # use std::path::PathBuf; //! //! // 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); //! ``` //! ## Logs //! guidon uses the log facade. //! #[cfg(feature = "crypto")] mod crypto; mod errors; #[cfg(feature = "git")] mod git; mod guidon; mod helpers; #[cfg(feature = "crypto")] pub use crate::crypto::{gdecrypt, gen_key, gencrypt}; pub use crate::errors::{GuidonError, Result}; #[cfg(feature = "git")] pub use crate::git::{GitOptions, GitOptionsBuilder}; pub use crate::guidon::{Guidon, TryNew, CustomTemplate}; use crate::helpers::*;