bashly 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30efdcbeb1d466ddb9a273e1faee68a2f2a2d4290d75e6ea405e594c60cf029d
-  data.tar.gz: 637e95e22f679ade3483129a473c3cb912c16db6c976a6eb49d47921ab2fd4c9
+  metadata.gz: b40fa2dc3cc6b3f0f65b961ea06dab0230eb0346eaa7c51575f12e27f16bcc3e
+  data.tar.gz: 704cc06b8d06539c123d2fabd450764fa8926705acc584ef47da87e5f2ab3e87
 SHA512:
-  metadata.gz: 6bfd470d14131da08363c8b2f65412c09487927213a1ce2afdef0d1ebf06f3c655718d55275baed2502bd6a4f7f9c5ed723f1970e56d196b5d42585d0e84dd63
-  data.tar.gz: b203ffe70e063a58f0e0fd3a0bfd4d5fff42ac4a9e23aaaa18ea68a89c2fd204a4aafb06fc13b23bf21084283b487fb207c84f46610242056be582e456283f41
+  metadata.gz: 6b5755ebda8ded8cc3a414063b8c9f7559b34fb5682d8f351f55f2be768ac4d39868cacca11c7b6a39741f3c00b13c8ee1f2d14d24307518f8e9954afabbe3d4
+  data.tar.gz: 540459bf266a62c289fd0fc0799f45e0e72bfbe3117dcf975ad623c022beba7327f97331d6a6539b69901ccf82fc2696a329622f0b7126951fc53cfdf583d0c7

