bashly 0.4.2 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d486637f9d7ec6604d0495aec9f2396f69153f8cd193c126d51bc7dbc329a62
-  data.tar.gz: 5c58b05ad9ccb84d432c42228b7594e678b033555e55ea275948d4e70be118c7
+  metadata.gz: ca34648c628c4e7fe167d5f5b0d253792e9b4d3c494b253ed68d0127e4935572
+  data.tar.gz: 5247da7780a8424dd0a808ace6d182ed4284597e094122d94a8716bfca8f343b
 SHA512:
-  metadata.gz: 02fd6e6c50c5d370dde3d50047b0b6d317454c3d48531222711c6341c6e93d263cafa6a7d541bb939ff44a36b6025c9c8411e8f3820157c41e476312f4c64781
-  data.tar.gz: 031ea1db4c68fb6b780f01862b216178804cdc44f2e86fc66bc11f2910fff6d03ed250d7a01dd1c566d74c8f002ae6e9441bb13292f3e74620db455c993029e2
+  metadata.gz: 2145d1f4125d762c3d583f560c4caa9f4b98cfc2500e7e7b9ac977f4284a190a150a26da6e935c4e59c689f5efcd627924a10091cff0d4d91f00c3f60d26b943
+  data.tar.gz: 9df4695f43e4c57371f876de1dee3eab587bb227b7b0ee51d52d1772faf119cbd59cb117f5a1e3cbb06ef49b5796cd02b6fecba685b733aa35c51442fe9baf19

data/README.md

@@ -15,6 +15,7 @@ Create beautiful bash scripts from simple YAML configuration
 
 </div>
 
