bashly 1.2.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5000e81ecf047c31547832097355e0d1b5de630041ef2533a80ce70f146e8282
-  data.tar.gz: 9c03b8ef9215a317ebfd75333304065c271e77296a55753de65e612f9d1a8432
+  metadata.gz: cde8d4a8294ffd7dee63567440b351ffbd67b69f1295306b20931b8f4328a77c
+  data.tar.gz: e99ca77abffd677b1469e145383ef74a90a28da29af88625d7bf378563909031
 SHA512:
-  metadata.gz: c6dc6b49075f6e250aec3204f6b9ff2bd6e4236da1bcc5229691565dcc8a4ff4c1d1c06a139c092eae33c61123753cdb542583a69596caf299f87c6ccf3d4f07
-  data.tar.gz: ab9d9fc13a779bfd4d71adbae49e66961c697a46e5cb386875dac1d9e1b021828a2821332f2687d16b87b3fb820cdc006b61d86e7425dd6fdb37ac7aceb12b33
+  metadata.gz: 3f33a67b5da7958d3dccc0e8ada2f5fb097d786fd35045e8a8148ac543ec1326e0d1da51c2b264b674ba1f8ffb1c5dc868dc2244afccc5b8d93c7429b68797c1
+  data.tar.gz: 9972faa37b1f14b4dd38be6c0d15a743640f065357b7a347299f3255a8f50377a580e64b284631ae99cf8eb1207045ce08eb4c9e65860d67827a55be435219e3

data/lib/bashly/commands/shell.rb

@@ -19,7 +19,7 @@ module Bashly
           terminal = MisterBin::Terminal.new runner, {
             autocomplete: autocomplete,
             show_usage:   true,
-            prompt:       "\n$> bashly ",
+            prompt:       '$ bashly ',
           }
 
           terminal.on('help') { runner.run %w[--help] }

data/lib/bashly/concerns/completions.rb

@@ -29,7 +29,7 @@ module Bashly
           end
         end
 
-        public_commands.each do |command|
+        visible_commands.each do |command|
           result.merge! command.completion_data(with_version: false)
         end
 
@@ -62,7 +62,7 @@ module Bashly
       end
 
       def completion_flag_names
-        public_flags.map(&:name) + public_flags.map(&:short)
+        visible_flags.map(&:name) + visible_flags.map(&:short)
       end
 
       def completion_allowed_args
@@ -73,7 +73,7 @@ module Bashly
         trivial_flags = %w[--help -h]
         trivial_flags += %w[--version -v] if with_version
         all = (
-          public_command_aliases + trivial_flags +
+          visible_command_aliases + trivial_flags +
           completion_flag_names + completion_allowed_args
         )
 

data/lib/bashly/config_validator.rb

@@ -231,6 +231,10 @@ module Bashly
           assert value['args'].last['repeatable'],
             "#{key}.args cannot contain a repeatable arg unless it is the last one"
         end
+
+        required_order = value['args'].map { |x| x['required'] ? true : false }
+        refute required_order.include_sequence?(false, true),
+          "#{key}.args cannot contain required arg after optional arg"
       end
 
       if value['expose']

data/lib/bashly/docs/env.yml

@@ -49,6 +49,16 @@ environment_variable.required:
   help: Specify that this variable is required.
   url: https://bashly.dannyb.co/configuration/environment-variable/#required
   example: |-
+    environment_variables:
     - name: api_key
       help: Your API key
       required: true
+
+environment_variable.validate:
+  help: Apply custom validation functions.
+
+  url: https://bashly.dannyb.co/configuration/environment-variable/#validate
+  example: |-
+    environment_variables:
+    - name: build_dir
+      validate: dir_exists

data/lib/bashly/docs/flag.yml

@@ -113,6 +113,29 @@ flag.long:
       short: -s
       help: Clone using SSH
 
+flag.needs:
+  help: Specify that this flag needs one or more additional flags. Use the long name of these needed flags.
+  url: https://bashly.dannyb.co/configuration/flag/#needs
+  example: |-
+    flags:
+    - long: --add
+      arg: alias
+
+      # When using --add, --command and --target must also be provided
+      needs: [--command, --target]
+
+    - long: --command
+      arg: command
+      help: Command for the alias
+      
+      # Note that this relationship is marked on both sides
+      needs: [--add]
+
+    - long: --target
+      arg: target
+      help: Where to add the alias
+      needs: [--add]
+
 flag.private:
   help: Specify that this flag should not be displayed in the help text.
   url: https://bashly.dannyb.co/configuration/flag/#private

