cmds 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 82780e4858c704d9607db8032e99818163e80220
-  data.tar.gz: e0ba46030000a9c252940a1a80beb1f528ea3a6c
+  metadata.gz: 78e95949457351a76889d9559cace8e0d6357027
+  data.tar.gz: 1741db7b86690a11676165ccf6941696a24a63c5
 SHA512:
-  metadata.gz: 0c3bd920b4afeaaabc83d967aaaffbe7c24a084d2164532b741dbb96c0e03385452136ecfe3712069a716326d3725aab9a38ea5c387f9a043118235f0c16ab47
-  data.tar.gz: 4597c1e73ead17c16c850cd0d6043b0c3092c25499f858026f2ff3324975dafb0ce496f48e1eb2febd78a79308436cd5c0eaf8bedfd9e4e63d55634c497bb18f
+  metadata.gz: 74d33994938b16b3fc3c33c4ef915e21d729efb50d80f8c303329a7d0513f382a9c29093bdb4c1deb719833b81476389444e2e65922a6249103a254c4482d8e8
+  data.tar.gz: de650778601f8e6c1ed8faa751edc532badf978c281111c8d7e937635f1a699d1b6e265dc11ce5788e2a736f4e871fb9ebdeaee6d441f09be05616c93c7f872a

data/README.md

@@ -1,93 +1,112 @@
-# cmds
+Cmds
+=============================================================================
 
-cmds tries to make it easier to read, write and remember using shell commands in Ruby.
+`Cmds` tries to make it easier to read, write and remember using shell commands in Ruby.
 
-it treats generating shell the in a similar fashion to generating SQL or HTML.
+It treats generating shell the in a similar fashion to generating SQL or HTML.
 
