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

// 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();
//! guidon.use_template_dir(false);
//! ```
//! 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 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}}`
//!
//! ## 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.
//!
mod errors;
#[cfg(feature = "git")]
mod git;
mod guidon;
mod helpers;

pub use crate::errors::{GuidonError, Result};
#[cfg(feature = "git")]
pub use crate::git::{GitOptions, GitOptionsBuilder};
pub use crate::guidon::{Guidon, TryNew};
use crate::helpers::*;