data/lib/bashly/extensions/array.rb

@@ -13,4 +13,10 @@ class Array
   def nonuniq
     tally.select { |_key, count| count > 1 }.keys
   end
+
+  def include_sequence?(*elements)
+    return false if elements.empty?
+
+    each_cons(elements.size).any?(elements)
+  end
 end

data/lib/bashly/libraries/render/mandoc/mandoc.gtx

@@ -43,7 +43,7 @@ if extensible
 end
 >
 
-if public_commands.any?
+if visible_commands.any?
   grouped_commands.each do |group, commands|
     > {{ group.gsub(/:$/, '').upcase }}
     > ==================================================
@@ -127,6 +127,9 @@ if flags.any?
     if flag.conflicts
       > - Conflicts With: **{{ flag.conflicts.join(', ') }}**
     end
+    if flag.needs
+      > - Needs: **{{ flag.needs.join(', ') }}**
+    end
     >
   end
 end
@@ -147,11 +150,11 @@ if dependencies.any?
   end
 end
 
-if public_environment_variables.any?
+if visible_environment_variables.any?
   > ENVIRONMENT VARIABLES
   > ==================================================
   >
-  public_environment_variables.each do |environment_variable|
+  visible_environment_variables.each do |environment_variable|
     > {{ environment_variable.name.upcase }}
     > --------------------------------------------------
     >
@@ -183,7 +186,7 @@ end
 
 see_also = []
 see_also << parents.first if parents.any?
-see_also += public_commands.map { |x| x.full_name.to_hyphen } if public_commands.any?
+see_also += visible_commands.map { |x| x.full_name.to_hyphen } if visible_commands.any?
 see_also += x_mandoc_see_also if x_mandoc_see_also && x_mandoc_see_also.is_a?(Array)
 see_also.map! do |item|
   item.match(/(.+)(\(\d\))/) ? "**#{$1}**#{$2}" : "**#{item}**(1)"

data/lib/bashly/libraries/render/markdown/markdown.gtx

@@ -62,10 +62,10 @@ end
 
 # === Environment Variables
 
-if public_environment_variables.any?
+if visible_environment_variables.any?
   > ## Environment Variables
   >
-  public_environment_variables.each do |environment_variable|
+  visible_environment_variables.each do |environment_variable|
     attributes = environment_variable.required || environment_variable.default
 
     > #### *{{ environment_variable.name.upcase }}*
@@ -152,7 +152,8 @@ if flags.any?
   > ## Options
   >
   flags.each do |flag|
-    attributes = flag.required || flag.repeatable || flag.default || flag.allowed || flag.conflicts
+    attributes = flag.required || flag.repeatable || flag.default ||
+      flag.allowed || flag.conflicts || flag.needs
 
     > #### *{{ flag.usage_string }}*
     >
@@ -177,6 +178,9 @@ if flags.any?
       if flag.conflicts
         > | Conflicts With: | *{{ flag.conflicts.join(', ') }}*
       end
+      if flag.needs
+        > | Needs: | *{{ flag.needs.join(', ') }}*
+      end
       >
     end
   end

data/lib/bashly/libraries/settings/settings.yml

@@ -59,6 +59,11 @@ partials_extension: sh
 # required arguments
 show_examples_on_error: false
 
+# When using private commands, flags, or environment variables, you may set 
+# this option to a name of an environment variable that, if set, will reveal
+# all the private elements in the usage texts, as if they were public.
+private_reveal_key: ~
+
 # Display various usage elements in color by providing the name of the color
 # function. The value for each property is a name of a function that is
 # available in your script, for example: `green` or `bold`.

data/lib/bashly/libraries/strings/strings.yml

@@ -18,6 +18,8 @@ required: "(required)"
 repeatable: "(repeatable)"
 default: "Default: %{value}"
 allowed: "Allowed: %{values}"
+needs: "Needs: %{values}"
+conflicts: "Conflicts: %{values}"
 
 # Fixed flags help text
 help_flag_text: Show this help
@@ -25,6 +27,7 @@ version_flag_text: Show version number
 
 # Error messages
 flag_requires_an_argument: "%{name} requires an argument: %{usage}"
+flag_needs_another: "%{name} needs %{need}"
 invalid_argument: "invalid argument: %s"
 invalid_flag: "invalid option: %s"
 invalid_command: "invalid command: %s"
@@ -39,3 +42,4 @@ disallowed_argument: "%{name} must be one of: %{allowed}"
 disallowed_environment_variable: "%{name} environment variable must be one of: %{allowed}"
 unsupported_bash_version: "bash version 4 or higher is required"
 validation_error: "validation error in %s:\\n%s"
