cmd-utils 1.1.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1f047ffb87574fcc165f9651ff733e2f42f0c2e3
-  data.tar.gz: b64622069ed70aca2474362658474f88c9f26542
+  metadata.gz: 19937d5ab0376abd84254c084edaec772b501d42
+  data.tar.gz: 130e9b5ec4997a36db8c4e46503650ca55f53288
 SHA512:
-  metadata.gz: d74547e65fb7d59e99aae4cc87d6bb358c3b3a0a784e2894b90e37db53e58f0be35fbb10cf107c3c0c8f6b4cc74a17fada172071c5f658d4498232a7ac7580fd
-  data.tar.gz: e56c5364aed15bb4cc340924bf0e64c434007081e600eaa3ddd65e7377a22858fae8671b8244707f905d4e93754442857ce693371470e13424a7d83ba141b137
+  metadata.gz: a1fe074ab79e0f4e541f3ab7c3325ad60e836e40ff8895168591131ea1391433347eb5f3dbb1e3d9a25eb053643105c48ccd2f66e7303fbd91e75da28c87c9ac
+  data.tar.gz: 9f359fed8970713e8a5ce436ce031a9b5d67d0ac80383691a89daa195d275c001f84f573e039664f776a8f2dcfe7e4ec539e0e9a897c60291ab4268bd14d7d0b

data/Gemfile

@@ -6,10 +6,8 @@ source "http://rubygems.org"
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem "minitest", ">= 5.3.0"
-  #gem "shoulda"
-  gem "rdoc"
-  gem "bundler"
-  gem "jeweler"
-  gem "simplecov"
+  gem "minitest", '~> 5.3'
+  gem "rdoc",     "~> 4.1"
+  gem "bundler",  "~> 1.0"
+  gem "jeweler",  "~> 2.0"
 end

data/Gemfile.lock

@@ -1,13 +1,13 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    addressable (2.3.5)
+    addressable (2.3.6)
     builder (3.2.2)
-    descendants_tracker (0.0.3)
-    docile (1.1.3)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
     faraday (0.9.0)
       multipart-post (>= 1.2, < 3)
-    git (1.2.6)
+    git (1.2.7)
     github_api (0.11.3)
       addressable (~> 2.3)
       descendants_tracker (~> 0.0.1)
@@ -16,7 +16,7 @@ GEM
       multi_json (>= 1.7.5, < 2.0)
       nokogiri (~> 1.6.0)
       oauth2
-    hashie (2.0.5)
+    hashie (3.0.0)
     highline (1.6.21)
     jeweler (2.0.1)
       builder
@@ -28,37 +28,31 @@ GEM
       rake
       rdoc
     json (1.8.1)
-    jwt (0.1.11)
-      multi_json (>= 1.5)
-    mini_portile (0.5.2)
-    minitest (5.3.0)
-    multi_json (1.8.4)
+    jwt (1.0.0)
+    mini_portile (0.6.0)
+    minitest (5.3.5)
+    multi_json (1.10.1)
     multi_xml (0.5.5)
     multipart-post (2.0.0)
-    nokogiri (1.6.1)
-      mini_portile (~> 0.5.0)
-    oauth2 (0.9.3)
+    nokogiri (1.6.2.1)
+      mini_portile (= 0.6.0)
+    oauth2 (0.9.4)
       faraday (>= 0.8, < 0.10)
-      jwt (~> 0.1.8)
+      jwt (~> 1.0)
       multi_json (~> 1.3)
       multi_xml (~> 0.5)
       rack (~> 1.2)
     rack (1.5.2)
-    rake (10.1.1)
+    rake (10.3.2)
     rdoc (4.1.1)
       json (~> 1.4)
-    simplecov (0.8.2)
-      docile (~> 1.1.0)
-      multi_json
-      simplecov-html (~> 0.8.0)
-    simplecov-html (0.8.0)
+    thread_safe (0.3.4)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler
-  jeweler
-  minitest (>= 5.3.0)
-  rdoc
-  simplecov
+  bundler (~> 1.0)
+  jeweler (~> 2.0)
+  minitest (~> 5.3)
+  rdoc (~> 4.1)

