cmds 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 49d2979f3b8330647a63142158c793edabe0016d
-  data.tar.gz: b1e6d69cd6324cea64ae349dae9f6613ec41ef26
+  metadata.gz: 821f3c58f93958b7b377f6fb912a23f10bb7b4a3
+  data.tar.gz: 99bf03427c619cd9462c9425000c48e1b00361df
 SHA512:
-  metadata.gz: 0bf4ce786dedf1ff4eb19768bc6985bba4a45e26669745797f023e4b7046467a4fd748519e766e3c5cbc44159ac5ef10917cf4ca2dfbc5cc1f45d206da0b6915
-  data.tar.gz: d2b7eebf773c8c3c6f5f04f26441e8d24823f36ae8549ee6cd8f72222d61775aefc5249a02e3f34e61d8c6fe42a84c6bd0fe7c92b139353e5fc38f5a3230ad97
+  metadata.gz: 1ef68ea914815640394af242902cde624b9ba55cd7c19244169021f2367e26a853f7c582275727e22dd44d25c64df24a53e9d52c39f8c9c642ad7ca259f3a640
+  data.tar.gz: 91e660c34a7e9386b3e523fa1eb8070a7e037e43640c56822e7fed11e05a87e231d3f4e2ebdaf3a77ef476754b2947fd082acd140775d790ffc6333bb652c9c6

data/README.md

@@ -88,6 +88,89 @@ Cmds 'PGPASSWORD=%{password} pg_dump %{opts} %{database} > %{filepath}',
 
 
 
