cmds 0.0.9 → 0.1.0

data/lib/cmds/util/defaults.rb

@@ -0,0 +1,71 @@
+module Cmds
+  # hash of common default values used in method options.
+  # 
+  # don't use them directly -- use {Cmds.defaults}.
+  # 
+  # the values themselves are frozen so we don't have to worry about cloning
+  # them before providing them for use.
+  # 
+  # the constant Hash itself is **not** frozen -- you can mutate this to
+  # change the default options for **ALL** Cmds method calls...
+  # just be aware of what you're doing. not recommended
+  # outside of quick hacks and small scripts since other pieces and parts
+  # you don't even know about may depend on said behavior.
+  # 
+  DEFAULTS = {
+    # positional arguments for a command
+    args: [],
+    
+    # keyword arguments for a command
+    kwds: {},
+    
+    # how to format a command string for execution
+    format: :squish,
+    
+    # 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: ',',
+    
+    # what to do with false array values
+    false_mode: :omit,
+  }.map {|k, v| [k, v.freeze]}.to_h
+  
+  # merge an method call options hash with common defaults for the module.
+  # 
+  # this makes it easy to use the same defaults in many different methods
+  # without repeating the declarations everywhere.
+  # 
+  # @param [Hash] opts
+  #   hash of overrides provided by method caller.
+  # 
+  # @param [Array<Symbol>, '*'] keys
+  #   keys for the defaults you want to use.
+  # 
+  # @param [Hash<Symbol, Object>] extras
+  #   extra keys and values to add to the returned defaults.
+  # 
+  # @return [Hash<Symbol, Object>]
+  #   defaults to use in the method call.
+  #   
+  def self.defaults opts, keys = '*', extras = {}
+    if keys == '*'
+      DEFAULTS
+    else      
+      keys.
+        map {|key|
+          [key, DEFAULTS.fetch(key)]
+        }.
+        to_h
+    end.
+      merge!(extras).
+      merge!(opts)
+  end
+  
+  # proxy through to class method {Cmds.defaults}.
+  # 
+  def defaults opts, keys = '*', extras = {}
+    self.class.defaults opts, keys, extras
+  end
+end

data/lib/cmds/util/params.rb

@@ -0,0 +1,56 @@
+module Cmds
+  class Params
+    # Cmds instance execution methods take a splat and block 
+    def self.normalize *params, &input
+      args = []
+      kwds = {}
+      input = input_block.nil? ? nil : input_block.call
+
+      case subs.length
+      when 0
+        # nothing to do
+      when 1
+        # can either be a hash, which is interpreted as a keywords,
+        # or an array, which is interpreted as positional arguments
+        case subs[0]
+        when Hash
+          kwds = subs[0]
+
+        when Array
+          args = subs[0]
+
+        else
+          raise TypeError.new NRSER.squish <<-BLOCK
+            first *subs arg must be Array or Hash, not #{ subs[0].inspect }
+          BLOCK
+        end
+
+      when 2
+        # first arg needs to be an array, second a hash
+        unless subs[0].is_a? Array
+          raise TypeError.new NRSER.squish <<-BLOCK
+            first *subs arg needs to be an array, not #{ subs[0].inspect }
+          BLOCK
+        end
+
+        unless subs[1].is_a? Hash
+          raise TypeError.new NRSER.squish <<-BLOCK
+            second *subs arg needs to be a Hash, not #{ subs[1].inspect }
+          BLOCK
+        end
+
+        args, kwds = subs
+      else
+        raise ArgumentError.new NRSER.squish <<-BLOCK
+          must provide one or two *subs arguments, received #{ 1 + subs.length }
+        BLOCK
+      end
+
+      return {
+        args: args,
+        kwds: kwds,
+        input: input,
+      }
+    end # .normalize
+  end # Params
+end # Cmds

data/lib/cmds/util/tokenize_option.rb

