bashly 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33745534735d1a93f143a68939db55de17d618457b6873e948149317671f772d
-  data.tar.gz: 4ab52cd6f154cce246454d924fb898e8a092b1d7bb6e171dc9ff95d8dccc46c2
+  metadata.gz: d40ad6e14ab17c88a939cea3be81f4b72fe8383021478d94c93328c4842fb395
+  data.tar.gz: 4cb84c229411360da7633dd4ad4a15bb53bfdf49fba81e82aecbf88ec3422d72
 SHA512:
-  metadata.gz: f15b8e87c30fcb1bbec774ac101ef3f3225313df181bc78ab1786baa833e0c972ac01c4f451d20c2661c8383d3924fce182f737aa4f0579edfd27e3f006fa511
-  data.tar.gz: 7c51c2fd0b9564ba1be0e6a7b71b01176bbdc936da9d5382479ecbffee7671dd06e3c3c6172647b1c40d0d09d03ab347fecfe5f7464d1e0b90a4b49094116a88
+  metadata.gz: cb14645de6f614ce24393820591f6917bd92a7c41c48f14456b789183648c8031653c0304f8e59a2c43fecd7a4f0ed0e9ab4cf6a5092f0e5bd742de157af7b0c
+  data.tar.gz: b1b9fca567512ade4957a9b484d853b871f2c2edbefb267fc0c8fdbea8e5c2b1c5792cc011e04b60d07dc9e09b62996e18c826fd67902d28549e505bce8c30ce

data/README.md

@@ -119,36 +119,42 @@ Configuration Reference
 
 ### Command options
 
-With the exception of `version` and `commands` (which define subcommands),
-everything else in this section is suitable both for the main script, and for
-any subcommand you define using `commands`.
+Unless otherwise specified, these definitiona can be used for both the root
+command and subcommands (under the `commands` definition).
 
 ```yaml
 # The name of the script or subcommand
 name: myscript
 
+# An additional, optional name - usually used to denote a one letter 
+# variation of the command name
+# Applicable only in subcommands
+short: m
+
 # The header text to display when using --help
 # This can have multiple lines. In this case, the first line will be used as
 # summary wherever appropriate.
 help: a sample script generated with bashly
 
 # The string to display when using --version
+# Applicable only in the main command
 version: 0.1.0
 
 # Specify an array of examples to show when using --help
+# Each example can have multiple lines.
 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 the array of subcommands to generate.
 # Each subcommand will have its own args and flags.
-# If this is provided, then you cannot provide flags or args for the main
-# script.
+# If this is provided, you cannot provide flags or args for the main script.
 commands: 
 - ...
 
@@ -185,8 +191,7 @@ bash function.
 name: user
 
 # The message to display when using --help.
-# This can have multiple lines, but it is recommended to keep lines shorter
-# than ~70 characters, to avoid text wrapping in narrower terminals.
+# This can have multiple lines.
 help: Username to use for logging in
 
 # Specify if this argument is required.
@@ -216,8 +221,7 @@ long: --output
 short: -o
 
 # The text to display when using --help
-# This can have multiple lines, but it is recommended to keep lines shorter
-# than ~70 characters, to avoid text wrapping in narrower terminals.
+# This can have multiple lines.
 help: Specify the output directory
 
 # If the flag requires an argument, specify its name here.
@@ -227,6 +231,13 @@ arg: directory
 required: true
 ```
 
+
+Real World Examples
+--------------------------------------------------
+
+- [Rush][rush] - a Personal Package Manager
+
+
 Contributing / Support
 --------------------------------------------------
 
@@ -234,4 +245,4 @@ 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

data/lib/bashly/commands/generate.rb

@@ -36,8 +36,9 @@ module Bashly
       end
 
       def create_all_command_files
-        command.commands.each do |subcommand|
-          file = "#{Settings.source_dir}/#{subcommand.full_name.to_underscore}_command.sh"
+        command.deep_commands.each do |subcommand|
+          next if subcommand.commands.any?
+          file = "#{Settings.source_dir}/#{subcommand.filename}"
           content = subcommand.render :default_script
           create_file file, content
         end