+1.  [Status](#status)
+3.  [Real-World Examples](#real-world-examples)
+2.  [Installation](#installation)
 
-## status
 
-eh, it's kinda starting to work... i'll be using it for stuff and seeing how it goes, but no promises until `1.0` of course.
+-----------------------------------------------------------------------------
+Status
+-----------------------------------------------------------------------------
 
+Ya know, before you get too excited...
 
-## installation
+It's kinda starting to work. I'll be using it for stuff and seeing how it goes, but no promises until `1.0` of course.
 
-Add this line to your application's Gemfile:
-
-```
-gem 'cmds'
-```
-
-
-And then execute:
-
-```
-$ bundle
-```
-
-
-Or install it yourself as:
-
-```
-$ gem install cmds
-```
 
+-----------------------------------------------------------------------------
+Real-World Examples
+-----------------------------------------------------------------------------
 
+-   Instead of
+    
+    ```Ruby
+    `psql -U #{ db_config['username'] || ENV['USER'] } #{ db_config['database']} <     #{ filepath.shellescape }`
+    ```
+    
+    write
+    
+    ```Ruby
+    Cmds 'psql %{opts} %{db} < %{dump}',
+      db: db_config['database'],
+      dump: filepath,
+      opts: {
+        username: db_config['username'] || ENV['USER']
+      }
+    ```
+    
+    to run a command like
+    
+    ```bash
+    psql --username=nrser that_db < ./some/file/path
+    ```
+    
+    
+-   Instead of
+    
+    ```Ruby
+    `aws s3 sync s3://#{ PROD_APP_NAME } #{ s3_path.shellescape }`
+    ```
+    
+    write
+    
+    ```Ruby
+    Cmds 'aws s3 sync %{uri} %{path}', 
+      uri: "s3://#{ PROD_APP_NAME }",
+      path: s3_path
+    ```
 
-## real-world examples
 
-instead of
+-   Instead of
+    
+    ```Ruby
+    `PGPASSWORD=#{ config[:password].shellescape } pg_dump -U #{     config[:username].shellescape } -h #{ config[:host].shellescape } -p #{     config[:port] } #{ config[:database].shellescape } > #{ filepath.shellescape }`
+    ```
+    
+    write
+    
+    ```Ruby
+    Cmds 'PGPASSWORD=%{password} pg_dump %{opts} %{database} > %{filepath}',
+      password: config[:password],
+      database: config[:database],
+      filepath: filepath,
+      opts: {
+        username: config[:username],
+        host: config[:host],
+        port: config[:port],
+      }
+    ```
 
-```
-`psql -U #{ db_config['username'] || ENV['USER'] } #{ db_config['database']} < #{ filepath.shellescape }`
-```
+-----------------------------------------------------------------------------
+Installation
+-----------------------------------------------------------------------------
 
-write
+Add this line to your application's `Gemfile`:
 
 ```
-Cmds 'psql %{opts} %{db} < %{dump}',
-  db: db_config['database'],
-  dump: filepath,
-  opts: {
-    username: db_config['username'] || ENV['USER']
-  }
+gem 'cmds'
 ```
 
-instead of
-
-```
-`aws s3 sync s3://#{ PROD_APP_NAME } #{ s3_path.shellescape }`
-```
 
-write
+And then execute:
 
 ```
-Cmds 'aws s3 sync %{uri} %{path}', uri: "s3://#{ PROD_APP_NAME }"
-                                   path: s3_path
+$ bundle
 ```
 
-instead of
-
-```
-`PGPASSWORD=#{ config[:password].shellescape } pg_dump -U #{ config[:username].shellescape } -h #{ config[:host].shellescape } -p #{ config[:port] } #{ config[:database].shellescape } > #{ filepath.shellescape }`
-```
 
-write
+Or install it yourself as:
 
 ```
-Cmds 'PGPASSWORD=%{password} pg_dump %{opts} %{database} > %{filepath}',
-  password: config[:password],
-  database: config[:database],
-  filepath: filepath,
-  opts: {
-    username: config[:username],
-    host: config[:host],
-    port: config[:port],
-  }
+$ gem install cmds
 ```
 
 
-
 ## architecture
 
 Cmds is based around a central `Cmds` class that takes a template for the command and a few options and operates by either wrapping the results in a `Cmds::Result` instance or streaming the results to `IO` objects or handler blocks. the Cmds` `augmented with a health helping of connivence methods for creating and executing a `Cmds` instance in common ways.
@@ -136,7 +155,7 @@ all `Cmds` instance execution methods have the same form for accepting these:
     
     `Cmds "cp <%= arg %> <%= arg %>", [src_path, dest_path]`
     
-    note that the arguments need to be enclosed in square braces. Cmds does **NOT** use *splat for positional arguments because it would make a `Hash` final parameter ambiguous.
+    note that the arguments need to be enclosed in square braces. Cmds does **NOT** use \*splat for positional arguments because it would make a `Hash` final parameter ambiguous.
     
 2. keyword arguments are provided as optional hash that must be the last argument:
     
@@ -288,9 +307,15 @@ Cmds "blah <%= maybe? %> <%= arg %>", ["value"]
 Cmds "blah <%= maybe? %> <%= arg %>", ["value"], maybe: "yes!"
 ```
 
-### shortcuts
+************************************************************************
+
+
+### Shortcuts
+
+`Cmds` has (limited, custom) support for [printf][]-style shortcuts.
+
+[printf]: https://en.wikipedia.org/wiki/Printf_format_string
 
-there are support for `sprintf`-style shortcuts.
 
 **positional**
 

data/bin/console

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require 'nrser'
+require 'cmds'
+
+
+require 'nrser/refinements'
+using NRSER
+
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+begin
+  require "pry"
+rescue LoadError => error
+  puts "Failed to load `pry` gem - add it to your Gemfile or edit this file"
+  
+  require "irb"
+  IRB.start
+else
+  Pry.start
+end

data/cmds.gemspec

@@ -28,4 +28,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "yard", "~> 0.9.9"
   spec.add_development_dependency "redcarpet"
   spec.add_development_dependency 'github-markup'
+  
+  # A better REPL
+  spec.add_development_dependency 'pry'
 end

data/lib/cmds.rb

@@ -208,37 +208,19 @@ class Cmds
   #   
   #   Available as the {#kwds} attribute.
   # 
-  def initialize  template,
-                  args: [],
-                  assert: false,
-                  chdir: nil,
-                  env: {},
-                  env_mode: :inline,
-                  format: :squish,
-                  input: nil,
-                  kwds: {}
+  def initialize  template, **opts
+    opts = defaults opts
+    
     Cmds.debug "Cmd constructing...",
       template: template,
-      opts: {
-        args: args,
-        kwds: kwds,
-        input: input,
-        assert: assert,
-        env: env,
-        format: format,
-        env_mode: env_mode,
-        chdir: chdir,
-      }
+      opts: opts
 
     @template = template
-    @args = args.freeze
-    @kwds = kwds.freeze
-    @input = input
-    @assert = assert
-    @env = env.freeze
-    @format = format
-    @env_mode = env_mode
-    @chdir = chdir
+    
+    # Assign options to instance variables
+    opts.each { |key, value|
+      instance_variable_set "@#{ key }", value
+    }
     
     # An internal cache of the last result of calling {#prepare}, or `nil` if
     # {#prepare} has never been called. Kinda funky but ends up being useful.
@@ -274,8 +256,21 @@ class Cmds
   #   the rendered command string.
   # 
   def render *args, **kwds
-    context = Cmds::ERBContext.new((self.args + args), self.kwds.merge(kwds))
-    erb = Cmds::ShellEruby.new Cmds.replace_shortcuts(self.template)
+    # Create the context for ERB
+    context = Cmds::ERBContext.new(
+      (self.args + args),
+      
+      self.kwds.merge( kwds ),
+      
+      tokenize_options_opts: TOKENIZE_OPT_KEYS.
+        each_with_object( {} ) { |key, hash|
+          value = instance_variable_get "@#{ key}"
+          hash[key] = value unless value.nil?
+        }
+    )
+    
+    erb = Cmds::ShellEruby.new Cmds.replace_shortcuts( self.template )
+    
     rendered = NRSER.dedent erb.result(context.get_binding)
     
     if self.env_mode == :inline && !self.env.empty?

data/lib/cmds/erb_context.rb

@@ -2,10 +2,11 @@ class Cmds
   class ERBContext < BasicObject
     attr_reader :args
     
-    def initialize args, kwds
+    def initialize args, kwds, tokenize_options_opts: {}
       @args = args
       @kwds = kwds
       @arg_index = 0
+      @tokenize_options_opts = tokenize_options_opts
     end
 
     def method_missing sym, *args, &block

data/lib/cmds/shell_eruby.rb

@@ -5,7 +5,7 @@ class Cmds
   # leaves `<%== %>` raw) that calls `Cmds.expand_sub` on the value
   class ShellEruby < Erubis::EscapedEruby
     def escaped_expr code
-      "::Cmds.tokenize(#{code.strip})"
+      "::Cmds.tokenize(#{code.strip}, **@tokenize_options_opts)"
     end
   end
 end # class Cmds

data/lib/cmds/sugar.rb

@@ -37,8 +37,14 @@ class Cmds
   # @return [String]
   #   rendered and formatted command string ready to be executed.
   # 
-  def self.prepare template, *args, **kwds
-    Cmds.new(template).prepare *args, **kwds
+  def self.prepare template, *args, **kwds, &options_block
+    options = if options_block
+      options_block.call
+    else
+      {}
+    end
+    
+    Cmds.new(template, **options).prepare *args, **kwds
   end
   
   

data/lib/cmds/util.rb

@@ -29,14 +29,14 @@ class Cmds
   # @return [String]
   #   tokenized string ready for the shell.
   # 
-  def self.tokenize *values
+  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
+        tokenize_options value, **opts
       else
         esc value.to_s
       end

data/lib/cmds/util/defaults.rb

@@ -30,7 +30,24 @@ class Cmds
     
     # what to do with false array values
     false_mode: :omit,
-  }.map {|k, v| [k, v.freeze]}.to_h
+    
+    # Stick ENV var defs inline at beginning of command
+    env_mode: :inline,
+    
+    # No additional environment
+    env: {},
+    
+    # Don't change directories
+    chdir: nil,
+    
+    # Don't asset (raise error if exit code is not 0)
+    assert: false,
+    
+    # No input
+    input: nil,
+    
+  }.map { |k, v| [k, v.freeze] }.to_h.freeze
+  
   
   # merge an method call options hash with common defaults for the module.
   # 
@@ -51,7 +68,7 @@ class Cmds
   #   
   def self.defaults opts, keys = '*', extras = {}
     if keys == '*'
-      DEFAULTS
+      DEFAULTS.dup
     else      
       keys.
         map {|key|
@@ -59,13 +76,15 @@ class Cmds
         }.
         to_h
     end.
-      merge!(extras).
-      merge!(opts)
+      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/tokenize_option.rb

@@ -4,6 +4,8 @@ require 'nrser/refinements'
 require_relative "defaults"
 
 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.
   # 
@@ -13,7 +15,7 @@ class Cmds
   # @param [*] value
   #   value of the option.
   # 
-  # @param [Hash] opts
+  # @param [Hash] **opts
   # @option [Symbol] :array_mode (:multiple)
   #   one of:
   #   
@@ -33,8 +35,10 @@ class Cmds
   # @return [Array<String>]
   #   string tokens.
   # 
-  def self.tokenize_option name, value, opts = {}
-    opts = defaults opts, [:array_mode, :array_join_string, :false_mode]
+  def self.tokenize_option name, value, **opts
+    pp opts: opts
+    
+    opts = defaults opts, TOKENIZE_OPT_KEYS
     
     unless name.is_a?(String) && name.length > 0
       raise ArgumentError.new NRSER.squish <<-END
@@ -72,7 +76,7 @@ class Cmds
           esc(value.join opts[:array_join_string]) ]
         
       when :json