@@ -0,0 +1,118 @@
+require 'json'
+require 'nrser/refinements'
+
+using NRSER
+
+require_relative "defaults"
+
+module Cmds
+  # turn an option name and value into an array of shell-escaped string
+  # token suitable for use in a command.
+  # 
+  # @param [String] name
+  #   string name (one or more characters).
+  # 
+  # @param [*] value
+  #   value of the option.
+  # 
+  # @param [Hash] opts
+  # @option [Symbol] :array_mode (:multiple)
+  #   one of:
+  #   
+  #   1.  `:multiple` (default) provide one token for each value.
+  #       
+  #           expand_option 'blah', [1, 2, 3]
+  #           => ['--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`.
+  # 
+  # @return [Array<String>]
+  #   string tokens.
+  # 
+  def self.tokenize_option name, value, opts = {}
+    opts = defaults opts, [:array_mode, :array_join_string, :false_mode]
+    
+    unless name.is_a?(String) && name.length > 0
+      raise ArgumentError.new <<-END.squish
+        `name` must be a String of length greater than zero,
+        found #{ name.inspect }
+      END
+    end
+    
+    prefix, separator = if name.length == 1
+      # -b <value> style
+      ['-', ' ']
+    else
+      # --blah=<value> style
+      ['--', '=']
+    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 + esc(JSON.dump value)]
+        
+      else
+        # SOL
+        raise ArgumentError.new <<-END.squish
+          bad array_mode option: #{ opts[:array_mode] }, 
+          should be :repeat, :join or :json
+        END
+        
+      end
+      
+    when true
+      # `-b` or `--blah`
+      [prefix + esc(name)]
+      
+    when false
+      case opts[:false_mode]
+      when :omit
+        # 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`
+        # 
+        ["--no-#{ esc(name) }"]
+        
+      else
+        raise ArgumentError.new <<-END.squish
+          bad :false_mode option: #{ opts[:false_mode] }, 
+          should be :omit or :no
+        END
+      end
+      
+    else
+      # we let .esc handle it
+      [prefix + esc(name) + separator + esc(value)]
+      
+    end
+  end
+end

data/lib/cmds/util/tokenize_options.rb

@@ -0,0 +1,50 @@
+require_relative 'tokenize_option'
+
+module Cmds
+  # escape option hash.
+  #
+  # this is only useful for the two common option styles: 
+  #
+  # -   single character keys become `-<char> <value>`
+  #
+  #         {x: 1}    => "-x 1"
+  # 
+  # -   longer keys become `--<key>=<value>` options
+  # 
+  #         {blah: 2} => "--blah=2"
+  #
+  # if you have something else, you're going to have to just put it in
+  # the cmd itself, like:
+  # 
+  #     Cmds "blah -assholeOptionOn:%{s}", "ok"
+  # 
+  # or whatever similar shit said command requires.
+  #
+  # however, if the value is an Array, it will repeat the option for each
+  # value:
+  # 
+  #     {x:     [1, 2, 3]} => "-x 1 -x 2 -x 3"
+  #     {blah:  [1, 2, 3]} => "--blah=1 --blah=2 --blah=3"
+  # 
+  # i can't think of any right now, but i swear i've seen commands that take
+  # opts that way.
+  # 
+  def self.tokenize_options hash, opts = {}
+    opts = defaults opts, [:array_mode, :array_join_string, :false_mode]
+    
+    hash.map {|key, value|
+      # keys need to be strings
+      key = key.to_s unless key.is_a? String
+
+      [key, value]
+
+    }.sort {|(key_a, value_a), (key_b, value_b)|
+      # sort by the (now string) keys
+      key_a <=> key_b
+
+    }.map {|key, value|
+      tokenize_option key, value
+      
+    }.flatten.join ' '
+  end # .tokenize_options
+end

data/lib/cmds/util.rb

@@ -1,5 +1,11 @@
 # util functions
-class Cmds
+
+# stdlib
+require 'shellwords'
+
+require_relative 'util/tokenize_options'
+
+module Cmds
   # class methods
   # =============
 
@@ -8,73 +14,7 @@ class Cmds
   # also makes it easier to change or customize or whatever
   def self.esc str
     Shellwords.escape str