data/README.md

@@ -1,5 +1,4 @@
-cmd-utils
-=========
+# cmd-utils
 
 Utilities for writing command line tools in ruby.
 
@@ -9,27 +8,35 @@ Installation:
 
 Usage:
 
-    require 'cmd-utils'
-    require 'ssh-utils'
+    require 'cmd-utils'   # include all libraries in this repo
+
+or
+
+    require 'arg-utils'
+    require 'error-utils'
     require 'lookup'
+    require 'run-utils'
+    require 'ssh-utils'
+    require 'talk-utils'
 
 This gem provides:
 
-* routines for output on `$stderr`, controlled by several global variables
-* error-reporting-and-exit
-* system call handling, with verbose or debug output, error and "ok" message handling
-* remote system command invocation (based on ssh)
-* ambiguous, case-insensitive string lookups in arrays or hashs, with error handling
+* `arg-utils`: help manage variable argumentlists.
+* `talk-utils`: routines for output on `$stderr`, controlled by several global variables.
+* `error-utils`: error-reporting-and-exit.
+* `run-utils`: system call handling, with verbose or debug output, error and "ok" message handling.
+* `ssh-utils`: remote system command invocation (based on ssh).
+* `lookup`: ambiguous, case-insensitive string lookups in arrays or hashs, with error handling.
+* `cmd-utils`: includes all the above libraries.
 
-talk, dtalk, qtalk, vtalk, nrtalk, nvtalk
-=========================================
+## talk-utils: talk, dtalk, qtalk, vtalk, nrtalk, nvtalk
 
 These utilities provide simple utilities that rely on the following global variables:
 
-    `$verbose` -- enables vtalk(f) function output
-    `$norun`   -- enables nrtalk(f) output, and disables the "run" command execution
-    `$quiet`   -- disables talk(f) output, and enables qtalk(f) function output
-    `$debug`   -- enables dtalk(f) function output
+    $verbose -- enables vtalk(f) function output
+    $norun   -- enables nrtalk(f) output, and disables the run command execution
+    $quiet   -- disables talk(f) output, and enables qtalk(f) function output
+    $debug   -- enables dtalk(f) function output
 
 These routines provide option-controlled output.  The arguments can be given as
 part of the the function calls, or, can be provided as the return value of a
@@ -94,8 +101,26 @@ Error output:
 The `error` routine take an optional numeric first argument which is used to
 set the exit code.  If not given, the exit code is 1.
 
-`cmd_run` 
---------
+## error-utils: `error`, `errorf`
+
+The `error` and `errorf` family of methods make it easy display an error message
+and then exit, possibly with a specific error code.
+
+The arguments may be given as a parameters on the method, or as return values 
+from a yield block.
+
+    error   MSG
+    error  {MSG}
+    error  CODE,   MSG
+    error( CODE) { MSG }
+    error{ CODE,   MSG }
+
+    errorf  FMT, *ARGS
+    errorf( FMT){ ARGS }
+    errorf{ FMT,  ARGS  }
+
+
+## run-utils: `cmd_run`, `safe_run`
 
     cmd_run     cmd 
     cmd_run   { cmd }
@@ -134,11 +159,10 @@ command evaluation with the `$verbose` treatment.
     safe_run { cmd } 
     safe_run {[cmd, errmsg, okmsg]} 
 
-ssh-utils
-=========
+## ssh-utils
 
 A module to define some routines for running commands across many systems using
-ssh.  Environment variables can be specified (PATH is used by default).
+ssh.  Environment variables can be specified (`PATH` is used by default).
 
 Usage:
 
@@ -146,14 +170,13 @@ Usage:
 
     on serverlist, :debug = true do |server|
       as user do
-        with PATH
+        with PATH do
           remote_run :whoami
         end
       end
     end
 
-Method Descriptions
--------------------
+### `on`
 
     on SERVERLIST, OPTIONSHASH |server|
       BLOCK-TO-EXECUTE-FOR-EACH-SERVER
@@ -193,6 +216,7 @@ is globally available, but the `:debug` option is a block-local specification.
 Sets the `:verbose` flag for use within the associated block.  The `$verbose` flag
 is globally available, but the `:verbose` option is a block-local specification.
 
+### `as`
 
     as USERLIST, OPTIONSHASH
       BLOCK-TO-EXECUTE-FOR-EACH-USER
@@ -215,10 +239,18 @@ option.  For example, the following two sections are equivalent:
       remote_run :whoami
     end
 
+### `with`
+
+    as USERLIST, OPTIONSHASH do
+      with SOMEENVAR do
+        BLOCK-TO-EXECUTE-WITH-SOMEENVAR
+      end
+    end
 
+The `with` method is used to set additional environment variables, or to
+reset them.
 
-lookup
-======
+## lookup-utils:
 
 usage:
 
@@ -249,7 +281,6 @@ nil.
 If `err_ambigmsg` is nil, do not raise a `LookupAmbigError`, and return the list
 of possible results.
 
-Author
-------
+# Author
 
 Alan K. Stebbens <aks@stebbens.org>

data/Rakefile

@@ -32,11 +32,11 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = true
 end
 
-desc "Code coverage detail"
-task :simplecov do
-  ENV['COVERAGE'] = "true"
-  Rake::Task['test'].execute
-end
+#desc "Code coverage detail"
+#task :simplecov do
+#  ENV['COVERAGE'] = "true"
+#  Rake::Task['test'].execute
+#end
 
 task :default => :test
 

data/VERSION

@@ -1 +1 @@
-1.1.2
+1.2.0

data/cmd-utils.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: cmd-utils 1.1.2 ruby lib
+# stub: cmd-utils 1.2.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "cmd-utils"
-  s.version = "1.1.2"
+  s.version = "1.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Alan K. Stebbens"]
-  s.date = "2014-03-03"
+  s.date = "2014-06-25"
   s.description = "Several ruby libraries for building command-line utilities."
   s.email = "aks@stebbens.org"
   s.extra_rdoc_files = [
@@ -27,13 +27,17 @@ Gem::Specification.new do |s|
     "Rakefile",
     "VERSION",
     "cmd-utils.gemspec",
+    "lib/arg-utils.rb",
     "lib/cmd-utils.rb",
+    "lib/error-utils.rb",
     "lib/lookup.rb",
+    "lib/run-utils.rb",
     "lib/ssh-utils.rb",
+    "lib/talk-utils.rb",
     "test/helper.rb",
-    "test/test-cmd-utils.rb",
     "test/test-lookup.rb",
-    "test/test_cmd-utils.rb.off"
+    "test/test-run-utils.rb",
+    "test/test-talk-utils.rb"
   ]
   s.homepage = "http://bitbucket.org/aks_/cmd-utils"
   s.licenses = ["MIT"]
