Merge pull request #37 from DannyBen/env-vars

Add support for required environment variables

Author: DannyBen

README.md

@@ -119,6 +119,15 @@ See the [examples](examples) folder for more examples.
 Configuration Reference
 --------------------------------------------------
 
+The `bashly.yml` configuration file consists of these types:
+
+- [Command](#command-options) - defines the root command as well as any 
+  subcommand.
+- [Argument](#argument-options) - defines positional arguments.
+- [Flag](#flag-options) - defines option flags.
+- [Environment Variable](#environment-variable-options) - defines 
+  environment variables required (or desired) by your script.
+
 ### Command options
 
 Unless otherwise specified, these definitiona can be used for both the root
@@ -149,11 +158,9 @@ examples:
 - myscript download
 - myscript download --force
 
-# Specify an array of environment variables needed by your script
-# This is used purely for displaying in the help text (when using --help)
-# The help for each variable can have multiple lines.
-environment_variable:
-  VARIABLE_NAME: Variable help text
+# Specify an array of environment variables needed by your script.
+environment_variables:
+- ... see below ...
 
 # Specify the array of subcommands to generate.
 # Each subcommand will have its own args and flags.
@@ -164,12 +171,12 @@ commands:
 # Specify the array of positional arguments this script needs.
 # If this is provided, then you cannot specify commands.
 args:
-- ...
+- ... see below ...
 
 # Specify the array of option flags this script needs.
 # If this is provided, then you cannot specify commands.
 flags:
-- ...
+- ... see below ...
 ```
 
 
@@ -208,8 +215,9 @@ required: true
 The below configuration generates this flag:
 
 ```
-   -o, --output DIRECTORY (required)
-     Specify the output directory
+  Options:
+    -o, --output DIRECTORY (required)
+      Specify the output directory
 ```
 
 The flag's value will be available to you as `${args[--output]}` in your 
@@ -234,6 +242,33 @@ arg: directory
 required: true
 ```
 
+### Environment Variable options
+
+The below configuration generates this environment variable usage text:
+
+```
+  Environment Variables:
+    SECRET_KEY (required)
+      Your API secret key
+```
+
+If an environment variable is defined as required (false by default), the
+execution of the script will be halted with a friendly error if it is not
+set.
+
+```yaml
+# The name of the variable (it will be automatically capitalized).
+name: secret_key
+
+# The message to display when using --help.
+# This can have multiple lines.
+help: Your API secret key
+
+# Specify if this variable is required.
+required: true
+```
+
+
 
 Real World Examples
 --------------------------------------------------

Runfile

@@ -35,6 +35,7 @@ def examples
     "examples/minimal/download",
     "examples/multiline/multi",
     "examples/subcommands/cli",
+    "examples/environment-variables/cli",
     "examples/yaml/yaml",
     "spec/fixtures/workspaces/short-flag/rush",
   ]

examples/colors/colorly

@@ -99,8 +99,8 @@ cyan_underlined() { echo -e "\e[4;36m$*\e[0m" ; }
 
 # :command.command_functions
 
-# :command.parse_args
-parse_args() {
+# :command.parse_requirements
+parse_requirements() {
   # :command.fixed_flag_filter
   case "$1" in
   --version )
@@ -115,11 +115,12 @@ parse_args() {
     ;;
 
   esac
+  # :command.environment_variables_filter
   # :command.command_filter
   action="root"
   # :command.required_args_filter
   # :command.required_flags_filter
-  # :command.parse_args_while
+  # :command.parse_requirements_while
   while [[ $# -gt 0 ]]; do
     key="$1"
     case "$key" in
@@ -130,7 +131,7 @@ parse_args() {
       ;;
 
     * )
-      # :command.parse_args_case
+      # :command.parse_requirements_case
       if [[ ! ${args[message]} ]]; then
         args[message]=$1
         shift
@@ -162,7 +163,7 @@ initialize() {
 # :command.run
 run() {
   declare -A args
-  parse_args "$@"
+  parse_requirements "$@"
 
   if [[ ${args[--version]} ]]; then
     version_command

examples/config-ini/configly

@@ -274,8 +274,8 @@ configly_list_command() {
   config_show
 }
 
-# :command.parse_args
-parse_args() {
+# :command.parse_requirements
+parse_requirements() {
   # :command.fixed_flag_filter
   case "$1" in
   --version )
@@ -290,6 +290,7 @@ parse_args() {
     ;;
 
   esac
+  # :command.environment_variables_filter
   # :command.command_filter
   action=$1
 
@@ -300,21 +301,21 @@ parse_args() {
   set | s )
     action="set"
     shift
-    configly_set_parse_args "$@"
+    configly_set_parse_requirements "$@"
     shift $#
     ;;    
 
   get | g )
     action="get"
     shift
-    configly_get_parse_args "$@"
+    configly_get_parse_requirements "$@"
     shift $#
     ;;    
 
   list | l )
     action="list"
     shift
-    configly_list_parse_args "$@"
+    configly_list_parse_requirements "$@"
     shift $#
     ;;    
 
@@ -326,7 +327,7 @@ parse_args() {
   esac
   # :command.required_args_filter
   # :command.required_flags_filter
-  # :command.parse_args_while
+  # :command.parse_requirements_while
   while [[ $# -gt 0 ]]; do
     key="$1"
     case "$key" in
@@ -337,7 +338,7 @@ parse_args() {
       ;;
 
     * )
-      # :command.parse_args_case
+      # :command.parse_requirements_case
       echo -e "invalid argument: $key"
       exit 1
       ;;
@@ -346,8 +347,8 @@ parse_args() {
   done
 }
 
-# :command.parse_args
-configly_set_parse_args() {
+# :command.parse_requirements
+configly_set_parse_requirements() {
   # :command.fixed_flag_filter
   case "$1" in
   --version )
@@ -362,6 +363,7 @@ configly_set_parse_args() {
     ;;
 
   esac
+  # :command.environment_variables_filter
   # :command.command_filter
   action="set"
   # :command.required_args_filter
@@ -381,7 +383,7 @@ configly_set_parse_args() {
     exit 1
   fi
   # :command.required_flags_filter
-  # :command.parse_args_while
+  # :command.parse_requirements_while
   while [[ $# -gt 0 ]]; do
     key="$1"
     case "$key" in
@@ -392,7 +394,7 @@ configly_set_parse_args() {
       ;;
 
     * )
-      # :command.parse_args_case
+      # :command.parse_requirements_case
       if [[ ! ${args[key]} ]]; then
         args[key]=$1
         shift
@@ -409,8 +411,8 @@ configly_set_parse_args() {
   done
 }
 
-# :command.parse_args
-configly_get_parse_args() {
+# :command.parse_requirements
+configly_get_parse_requirements() {
   # :command.fixed_flag_filter
   case "$1" in
   --version )
@@ -425,6 +427,7 @@ configly_get_parse_args() {
     ;;
 
   esac
+  # :command.environment_variables_filter
   # :command.command_filter
   action="get"
   # :command.required_args_filter
@@ -436,7 +439,7 @@ configly_get_parse_args() {
     exit 1
   fi
   # :command.required_flags_filter
-  # :command.parse_args_while
+  # :command.parse_requirements_while
   while [[ $# -gt 0 ]]; do
     key="$1"
     case "$key" in
@@ -447,7 +450,7 @@ configly_get_parse_args() {
       ;;
 
     * )
-      # :command.parse_args_case
+      # :command.parse_requirements_case
       if [[ ! ${args[key]} ]]; then
         args[key]=$1
         shift
@@ -461,8 +464,8 @@ configly_get_parse_args() {
   done
 }
 
-# :command.parse_args
-configly_list_parse_args() {
+# :command.parse_requirements
+configly_list_parse_requirements() {
   # :command.fixed_flag_filter
   case "$1" in
   --version )
@@ -477,11 +480,12 @@ configly_list_parse_args() {
     ;;
 
   esac
+  # :command.environment_variables_filter
   # :command.command_filter
   action="list"
   # :command.required_args_filter
   # :command.required_flags_filter
-  # :command.parse_args_while
+  # :command.parse_requirements_while
   while [[ $# -gt 0 ]]; do
     key="$1"
     case "$key" in
@@ -492,7 +496,7 @@ configly_list_parse_args() {
       ;;
 
     * )
-      # :command.parse_args_case
+      # :command.parse_requirements_case
       echo -e "invalid argument: $key"
       exit 1
       ;;
@@ -519,7 +523,7 @@ initialize() {
 # :command.run
 run() {
   declare -A args
-  parse_args "$@"
+  parse_requirements "$@"
 
   if [[ $action == "set" ]]; then
     if [[ ${args[--help]} ]]; then

examples/custom-includes/download

@@ -71,8 +71,8 @@ my_extra_function() {
 
 # :command.command_functions
 
-# :command.parse_args
-parse_args() {
+# :command.parse_requirements
+parse_requirements() {
   # :command.fixed_flag_filter
   case "$1" in
   --version )
@@ -87,11 +87,12 @@ parse_args() {
     ;;
 
   esac
+  # :command.environment_variables_filter
   # :command.command_filter
   action="root"
   # :command.required_args_filter
   # :command.required_flags_filter
-  # :command.parse_args_while
+  # :command.parse_requirements_while
   while [[ $# -gt 0 ]]; do
     key="$1"
     case "$key" in
@@ -102,7 +103,7 @@ parse_args() {
       ;;
 
     * )
-      # :command.parse_args_case
+      # :command.parse_requirements_case
       if [[ ! ${args[source]} ]]; then
         args[source]=$1
         shift
@@ -134,7 +135,7 @@ initialize() {
 # :command.run
 run() {
   declare -A args
-  parse_args "$@"
+  parse_requirements "$@"
 
   if [[ ${args[--version]} ]]; then
     version_command