bashly 0.4.0 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14ee3d9cf49b4497ffbb7e374894cc0cfe18e1a1493a58c638cf4fd8896f30e2
-  data.tar.gz: 18dd37e6cfc3efd1f3c3d103f943e5ba8db4b414b2b26bed1bb096728c40cd1d
+  metadata.gz: 3b9f48152171cac044c5f26ec11f6fcdad64d9bb5fcf3363ab23a609d24c5b3b
+  data.tar.gz: 7ffcba2d9cc3448f0e08972086c5518dfc7d5c0b2969f5f112045b6b5f114f4f
 SHA512:
-  metadata.gz: 2564fbacc1cd7584e6a0a4da943a25fa70bb51e01a935e18e1c15cb98f3a95e75147f404f858f294df26e18499233e1f82d99f3b344a8464e8ecfccd90c5a0e2
-  data.tar.gz: d638eff5ef4a4d407b558ba153e199ede105fe34b23ee00b7c8961c843cd8e5ef23e21de1396c92b6f3742f9ec7585f02ac182ccd19329b0008f5c2f5b702cc7
+  metadata.gz: 6fe841722c54b62f72ddce5afdd8448feb30e973a034e623146981b1166be57826238eec5d5e2ac18e3d8357872b5305709110302ae13a7ce5130a0aa46d3a87
+  data.tar.gz: 6d93748b46b22c2e42f5abcd8751e99454545da4293e7a8deeca28869be8df4eccc980d21ca4e4e2acb6b682a2b5451fddc5e339759f40bbb4202e15923cdceb

data/README.md

@@ -1,8 +1,7 @@
 <div align='center'>
 <img src='logo.svg' width=280>
 
-Bashly - Bash CLI Framework and Generator
-==================================================
+# Bashly - Bash CLI Framework and Generator
 
 Create beautiful bash scripts from simple YAML configuration
 
@@ -16,10 +15,28 @@ Create beautiful bash scripts from simple YAML configuration
 
 </div>
 
+## Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [Installation](#installation)
+- [Prerequisites](#prerequisites)
+- [What is Bashly](#what-is-bashly)
+- [Usage](#usage)
+  - [Using the input arguemnts in your code](#using-the-input-arguemnts-in-your-code)
+- [Examples](#examples)
+  - [Sample configuraiton for a script without commands](#sample-configuraiton-for-a-script-without-commands)
+  - [Sample configuraiton for a script with commands](#sample-configuraiton-for-a-script-with-commands)
+- [Configuration Reference](#configuration-reference)
+  - [Command options](#command-options)
+  - [Argument options](#argument-options)
+  - [Flag options](#flag-options)
+  - [Environment Variable options](#environment-variable-options)
+- [Real World Examples](#real-world-examples)
+- [Contributing / Support](#contributing--support)
+
 ---
 
-Installation
---------------------------------------------------
+## Installation
 
 ```shell
 $ gem install bashly
@@ -31,15 +48,13 @@ or with Docker:
 $ alias bashly='docker run --rm -it --volume "$PWD:/app" dannyben/bashly'
 ```
 
-Prerequisites
---------------------------------------------------
+## Prerequisites
 
 The bash scripts generated by bashly require bash 4 or higher due to heavy
 use of associative arrays.
 
 
-What is Bashly
---------------------------------------------------
+## What is Bashly
 
 Bashly is a command line application (written in Ruby) that lets you generate
 feature-rich bash command line tools.
@@ -68,8 +83,7 @@ Bahsly is responsible for:
   - **YAML parsing**.
   - and more.
 
-Usage
---------------------------------------------------
+## Usage
 
 In an empty directory, create a sample configuration file by running
 
@@ -99,9 +113,46 @@ Finally, edit the files in the `src` folder. Each of your script's commands
 get their own file. Once you edit, run `bashly generate` again to merge the
 content from your functions back into the script.
 
+### Using the input arguemnts in your code
+
+In order to access the parsed arguments in any of your partial scripts, you
+may simply access the `$args` associative array.
+
+For example:
+
+1. Generate a minimal configuration with `bashly init --minimal`
+2. Generate the bash script with `bashly generate`
+3. Run the script with `./download hello --force`
 
-Examples
---------------------------------------------------
+You will notice that all the arguments of the associative array are printed 
+on screen. This is done by the `inspect_args` function that was inserted into
+the generated partial script `src/root_command.sh`.
+
+You can now access these variables by modifying `sec/root_command.sh` like
+this:
+
+
+```bash
+# src/root_command.sh
+source_url=${args[source]}
+force=${args[--force]}
+
+if [[ $force ]]; then
+  echo "downloading $source_url with --force"
+else
+  echo "downloading $source_url"
+fi
+```
+
+After editing the file, run `bashly generate` (or `bashly g` for short) and
+run:
+
+```
+$ ./download a --force
+downloading a with --force
+```
+
+## Examples
 
 The `bashly.yml` file can be set up to generate two types of scripts:
 
@@ -129,8 +180,7 @@ See the [examples](examples) folder for more examples.
 
 
 
-Configuration Reference
---------------------------------------------------
+## Configuration Reference
 
 The `bashly.yml` configuration file consists of these types:
 
@@ -146,19 +196,19 @@ The `bashly.yml` configuration file consists of these types:
 Unless otherwise specified, these definitiona can be used for both the root
 command and subcommands (under the `commands` definition).
 
-
  Option    | Description
 -----------|-------------
 `name`     | The name of the script or subcommand.
 `short`    | An additional, optional pattern - usually used to denote a one letter variation of the command name. You can add `*` as a suffix, to denote a "starts with" pattern - for example `short: m*`. *Applicable only in subcommands*.
 `help`     | The header text to display when using `--help`. This option can have multiple lines. In this case, the first line will be used as summary wherever appropriate.
 `version`  | The string to display when using `--version`. *Applicable only in the main command*.
-`default`  | Setting this to `yes` on any command, will make unrecognized command line arguments to be passed to this command. *Applicable only in subcommands*.
+`default`  | Setting this to `true` on any command, will make unrecognized command line arguments to be passed to this command. *Applicable only in subcommands*.
 `examples` | Specify an array of examples to show when using `--help`. Each example can have multiple lines.
 `environment_variables` | Specify an array of environment variables needed by your script. 
 `commands` | Specify the array of commands. Each command will have its own args and flags. Note: if `commands` is provided, you cannot specify flags or args at the same level.
 `args`     | Specify the array of positional arguments this script needs.
 `flags`    | Specify the array of option flags this script needs.
+`catch_all` | Specify that this command should allow for additional arbitrary arguments or flags. It can be set in one of three ways:<br>- Set to `true` to just enable it.<br>- Set to a string, to use this string in the usage help text.<br>- Set to a hash containing `label` and `help` keys, to show a detailed help for it when running with `--help`.
 `dependencies` | Specify an array of any required external dependencies (commands). The script execution will be halted with a friendly error unless all dependency commands exist.
 `group`    | In case you have many commands, use this option to specify a caption to display before this command. This option is purely for display purposes, and needs to be specified only for the first command in each group.
 
@@ -173,6 +223,7 @@ bash function.
 `help`     | The message to display when using `--help`. Can have multiple lines.
 `required` | Specify if this argument is required. Note that once you define an optional argument (without required: true) then you cannot define required arguments after it.
 `default`  | The value to use in case it is not provided by the user. Implies that this argument is optional.
+`allowed`  | Limit the allowed values by providing an array.
 
 ### Flag options
 
@@ -188,6 +239,7 @@ short form).
 `arg`      | If the flag requires an argument, specify its name here.
 `required` | Specify if this flag is required.
 `default`  | The value to use in case it is not provided by the user. Implies that this flag is optional, and only makes sense when the flag has an argument.
+`allowed`  | For flags with an argument, you can limit the allowed values by providing an array.
 
 #### Special handling for -v and -h
 
@@ -210,16 +262,14 @@ set.
 `required` | Specify if this variable is required.
 
 
-Real World Examples
---------------------------------------------------
+## Real World Examples
 
 - [Rush][rush] - a Personal Package Manager
 - [Alf][alf] - a generator for bash aliases and sub-aliases
 - [git-changelog][git-changelog] - a change log generator
 
 
-Contributing / Support
---------------------------------------------------
+## Contributing / Support
 
 If you experience any issue, have a question or a suggestion, or if you wish
 to contribute, feel free to [open an issue][issues].

data/lib/bashly/commands/generate.rb

@@ -3,14 +3,18 @@ module Bashly
     class Generate < Base
       help "Generate the bash script and required files"
 
-      usage "bashly generate [--force]"
+      usage "bashly generate [--force --wrap FUNCTION]"
       usage "bashly generate (-h|--help)"
 
       option "-f --force", "Overwrite existing files"
+      option "-w --wrap FUNCTION", "Wrap the entire script in a function so it can also be sourced"
 
       environment "BASHLY_SOURCE_DIR", "The path containing the bashly configuration and source files [default: src]"
       environment "BASHLY_TARGET_DIR", "The path to use for creating the bash script [default: .]"
 
+      example "bashly generate --force"
+      example "bashly generate --wrap my_function"
+
       def run
         create_user_files
         create_master_script
@@ -54,12 +58,15 @@ module Bashly
       end
 
       def create_master_script
-        master_script = command.render('master_script').lint
-        File.write master_script_path, master_script
+        File.write master_script_path, script.code
         FileUtils.chmod "+x", master_script_path
         say "created !txtgrn!#{master_script_path}"
       end
 
+      def script
+        @script ||= Models::Script.new(command, args['--wrap'])
+      end
+
       def master_script_path
         "#{Settings.target_dir}/#{command.name}"
       end

data/lib/bashly/commands/preview.rb

@@ -11,7 +11,8 @@ module Bashly
       def run
         config = Config.new "#{Settings.source_dir}/bashly.yml"
         command = Models::Command.new(config)
-        puts command.render 'master_script'
+        script = Models::Script.new command
+        puts script.code
       end
     end
   end

data/lib/bashly/models/base.rb

@@ -6,10 +6,12 @@ module Bashly
       attr_reader :options
 
       OPTION_KEYS = %i[
+        allowed
         arg
+        catch_all
+        default
         dependencies
         description
-        default
         environment_variables
         examples
         flags

data/lib/bashly/models/command.rb

@@ -28,6 +28,29 @@ module Bashly
         help ? "#{full_name} - #{summary}" : full_name
       end
 
+      # Returns a label for the catch_all directive
+      def catch_all_label
+        return nil unless catch_all
+
+        if catch_all.is_a? String
+          "#{catch_all.upcase}..."
+        elsif catch_all.is_a?(Hash) and catch_all['label'].is_a?(String)
+          "#{catch_all['label'].upcase}..."
+        else
+          "..."
+        end
+      end
+
+      def catch_all_help
+        return nil unless catch_all
+
+        if catch_all.is_a?(Hash) and catch_all['help'].is_a?(String)
+          catch_all['help']
+        else
+          nil
+        end
+      end
+
       # Returns only the names of the Commands
       def command_names
         commands.map &:name
@@ -159,6 +182,7 @@ module Bashly
           result << arg.usage_string
         end
         result << "[options]" unless flags.empty?
+        result << "[#{catch_all_label}]" if catch_all
         result.join " "
       end
 
@@ -175,6 +199,16 @@ module Bashly
         verify_commands if commands.any?
       end
 
+      # Returns an array of all the args with a whitelist
+      def whitelisted_args
+        args.select &:allowed
+      end
+
+      # Returns an array of all the flags with a whitelist arg
+      def whitelisted_flags
+        flags.select &:allowed
+      end
+
     private
 
       def verify_commands

data/lib/bashly/models/script.rb

@@ -0,0 +1,33 @@
+module Bashly
+  module Models
+    class Script
+      include Renderable
+
+      attr_reader :command, :function_name
+
+      def initialize(command, function_name = nil)
+        @command, @function_name = command, function_name
+      end
+
+      def code
+        if function_name
+          result = [header, render('wrapper')].join "\n"
+        else
+          result = [header, body].join "\n"
+        end
+
+        result.lint
+      end
+
+    private
+
+      def header
+        @header ||= render('header')
+      end
+
+      def body
+        @body ||= command.render('master_script')
+      end
+    end
+  end
+end

data/lib/bashly/templates/strings.yml

@@ -15,6 +15,7 @@ command_shortcut: "Shortcut: %{short}"
 default_command_summary: "%{summary} (default)"
 required: "(required)"
 default: "Default: %{value}"
+allowed: "Allowed: %{values}"
 
 # Fixed flags help text
 help_flag_text: Show this help
@@ -28,3 +29,5 @@ 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}"
+disallowed_flag: "%{name} must be one of: %{allowed}"
+disallowed_argument: "%{name} must be one of: %{allowed}"

data/lib/bashly/version.rb

@@ -1,3 +1,3 @@
 module Bashly
-  VERSION = "0.4.0"
+  VERSION = "0.4.4"
 end

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

@@ -1,6 +1,9 @@
 # :argument.usage
 echo "  <%= name.upcase %>"
 printf "<%= help.wrap(76).indent(4).sanitize_for_print %>\n"
+<%- if allowed -%>
+printf "    <%= strings[:allowed] % { values: allowed.join(', ') } -%>\n"
+<%- end -%>
 <%- if default -%>
 printf "    <%= strings[:default] % { value: default } -%>\n"
 <%- end -%>

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

@@ -1,5 +1,19 @@
 # :command.inspect_args
 inspect_args() {
-  echo args:
-  for k in "${!args[@]}"; do echo "- \${args[$k]} = ${args[$k]}"; done
+  readarray -t sorted_keys < <(printf '%s\n' "${!args[@]}" | sort)
+  if (( ${#args[@]} )); then
+    echo args:
+    for k in "${sorted_keys[@]}"; do echo "- \${args[$k]} = ${args[$k]}"; done
+  else
+    echo args: none
+  fi
+
+  if (( ${#other_args[@]} )); then
+    echo
+    echo other_args:
+    echo "- \${other_args[*]} = ${other_args[*]}"
+    for i in "${!other_args[@]}"; do
+      echo "- \${other_args[$i]} = ${other_args[$i]}"
+    done
+  fi
 }

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

@@ -1,7 +1,3 @@
-#!/usr/bin/env bash
-# This script was generated by bashly (https://github.com/DannyBen/bashly)
-# Modifying it manually is not recommended
-
 <%= render :root_command if commands.empty? %>
 <%= render :version_command %>
 <%= render :usage %>

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

@@ -12,6 +12,7 @@ parse_requirements() {
 <%= render(:required_flags_filter).indent 2 %>
 <%= render(:parse_requirements_while).indent 2 %>
 <%= render(:default_assignments).indent 2 %>
+<%= render(:whitelist_filter).indent 2 %>
 }
 
 <%- commands.each do |command| %>

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

@@ -8,9 +8,17 @@
 <%- condition = "elif" -%>
 <%- end -%>
 else
+<%- if catch_all -%>
+  other_args+=("$1")
+  shift
+<%- else -%>
   printf "<%= strings[:invalid_argument] %>\n" "$key"
   exit 1
+<%- end -%>
 fi
+<%- elsif catch_all -%>
+  other_args+=("$1")
+  shift
 <%- else -%>
 printf "<%= strings[:invalid_argument] %>\n" "$key"
 exit 1

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

@@ -8,9 +8,15 @@ while [[ $# -gt 0 ]]; do
   <%- end -%>
 
   -* )
+<%- if catch_all -%>
+    other_args+=("$1")
+    shift
+    ;;
+<%- else -%>
     printf "<%= strings[:invalid_flag] %>\n" "$key"
     exit 1
     ;;
+<%- end -%>
 
   * )
 <%= render(:parse_requirements_case).indent 4 %>

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

@@ -1,6 +1,7 @@
 # :command.run
 run() {
   declare -A args
+  declare -a other_args
   parse_requirements "$@"
 
   <%- condition = "if" -%>
@@ -14,12 +15,7 @@ run() {
     fi
   <% condition = "elif" %>
   <%- end -%>
-  <%= condition %> [[ ${args[--version]} ]]; then
-    version_command
-  elif [[ ${args[--help]} ]]; then
-    long_usage=yes
-    <%= name %>_usage
-  elif [[ $action == "root" ]]; then
+  <%= condition %> [[ $action == "root" ]]; then
     root_command
   fi
 }

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

@@ -37,7 +37,7 @@
     printf "<%= strings[:options] %>\n"
 <%= render(:usage_fixed_flags).indent 4 %>
 <%= render(:usage_flags).indent 4 if flags.any? %>
-<%= render(:usage_args).indent 4 if args.any? %>
+<%= render(:usage_args).indent 4 if args.any? or catch_all_help %>
 <%= render(:usage_environment_variables).indent 4 if environment_variables.any? %>
 <%= render(:usage_examples).indent 4 if examples %>
 

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

@@ -1,6 +1,14 @@
 # :command.usage_args
 printf "<%= strings[:arguments] %>\n"
+<%- if args.any? -%>
 
 <%- args.each do |arg| -%>
 <%= arg.render(:usage) %>
 <%- end -%>
+<%- end -%>
+<%- if catch_all_help -%>
+
+echo "  <%= catch_all_label %>"
+printf "<%= catch_all_help.wrap(76).indent(4).sanitize_for_print %>\n"
+echo
+<%- end -%>

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

@@ -0,0 +1,13 @@
+# :command.whitelist_filter
+<%- whitelisted_args.each do |arg| -%>
+if [[ ! ${args[<%= arg.name %>]} =~ ^(<%= arg.allowed.join '|' %>)$ ]]; then
+  printf "%s\n" "<%= strings[:disallowed_argument] % { name: arg.name, allowed: arg.allowed.join(', ') } %>"
+  exit 1
+fi
+<%- end -%>
+<%- whitelisted_flags.each do |flag| -%>
+if [[ ! ${args[<%= flag.name %>]} =~ ^(<%= flag.allowed.join '|' %>)$ ]]; then
+  printf "%s\n" "<%= strings[:disallowed_flag] % { name: flag.name, allowed: flag.allowed.join(', ') } %>"
+  exit 1
+fi
+<%- end -%>

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

@@ -1,7 +1,7 @@
 # :flag.case
 <%= aliases.join " | " %> )
   <%- if arg -%>
-  if [[ $2 && $2 != -* ]]; then
+  if [[ $2 ]]; then
     args[<%= name %>]="$2"
     shift
     shift

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

@@ -1,6 +1,9 @@
 # :flag.usage
 echo "  <%= usage_string extended: true %>"
 printf "<%= help.wrap(76).indent(4).sanitize_for_print %>\n"
+<%- if allowed -%>
+printf "    <%= strings[:allowed] % { values: allowed.join(', ') } -%>\n"
+<%- end -%>
 <%- if default -%>
 printf "    <%= strings[:default] % { value: default } -%>\n"
 <%- end -%>

data/lib/bashly/views/script/header.erb

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# This script was generated by bashly (https://github.com/DannyBen/bashly)
+# Modifying it manually is not recommended

data/lib/bashly/views/script/wrapper.erb

@@ -0,0 +1,6 @@
+# :script.wrapper
+<%= function_name %>() {
+<%= body.indent 2 %>
+}
+
+(return 0 2>/dev/null) || <%= function_name %> "$@"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bashly
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.4
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-21 00:00:00.000000000 Z
+date: 2021-06-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colsole
@@ -80,6 +80,7 @@ files:
 - lib/bashly/models/command.rb
 - lib/bashly/models/environment_variable.rb
 - lib/bashly/models/flag.rb
+- lib/bashly/models/script.rb
 - lib/bashly/polyfills/hash.rb
 - lib/bashly/settings.rb
 - lib/bashly/templates/bashly.yml
@@ -120,9 +121,12 @@ 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/command/whitelist_filter.erb
 - lib/bashly/views/environment_variable/usage.erb
 - lib/bashly/views/flag/case.erb
 - lib/bashly/views/flag/usage.erb
+- lib/bashly/views/script/header.erb
+- lib/bashly/views/script/wrapper.erb
 homepage: https://github.com/dannyben/bashly
 licenses:
 - MIT
@@ -142,7 +146,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.16
 signing_key: 
 specification_version: 4
 summary: Bash Command Line Tool Generator