data/lib/bashly/concerns/renderable.rb

@@ -1,3 +1,5 @@
+require 'erb'
+
 module Bashly
   module Renderable
     def render(view)

data/lib/bashly/extensions/string.rb

@@ -1,20 +1,27 @@
-require 'erb'
-require 'ostruct'
-
 class String
+  def escape_newlines
+    gsub "\n", "\\n"
+  end
+
   def indent(offset)
     return self unless offset > 0
     split("\n").indent(offset).join("\n")
   end
 
-  def to_underscore!
-    gsub!(/(.)([A-Z])/,'\1_\2')
-    gsub!(' ', '_')
-    downcase!
+  def to_underscore
+    gsub(/(.)([A-Z])/,'\1_\2').gsub(' ', '_').downcase
   end
 
-  def to_underscore
-    dup.tap { |s| s.to_underscore! }
+  def wrap(length = 80)
+    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
+      end
+    end * "\n"
   end
 
 end

data/lib/bashly/models/argument.rb

@@ -1,18 +1,9 @@
 module Bashly
   module Models
     class Argument < Base
-      def optional
-        !required
-      end
-
       def usage_string
         required ? name.upcase : "[#{name.upcase}]"
       end
-
-      def summary
-        return "" unless help
-        help.split("\n").first
-      end
     end
   end
 end

data/lib/bashly/models/base.rb

@@ -26,13 +26,24 @@ module Bashly
         verify if respond_to? :verify
       end
 
+      def optional
+        !required
+      end
+
+      def summary
+        help.empty? ? "" : help.split("\n").first
+      end
+
+      def help
+        options['help'] ||= ''
+      end
+
       def method_missing(method_name, *arguments, &block)
         key = method_name.to_s
         respond_to?(method_name) ? options[key] : super
       end
 
       def respond_to?(method_name, include_private = false)
-        # options.has_key?(method_name.to_s) || super
         OPTION_KEYS.include?(method_name) || super
       end
     end

data/lib/bashly/models/command.rb

@@ -1,6 +1,15 @@
 module Bashly
   module Models
     class Command < Base
+      # Returns the name to be used as an action.
+      # - If it is the root command, the action is "root"
+      # - Else, it is all the parents, except the first tone (root) joined
+      #   by space. For example, for a command like "docker container run"
+      #   the action name is "container run".
+      def action_name
+        parents.any? ? (parents[1..-1] + [name]).join(' ') : "root"
+      end
+
       # Returns all the possible aliases for this command
       def aliases
         short ? [name, short] : [name]
@@ -28,11 +37,30 @@ module Bashly
       def commands
         return [] unless options["commands"]
         options["commands"].map do |options|
-          options['parent_name'] = full_name
+          options['parents'] = parents + [name]
           command = Command.new options
         end
       end
 
+      # Returns a flat array containing all the commands in this tree.
+      # This includes self + children + grandchildres + ...
+      def deep_commands
+        result = []
+        commands.each do |command|
+          result << command
+          if command.commands.any?
+            result += command.deep_commands
+          end
+        end
+        result
+      end
+
+      # Returns the bash filename that is expected to hold the user code
+      # for this command
+      def filename
+        "#{action_name.to_underscore}_command.sh"
+      end
+
       # Returns an array of Flags
       def flags
         return [] unless options["flags"]
@@ -41,10 +69,15 @@ module Bashly
         end
       end
 
+      # Returns a unique name, suitable to be used in a bash function
+      def function_name
+        full_name.to_underscore
+      end
+
       # Returns the name of the command, including its parent name (in case
       # this is a subcommand)
       def full_name
-        parent_name ? "#{parent_name} #{name}" : name
+        parents.any? ? (parents + [name]).join(' ') : name
       end
 
       # Reads a file from the userspace (Settings.source_dir) and returns
@@ -52,7 +85,7 @@ module Bashly
       # If the file is not found, returns a string with a hint.
       def load_user_file(file, placeholder: true)
         path = "#{Settings.source_dir}/#{file}"