+
 ## Table of Contents
 
 - [Table of Contents](#table-of-contents)
@@ -22,20 +23,20 @@ Create beautiful bash scripts from simple YAML configuration
 - [Prerequisites](#prerequisites)
 - [What is Bashly](#what-is-bashly)
 - [Usage](#usage)
-  - [Using the input arguemnts in your code](#using-the-input-arguemnts-in-your-code)
+  - [Using the input arguments in your code](#using-the-input-arguments-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)
+- [Extensible Scripts](#extensible-scripts)
 - [Real World Examples](#real-world-examples)
 - [Contributing / Support](#contributing--support)
 
 ---
 
+
 ## Installation
 
 ```shell
@@ -83,8 +84,17 @@ Bahsly is responsible for:
   - **YAML parsing**.
   - and more.
 
+
 ## Usage
 
+The `bashly.yml` file can be set up to generate two types of scripts:
+
+1. Script with commands (for example, like `docker` or `git`).
+2. Script without commands (for example, like `ls`)
+
+This is detected automatically by the contents of the configuration: If it
+contains a `commands` definition, it will generate a script with commands.
+
 In an empty directory, create a sample configuration file by running
 
 ```shell
@@ -113,7 +123,7 @@ 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
+### Using the input arguments in your code
 
 In order to access the parsed arguments in any of your partial scripts, you
 may simply access the `$args` associative array.
@@ -152,32 +162,11 @@ $ ./download a --force
 downloading a with --force
 ```
 
-## Examples
-
-The `bashly.yml` file can be set up to generate two types of scripts:
-
-1. Script with commands (for example, like `docker` or `git`).
-2. Script without commands (for example, like `ls`)
 
-This is detected automatically by the contents of the configuration: If it
-contains a `commands` definition, it will generate a script with commands.
-
-
-### Sample configuraiton for a script without commands
-
-- Generate this script by running `bashly generate --minimal`
-- [See the initial sample bashly.yml file](examples/minimal/src/bashly.yml)
-- [See the generated bash script](examples/minimal/download)
-
-### Sample configuraiton for a script with commands
-
-- Generate this script by running `bashly generate`
-- [See the initial sample bashly.yml file](examples/commands/src/bashly.yml)
-- [See the generated bash script](examples/commands/cli)
-
-
-See the [examples](examples) folder for more examples.
+## Examples
 
+The [examples folder](examples#readme) contains many detailed and documented 
+example configuration files, with their output.
 
 
 ## Configuration Reference
@@ -193,24 +182,26 @@ The `bashly.yml` configuration file consists of these types:
 
 ### Command options
 
-Unless otherwise specified, these definitiona can be used for both the root
+Unless otherwise specified, these definitions 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 cause any unrecognized command line to be passed to this command. *Applicable only in subcommands*.
+`extensible` | Specify that this command can be [externally extended](#extensible-scripts). *Applicable only in the main command*.
 `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.
+`environment_variables` | Specify an array of [environment variables](#environment-variable-options) needed by your script. 
+`commands` | Specify the array of [commands](#command-options). 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](#argument-options) this script needs.
+`flags`    | Specify the array of option [flags](#flag-options) 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.
+`footer` | Add a custom message that will be displayed at the end of the `--help` text. 
 
 ### Argument options
 
@@ -247,9 +238,7 @@ The `-v` and `-h` flags will be used as the short options for `--version` and
 `--help` respectively **only if you are not using them in any of your own
 flags**.
 
-### Environment Variable options
-
-The below configuration generates this environment variable usage text:
+### Environment variable options
 
 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
@@ -262,6 +251,81 @@ set.
 `required` | Specify if this variable is required.
 
 
+## Extensible Scripts
+
+You may configure your generated bash script to delegate any unknown command
+to an external executable, by setting the `extensible` option to either `true`,
+or to a different external command.
+
+This is similar to how `git` works. When you execute `git whatever`, the `git`
+command will look for a file named `git-whatever` in the path, and execute it.
+
+Note that this option cannot be specified together with the `default` option,
+since both specify a handler for unknown commands.
+
+Bashly supports two operation modes.
+
+### Extension Mode (`extensible: true`)
+
+By setting `extensible` to `true`, a specially named executable will be called
+when an unknown command is called by the user.
+
+Given this `bashly.yml` configuration:
+
+```yaml
+name: myscript
+help: Example
+version: 0.1.0
+extensible: true
+
+commands:
+- name: upload
+  help: Upload a file
+```
+
+And this user command:
+
+```
+$ myscript something
+
+```
+
+The generated script will look for an executable named `myscript-something` 
+in the path. If found, it will be called.
+
+See the [extensible example](examples/extensible).
+
+
+### Delegate Mode (`extensible: <executable name>`)
+
+By setting `extensible` to any string, unknown command calls by the user will
+be delegated to the executable with that name.
+
+Given this `bashly.yml` configuration:
+
+```yaml
+name: mygit
+help: Example
+version: 0.1.0
+extensible: git
+
+commands:
+- name: push
+  help: Push to my repository
+```
+
+And this user command:
+
+```
+$ mygit status
+
+```
+
+The generated script will execute `git status`.
+
+See the [extensible-delegate example](examples/extensible-delegate).
+
+
 ## Real World Examples
 
 - [Rush][rush] - a Personal Package Manager
@@ -274,9 +338,9 @@ set.
 If you experience any issue, have a question or a suggestion, or if you wish
 to contribute, feel free to [open an issue][issues].
 
+
+
 [issues]: https://github.com/DannyBen/bashly/issues
 [rush]: https://github.com/DannyBen/rush-cli
 [alf]: https://github.com/DannyBen/alf
 [git-changelog]: https://github.com/DannyBen/git-changelog
-
-

data/lib/bashly/extensions/string.rb

@@ -16,7 +16,6 @@ class String
     strip!
     split("\n").collect! do |line|
       if line.length > length
-        line.gsub!(/([^\s]{#{length}})([^\s$])/, "\\1 \\2")
         line.gsub(/(.{1,#{length}})(\s+|$)/, "\\1\n").rstrip
       else
         line

data/lib/bashly/models/base.rb

@@ -8,12 +8,15 @@ module Bashly
       OPTION_KEYS = %i[
         allowed
         arg
+        catch_all
         default
         dependencies
         description
         environment_variables
         examples
+        extensible
         flags
+        footer
         group
         help
         long

data/lib/bashly/models/command.rb

@@ -28,6 +28,30 @@ 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
+
+      # Returns a used defined help string for the catch_all directive
+      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 +183,7 @@ module Bashly
           result << arg.usage_string
         end
         result << "[options]" unless flags.empty?
+        result << "[#{catch_all_label}]" if catch_all
         result.join " "
       end
 

data/lib/bashly/version.rb

@@ -1,3 +1,3 @@
 module Bashly
-  VERSION = "0.4.2"
+  VERSION = "0.5.1"
 end

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

@@ -0,0 +1,45 @@
+# :command.command_fallback
+<%- if default_command -%>
+"" )
+  <%= function_name %>_usage
+  exit 1
+  ;;
+
+* )
+  action="<%= default_command.name %>"
+  <%= default_command.function_name %>_parse_requirements "$@"
+  shift $#
+  ;;
+<%- elsif extensible.is_a? String -%>
+"" )
+  <%= function_name %>_usage
+  exit 1
+  ;;
+
+* )
+  if [[ -x "$(command -v "<%= extensible %>")" ]]; then
+    exec <%= extensible %> "$@"
+  else
+    <%= function_name %>_usage
+    exit 1
+  fi
+<%- elsif extensible -%>
+"" )
+  <%= function_name %>_usage
+  exit 1
+  ;;
+
+* )
+  if [[ -x "$(command -v "<%= function_name %>-$action")" ]]; then
+    shift
+    exec "<%= function_name %>-$action" "$@"
+  else
+    <%= function_name %>_usage
+    exit 1
+  fi
+<%- else -%>
+* )
+  <%= function_name %>_usage
+  exit 1
+  ;;
+<%- end -%>

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

@@ -15,25 +15,7 @@ case $action in
   ;;    
 
 <%- end -%>
-<%- if default_command -%>
-"" )
-  <%= function_name %>_usage
-  exit 1
-  ;;
-
-* )
-  action="<%= default_command.name %>"
-  <%= default_command.function_name %>_parse_requirements "$@"
-  shift $#
-  ;;
-
-<%- else -%>
-* )
-  <%= function_name %>_usage
-  exit 1
-  ;;
-
-<%- end -%>
+<%= render :command_fallback %>
 esac
 <%- else -%>
 action="<%= action_name %>"

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

@@ -0,0 +1,2 @@
+printf "<%= footer.gsub("\n", '\n').gsub('"', '\"') %>\n"
+echo

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

@@ -7,4 +7,13 @@ inspect_args() {
   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/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" -%>

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

@@ -37,9 +37,10 @@
     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 %>
+<%= render(:footer).indent 4 if footer %>
 
   fi
 }

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 -%>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bashly
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.1
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-03-04 00:00:00.000000000 Z
+date: 2021-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colsole
@@ -92,6 +92,7 @@ files:
 - lib/bashly/templates/strings.yml
 - lib/bashly/version.rb
 - lib/bashly/views/argument/usage.erb
+- lib/bashly/views/command/command_fallback.erb
 - lib/bashly/views/command/command_filter.erb
 - lib/bashly/views/command/command_functions.erb
 - lib/bashly/views/command/default_assignments.erb
@@ -101,6 +102,7 @@ files:
 - 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/footer.erb
 - lib/bashly/views/command/function.erb
 - lib/bashly/views/command/initialize.erb
 - lib/bashly/views/command/inspect_args.erb
@@ -146,7 +148,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.2.16
 signing_key: 
 specification_version: 4
 summary: Bash Command Line Tool Generator