-        [prefix + esc(name) + separator + esc(JSON.dump value)]
+        [prefix + esc(name) + separator + "'" + JSON.dump(value).gsub(%{'}, %{'"'"'}) + "'"]
         
       else
         # SOL

data/lib/cmds/util/tokenize_options.rb

@@ -29,8 +29,8 @@ class Cmds
   # 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]
+  def self.tokenize_options hash, **opts
+    opts = defaults opts, TOKENIZE_OPT_KEYS
     
     hash.map {|key, value|
       # keys need to be strings
@@ -43,7 +43,7 @@ class Cmds
       key_a <=> key_b
 
     }.map {|key, value|
-      tokenize_option key, value
+      tokenize_option key, value, **opts
       
     }.flatten.join ' '
   end # .tokenize_options

data/lib/cmds/version.rb

@@ -1,3 +1,3 @@
 class Cmds
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 end

data/spec/cmds/prepare_spec.rb

@@ -207,4 +207,48 @@ describe "Cmds.prepare" do
       ).to eq "git add x y z"
     end
   end
+  
+  describe "options with list values" do
+    
+    context "default behavior (:join)" do
+      it "outputs a comma-separated list" do
+        expect(
+          Cmds.prepare 'blah <%= opts %>', opts: {list: ['a', 'b', 'see']}
+        ).to eq 'blah --list=a,b,see'
+      end
+    end
+    
+    context "specify :repeat behavior" do
+      it "outputs repeated options" do
+        expect(
+          Cmds.prepare 'blah <%= opts %>',
+            opts: { list: ['a', 'b', 'see'] } {
+            { array_mode: :repeat }
+          }
+        ).to eq 'blah --list=a --list=b --list=see'
+      end
+    end
+    
+    context "specify :json behavior" do
+      it "outputs JSON-encoded options" do
+        expect(
+          Cmds.prepare 'blah <%= opts %>',
+            opts: { list: ['a', 'b', 'see'] } {
+            { array_mode: :json }
+          }
+        ).to eq %{blah --list='["a","b","see"]'}
+      end
+      
+      it "handles single quotes in the string" do
+        expect(
+          Cmds.prepare 'blah <%= opts %>',
+            opts: { list: ["you're the best"] } {
+            { array_mode: :json }  
+          }
+        ).to eq %{blah --list='["you'"'"'re the best"]'}
+      end
+    end
+    
+  end # "options with list values"
+  
 end # ::sub

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cmds
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - nrser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-16 00:00:00.000000000 Z
+date: 2017-12-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nrser
@@ -136,6 +136,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - neil@ztkae.com
@@ -152,6 +166,7 @@ files:
 - Rakefile
 - ansible/dev.yml
 - ansible/hosts
+- bin/console
 - bin/rake
 - bin/rspec
 - cmds.gemspec