-        default_content = placeholder ? "# error: cannot load file" : ''
+        default_content = placeholder ? "echo \"error: cannot load file\"" : ''
 
         content = if File.exist? path
           File.read path
@@ -63,6 +96,12 @@ module Bashly
         "# :#{path}\n#{content}"
       end
 
+      # Returns an array of all parents. For example, the command 
+      # "docker container run" will have [docker, container] as its parents
+      def parents
+        options['parents'] || []
+      end
+
       # Returns an array of all the required Arguments
       def required_args
         args.select &:required
@@ -73,10 +112,9 @@ module Bashly
         flags.select &:required
       end
 
-      # Returns the first line of the help message
-      def summary
-        return "" unless help
-        help.split("\n").first
+      # Returns trus if this is the root command (no parents)
+      def root_command?
+        parents.empty?
       end
 
       # Returns a constructed string suitable for Usage pattern
@@ -109,10 +147,6 @@ module Bashly
         if args.any? or flags.any?
           raise ConfigurationError, "Error in the !txtgrn!#{full_name}!txtrst! command.\nThe !txtgrn!commands!txtrst! key cannot be at the same level as the !txtgrn!args!txtrst! or !txtgrn!flags!txtrst! keys."
         end
-
-        if parent_name
-          raise ConfigurationError, "Error in the !txtgrn!#{full_name}!txtrst! command.\nNested commands are not supported."
-        end
       end
 
     end

data/lib/bashly/models/flag.rb

@@ -11,15 +11,6 @@ module Bashly
         end
       end
 
-      def optional
-        !required
-      end
-
-      def summary
-        return "" unless help
-        help.split("\n").first
-      end
-
       def usage_string(extended: false)
         result = [aliases.join(", ")]
         result << arg.upcase if arg

data/lib/bashly/templates/lib/config.sh

@@ -100,7 +100,6 @@ config_show() {
 #   done
 #
 config_keys() {
-  key=$1
   regex="^(.*)\s*="
 
   config_init
@@ -112,5 +111,5 @@ config_keys() {
       keys+=("$key")
     fi
   done < "$CONFIG_FILE"
-  echo ${keys[@]}
+  echo "${keys[@]}"
 }

data/lib/bashly/templates/strings.yml

@@ -7,8 +7,8 @@ examples: "Examples:"
 environment_variables: "Environment Variables:"
 
 # Fixed flags help text
-show_this_help: Show this help
-show_version_number: Show version number
+help_flag_text: Show this help
+version_flag_text: Show version number
 
 # Error messages
 flag_requires_an_argument: "%{long} requires an argument: %{usage}"

data/lib/bashly/version.rb

@@ -1,3 +1,3 @@
 module Bashly
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 end

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

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

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

@@ -10,17 +10,17 @@ case $action in
 <%= command.aliases.join " | " %> )
   action="<%= command.name %>"
   shift
-  <%= command.name %>_parse_args "$@"
+  <%= command.function_name %>_parse_args "$@"
   shift $#
   ;;    
 
 <%- end -%>
 * )
-  <%= name %>_usage
+  <%= function_name %>_usage
   exit 1
   ;;
 
 esac
 <%- else -%>
-action=root
+action="<%= action_name %>"
 <%- end -%>

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

@@ -1,4 +1,4 @@
 # :command.command_functions
-<%- commands.each do |command| -%>
-<%= command.render :function %>
+<%- deep_commands.each do |command| -%>
+<%= command.render :function unless command.commands.any? %>
 <%- end -%>

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

@@ -1,4 +1,4 @@
-echo "# this file is located in '<%= Settings.source_dir %>/<%= full_name.to_underscore %>_command.sh'"
+echo "# this file is located in '<%= "#{Settings.source_dir}/#{filename}" %>'"
 echo "# code for '<%= full_name %>' goes here"
 echo "# you can edit it freely and regenerate (it will not be overwritten)"
 inspect_args

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

@@ -1,13 +1,13 @@
 # :command.fixed_flag_filter
 case "$1" in
---version | -v ) 
+--version )
   version_command
   exit 1
   ;;
 
 --help | -h ) 
   long_usage=yes