+environment_variable_validation_error: "validation error in environment variable %s:\\n%s"

data/lib/bashly/script/command.rb

@@ -2,6 +2,13 @@ module Bashly
   module Script
     class Command < Base
       include Completions::Command
+      include Introspection::Arguments
+      include Introspection::Commands
+      include Introspection::Dependencies
+      include Introspection::EnvironmentVariables
+      include Introspection::Examples
+      include Introspection::Flags
+      include Introspection::Visibility
 
       class << self
         def option_keys
@@ -39,15 +46,6 @@ module Bashly
         options['alias'].is_a?(String) ? [options['alias']] : options['alias']
       end
 
-      # Returns an array of Arguments
-      def args
-        return [] unless options['args']
-
-        options['args'].map do |options|
-          Argument.new options
-        end
-      end
-
       # Returns a string suitable to be a headline
       def caption_string
         help.empty? ? full_name : "#{full_name} - #{summary}"
@@ -58,123 +56,12 @@ module Bashly
         @catch_all ||= CatchAll.from_config options['catch_all']
       end
 
-      # Returns a full list of the Command names and aliases combined
-      def command_aliases
-        commands.map(&:aliases).flatten
-      end
-
-      # Returns a data structure for displaying subcommands help
-      def command_help_data
-        result = {}
-
-        public_commands.each do |command|
-          result[command.group_string] ||= {}
-          result[command.group_string][command.name] = { summary: command.summary_string }
-          next unless command.expose
-
-          command.public_commands.each do |subcommand|
-            result[command.group_string]["#{command.name} #{subcommand.name}"] = {
-              summary:   subcommand.summary_string,
-              help_only: command.expose != 'always',
-            }
-          end
-        end
-
-        result
-      end
-
-      # Returns only the names of the Commands
-      def command_names
-        commands.map(&:name)
-      end
-
-      # Returns an array of the Commands
-      def commands
-        return [] unless options['commands']
-
-        options['commands'].map do |options|
-          result = Command.new options
-          result.parents = parents + [name]
-          result.parent_command = self
-          result
-        end
-      end
-
-      # Returns a flat array containing all the commands in this tree.
-      # This includes children + grandchildren (recursive), and may include self
-      def deep_commands(include_self: false)
-        result = []
-        result << self if include_self
-        commands.each do |command|
-          result << command
-          if command.commands.any?
-            result += command.deep_commands
-          end
-        end
-        result
-      end
-
-      # If any of this command's subcommands has the default option set to
-      # true, this default command will be returned, nil otherwise.
-      def default_command
-        commands.find(&:default)
-      end
-
-      # Returns an array of all the default Args
-      def default_args
-        args.select(&:default)
-      end
-
-      # Returns an array of all the default Environment Variables
-      def default_environment_variables
-        environment_variables.select(&:default)
-      end
-
-      # Returns an array of all the default Flags
-      def default_flags
-        flags.select(&:default)
-      end
-
-      # Returns an array of Dependency objects
-      def dependencies
-        return [] unless options['dependencies']
-
-        @dependencies ||= options['dependencies'].map do |key, value|
-          Dependency.from_config key, value
-        end
-      end
-
-      # Returns an array of EnvironmentVariable objects
-      def environment_variables
-        return [] unless options['environment_variables']
-
-        options['environment_variables'].map do |options|
-          EnvironmentVariable.new options
-        end
-      end
-
-      # Returns an array of examples
-      def examples
-        return nil unless options['examples']
-
-        options['examples'].is_a?(Array) ? options['examples'] : [options['examples']]
-      end
-
       # Returns the filename that is expected to hold the user code for this
       # command
       def filename
         options['filename'] || implicit_filename
       end
 
-      # Returns an array of Flags
-      def flags
-        return [] unless options['flags']
-
-        options['flags'].map do |options|
-          Flag.new options
-        end
-      end
-
       # Returns a unique name, suitable to be used in a bash function
       def function_name
         options['function'] || full_name.to_underscore
@@ -186,12 +73,6 @@ module Bashly
         parents.any? ? (parents + [name]).join(' ') : name
       end
 
-      # Returns true if this command's flags should be considered as gloal
-      # flags, and cascade to subcommands
-      def global_flags?
-        flags.any? and commands.any?
-      end
-
       # Returns the string for the group caption
       def group_string
         if group
@@ -201,23 +82,6 @@ module Bashly
         end
       end
 
-      # Returns subcommands by group
-      def grouped_commands
-        result = {}
-
-        public_commands.each do |command|
-          result[command.group_string] ||= []
-          result[command.group_string] << command
-          next unless command.expose
-
-          command.public_commands.each do |subcommand|
-            result[command.group_string] << subcommand
-          end
-        end
-
-        result
-      end
-
       # Returns true if this command, or any subcommand (deep) as any arg or
       # flag with arg that is defined as unique
       def has_unique_args_or_flags?
@@ -246,56 +110,11 @@ module Bashly
         @parents ||= []
       end
 
-      # Returns only commands that are not private
-      def public_commands
-        commands.reject(&:private)
-      end
-
-      # Returns a full list of the public Command names and aliases combined
-      def public_command_aliases
-        public_commands.map(&:aliases).flatten
-      end
-
-      # Returns only environment variables that are not private
-      def public_environment_variables
-        environment_variables.reject(&:private)
-      end
-
-      # Returns only flags that are not private
-      def public_flags
-        flags.reject(&:private)
-      end
-
-      # Returns true if one of the args is repeatable
-      def repeatable_arg_exist?
-        args.any?(&:repeatable)
-      end
-
-      # Returns an array of all the required Arguments
-      def required_args
-        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)
-      end
-
       # Returns true if this is the root command (no parents)
       def root_command?
         parents.empty?
       end
 
-      # Returns true if one of the flags matches the provided short code
-      def short_flag_exist?(flag)
-        flags.any? { |f| f.short == flag }
-      end
-
       # Returns the summary string
       def summary_string
         if default
@@ -322,11 +141,8 @@ module Bashly
         result.compact.join ' '
       end
 
-      # Returns an array of args usage_string for the command's usage_string
-      def usage_string_args
-        args.map(&:usage_string)
-      end
-
+      # Returns a base usage string that considers whether this command is the
+      # default, and if it has any parents. Used internally by `usage_string`.
       def base_usage_pattern
         usage_pattern = default ? "[#{name}]" : name
         parents.any? ? (parents + [usage_pattern]).join(' ') : usage_pattern
@@ -344,21 +160,6 @@ module Bashly
         @validatables ||= args.select(&:validate) + flags.select(&:validate)
       end
 
-      # Returns an array of all the args with a whitelist
-      def whitelisted_args
-        args.select(&:allowed)
-      end
-
-      # Returns an array of all the environment_variables with a whitelist arg
-      def whitelisted_environment_variables
-        environment_variables.select(&:allowed)
-      end
-
-      # Returns an array of all the flags with a whitelist arg
-      def whitelisted_flags
-        flags.select(&:allowed)
-      end
-
     private
 
       # Returns either a flat filename (docker_status_command.sh) or a nested

data/lib/bashly/script/environment_variable.rb

@@ -1,9 +1,13 @@
 module Bashly
   module Script
     class EnvironmentVariable < Base
+      include Introspection::Visibility
+
       class << self
         def option_keys
-          @option_keys ||= %i[allowed default help name required private]
+          @option_keys ||= %i[
+            allowed default help name required private validate
+          ]
         end
       end
 

data/lib/bashly/script/flag.rb

@@ -1,13 +1,16 @@
+require 'shellwords'
+
 module Bashly
   module Script
     class Flag < Base
       include Completions::Flag
+      include Introspection::Visibility
 
       class << self
         def option_keys
           @option_keys ||= %i[
-            allowed arg completions conflicts default help long repeatable
-            required short unique validate private
+            allowed arg completions conflicts default help long needs
+            repeatable required short unique validate private
           ]
         end
       end

data/lib/bashly/script/introspection/arguments.rb

@@ -0,0 +1,41 @@
+module Bashly
+  module Script
+    module Introspection
+      module Arguments
+        # Returns an array of Arguments
+        def args
+          return [] unless options['args']
+
+          options['args'].map do |options|
+            Argument.new options
+          end
+        end
+
+        # Returns an array of all the default Args
+        def default_args
+          args.select(&:default)
+        end
+
+        # Returns true if one of the args is repeatable
+        def repeatable_arg_exist?
+          args.any?(&:repeatable)
+        end
+
+        # Returns an array of all the required Arguments
+        def required_args
+          args.select(&:required)
+        end
+
+        # Returns an array of args usage_string for the command's usage_string
+        def usage_string_args
+          args.map(&:usage_string)
+        end
+
+        # Returns an array of all the args with a whitelist
+        def whitelisted_args
+          args.select(&:allowed)
+        end
+      end
+    end
+  end
+end