-  end
-
-  # escape option hash.
-  #
-  # this is only useful for the two common option styles: 
-  #
-  # -   single character keys become `-<char> <value>`
-  #
-  #         {x: 1}    => "-x 1"
-  # 
-  # -   longer keys become `--<key>=<value>` options
-  # 
-  #         {blah: 2} => "--blah=2"
-  #
-  # if you have something else, you're going to have to just put it in
-  # the cmd itself, like:
-  # 
-  #     Cmds "blah -assholeOptionOn:%{s}", "ok"
-  # 
-  # or whatever similar shit said command requires.
-  #
-  # however, if the value is an Array, it will repeat the option for each
-  # value:
-  # 
-  #     {x:     [1, 2, 3]} => "-x 1 -x 2 -x 3"
-  #     {blah:  [1, 2, 3]} => "--blah=1 --blah=2 --blah=3"
-  # 
-  # i can't think of any right now, but i swear i've seen commands that take
-  # opts that way.
-  # 
-  def self.expand_option_hash hash
-    hash.map {|key, values|
-      # keys need to be strings
-      key = key.to_s unless key.is_a? String
-
-      [key, values]
-
-    }.sort {|(key_a, values_a), (key_b, values_b)|
-      # sort by the (now string) keys
-      key_a <=> key_b
-
-    }.map {|key, values|
-      # for simplicity's sake, treat all values like an array
-      values = [values] unless values.is_a? Array
-
-      # keys of length 1 expand to `-x v` form
-      expanded = if key.length == 1
-        values.map {|value|
-          if value.nil?
-            "-#{ esc key }"
-          else
-            "-#{ esc key } #{ esc value}"
-          end
-        }
-
-      # longer keys expand to `--key=value` form
-      else
-        values.map {|value|
-          if value.nil?
-            "--#{ esc key }"
-          else
-            "--#{ esc key }=#{ esc value }"
-          end
-        }
-      end
-    }.flatten.join ' '
-  end # ::expand_option_hash
+  end  
 
   # expand one of the substitutions
   def self.expand_sub sub
@@ -83,108 +23,37 @@ class Cmds
       # nil is just an empty string, NOT an empty string bash token
       ''
     when Hash
-      expand_option_hash sub
+      tokenize_options sub
     else
       esc sub.to_s
     end
   end # ::expand_sub
-
-  # substitute values into a command template, escaping them for the shell and
-  # offering convenient expansions for some structures. uses ERB templating,
-  # so logic is supported as well.
-  # 
-  # check out the {file:README.md#substitutions README} for details on use.
-  # 
-  # @param template [String] command template with token to be replaced /
-  #     expanded / escaped.
-  # 
-  # @param args [Array] positional substitutions for occurances of
-  #     - `<%= arg %>`
-  #     - `%s`
-  #     
-  #     tokens in the `template` parameter.
-  # 
-  # @param kwds [Hash] keyword subsitutions for occurances of the form
-  #     
-  #     - `<%= key %>`
-  #     - `%{key}`
-  #     - `%<key>s`
-  #     
-  #     as well as optional
-  # 
-  #     - `<%= key? %>`
-  #     - `%{key?}`
-  #     - `%<key?>s`
-  #     
-  #     tokens in the `template` parameter (where `key` is replaced with the
-  #     symbol name in the hash).
-  #
-  # @return [String] formated command string suitable for execution.
-  # 
-  # @raise [TypeError] if `args` is not an {Array}.
-  # @raise [TypeError] if `kwds` is not a {Hash}.
-  # 
-  def self.sub template, args = [], kwds = {}
-    raise TypeError.new("args must be an Array") unless args.is_a? Array
-    raise TypeError.new("kwds must be an Hash") unless kwds.is_a? Hash
-
-    context = ERBContext.new(args, kwds)
-    erb = ShellEruby.new replace_shortcuts(template)
-
-    NRSER.squish erb.result(context.get_binding)
-  end # ::sub
-
-  def self.options subs, input_block
-    args = []
-    kwds = {}
-    input = input_block.nil? ? nil : input_block.call
-
-    case subs.length
-    when 0
-      # nothing to do
-    when 1
-      # can either be a hash, which is interpreted as a keywords,
-      # or an array, which is interpreted as positional arguments
-      case subs[0]
-      when Hash
-        kwds = subs[0]
-
-      when Array
-        args = subs[0]
-
-      else
-        raise TypeError.new NRSER.squish <<-BLOCK
-          first *subs arg must be Array or Hash, not #{ subs[0].inspect }
-        BLOCK
-      end
-
-    when 2
-      # first arg needs to be an array, second a hash
-      unless subs[0].is_a? Array
-        raise TypeError.new NRSER.squish <<-BLOCK
-          first *subs arg needs to be an array, not #{ subs[0].inspect }
-        BLOCK
-      end
-
-      unless subs[1].is_a? Hash
-        raise TypeError.new NRSER.squish <<-BLOCK
-          second *subs arg needs to be a Hash, not #{ subs[1].inspect }
-        BLOCK
-      end
-
-      args, kwds = subs
+  
+  # formats a command string 
+  def self.format string, with = :squish
+    case with
+    when :squish
+      NRSER.squish string
+      
+    when :pretty
+      pretty_format string
+    
     else
-      raise ArgumentError.new NRSER.squish <<-BLOCK
-        must provide one or two *subs arguments, received #{ 1 + subs.length }
-      BLOCK
+      with.call string
     end
-
-    return {
-      args: args,
-      kwds: kwds,
-      input: input,
-    }
-  end # ::options
+  end
+  
+  def self.pretty_format string
+    string.lines.map {|line|
+      line = line.rstrip
+      
+      if line.end_with? '\\'
+        line
+      else
+        line + ' \\'
+      end
+    }.join("\n")
+  end
 
   def self.replace_shortcuts template
     template
@@ -219,34 +88,5 @@ class Cmds
         '\1<\2>s'
       )
   end # ::replace_shortcuts
-
-  # instance methods
-  # ================
-
-  # returns a new `Cmds` with the subs and input block merged in
-  def curry *subs, &input_block
-    self.class.new @template, merge_options(subs, input_block)
-  end
-
-  private
-
-    # merges options already present on the object with options
-    # provided via subs and input_block and returns a new options
-    # Hash
-    def merge_options subs, input_block
-      # get the options present in the arguments
-      options = Cmds.options subs, input_block
-      # the new args are created by appending the provided args to the
-      # existing ones
-      options[:args] = @args + options[:args]
-      # the new kwds are created by merging the provided kwds into the
-      # exising ones (new values override previous)
-      options[:kwds] = @kwds.merge options[:kwds]
-      # if there is input present via the provided block, it is used.
-      # otherwise, previous input is used, which may be `nil`
-      options[:input] ||= @input
-      return options
-    end # #merge_options
-
-  # end private
-end # class Cmds
+  
+end # module Cmds

data/lib/cmds/version.rb

@@ -1,3 +1,3 @@
-class Cmds
-  VERSION = "0.0.9"
+module Cmds
+  VERSION = "0.1.0"
 end

data/lib/cmds.rb

@@ -1,36 +1,3 @@
-# stdlib
-require 'shellwords'
-require 'open3'
-require 'thread'
-
-# deps
-require 'nrser'
-
-# project
-require "cmds/capture"
-require "cmds/debug"
-require "cmds/erb_context"
-require "cmds/io_handler"
-require "cmds/pipe"
-require "cmds/result"
-require "cmds/shell_eruby"
-require "cmds/stream"
-require "cmds/sugar"
-require "cmds/util"
-require "cmds/version"
-
-class Cmds
-  attr_reader :template, :args, :kwds, :input, :assert
-
-  def initialize template, opts = {}
-    Cmds.debug "Cmds constructed",
-      template: template,
-      options: opts
-
-    @template = template
-    @args = opts[:args] || []
-    @kwds = opts[:kwds] || {}
-    @input = opts[:input] || nil
-    @assert = opts[:assert] || false
-  end # #initialize
-end
+require 'cmds/version'
+require 'cmds/cmd'
+require 'cmds/sugar'

data/scratch/proxy.rb

@@ -1,5 +1,5 @@
 require 'cmds'
 
 Cmds.enable_debug do
-  Cmds.new("./test/questions.rb").proxy
+  Cmds::Cmd.new("./test/questions.rb").proxy
 end

data/spec/cmds/assert_spec.rb

@@ -11,6 +11,6 @@ describe "Cmds::assert" do
 
   it "should be chainable when the command is ok" do
     expect( Cmds!("echo hey").out ).to eq "hey\n"
-    expect( Cmds.new("echo hey").capture.assert.out ).to eq "hey\n"
+    expect( Cmds::Cmd.new("echo hey").capture.assert.out ).to eq "hey\n"
   end
 end # Cmds::run

data/spec/cmds/capture_spec.rb

@@ -3,13 +3,13 @@ require 'spec_helper'
 describe "Cmds::capture" do
   it "captures stdout" do
     expect(
-      Cmds.new(%{ruby -e '$stdout.puts "hey"'}).capture.out
+      Cmds::Cmd.new(%{ruby -e '$stdout.puts "hey"'}).capture.out
     ).to eq "hey\n"
   end
 
   it "captures stderr" do
     expect(
-      Cmds.new(%{ruby -e '$stderr.puts "ho"'}).capture.err
+      Cmds::Cmd.new(%{ruby -e '$stderr.puts "ho"'}).capture.err
     ).to eq "ho\n"
   end
 
@@ -25,7 +25,7 @@ describe "Cmds::capture" do
 
     context "positional args" do
       let(:result) {
-        Cmds "./test/echo_cmd.rb <%= arg %>", ["hello world!"]
+        Cmds "./test/echo_cmd.rb <%= arg %>", "hello world!"
       }
 
       it_behaves_like "executes correctly"
@@ -41,31 +41,15 @@ describe "Cmds::capture" do
 
   end # context echo_cmd.rb 'hello world!'
 
-  # context "feeding kwargs to args cmd" do
-  #   let(:result) {
-  #     Cmds "./test/echo_cmd.rb %s", s: "sup y'all"
-  #   }
-
-  #   it "" do
-  #     expect( result.cmd ).to eq nil
-  #   end
-  # end
-
-  it "should error when second (subs) arg is not a hash or array" do
-    expect {
-      Cmds "./test/echo_cmd.rb <%= arg %>", "hello world!"
-    }.to raise_error TypeError
-  end
-
   it "is reusable" do
-    args_cmd = Cmds.new "./test/echo_cmd.rb <%= arg %>"
-    kwds_cmd = Cmds.new "./test/echo_cmd.rb <%= s %>"
+    args_cmd = Cmds::Cmd.new "./test/echo_cmd.rb <%= arg %>"
+    kwds_cmd = Cmds::Cmd.new "./test/echo_cmd.rb <%= s %>"
 
     args = ["arg one", "arg two", "arg three"]
 
     args.each do |arg|
       results = [
-        args_cmd.capture([arg]),
+        args_cmd.capture(arg),
         kwds_cmd.capture(s: arg)
       ]
 
@@ -86,12 +70,12 @@ describe "Cmds::capture" do
     }
 
     it "accepts input via options" do
-      cmd = Cmds.new(ECHO_CMD, input: input)
+      cmd = Cmds::Cmd.new(ECHO_CMD, input: input)
       expect( echo_cmd_stdin cmd.capture ).to eq input
     end
 
     it "accepts input via block" do
-      cmd = Cmds.new ECHO_CMD
+      cmd = Cmds::Cmd.new ECHO_CMD
       expect( echo_cmd_stdin cmd.capture { input } ).to eq input
     end
 
@@ -100,7 +84,7 @@ describe "Cmds::capture" do
         input = f.read
         f.rewind
 
-        cmd = Cmds.new ECHO_CMD
+        cmd = Cmds::Cmd.new ECHO_CMD
         expect( echo_cmd_stdin cmd.capture { f } ).to eq input
       end
     end