+ helper functions

Author: Alexander Weber

.complate/config.yaml

@@ -1,18 +1,18 @@
-version: 0.10
+version: 0.11
 templates:
   zero:
     content:
       inline: |-
         {{ a.alpha }}
     values:
       a.alpha:
-        static: '"test"'
+        static: ALPHA
   one:
     content:
       file: ./.complate/templates/arbitraty-template-file.tpl
     values:
-      a.summary:
-        static: "random summary"
+      a.pwd:
+        env: "PWD"
   two:
     content:
       inline: |-
@@ -53,3 +53,14 @@ templates:
               display: bravo
               value:
                 shell: printf bravo
+      f.foxtrot:
+        env: "FOXTROT"
+  three:
+    content:
+      inline: |-
+        {{ _decode "dGVzdA==" }}
+    helpers:
+      "_decode":
+        shell: |-
+          printf "$(printf $VALUE | base64 -D)"
+    values: {}

docs/wiki/content/docs/command reference/_index.adoc

@@ -56,13 +56,15 @@ Either one of the `backend+` features (or both) MUST be enabled for `complate` t
 |Template|-t|--template|Skip the template selection by defining the used template from the configuration via this argument||stable
 |Backend|-b|--backend|Defines the backend for the user interaction.||`CLI` is stable. `UI` is experimental (feature = "backend+ui").
 |Value|-v|--value|Overrides a certain variable with a given string value. Specify the variable and value with an equals sign as separator|Multiple allowed. Example: <br/> `-v"variable=some arbitrary value"`|experimental
+|Helpers||--helpers|Enables helper functions.||experimental
 |===
 
 === Examples:
 
 * `complate render` +
 * `complate render -c .complate/alternative.yml` +
 * `complate -e render -c <(cat .complate/alternative.yaml) -bui -t0.default` +
+* `complate -e render -t three --helpers` +
 
 == Configuration file
 

docs/wiki/content/docs/configuration/_index.adoc

@@ -15,21 +15,21 @@ The `complate` configuration schema written in YAML. It includes a version numbe
 == Structure by example
 
 ```
-version: 0.10
+version: 0.11
 templates:
   zero:
     content:
       inline: |-
         {{ a.alpha }}
     values:
       a.alpha:
-        env: ALPHA
+        static: ALPHA
   one:
     content:
       file: ./.complate/templates/arbitraty-template-file.tpl
     values:
-      a.summary:
-        static: "random summary"
+      a.pwd:
+        env: "PWD"
   two:
     content:
       inline: |-
@@ -70,6 +70,18 @@ templates:
               display: bravo
               value:
                 shell: printf bravo
+      f.foxtrot:
+        env: "FOXTROT"
+  three:
+    content:
+      inline: |-
+        {{ _decode "dGVzdA==" }}
+    helpers:
+      "_decode":
+        shell: |-
+          printf "$(printf $VALUE | base64 -D)"
+    values: {}
+
 ```
 
 The first tag has the current version of the configuration schema. It needs to be equal to the major version number of the cli program. Since `complate` is still sub-one, the versioning is not yet stable and therefore, the major *and* minor version need to be equal to the ones of the cli program. +
@@ -94,3 +106,7 @@ You can resolve the value for each variable individual. Following options are av
 #### Shell security
 
 Since the `shell` value provider is able to run arbitrary shell commands, it is only allowed if and only if the `SHELL_TRUST` argument is explicitly set. See the `render` command reference for possible values for this setting. If *not* set, the provider will throw an unrecoverable error and the program will abort.
+
+### Helpers
+
+Helper functions can be used to modify a value that is encoded into the template itself. These functions can be defined freely. This functionality is experimental and requires the `--helpers` flag to be enabled. The value that is to be modified is given to the shell command via the environment variable "$VALUE".

src/args/mod.rs

