garden: add support for required variables

Add a "required variables" concept to garden. Variables can now
be defined using a YAML hash syntax with a "required" key
that will make garden abort its execution when the
variable resolves to an empty value.

Closes #21
Ref: https://gitlab.com/garden-rs/garden/-/issues/21

Author: davvid

doc/src/changelog.md

@@ -4,6 +4,12 @@
 
 **Features**:
 
+- Garden variables can now be defined as being *required* variables. A required variable
+must evaluate to a non-empty string. If a required variable evaluates to an empty value
+then an error is reported and execution is aborted.
+([#21](https://gitlab.com/garden-rs/garden/-/issues/21))
+
+
 - `garden ls -cc` now displays command recipes.
 
 **Development**:

doc/src/configuration.md

@@ -256,6 +256,45 @@ variables defined at the global scope.  Variables defined in garden scope
 override/replace variables defined in a tree scope.
 
 
+### Required Variables
+
+Required variables prevent empty values from being used at runtime.
+A variable can be defined as required using the YAML syntax below.
+
+```yaml
+variables:
+  # This is a required variable.
+  required-value:
+    required: true
+    value: ${default-value}
+    # The ${default-value} expression above might resolve to an empty value.
+    # Required variables prevent empty values from being used at runtime.
+
+  default-value: $ test -f garden.yaml && echo not empty
+  # This a normal variable using an exec expression that might result in an empty value.
+
+# Commands that use empty required variables are prevented from running.
+commands:
+  example: echo required-value = ${required-value}
+```
+
+A required variable is can be used just like a regular variable. The only difference is
+that it terminates `garden` when it evaluates to an empty value in the course of
+evaluating a garden command or expression.
+
+The `required-value` variable above is a required variable. When `default-value`
+evaluates to an empty value then an error will be reported and execution will be stopped
+right before the command that references the variable is run.
+
+Running `garden example` with the example configuration above will not execute the
+`echo` inside of the `example` garden command. An error will be reported before the
+command is run and `garden` will exit with exit code 65
+(`EX_DATAERR` from `/usr/include/sysexits.h`).
+
+You can specify values for (required) variables using the `--define | -D name=value`
+command-line arguments.
+
+
 ## Built-in variables
 
 Garden automatically defines some built-in variables that can be useful
@@ -275,6 +314,7 @@ that re-execute `garden`. These variables allow you to forward the user-specifie
 * **GARDEN_CMD_QUIET** -- `--quiet` when `--quiet` is specified, empty otherwise.
 * **GARDEN_CMD_VERBOSE** -- `-v`, `-vv` etc. when verbosity is increased, empty otherwise.
 
+
 ## Environment Variables
 
 The "environment" block defines variables that are stored in the environment.

src/cmds/init.rs

@@ -92,7 +92,8 @@ pub fn main(options: &cli::MainOptions, init_options: &mut InitOptions) -> Resul
     };
 
     let mut config = model::Configuration::new();
-    config.root = model::Variable::from_expr(init_options.root.clone());
+    config.root =
+        model::Variable::from_expr(constants::ROOT.to_string(), init_options.root.clone());
     config.root_path.clone_from(&dirname);
     config.path = Some(config_path.clone());
 

src/config/reader.rs

@@ -125,15 +125,21 @@ fn parse_recursive(
     // Provide GARDEN_ROOT.
     config.variables.insert(
         string!(constants::GARDEN_ROOT),
-        model::Variable::from_expr(config.root.get_expr().to_string()),
+        model::Variable::from_expr(
+            constants::GARDEN_ROOT.to_string(),
+            config.root.get_expr().to_string(),
+        ),
     );
 
     if let Some(config_path_raw) = config.dirname.as_ref() {
         // Calculate an absolute path for GARDEN_CONFIG_DIR.
         if let Ok(config_path) = path::canonicalize(config_path_raw) {
             config.variables.insert(
                 string!(constants::GARDEN_CONFIG_DIR),
-                model::Variable::from_expr(config_path.to_string_lossy().to_string()),
+                model::Variable::from_expr(
+                    constants::GARDEN_CONFIG_DIR.to_string(),
+                    config_path.to_string_lossy().to_string(),
+                ),
             );
         }
     }
@@ -156,6 +162,7 @@ fn parse_recursive(
     // override the same variables when also defined in an included garden file.
     let mut config_includes = Vec::new();
     if get_vec_variables(
+        constants::INCLUDES,
         &doc[constants::GARDEN][constants::INCLUDES],
         &mut config_includes,
     ) {
@@ -375,13 +382,13 @@ fn get_indexset_str(yaml: &Yaml, values: &mut StringSet) -> bool {
 }
 
 /// Construct a model::Variable from a ran YAML object.
-fn variable_from_yaml(yaml: &Yaml) -> Option<model::Variable> {
+fn variable_from_yaml(name: String, yaml: &Yaml) -> Option<model::Variable> {
     match yaml {
-        Yaml::String(yaml_str) => Some(model::Variable::from_expr(yaml_str.to_string())),
+        Yaml::String(yaml_str) => Some(model::Variable::from_expr(name, yaml_str.to_string())),
         Yaml::Array(yaml_array) => {
             // If we see an array we loop over so that the first value wins.
-            for array_value in yaml_array.iter().rev() {
-                return variable_from_yaml(array_value);
+            if let Some(array_value) = yaml_array.iter().next_back() {
+                return variable_from_yaml(name, array_value);
             }
 
             None
@@ -390,13 +397,30 @@ fn variable_from_yaml(yaml: &Yaml) -> Option<model::Variable> {
             // Integers are already resolved.
             let int_value = yaml_int.to_string();
 
-            Some(model::Variable::from_resolved_expr(int_value))
+            Some(model::Variable::from_resolved_expr(name, int_value))
         }
         Yaml::Boolean(yaml_bool) => {
             // Booleans are already resolved.
             let bool_value = syntax::bool_to_string(*yaml_bool);
 
-            Some(model::Variable::from_resolved_expr(bool_value))
+            Some(model::Variable::from_resolved_expr(name, bool_value))
+        }
+        Yaml::Hash(yaml_hash) => {
+            let required = yaml_hash
+                .get(&Yaml::String(constants::REQUIRED.to_string()))
+                .and_then(|v| v.as_bool())
+                .unwrap_or(false);
+            let value = yaml_hash
+                .get(&Yaml::String(constants::VALUE.to_string()))
+                .and_then(|v| v.as_str())
+                .unwrap_or_default()
+                .to_string();
+
+            if required {
+                Some(model::Variable::from_required_expr(name, value))
+            } else {
+                Some(model::Variable::from_expr(name, value))
+            }
         }
         _ => {
             // dump_node(yaml, 1, "");
@@ -406,8 +430,8 @@ fn variable_from_yaml(yaml: &Yaml) -> Option<model::Variable> {
 }
 
 // Extract a `Variable` from `yaml`. Return `false` when `yaml` is not a `Yaml::String`.
-fn get_variable(yaml: &Yaml, value: &mut model::Variable) -> bool {
-    if let Some(variable) = variable_from_yaml(yaml) {
+fn get_variable(name: String, yaml: &Yaml, value: &mut model::Variable) -> bool {
+    if let Some(variable) = variable_from_yaml(name, yaml) {
         *value = variable;
 
         true
@@ -417,17 +441,17 @@ fn get_variable(yaml: &Yaml, value: &mut model::Variable) -> bool {
 }
 
 /// Promote `Yaml::String` or `Yaml::Array<Yaml::String>` into a `Vec<Variable>`.
-fn get_vec_variables(yaml: &Yaml, vec: &mut Vec<model::Variable>) -> bool {
+fn get_vec_variables(name: &str, yaml: &Yaml, vec: &mut Vec<model::Variable>) -> bool {
     if let Yaml::Array(yaml_array) = yaml {
         for value in yaml_array {
-            if let Some(variable) = variable_from_yaml(value) {
+            if let Some(variable) = variable_from_yaml(name.to_string(), value) {
                 vec.push(variable);
             }
         }
         return true;
     }
 
-    if let Some(variable) = variable_from_yaml(yaml) {
+    if let Some(variable) = variable_from_yaml(name.to_string(), yaml) {
         vec.push(variable);
         return true;
     }
@@ -447,7 +471,7 @@ fn get_variables_map(yaml: &Yaml, map: &mut model::VariableMap) -> bool {
                         continue;
                     }
                 };
-                if let Some(variable) = variable_from_yaml(v) {
+                if let Some(variable) = variable_from_yaml(key.to_string(), v) {
                     map.insert(key, variable);
                 }
             }
@@ -469,15 +493,15 @@ fn get_multivariables(yaml: &Yaml, vec: &mut Vec<model::MultiVariable>) -> bool
             if let Yaml::Array(yaml_array) = v {
                 let mut variables = Vec::new();
                 for value in yaml_array {
-                    if let Some(variable) = variable_from_yaml(value) {
+                    if let Some(variable) = variable_from_yaml(key.to_string(), value) {
                         variables.push(variable);
                     }
                 }
                 vec.push(model::MultiVariable::new(key, variables));
                 continue;
             }
 
-            if let Some(variable) = variable_from_yaml(v) {
+            if let Some(variable) = variable_from_yaml(key.to_string(), v) {
                 let variables = vec![variable];
                 vec.push(model::MultiVariable::new(key, variables));
             }
@@ -501,15 +525,15 @@ fn get_multivariables_map(yaml: &Yaml, multivariables: &mut model::MultiVariable
                 if let Yaml::Array(yaml_array) = v {
                     let mut variables = Vec::new();
                     for value in yaml_array {
-                        if let Some(variable) = variable_from_yaml(value) {
+                        if let Some(variable) = variable_from_yaml(key.to_string(), value) {
                             variables.push(variable);
                         }
                     }
                     multivariables.insert(key, variables);
                     continue;
                 }
 
-                if let Some(variable) = variable_from_yaml(v) {
+                if let Some(variable) = variable_from_yaml(key.to_string(), v) {
                     let variables = vec![variable];
                     multivariables.insert(key, variables);
                 }
@@ -561,19 +585,19 @@ fn get_template(
         // templates:
         //   example: git://git.example.org/example/repo.git
         if get_str(value, &mut url) {
-            template
-                .tree
-                .remotes
-                .insert(string!(constants::ORIGIN), model::Variable::from_expr(url));
+            template.tree.remotes.insert(
+                constants::ORIGIN.to_string(),
+                model::Variable::from_expr(constants::ORIGIN.to_string(), url),
+            );
             return template;
         }
         // If a `<url>` is configured then populate the "origin" remote.
         // The first remote is "origin" by convention.
         if get_str(&value[constants::URL], &mut url) {
-            template
-                .tree
-                .remotes
-                .insert(string!(constants::ORIGIN), model::Variable::from_expr(url));
+            template.tree.remotes.insert(
+                string!(constants::ORIGIN),
+                model::Variable::from_expr(constants::URL.to_string(), url),
+            );
         }
     }
 
@@ -671,8 +695,8 @@ fn get_tree_from_url(name: &Yaml, url: &str) -> model::Tree {
         tree.is_bare_repository = true;
     }
     tree.remotes.insert(
-        string!(constants::ORIGIN),
-        model::Variable::from_expr(url.to_string()),
+        constants::ORIGIN.to_string(),
+        model::Variable::from_expr(constants::ORIGIN.to_string(), url.to_string()),
     );
 
     tree
@@ -686,15 +710,27 @@ fn get_tree_fields(value: &Yaml, tree: &mut model::Tree) {
     get_str(&value[constants::DEFAULT_REMOTE], &mut tree.default_remote);
     get_str_trimmed(&value[constants::DESCRIPTION], &mut tree.description);
     get_str_variables_map(&value[constants::REMOTES], &mut tree.remotes);
-    get_vec_variables(&value[constants::LINKS], &mut tree.links);
+    get_vec_variables(constants::LINKS, &value[constants::LINKS], &mut tree.links);
 
     get_multivariables(&value[constants::ENVIRONMENT], &mut tree.environment);
     get_multivariables_map(&value[constants::COMMANDS], &mut tree.commands);
 
-    get_variable(&value[constants::BRANCH], &mut tree.branch);
+    get_variable(
+        constants::BRANCH.to_string(),
+        &value[constants::BRANCH],
+        &mut tree.branch,
+    );
     get_variables_map(&value[constants::BRANCHES], &mut tree.branches);
-    get_variable(&value[constants::SYMLINK], &mut tree.symlink);
-    get_variable(&value[constants::WORKTREE], &mut tree.worktree);
+    get_variable(
+        constants::SYMLINK.to_string(),
+        &value[constants::SYMLINK],
+        &mut tree.symlink,
+    );
+    get_variable(
+        constants::WORKTREE.to_string(),
+        &value[constants::WORKTREE],
+        &mut tree.worktree,
+    );
 
     get_i64(&value[constants::DEPTH], &mut tree.clone_depth);
     get_bool(&value[constants::BARE], &mut tree.is_bare_repository);
@@ -706,7 +742,7 @@ fn get_tree_fields(value: &Yaml, tree: &mut model::Tree) {
         if get_str(&value[constants::URL], &mut url) {
             tree.remotes.insert(
                 tree.default_remote.to_string(),
-                model::Variable::from_expr(url),
+                model::Variable::from_expr(constants::URL.to_string(), url),
             );
         }
     }
@@ -803,7 +839,7 @@ fn get_str_variables_map(yaml: &Yaml, remotes: &mut model::VariableMap) {
         if let (Some(name_str), Some(value_str)) = (name.as_str(), value.as_str()) {
             remotes.insert(
                 name_str.to_string(),
-                model::Variable::from_expr(value_str.to_string()),
+                model::Variable::from_expr(name_str.to_string(), value_str.to_string()),
             );
         }
     }

src/constants.rs

@@ -130,6 +130,10 @@ pub const REMOTES: &str = "remotes";
 /// encountered.
 pub const REPLACE: &str = "replace";
 
+/// The "required" key in a variable hash definition causes the variable to require
+/// that it evaluate to a non-empty value.
+pub const REQUIRED: &str = "required";
+
 /// The "root" key in the garden block defines where trees are located and grown.
 pub const ROOT: &str = "root";
 
@@ -208,6 +212,9 @@ pub const URL: &str = "url";
 /// can use "$ exec" expressions to capture stdout from a command.
 pub const VARIABLES: &str = "variables";
 
+/// The "value" field in a Variable dict represents the variable's expression value.
+pub const VALUE: &str = "value";
+
 /// The "worktree" key in a tree block is used to refer to a parent
 /// tree that will be used to grow the tree using "git worktree add".
 pub const WORKTREE: &str = "worktree";