data/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,18 @@ 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 ...
+
+# Specify an array of any required external dependencies (commands).
+# The script execution will be halted with a friendly error unless all
+# dependency commands exist.
+dependencies:
+- curl
 ```
 
 
@@ -208,8 +221,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 +248,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
 --------------------------------------------------

data/lib/bashly/extensions/string.rb

@@ -1,6 +1,6 @@
 class String
-  def escape_newlines
-    gsub "\n", "\\n"
+  def sanitize_for_print
+    gsub("\n", "\\n").gsub("\"", "\\\"")
   end
 
   def indent(offset)
@@ -9,7 +9,7 @@ class String
   end
 
   def to_underscore
-    gsub(/(.)([A-Z])/,'\1_\2').gsub(' ', '_').downcase
+    gsub(/(.)([A-Z])/,'\1_\2').gsub(/[\- ]/, '_').downcase
   end
 
   def wrap(length = 80)

data/lib/bashly/models/base.rb

@@ -7,6 +7,7 @@ module Bashly
 
       OPTION_KEYS = %i[
         arg
+        dependencies
         description
         environment_variables
         examples

data/lib/bashly/models/command.rb

@@ -55,6 +55,14 @@ module Bashly
         result
       end
 
+      # Returns an array of EnvironmentVariables
+      def environment_variables
+        return [] unless options["environment_variables"]
+        options["environment_variables"].map do |options|
+          EnvironmentVariable.new options
+        end
+      end
+
       # Returns the bash filename that is expected to hold the user code
       # for this command
       def filename
@@ -107,6 +115,11 @@ module Bashly
         args.select &:required
       end
 
+      # Returns an array of all the required EnvironmentVariables
+      def required_environment_variables
+        environment_variables.select &:required
+      end
+
       # Returns an array of all the required Flags
       def required_flags
         flags.select &:required

data/lib/bashly/models/environment_variable.rb

@@ -0,0 +1,11 @@
+module Bashly
+  module Models
+    class EnvironmentVariable < Base
+      def usage_string(extended: false)
+        result = [name.upcase]
+        result << "(required)" if required and extended
+        result.join " "
+      end
+    end
+  end
+end

data/lib/bashly/templates/bashly.yml

@@ -3,7 +3,8 @@ help: Sample application
 version: 0.1.0
 
 environment_variables:
-  API_KEY: Set your API key
+- name: api_key
+  help: Set your API key
 
 commands:
 - name: download
@@ -27,7 +28,8 @@ commands:
   - cli download example.com ./output -f
 
   environment_variables:
-    DEFAULT_TARGET_LOCATION: Set the default location to download to
+  - name: default_target_location
+    help: Set the default location to download to
 
 - name: upload
   short: u

data/lib/bashly/templates/strings.yml

@@ -16,4 +16,5 @@ invalid_argument: "invalid argument: %{arg}"
 invalid_flag: "invalid option: %{flag}"
 missing_required_argument: "missing required argument: %{arg}\\nusage: %{usage}"
 missing_required_flag: "missing required flag: %{usage}"
-
+missing_required_environment_variable: "missing required environment variable: %{var}"
+missing_dependency: "missing dependency: %{dependency}"

data/lib/bashly/version.rb

@@ -1,3 +1,3 @@
 module Bashly
-  VERSION = "0.2.4"
+  VERSION = "0.3.0"
 end

data/lib/bashly/views/argument/usage.erb

@@ -1,4 +1,4 @@
 # :argument.usage
 echo "  <%= name.upcase %>"
-echo -e "<%= help.wrap(76).indent(4).escape_newlines %>"
+echo -e "<%= help.wrap(76).indent(4).sanitize_for_print %>"
 echo

data/lib/bashly/views/command/command_filter.erb

@@ -10,7 +10,7 @@ case $action in
 <%= command.aliases.join " | " %> )
   action="<%= command.name %>"
   shift
-  <%= command.function_name %>_parse_args "$@"
+  <%= command.function_name %>_parse_requirements "$@"
   shift $#
   ;;    
 

data/lib/bashly/views/command/dependencies_filter.erb

@@ -0,0 +1,9 @@
+# :command.dependencies_filter
+<%- if dependencies -%>
+<%- dependencies.each do |dependency| -%>
+if ! [[ -x "$(command -v <%= dependency %>)" ]]; then
+  echo -e "<%= strings[:missing_dependency] % { dependency: dependency } -%>"
+  exit 1
+fi
+<%- end -%>
+<%- end -%>

data/lib/bashly/views/command/environment_variables_filter.erb

@@ -0,0 +1,9 @@
+# :command.environment_variables_filter
+<%- if required_environment_variables.any? -%>
+<%- required_environment_variables.each do |env_var| -%>
+if [[ -z "$<%= env_var.name.upcase %>" ]]; then
+  echo -e "<%= strings[:missing_required_environment_variable] % { var: env_var.name.upcase } -%>"
+  exit 1
+fi
+<%- end -%>
+<%- end -%>

data/lib/bashly/views/command/master_script.erb

@@ -8,7 +8,7 @@
 <%= render :inspect_args %>
 <%= render :user_lib if user_lib.any? %>
 <%= render :command_functions %>
-<%= render :parse_args %>
+<%= render :parse_requirements %>
 <%= render :initialize %>
 <%= render :run %>
 

data/lib/bashly/views/command/parse_requirements.erb

@@ -0,0 +1,18 @@
+# :command.parse_requirements
+<%- if root_command? -%>
+parse_requirements() {
+<%- else -%>
+<%= function_name %>_parse_requirements() {
+<%- end -%>
+<%= render(:fixed_flags_filter).indent 2 %>
+<%= render(:environment_variables_filter).indent 2 %>
+<%= render(:dependencies_filter).indent 2 %>
+<%= render(:command_filter).indent 2 %>
+<%= render(:required_args_filter).indent 2 %>
+<%= render(:required_flags_filter).indent 2 %>
+<%= render(:parse_requirements_while).indent 2 %>
+}
+
+<%- commands.each do |command| %>
+<%= command.render :parse_requirements %>
+<%- end -%>

data/lib/bashly/views/command/{parse_args_case.erb → parse_requirements_case.erb}

@@ -1,4 +1,4 @@
-# :command.parse_args_case
+# :command.parse_requirements_case
 <%- if args.any? -%>
 <%- condition = "if" -%>
 <%- args.each do |arg| -%>

data/lib/bashly/views/command/{parse_args_while.erb → parse_requirements_while.erb}

@@ -1,4 +1,4 @@
-# :command.parse_args_while
+# :command.parse_requirements_while
 while [[ $# -gt 0 ]]; do
   key="$1"
   case "$key" in
@@ -13,7 +13,7 @@ while [[ $# -gt 0 ]]; do
     ;;
 
   * )
-<%= render(:parse_args_case).indent 4 %>
+<%= render(:parse_requirements_case).indent 4 %>
     ;;
 
   esac

data/lib/bashly/views/command/run.erb

@@ -1,7 +1,7 @@
 # :command.run
 run() {
   declare -A args
-  parse_args "$@"
+  parse_requirements "$@"
 
   <%- condition = "if" -%>
   <%- deep_commands.each do |command| -%>

data/lib/bashly/views/command/usage.erb

@@ -7,7 +7,7 @@
     <%- else -%>
     echo -e "<%= full_name %>"
     echo 
-    echo -e "<%= help.wrap(78).indent(2).escape_newlines %>"
+    echo -e "<%= help.wrap(78).indent(2).sanitize_for_print %>"
     echo 
     <%- end -%>
   else
@@ -32,7 +32,7 @@
 <%= render(:usage_fixed_flags).indent 4 %>
 <%= render(:usage_flags).indent 4 if flags.any? %>
 <%= render(:usage_args).indent 4 if args.any? %>
-<%= render(:usage_environment_variables).indent 4 if environment_variables %>
+<%= render(:usage_environment_variables).indent 4 if environment_variables.any? %>
 <%= render(:usage_examples).indent 4 if examples %>
 
   fi

data/lib/bashly/views/command/usage_environment_variables.erb

@@ -1,7 +1,6 @@
 # :command.usage_environment_variables
 echo -e "<%= strings[:environment_variables] %>"
-<%- environment_variables.each do |name, description| -%>
-echo "  <%= name %>"
-echo -e "<%= description.wrap(76).indent(4).escape_newlines %>"
+
+<%- environment_variables.each do |env_var| -%>
+<%= env_var.render(:usage) %>
 <%- end -%>
-echo

data/lib/bashly/views/command/usage_examples.erb

@@ -2,6 +2,6 @@
 echo -e "<%= strings[:examples] %>"
 
 <%- examples.each do |example| -%>
-echo -e "<%= example.wrap(78).indent(2).escape_newlines %>"
+echo -e "<%= example.wrap(78).indent(2).sanitize_for_print %>"
 <%- end -%>
 echo

data/lib/bashly/views/environment_variable/usage.erb

@@ -0,0 +1,4 @@
+# :environment_variable.usage
+echo "  <%= usage_string extended: true %>"
+echo -e "<%= help.wrap(76).indent(4).sanitize_for_print %>"
+echo

data/lib/bashly/views/flag/usage.erb

@@ -1,4 +1,4 @@
 # :flag.usage
 echo "  <%= usage_string extended: true %>"
-echo -e "<%= help.wrap(76).indent(4).escape_newlines %>"
+echo -e "<%= help.wrap(76).indent(4).sanitize_for_print %>"
 echo

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bashly
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-26 00:00:00.000000000 Z
+date: 2019-11-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colsole
@@ -78,6 +78,7 @@ files:
 - lib/bashly/models/argument.rb
 - lib/bashly/models/base.rb
 - lib/bashly/models/command.rb
+- lib/bashly/models/environment_variable.rb
 - lib/bashly/models/flag.rb
 - lib/bashly/polyfills/hash.rb
 - lib/bashly/settings.rb
@@ -95,14 +96,16 @@ files:
 - lib/bashly/views/command/default_initialize_script.erb
 - lib/bashly/views/command/default_root_script.erb
 - lib/bashly/views/command/default_script.erb
+- lib/bashly/views/command/dependencies_filter.erb
+- lib/bashly/views/command/environment_variables_filter.erb
 - lib/bashly/views/command/fixed_flags_filter.erb
 - lib/bashly/views/command/function.erb
 - lib/bashly/views/command/initialize.erb
 - lib/bashly/views/command/inspect_args.erb
 - lib/bashly/views/command/master_script.erb
-- lib/bashly/views/command/parse_args.erb
-- lib/bashly/views/command/parse_args_case.erb
-- lib/bashly/views/command/parse_args_while.erb
+- lib/bashly/views/command/parse_requirements.erb
+- lib/bashly/views/command/parse_requirements_case.erb
+- lib/bashly/views/command/parse_requirements_while.erb
 - lib/bashly/views/command/required_args_filter.erb
 - lib/bashly/views/command/required_flags_filter.erb
 - lib/bashly/views/command/root_command.erb
@@ -116,6 +119,7 @@ files:
 - lib/bashly/views/command/usage_flags.erb
 - lib/bashly/views/command/user_lib.erb
 - lib/bashly/views/command/version_command.erb
+- lib/bashly/views/environment_variable/usage.erb
 - lib/bashly/views/flag/case.erb
 - lib/bashly/views/flag/usage.erb
 homepage: https://github.com/dannyben/bashly

data/lib/bashly/views/command/parse_args.erb

@@ -1,16 +0,0 @@
-# :command.parse_args
-<%- if root_command? -%>
-parse_args() {
-<%- else -%>
-<%= function_name %>_parse_args() {
-<%- end -%>
-<%= render(:fixed_flags_filter).indent 2 %>
-<%= render(:command_filter).indent 2 %>
-<%= render(:required_args_filter).indent 2 %>
-<%= render(:required_flags_filter).indent 2 %>
-<%= render(:parse_args_while).indent 2 %>
-}
-
-<%- commands.each do |command| %>
-<%= command.render 'parse_args' %>
-<%- end -%>