@@ -14,13 +14,22 @@ impl CallArgs {
                     match args.backend {
                         #[cfg(feature = "backend+ui")]
                         Backend::UI => {
-                            return Err(Box::new(crate::error::NeedExperimentalFlag::default()))
+                            return Err(Box::new(crate::error::NeedExperimentalFlag::new(
+                                "to enable UI backend",
+                            )))
                         }
                         #[cfg(feature = "backend+cli")]
                         Backend::CLI => {}
                     };
                     if args.value_overrides.len() > 0 {
-                        return Err(Box::new(crate::error::NeedExperimentalFlag::default()));
+                        return Err(Box::new(crate::error::NeedExperimentalFlag::new(
+                            "to enable value overrides",
+                        )));
+                    }
+                    if args.helpers {
+                        return Err(Box::new(crate::error::NeedExperimentalFlag::new(
+                            "to enable helpers",
+                        )));
                     }
                     #[allow(unreachable_code)]
                     Ok(())
@@ -46,6 +55,7 @@ pub struct RenderArguments {
     pub configuration: String,
     pub template: Option<String>,
     pub value_overrides: std::collections::HashMap<String, String>,
+    pub helpers: bool,
     pub shell_trust: ShellTrust,
     pub strict: bool,
     pub backend: Backend,
@@ -127,6 +137,13 @@ impl ClapArgumentLoader {
                     .multiple(false)
                     .required(false)
                     .takes_value(true))
+                .arg(clap::Arg::with_name("helpers")
+                    .long("helpers")
+                    .value_name("HELPERS")
+                    .help("Enables handlebar helpers.")
+                    .multiple(false)
+                    .required(false)
+                    .takes_value(false))
                 .arg(clap::Arg::with_name("backend")
                     .short("b")
                     .long("backend")
@@ -218,6 +235,8 @@ impl ClapArgumentLoader {
                     None => Backend::UI,
                 };
 
+                let helpers = x.is_present("helpers");
+
                 Ok(CallArgs {
                     privileges,
                     command: Command::Render(RenderArguments {
@@ -227,6 +246,7 @@ impl ClapArgumentLoader {
                         shell_trust,
                         strict,
                         backend,
+                        helpers,
                     }),
                 })
             }

src/config/mod.rs

@@ -11,6 +11,14 @@ pub struct Template {
     pub content: Content,
     #[serde(default)]
     pub values: std::collections::BTreeMap<String, VariableDefinition>,
+    #[serde(default)]
+    pub helpers: std::collections::BTreeMap<String, Helper>,
+}
+
+#[derive(Debug, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub struct Helper {
+    pub shell: String,
 }
 
 #[derive(Debug, serde::Serialize, serde::Deserialize)]
@@ -52,82 +60,74 @@ pub enum VariableDefinition {
     },
 }
 
-impl Config {
-    pub fn new(version: String) -> Self {
-        Self {
-            version,
-            templates: std::collections::BTreeMap::new(),
-        }
-    }
-}
-
-impl Template {
-    pub fn new(content: Content) -> Self {
-        Self {
-            content,
-            values: std::collections::BTreeMap::new(),
-        }
-    }
-}
-
 pub async fn default_config() -> String {
-    r###"version: 0.10
+    r###"version: 0.11
 templates:
-    zero:
-        content:
-            inline: |-
-                {{ a.alpha }}
-        values:
-            a.alpha:
-                env: ALPHA
-    one:
-        content:
-            file: ./.complate/templates/arbitraty-template-file.tpl
-        values:
-            a.summary:
-                env: "random summary"
-    two:
-        content:
-            inline: |-
-                {{ a.alpha }}
-                {{ b.bravo }}
-                {{ c.charlie }}
-                {{ d.delta }}
-                {{ e.echo }}
-        values:
-            a.alpha:
-              prompt: "alpha"
-            b.bravo:
-              shell: "printf bravo"
-            c.charlie:
-              static: "charlie"
-            d.delta:
-                select:
-                    text: Select the version level that shall be incremented
-                    options:
-                      alpha:
-                        display: alpha
-                        value:
-                          static: alpha
-                      bravo:
-                        display: bravo
-                        value:
-                          shell: printf bravo
-            e.echo:
-                check:
-                    text: Select the components that are affected
-                    separator: ", "
-                    options:
-                      alpha:
-                        display: alpha
-                        value:
-                          static: alpha
-                      bravo:
-                        display: bravo
-                        value:
-                          shell: printf bravo
-            f.foxtrot:
-                env: "FOXTROT"
+  zero:
+    content:
+      inline: |-
+        {{ a.alpha }}
+    values:
+      a.alpha:
+        static: ALPHA
+  one:
+    content:
+      file: ./.complate/templates/arbitraty-template-file.tpl
+    values:
+      a.pwd:
+        env: "PWD"
+  two:
+    content:
+      inline: |-
+        {{ a.alpha }}
+        {{ b.bravo }}
+        {{ c.charlie }}
+        {{ d.delta }}
+        {{ e.echo }}
+    values:
+      a.alpha:
+        prompt: "alpha"
+      b.bravo:
+        shell: "printf bravo"
+      c.charlie:
+        static: "charlie"
+      d.delta:
+        select:
+          text: Select the version level that shall be incremented
+          options:
+            alpha:
+              display: alpha
+              value:
+                static: alpha
+            bravo:
+              display: bravo
+              value:
+                shell: printf bravo
+      e.echo:
+        check:
+          text: Select the components that are affected
+          separator: ", "
+          options:
+            alpha:
+              display: alpha
+              value:
+                static: alpha
+            bravo:
+              display: bravo
+              value:
+                shell: printf bravo
+      f.foxtrot:
+        env: "FOXTROT"
+  three:
+    content:
+      inline: |-
+        {{ _decode "dGVzdA==" }}
+    helpers:
+      "_decode":
+        shell: |-
+          printf "$(printf $VALUE | base64 -D)"
+    values: {}
+
 "###
     .to_owned()
 }

src/render/mod.rs

@@ -14,6 +14,7 @@ pub async fn render(
     args: &crate::args::RenderArguments,
     template: &str,
     values: &BTreeMap<String, String>,
+    helpers: &BTreeMap<String, crate::config::Helper>,
 ) -> Result<String, Box<dyn std::error::Error>> {
     fn recursive_add(
         namespace: &mut std::collections::VecDeque<String>,
@@ -52,6 +53,35 @@ pub async fn render(
     if args.strict {
         hb.set_strict_mode(true);
     }
+
+    if args.helpers {
+        for helper in helpers {
+            let h_func = move |h: &handlebars::Helper,
+                               _: &handlebars::Handlebars,
+                               _: &handlebars::Context,
+                               _: &mut handlebars::RenderContext,
+                               out: &mut dyn handlebars::Output|
+                  -> handlebars::HelperResult {
+                let param = h.param(0).unwrap();
+                // dbg!(param);
+                let cmd = helper.1.shell.to_owned();
+
+                let output = std::process::Command::new("sh")
+                    .arg("-c")
+                    .arg(cmd)
+                    .env("VALUE", param.value().as_str().unwrap())
+                    .output()?;
+                if output.status.code().unwrap() != 0 {
+                    return Err(handlebars::RenderError::new("failed to get command status"));
+                }
+
+                out.write(String::from_utf8(output.stdout).unwrap().as_str())?;
+                Ok(())
+            };
+            hb.register_helper(helper.0, Box::new(h_func))
+        }
+    }
+
     let rendered_template = hb.render_template(template, &values_json).unwrap();
     Ok(rendered_template)
 }
@@ -120,7 +150,7 @@ pub async fn select_and_render(
         &invoke_options.backend,
     )
     .await?;
-    render(&invoke_options, &template_str, &values).await
+    render(&invoke_options, &template_str, &values, &template.helpers).await
 }
 
 #[async_trait]

test/config.yaml

@@ -1,4 +1,4 @@
-version: 0.10
+version: 0.11
 templates:
     test:
         content: