cmds 0.2.4 → 0.2.5

data/lib/cmds/util.rb

@@ -7,19 +7,13 @@ require 'shellwords'
 require 'nrser'
 
 # package
+require 'cmds/util/shell_escape'
 require 'cmds/util/tokenize_options'
 
 class Cmds
   # class methods
   # =============
 
-  # shortcut for Shellwords.escape
-  # 
-  # also makes it easier to change or customize or whatever
-  def self.esc str
-    Shellwords.escape str
-  end  
-
   # tokenize values for the shell. each values is tokenized individually
   # and the results are joined with a space.
   # 
@@ -32,15 +26,12 @@ class Cmds
   def self.tokenize *values, **opts
     values.map {|value|
       case value
-      when nil
-        # nil is just an empty string, NOT an empty string bash token
-        ''
       when Hash
         tokenize_options value, **opts
       else
-        esc value.to_s
+        tokenize_value value, **opts
       end
-    }.join ' '
+    }.flatten.join ' '
   end # .tokenize
   
   

data/lib/cmds/util/defaults.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Cmds
   # hash of common default values used in method options.
   # 
@@ -13,39 +15,66 @@ class Cmds
   # you don't even know about may depend on said behavior.
   # 
   DEFAULTS = {
+    # Alphabetical...
+    
     # positional arguments for a command
     args: [],
     
-    # keyword arguments for a command
-    kwds: {},
-    
-    # how to format a command string for execution
-    format: :squish,
+    # what to join array option values with when using `array_mode = :join`
+    array_join_string: ',',
     
     # what to do with array option values
     array_mode: :join,
     
-    # what to join array option values with when using `array_mode = :join`
-    array_join_string: ',',
+    # Don't asset (raise error if exit code is not 0)
+    assert: false,
     
-    # what to do with false array values
-    false_mode: :omit,
+    # Don't change directories
+    chdir: nil,
+    
+    # No additional environment
+    env: {},
     
     # Stick ENV var defs inline at beginning of command
     env_mode: :inline,
     
-    # No additional environment
-    env: {},
+    # What to do with `false` *option* values (not `false` values as regular
+    # values or inside collections)
+    # 
+    # Just leave them out all-together
+    false_mode: :omit,
     
-    # Don't change directories
-    chdir: nil,
+    # Flatten nested array values to a single array.
+    # 
+    # Many CLI commands accept arrays in some form or another, but I'm hard
+    # pressed to think of one that accepts nested arrays. Flattening can make
+    # it simpler to generate values.
+    # 
+    flatten_array_values: true,
     
-    # Don't asset (raise error if exit code is not 0)
-    assert: false,
+    # how to format a command string for execution
+    format: :squish,
+    
+    hash_mode: :join,
+    
+    # Join hash keys and values with `:`
+    hash_join_string: ':',
     
     # No input
     input: nil,
     
+    # keyword arguments for a command
+    kwds: {},
+
+    # What to use to separate "long" opt names (more than one character) from
+    # their values. I've commonly seen '=' (`--name=VALUE`)
+    # and ' ' (`--name VALUE`).
+    long_opt_separator: '=',
+    
+    # What to use to separate "short" opt names (single character) from their
+    # values. I've commonly seen ' ' (`-x VALUE`) and '' (`-xVALUE`).
+    short_opt_separator: ' ',
+    
   }.map { |k, v| [k, v.freeze] }.to_h.freeze
   
   
@@ -69,7 +98,7 @@ class Cmds
   def self.defaults opts, keys = '*', extras = {}
     if keys == '*'
       DEFAULTS.dup