-  <%= full_name.to_underscore %>_usage
+  <%= function_name %>_usage
   exit 1
   ;;
 

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

@@ -1,4 +1,4 @@
 # :command.function
-<%= full_name.to_underscore %>_command() {
-<%= load_user_file("#{full_name.to_underscore}_command.sh").indent 2 %>
+<%= function_name %>_command() {
+<%= load_user_file(filename).indent 2 %>
 }

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

@@ -1,5 +1,9 @@
 # :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 %>
@@ -8,5 +12,5 @@ parse_args() {
 }
 
 <%- commands.each do |command| %>
-<%= command.render 'parse_args_secondary' %>
+<%= command.render 'parse_args' %>
 <%- end -%>

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

@@ -4,13 +4,13 @@ run() {
   parse_args "$@"
 
   <%- condition = "if" -%>
-  <%- commands.each do |command| -%>
-  <%= condition %> [[ $action == "<%= command.name %>" ]]; then
+  <%- deep_commands.each do |command| -%>
+  <%= condition %> [[ $action == "<%= command.action_name %>" ]]; then
     if [[ ${args[--help]} ]]; then
       long_usage=yes
-      <%= command.full_name.to_underscore %>_usage
+      <%= command.function_name %>_usage
     else
-      <%= command.full_name.to_underscore %>_command
+      <%= command.function_name %>_command
     fi
   <% condition = "elif" %>
   <%- end -%>

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

@@ -1,9 +1,29 @@
 # :command.usage
-<%= full_name.to_underscore %>_usage() {
-  echo -e "<%= caption_string %>"
-  echo 
+<%= function_name %>_usage() {
+  if [[ -n $long_usage ]]; then
+    <%- if summary == help -%>
+    echo -e "<%= caption_string %>"
+    echo 
+    <%- else -%>
+    echo -e "<%= full_name %>"
+    echo 
+    echo -e "<%= help.wrap(78).indent(2).escape_newlines %>"
+    echo 
+    <%- end -%>
+  else
+    echo -e "<%= caption_string %>"
+    echo 
+  fi
   echo -e "<%= strings[:usage] %>"
   echo -e "  <%= usage_string %>"
+  <%- if commands.any? -%>
+  echo -e "  <%= full_name %> [command] --help | -h"
+  <%- else -%>
+  echo -e "  <%= full_name %> --help | -h"
+  <%- end -%>
+  <%- if root_command? -%>
+  echo -e "  <%= full_name %> --version"
+  <%- end -%>
   echo
 <%= render(:usage_commands).indent 2 if commands.any? %>
 

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

@@ -2,6 +2,6 @@
 echo -e "<%= strings[:environment_variables] %>"
 <%- environment_variables.each do |name, description| -%>
 echo "  <%= name %>"
-echo "    <%= description %>"
+echo -e "<%= description.wrap(76).indent(4).escape_newlines %>"
 <%- end -%>
 echo

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

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

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

@@ -1,7 +1,9 @@
 # :command.usage_fixed_flags
 echo "  --help, -h"
-echo -e "    <%= strings[:show_this_help] %>"
+echo -e "    <%= strings[:help_flag_text] %>"
 echo
+<%- if root_command? -%>
 echo "  --version"
-echo -e "    <%= strings[:show_version_number] %>"
+echo -e "    <%= strings[:version_flag_text] %>"
 echo
+<%- end -%>

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

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bashly
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-22 00:00:00.000000000 Z
+date: 2019-11-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colsole
@@ -101,7 +101,6 @@ files:
 - 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_secondary.erb
 - lib/bashly/views/command/parse_args_while.erb
 - lib/bashly/views/command/required_args_filter.erb
 - lib/bashly/views/command/required_flags_filter.erb

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

@@ -1,7 +0,0 @@
-# :command.parse_args_secondary
-<%= name %>_parse_args() {
-<%= render(:fixed_flags_filter).indent 2 %>
-<%= render(:required_args_filter).indent 2 %>
-<%= render(:required_flags_filter).indent 2 %>
-<%= render(:parse_args_while).indent 2 %>
-}