+## 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.
+
+### constructor
+
+the `Cmds` constructor looks like
+
+```
+Cmds(template:String, opts:Hash)
+```
+
+a brief bit about the arguments:
+
+* `template`
+    * a `String` template processed with ERB against positional and keyword arguments.
+* `opts`
+    * `:args`
+        * an `Array` of positional substitutions for the template.
+        * assigned to `@args`.
+        * defaults to an empty `Array`.
+    * `:kwds`
+        * a `Hash` of keyword substitutions for the template.
+        * assigned to `@kwds`.
+        * defaults to an empty `Hash`.
+    * `:input`
+        * a `String` to provide as standard input.
+        * assigned to `@input`.
+        * defaults to `nil`.
+    * `:assert`
+        * if this tests true, the execution of the command will raise an error on a nonzero exit status.
+        * assigned to `@assert`.
+        * defaults to `False`.
+
+### execution
+
+you can provide three types of arguments when executing a command:
+
+1. positional arguments for substitution
+2. keyword arguments for substitution
+3. input to stdin
+
+all `Cmds` instance execution methods have the same form for accepting these:
+
+1. positional arguments are provided in an optional array that must be the first argument:
+    
+    `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.
+    
+2. keyword arguments are provided as optional hash that must be the last argument:
+    
+    `Cmds "cp <%= src %> <%= dest %>", src: src_path, dest: dest_path`
+    
+    in this case, curly braces are not required since Ruby turns the trailing keywords into a `Hash` provided as the last argument (or second-to-last argument in the case of a block included in the method signature).
+    
+3. input and output is handled with blocks:
+    
+    `Cmds(“wc -l”){ “one\ntwo\nthree\n” } 
+    
+    Cmds.stream './test/tick.rb <%= times %>', times: times do |io|
+      io.on_out do |line|
+        # do something with the output line
+      end
+    
+      io.on_err do |line|
+        # do something with the error line
+      end
+    end`
+
+
+
+## templates
+
+command templates are processed with [eRuby](https://en.wikipedia.org/wiki/ERuby), which many people know as [ERB](http://ruby-doc.org/stdlib-2.2.2/libdoc/erb/rdoc/ERB.html). you may know ERB from [Rails](http://guides.rubyonrails.org/layouts_and_rendering.html).
+
+actually, Cmds uses [Erubis](http://www.kuwata-lab.com/erubis/). which is the same thing Rails uses; calm down.
+
+this takes care of a few things:
+
+1. automatically shell escape values substituted into templates with [`Shellwords.escape`](http://ruby-doc.org/stdlib-2.2.2/libdoc/shellwords/rdoc/Shellwords.html#method-c-escape). it doesn't always do the prettiest job, but `Shellwords.escape` is part of Ruby's standard library and seems to work pretty well.
+2. allow for fairly nice and readable logical structures like `if` / `else` in the command template. you've probably built html like this at some point. of course, the full power of Ruby is also available, though you probably won't find yourself needing much beyond some simple control structures.
+
 ## substitutions
 
 substitutions can be positional, keyword, or both.
@@ -304,8 +387,20 @@ prod_playbook.call playbook: "setup.yml", inventory: "inventory/prod"
 
 
 
+## input
+
+```
+c = Cmds.new("wc", input: "blah blah blah).call
+```
+
+
+
 ## future..?
 
+### exec
+
+want to be able to use to exec commands
+
 ### formatters
 
 kinda like `sprintf` formatters or string escape helpers in Rails, they would be exposed as functions in ERB and as format characters in the shorthand versions:
@@ -330,4 +425,3 @@ other formatters could include
 * `l` or `,` for comma-separated list (which some commands like as input)
 * `y` for YAML
 * `p` for path, joining with `File.join`
-

data/lib/cmds/util.rb

@@ -89,49 +89,47 @@ class Cmds
     end
   end # ::expand_sub
 
-  # substitute values into a command, escaping them for the shell and
-  # offering convenient expansions for some structures.
+  # 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.
   # 
-  # `cmd` is a string that can be substituted via ruby's `%` operator, like
+  # check out the {file:README.md#substitutions README} for details on use.
   # 
-  #     "git diff %s"
+  # @param template [String] command template with token to be replaced /
+  #     expanded / escaped.
   # 
-  # for positional substitution, or 
-  # 
-  #     "git diff %{path}"
-  # 
-  # for keyword substitution.
-  # 
-  # `subs` is either:
-  # 
-  # -   an Array when `cmd` has positional placeholders
-  # -   a Hash when `cmd` has keyword placeholders.
-  # 
-  # the elements of the `subs` array or values of the `subs` hash are:
+  # @param args [Array] positional substitutions for occurances of
+  #     - `<%= arg %>`
+  #     - `%s`
+  #     
+  #     tokens in the `template` parameter.
   # 
-  # -   strings that are substituted into `cmd` after being escaped:
+  # @param kwds [Hash] keyword subsitutions for occurances of the form
+  #     
+  #     - `<%= key %>`
+  #     - `%{key}`
+  #     - `%<key>s`
   #     
-  #         sub "git diff %{path}", path: "some path/to somewhere"
-  #         # => 'git diff some\ path/to\ somewhere'
+  #     as well as optional
   # 
-  # -   hashes that are expanded into options:
+  #     - `<%= key? %>`
+  #     - `%{key?}`
+  #     - `%<key?>s`
   #     
-  #         sub "psql %{opts} %{database} < %{filepath}",
-  #           database: "blah",
-  #           filepath: "/where ever/it/is.psql",
-  #           opts: {
-  #             username: "bingo bob",
-  #             host: "localhost",
-  #             port: 12345,
-  #           }
-  #         # => 'psql --host=localhost --port=12345 --username=bingo\ bob blah < /where\ ever/it/is.psql'
+  #     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 cmd, args = [], kwds = {}
+  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 cmd)
+    erb = ShellEruby.new replace_shortcuts(template)
 
     NRSER.squish erb.result(context.get_binding)
   end # ::sub

data/lib/cmds/version.rb

@@ -1,3 +1,3 @@
 class Cmds
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

data/spec/spec_helper.rb

@@ -1,5 +1,6 @@
 require 'pathname'
 require 'json'
+require 'tempfile'
 
 $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
 require 'cmds'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmds
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - nrser