-    else      
+    else
       keys.
         map {|key|
           [key, DEFAULTS.fetch(key)]

data/lib/cmds/util/shell_escape.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+class Cmds
+  # @!group Shell Quoting and Escaping Methods
+  
+  # Constants
+  # ======================================================================
+  
+  # Quote "name" keys `:single` and `:double` mapped to their character.
+  # 
+  # @return [Hash<Symbol, String>]
+  # 
+  QUOTE_TYPES = {
+    single: %{'},
+    double: %{"},
+  }.freeze
+  
+  
+  # List containing just `'` and `"`.
+  # 
+  # @return [Array<String>]
+  # 
+  QUOTE_VALUES = QUOTE_TYPES.values.freeze
+  
+  
+  # Class Methods
+  # ======================================================================
+  
+  # Shortcut for Shellwords.escape
+  # 
+  # Also makes it easier to change or customize or whatever.
+  # 
+  # @see http://ruby-doc.org/stdlib/libdoc/shellwords/rdoc/Shellwords.html#method-c-escape
+  # 
+  # @param [#to_s] str
+  # @return [String]
+  # 
+  def self.esc str
+    Shellwords.escape str
+  end
+  
+  
+  # Format a string to be a shell token by wrapping it in either single or
+  # double quotes and replacing instances of that quote with what I'm calling
+  # a "quote dance":
+  # 
+  # 1.  Closing the type of quote in use
+  # 2.  Quoting the type of quote in use with the *other* type of quote
+  # 3.  Then opening up the type in use again and keeping going.
+  # 
+  # @example Single quoting string containing single quotes
+  #   
+  #   Cmds.quote_dance %{you're}, :single
+  #   # => %{'you'"'"'re'}
+  # 
+  # @example Double quoting string containing double quotes
+  #   
+  #   Cmds.quote_dance %{hey "ho" let's go}, :double
+  #   # => %{"hey "'"'"ho"'"'" let's go"}
+  # 
+  # **_WARNING:
+  #     Does NOT escape anything except the quotes! So if you double-quote a
+  #      string with shell-expansion terms in it and pass it to the shell
+  #     THEY WILL BE EVALUATED_**
+  # 
+  # @param [String] string
+  #   String to quote.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.quote_dance string, quote_type
+    outside = QUOTE_TYPES.fetch quote_type
+    inside = QUOTE_VALUES[QUOTE_VALUES[0] == outside ? 1 : 0]
+    
+    outside +
+    string.gsub(
+      outside,
+      outside + inside + outside + inside + outside
+    ) +
+    outside
+  end # .quote_dance
+  
+  
+  # Single quote a string for use in the shell.
+  # 
+  # @param [String] string
+  #   String to quote.
+  # 
+  # @return [String]
+  #   Single-quoted string.
+  # 
+  def self.single_quote string
+    quote_dance string, :single
+  end # .single_quote
+  
+  # Set {.single_quote} up as our quote method.
+  singleton_class.send :alias_method, :quote, :single_quote
+  
+  
+end # class Cmds

data/lib/cmds/util/tokenize_option.rb

@@ -1,43 +1,50 @@
 require 'json'
-require 'nrser/refinements'
+require 'nrser'
 
 require_relative "defaults"
+require_relative "tokenize_value"
 
 class Cmds
-  TOKENIZE_OPT_KEYS = [:array_mode, :array_join_string, :false_mode]
   
-  # turn an option name and value into an array of shell-escaped string
-  # token suitable for use in a command.
+  # Turn an option name and value into an array of shell-escaped string
+  # tokens suitable for use in a command.
   # 
   # @param [String] name
-  #   string name (one or more characters).
+  #   String name (one or more characters).
   # 
   # @param [*] value
-  #   value of the option.
+  #   Value of the option.
   # 
   # @param [Hash] **opts
-  # @option [Symbol] :array_mode (:multiple)
+  # 
+  # @option [Symbol] :array_mode (:join)
   #   one of:
+  # 
+  #   1.  `:join` (default) -- join values in one token.
+  #         
+  #           tokenize_option 'blah', [1, 2, 3], array_mode: :join
+  #           => ['--blah=1,2,3']
   #   
-  #   1.  `:multiple` (default) provide one token for each value.
+  #   2.  `:repeat` repeat the option for each value.
   #       
-  #           expand_option 'blah', [1, 2, 3]
+  #           tokenize_option 'blah', [1, 2, 3], array_mode: :repeat
   #           => ['--blah=1', '--blah=2', '--blah=3']
-  #   
-  #   2.  `:join` -- join values in one token.
-  #         
-  #           expand_option 'blah', [1, 2, 3], array_mode: :join
-  #           => ['--blah=1,2,3']
   # 
   # @option [String] :array_join_string (',')
-  #   string to join array values with when `:array_mode` is `:join`.
+  #   String to join array values with when `:array_mode` is `:join`.
   # 
   # @return [Array<String>]
-  #   string tokens.
+  #   List of individual shell token strings, escaped for use.
+  # 
+  # @raise [ArgumentError]
+  #   1.  If `name` is the wrong type or empty.
+  #   2.  If any options have bad values.
   # 
   def self.tokenize_option name, value, **opts
+    # Set defaults for any options not passed
     opts = defaults opts, TOKENIZE_OPT_KEYS
     
+    # Validate `name`
     unless name.is_a?(String) && name.length > 0
       raise ArgumentError.new NRSER.squish <<-END
         `name` must be a String of length greater than zero,
@@ -45,74 +52,138 @@ class Cmds
       END
     end
     
-    prefix, separator = if name.length == 1
-      # -b <value> style
-      ['-', ' ']
+    # Set type (`:short` or `:long`) prefix and name/value separator depending
+    # on if name is "short" (single character) or "long" (anything else)
+    # 
+    type, prefix, separator = if name.length == 1
+      # -b <value> style (short)
+      [ :short, '-', opts[:short_opt_separator] ]
     else
-      # --blah=<value> style
-      ['--', '=']
+      # --blah=<value> style (long)
+      [ :long, '--', opts[:long_opt_separator] ]
     end
-      
+    
     case value
-    when nil
-      []
-      
-    when Array
-      # the PITA one
-      case opts[:array_mode]
-      when :repeat
-        # `-b 1 -b 2 -b 3` / `--blah=1 --blah=2 --blah=3` style
-        value.flatten.map {|v|
-          prefix + esc(name) + separator + esc(v)
-        }
-        
-      when :join
-        # `-b 1,2,3` / `--blah=1,2,3` style
-        [ prefix + 
-          esc(name) + 
-          separator + 
-          esc(value.join opts[:array_join_string]) ]
-        
-      when :json
-        [prefix + esc(name) + separator + "'" + JSON.dump(value).gsub(%{'}, %{'"'"'}) + "'"]
-        
-      else
-        # SOL
-        raise ArgumentError.new NRSER.squish <<-END
-          bad array_mode option: #{ opts[:array_mode] }, 
-          should be :repeat, :join or :json
-        END
-        
-      end
-      
+    
+    # Special cases (booleans), where we may want to emit an option name but
+    # no value (depending on options)
+    # 
     when true
-      # `-b` or `--blah`
+      # `-b` or `--blah` style token
       [prefix + esc(name)]
       
     when false
       case opts[:false_mode]
-      when :omit
-        # don't emit any token for a false boolean
+      when :omit, :ignore
+        # Don't emit any token for a false boolean
         []
-      when :no
-        # `--no-blah` style
-        # 
-        # but there's not really a great way to handle short names...
-        # we use `--no-b`
+      
+      when :negate, :no
+        # Emit `--no-blah` style token
         # 
-        ["--no-#{ esc(name) }"]
+        if type == :long
+          # Easy one
+          ["--no-#{ esc(name) }"]
         
+        else
+          # Short option... there seems to be little general consensus on how
+          # to handle these guys; I feel like the most common is to invert the
+          # case, which only makes sense for languages that have lower and
+          # upper case :/
+          case opts[:false_short_opt_mode]
+          
+          when :capitalize, :cap, :upper, :upcase
+            # Capitalize the name
+            # 
+            # {x: false} => ["-X"]
+            # 
+            # This only really makes sense for lower case a-z, so raise if it's
+            # not in there
+            unless "a" <= name <= "z"
+              raise ArgumentError.new binding.erb <<-END
+                Can't negate CLI option `<%= name %>` by capitalizing name.
+                
+                Trying to tokenize option `<%= name %>` with `false` value and:
+                
+                1.  `:false_mode` is set to `<%= opts[:false_mode] %>`, which
+                    tells {Cmds.tokenize_option} to emit a "negating" name with
+                    no value like
+                    
+                        {update: false} => --no-update
+                    
+                2.  `:false_short_opt_mode` is set to `<%= opts[:false_short_opt_mode] %>`,
+                    which means negate through capitalizing the name character,
+                    like:
+                    
+                        {u: false} => -U
+                
+                3.  But this is only implemented for names in `a-z`
+                
+                Either change the {Cmds} instance configuration or provide a
+                different CLI option name or value.
+              END
+            end
+            
+            # Emit {x: false} => ['-X'] style
+            ["-#{ name.upcase }"]
+          
+          when :long
+            # Treat it the same as a long option,
+            # emit {x: false} => ['--no-x'] style
+            # 
+            # Yeah, I've never seen it anywhere else, but it seems reasonable I
+            # guess..?
+            #
+            ["--no-#{ esc(name) }"]
+          
+          when :string
+            # Use the string 'false' as a value
+            [prefix + esc( name ) + separator + 'false']
+          
+          when String
+            # It's some custom string to use
+            [prefix + esc( name ) + separator + esc( string )]
+            
+          else
+            raise ArgumentError.new binding.erb <<-END
+              Bad `:false_short_opt_mode` value:
+              
+                  <%= opts[:false_short_opt_mode].pretty_inspect %>
+              
+              Should be
+              
+              1.  :capitalize (or :cap, :upper, :upcase)
+              2.  :long
+              3.  :string
+              4.  any String
+              
+            END
+            
+          end # case opts[:false_short_opt_mode]
+        end # if :long else
       else
         raise ArgumentError.new NRSER.squish <<-END
-          bad :false_mode option: #{ opts[:false_mode] }, 
+          bad :false_mode option: #{ opts[:false_mode] },
           should be :omit or :no
         END
       end
-      
+    
+    # General case
     else
-      # we let .esc handle it
-      [prefix + esc(name) + separator + esc(value)]
-      
-    end
-  end
-end
+      # Tokenize the value, which may
+      # 
+      # 1.  Result in more than one token, like when `:array_mode` is `:repeat`
+      #     (in which case we want to emit multiple option tokens)
+      # 
+      # 2.  Result in zero tokens, like when `value` is `nil`
+      #     (in which case we want to emit no option tokens)
+      # 
+      # and map the resulting tokens into option tokens
+      # 
+      tokenize_value( value, **opts ).map { |token|
+        prefix + esc(name) + separator + token
+      }
+    
+    end # case value
+  end # .tokenize_option
+end # class Cmds