@@ -44,24 +48,21 @@ Gem::Specification.new do |s|
     s.specification_version = 4
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<minitest>, [">= 5.3.0"])
-      s.add_development_dependency(%q<rdoc>, [">= 0"])
-      s.add_development_dependency(%q<bundler>, [">= 0"])
-      s.add_development_dependency(%q<jeweler>, [">= 0"])
-      s.add_development_dependency(%q<simplecov>, [">= 0"])
+      s.add_development_dependency(%q<minitest>, ["~> 5.3"])
+      s.add_development_dependency(%q<rdoc>, ["~> 4.1"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 2.0"])
     else
-      s.add_dependency(%q<minitest>, [">= 5.3.0"])
-      s.add_dependency(%q<rdoc>, [">= 0"])
-      s.add_dependency(%q<bundler>, [">= 0"])
-      s.add_dependency(%q<jeweler>, [">= 0"])
-      s.add_dependency(%q<simplecov>, [">= 0"])
+      s.add_dependency(%q<minitest>, ["~> 5.3"])
+      s.add_dependency(%q<rdoc>, ["~> 4.1"])
+      s.add_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_dependency(%q<jeweler>, ["~> 2.0"])
     end
   else
-    s.add_dependency(%q<minitest>, [">= 5.3.0"])
-    s.add_dependency(%q<rdoc>, [">= 0"])
-    s.add_dependency(%q<bundler>, [">= 0"])
-    s.add_dependency(%q<jeweler>, [">= 0"])
-    s.add_dependency(%q<simplecov>, [">= 0"])
+    s.add_dependency(%q<minitest>, ["~> 5.3"])
+    s.add_dependency(%q<rdoc>, ["~> 4.1"])
+    s.add_dependency(%q<bundler>, ["~> 1.0"])
+    s.add_dependency(%q<jeweler>, ["~> 2.0"])
   end
 end
 

data/lib/arg-utils.rb

@@ -0,0 +1,52 @@
+# arg-utils.rb -- simple methods for managing variable argument lists
+#
+# Alan K. Stebbens <aks@stebbens.org>
+#
+#
+#    require 'arg-utils'
+#
+# defines two methods:
+#
+#   _msgargs(args, block_given?) { yield }
+#   _fmtargs(args, block_given?) { yield }
+#
+# These two functions can be used to pass a variable list of arguments
+# to a function accepting such, including possibly using a BLOCK to
+# produce some (or all) of the values.
+#
+# Example:
+#
+#   def dtalkf(*args) {
+#     if $debug
+#       $stderr.printf(*_fmtargs(args, block_given?) { yield })
+#     end
+#   }
+#
+# The arguments pass to `printf` will come from either the arguments
+# passed to `dtalkf` or the BLOCK given on the call to `dtalkf`.
+#
+
+####
+# _msgargs(args, block_given?) { yield }
+#
+# merge args with any block results
+
+def _msgargs args, flag
+  args.concat([yield].flatten) if flag
+  args
+end
+
+####
+# _fmtargs(args, block_given?) { yield }
+#
+# merge args with any block results
+# provide default format string if only one argument
+
+def _fmtargs args, flag
+  args.concat([yield].flatten) if flag
+  args.unshift('%s') if args.size < 2
+  args
+end
+
+# end of arg-utils.sh
+# vim: set ai sw=2

data/lib/cmd-utils.rb

@@ -1,279 +1,17 @@
-# cmd-utils.rb -- simple utilities for ruby command line tools
+# cmd-utils.rb -- a collection of utilities for ruby command line tools
 #
 # Alan K. Stebbens <aks@stebbens.org>
 #
-#
 #    require 'cmd-utils'
 #
-# Utilities for option-controlled output, and running commands.
-#
-# The output and run methods rely on some external variables:
-#
-#    $verbose -- enables vtalk(f) output
-#    $norun   -- enables nrtalk(f) output and controls the "run" command
-#    $quiet   -- enables qtalk(f) output, and disables talk(f) output
-#    $debug   -- enables dtalk(f) output
-#
-# These routines provide conditional output.  The arguments can be given as
-# part of the the function calls, or, can be provided as the return value of a
-# block.  The advantage of using a block is that the block is not evaluated
-# unless the conditions requiring output are met.  So, if the expression to
-# compute a value that _might_ be printed is expensive, do the computation
-# inside a block.
-#
-##
-# talk - Print msg on STDERR unless `$quiet` is set
-#
-# :call-seq:
-#    talk        msg ..
-#    talk      { msg .. }
-#    talkf fmt, args ...
-#    talkf fmt { [ args ... ] }
-
-def talk *args
-  if !$quiet && (args.size > 0 || block_given?)
-    $stderr.puts(*_msgargs(args, block_given?) { yield })
-  end
-end
-
-def talkf *args
-  if !$quiet && (args.size > 0 || block_given?)
-    $stderr.printf(*_fmtargs(args, block_given?) { yield } )
-  end
-end
-
-# _msgargs(args, block_given?) { yield }
-#
-# merge args with any block results
-
-def _msgargs args, flag
-  args.concat([yield].flatten) if flag
-  args
-end
-
-# _fmtargs(args, block_given?) { yield }
-#
-# merge args with any block results
-# provide default format string if only one argument
-
-def _fmtargs args, flag
-  args.concat([yield].flatten) if flag
-  args.unshift('%s') if args.size < 2
-  args
-end
-
-##
-# dtalk - "debug talk"
-# Print msg on STDERR only if `$debug` is set
-#
-# :call-seq:
-#     dtalk   msg
-#     dtalk { msg }
-#     dtalkf fmt,    args ..
-#     dtalkf fmt { [ args .. ] }
-
-def dtalk *args
-  if $debug && (args.size > 0 || block_given?)
-    $stderr.puts(*_msgargs(args, block_given?) { yield })
-  end
-end
-
-def dtalkf *args
-  if $debug && (args.size> 0 || block_given?)
-    $stderr.printf(*_fmtargs(args, block_given?) { yield })
-  end
-end
-
-##
-# qtalk - "quiet talk"
-# print msg on STDERR only if `$quiet` is set
-#
-# :call-seq:
-#     qtalk   msg
-#     qtalk { msg }
-#     qtalkf fmt,    args ..
-#     qtalkf fmt { [ args .. ] }
-
-def qtalk *args
-  if $quiet && (args.size > 0 || block_given?)
-    $stderr.puts(*_msgargs(args, block_given?) { yield })
-  end
-end
-
-def qtalkf *args
-  if $quiet && (args.size > 0 || block_given?)
-    $stderr.printf(*_fmtargs(args, block_given?) { yield } )
-  end
-end
-
-##
-# vtalk - "verbose talk"
-# Print msg on STDERR if `$verbose` is set
-#
-# :call-seq:
-#     vtalk   msg
-#     vtalk { msg }
-#     vtalkf fmt, args ..
-#     vtalkf fmt { args .. }
-
-def vtalk *args
-  if $verbose && (args.size > 0 || block_given?)
-    $stderr.puts(*_msgargs(args, block_given?) { yield })
-  end
-end
-
-def vtalkf *args
-  if $verbose && (args.size > 0 || block_given?)
-    $stderr.printf(*_fmtargs(args, block_given?) { yield } )
-  end
-end
-
-##
-# nvtalk -- "non-verbose" talk
-# Print msg on STDERR unless `$verbose` is set
-#
-# :call-seq:
-#     nvtalk msg
-#     nvtalk { msg }
-
-def  nvtalk *args
-  unless $verbose && (args.size > 0 || block_given?)
-    $stderr.puts(*_msgargs(args, block_given?) { yield })
-  end
-end
-
-def nvtalkf *args
-  unless $verbose && (args.size > 0 || block_given?)
-    $stderr.printf(*_fmtargs(args, block_given?) { yield } )
-  end
-end
-
-##
-# nrtalk -- "no run" talk
-# Print msg, prefixed with "(norun) ", on STDERR only if `$norun` is set
-#
-# :call-seq:
-#     nrtalk        msg
-#     nrtalk      { msg }
-#     nrtalkf fmt,  msg
-#     nrtalkf fmt { msg }
-
-def nrtalk *args
-  if $norun && (args.size > 0 || block_given?)
-    newargs = _msgargs(args, block_given?) { yield }
-    newargs[0] = '(norun) ' + newargs[0] unless newargs.size == 0 || newargs[0].nil? || newargs[0].include?('(norun)')
-    $stderr.puts(*newargs)
-  end
-end
-
-def nrtalkf *args
-  if $norun && (args.size > 0 || block_given?)
-    newargs = _fmtargs(args, block_given?) { yield }
-    newargs[0] = '(norun) ' + newargs[0] unless newargs.size == 0 || newargs[0].nil? || newargs[0].include?('(norun)')
-    $stderr.printf(*newargs)
-  end
-end
-
-##
-# error -- print an error message on STDERR, and then exit.
-# :call-seq:
-#     error   [code],   msg
-#     error(  [code]) { msg }
-#     error {[[code],   msg ] }
-#
-# Code defaults to 1 if not given.
-
-def error *args
-  args = _msgargs(args, block_given?) { yield }
-  code = args.size > 0 && args[0].class == Fixnum ? args.shift : 1
-  $stderr.puts(*args)
-  $stderr.flush
-  exit code
-end
-
-##
-# errorf -- print a formatted message on STDERR, and then exit
-#
-# :call-seq:
-#     errorf   [code],   fmt,   args ..
-#     errorf(  [code],   fmt) { args .. }
-#     errorf(  [code]) { fmt,   args .. }
-#     errorf {[[code],   fmt,   args .. ] }
-
-def errorf *args
-  args = _fmtargs(args, block_given?) { yield }
-  # default the error code to 1 unless the first argument is a Fixnum
-  code = args.size > 0 && args[0].class == Fixnum ? args.shift : 1
-  $stderr.printf(*args)
-  $stderr.flush
-  exit code
-end
-
-##
-# run -- run a command with support for testing, diagnostics and verbosity
-# safe_run -- run a command with support for diagnostics and verbosity
-#
-# Both may be given optional `errmsg` and `okmsg`, which are printed if given
-# for the corresponding condition.
-#
-# :call-seq:
-#     run         cmd
-#     run      {  cmd }
-#     run         cmd, errmsg
-#     run      { [cmd, errmsg] }
-#     run      { [cmd, errmsg, okmg] }
-#     run         cmd, errmsg, okmsg
-#
-#     safe_run    cmd
-#     safe_run    cmd, errmsg
-#     safe_run    cmd, errmsg, okmsg
-#     safe_run {  cmd }
-#     safe_run { [cmd, errmsg] }
-#     safe_run { [cmd, errmsg, okmsg] }
-#
-# if `$norun` is set, print `(norun) ` followed by `cmd` on `STDERR`, and
-# return.
-#
-# if `$verbose` is set, print `>> ` followed by `cmd` on `STDERR`.
-#
-# Invoke the `cmd` with the `system()` call.
-#
-# If there is an error, show the command (preceded by `>> `) if `$verbose` is
-# not set, then show the error code, followed by the given `errmsg` or the
-# default error message.
-#
-# The `cmd` can be given either as an argument, or as the returned value from a
-# block.  Important: the block should return a string value to be passed to
-# the system call.
-
-def cmd_run *args
-  args = _msgargs(args, block_given?) { yield }
-  if $norun
-    nrtalk(args.first)
-  elsif args.size > 0
-    safe_run *args
-  end
-end
-
-alias run cmd_run
+# This brings in several related utilities.
 
-def safe_run *args
-  args = _msgargs(args, block_given?) { yield }
-  cmd, errmsg, okmsg = args
-  vtalkf ">> %s\n", cmd
-  if cmd
-    if system cmd              # invoke the command
-      $stderr.puts okmsg if okmsg
-      return true
-    else                        # an error occured
-      qtalkf ">> %s\n", cmd
-      erm = sprintf(errmsg ? errmsg : "Command failed with code %d", $?>>8)
-      $stderr.puts erm
-      $stderr.flush
-      raise SystemCallError, erm            # instead of exit, use raise
-    end
-  end
-end
+require 'arg-utils'
+require 'talk-utils'
+require 'error-utils'
+require 'lookup'
+require 'run-utils'
+require 'ssh-utils'
 
 # end of cmd-utils.sh
 # vim: set ai sw=2