obfusk-util 0.0.1.SNAPSHOT.20130724234552

data/README.md

@@ -0,0 +1,232 @@
+[]: {{{1
+
+    File        : README.md
+    Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+    Date        : 2013-07-24
+
+    Copyright   : Copyright (C) 2013  Felix C. Stegerman
+    Version     : v0.0.1.SNAPSHOT
+
+[]: }}}1
+
+## Description
+[]: {{{1
+
+  [rb-]obfusk-util - miscellaneous utility library for ruby
+
+  ...
+
+[]: }}}1
+
+## Examples
+[]: {{{1
+
+[]: {{{2
+
+```ruby
+Obfusk::Util::Cmd.killsig 'SIGINT foo bar'
+# => { command: 'foo bar', signal: 'SIGINT' }
+
+Obfusk::Util::Cmd.killsig 'foo bar'
+# => { command: 'foo bar', signal: 'SIGTERM' }
+
+Obfusk::Util::Cmd.shell 'SHELL echo "$FOO: $BAR"'
+# => { command: 'echo "$FOO: $BAR"', shell: 'bash' }
+
+Obfusk::Util::Cmd.set_vars 'echo ${FOO} ... ${BAR} ...',
+  { 'FOO' => 'foo', 'BAR' => 'bar' }
+# => 'echo foo ... bar ...'
+```
+
+[]: }}}2
+
+[]: {{{2
+
+```ruby
+x = { x: { y: 0 }, z: [1,2,3] }
+Obfusk::Util.assoc(x, [:x,:y] => 1, [:z,1] => 99)
+x[:x][:y] == 1          # => true
+x[:z]     == [1,99,3]   # => true
+
+y = Obfusk::Util.deepdup x
+Obfusk::Util.empty_as_nil(ENV['FOO']) || default
+```
+
+[]: }}}2
+
+[]: {{{2
+
+```ruby
+Obfusk::Util::FS.append 'file', *lines
+Obfusk::Util::FS.exists? 'file-or-possibly-broken-symlink'
+```
+
+[]: }}}2
+
+[]: {{{2
+
+```ruby
+Obfusk::Util.ohai *%w{ rackup -p 8888 }
+# shows '==> rackup -p 8888' in colour
+
+Obfusk::Util.onow 'Starting', 'foo', 'bar'
+# shows '==> Starting: foo, bar' in colour
+
+Obfusk::Util.onoe 'Something is wrong!' # error in colour
+Obfusk::Util.opoo 'This looks funny!'   # warning in colour
+```
+
+There are some o\* methods all over obfusk-util that combine some
+operation with e.g. ohai.
+
+[]: }}}2
+
+[]: {{{2
+
+```ruby
+Obfusk::Util.require_all 'foo/bar'
+# requires foo/bar/*
+
+Obfusk::Util.submodules Foo
+# => { 'bar' => Foo::Bar, 'baz' => Foo:Baz, ... }
+```
+
+[]: }}}2
+
+[]: {{{2
+
+Slightly improved OptionParser (w/o officious options):
+
+```ruby
+p = Obfusk::Util::Opt::Parser.new # ...
+remaining_args = p.parse_r ARGV
+```
+
+[]: }}}2
+
+[]: {{{2
+
+```ruby
+Obfusk::Util::OS.home         # => current user's home
+Obfusk::Util::OS.home 'user'  # => user's home
+Obfusk::Util::OS.user         # => current user
+Obfusk::Util::OS.now          # => current time as '%F %T'
+```
+
+[]: }}}2
+
+[]: {{{2
+
+```ruby
+Obfusk::Util::Process.age pid     # => e.g. '01:06:19'
+Obfusk::Util::Process.alive? pid  # => false/true/:not_mine
+```
+
+[]: }}}2
+
+[]: {{{2
+
+spawn_w is spawn + wait (which is nicer than system).  No shell is
+ever used; env is an option instead of an optional first argument;
+ENOENT becomes RunError.  See also: exec, spawn, system, popen3.
+
+```ruby
+Obfusk::Util.spawn_w *%w{ some command }, env: { 'FOO' => 'bar' },
+  chdir: 'some/dir' #, ...
+# => $?
+
+# raise RunError if command returned non-zero
+Obfusk::Util.chk_exit(%w{ some command }) do |a|
+  # spawn + wait + ohai
+  Obfusk::Util.ospawn_w *a
+end
+```
+
+[]: }}}2
+
+[]: {{{2
+
+```ruby
+Foo = Obfusk::Util.struct(*%w{ field1 field2 field3 }) do
+  def some_method; field1 + field2; end
+end
+
+foo = Foo.new field1: 37, field2: 5
+foo.some_method # => 42
+
+# build a Foo which is frozen when the block ends
+bar = Foo.build(field1: 99) do |x|
+  c.field2 = 1
+  # ...
+end
+
+bar.field3 = 99   # => RuntimeError b/c frozen
+bar.check!        # => IncompleteError b/c there are empty fields
+```
+
+[]: }}}2
+
+[]: {{{2
+
+```ruby
+Obfusk::Util::Term.colour :red
+# => ansi escape code if $stdout is a tty, '' otherwise
+
+Obfusk::Util::Term.columns                # terminal columns
+Obfusk::Util::Term.lines                  # terminal lines
+Obfusk::Util::Term.tty?                   # is $stdout a tty?
+Obfusk::Util::Term.tty? :err              # is $stderr a tty?
+
+Obfusk::Util::Term.prompt 'foo> '         # prompt for input
+Obfusk::Util::Term.prompt 'foo> ', :hide  # prompt for password
+```
+
+[]: }}}2
+
+[]: {{{2
+
+```ruby
+def foo(*args_)
+  Obfusk::Util::Valid.args 'description', args_, 1, 3
+  # => ArgumentError if #args not in 1..3
+end
+```
+
+[]: }}}2
+
+[]: }}}1
+
+## Specs & Docs
+[]: {{{1
+
+    $ rake spec
+    $ rake docs
+
+[]: }}}1
+
+## TODO
+[]: {{{1
+
+  * write more specs
+  * write more docs
+  * dual-license under EPLv1?
+  * ...
+
+[]: }}}1
+
+## License
+[]: {{{1
+
+  GPLv2 [1].
+
+[]: }}}1
+
+## References
+[]: {{{1
+
+  [1] GNU General Public License, version 2
+  --- http://www.opensource.org/licenses/GPL-2.0
+
+[]: }}}1
+
+[]: ! ( vim: set tw=70 sw=2 sts=2 et fdm=marker : )

data/lib/obfusk/util/all.rb

@@ -0,0 +1,29 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/all.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+require 'obfusk/util/cmd'
+require 'obfusk/util/data'
+require 'obfusk/util/die'
+require 'obfusk/util/fs'
+require 'obfusk/util/message'
+require 'obfusk/util/misc'
+require 'obfusk/util/module'
+require 'obfusk/util/opt'
+require 'obfusk/util/os'
+require 'obfusk/util/process'
+require 'obfusk/util/run'
+require 'obfusk/util/spec'
+require 'obfusk/util/struct'
+require 'obfusk/util/term'
+require 'obfusk/util/valid'
+require 'obfusk/util/version'
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/cmd.rb

@@ -0,0 +1,69 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/cmd.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+# my namespace
+module Obfusk; module Util; module Cmd
+
+  SIG_RX  = /^(SIG[A-Z0-9]+)\s+(.*)$/
+  SH_RX   = /^SHELL(=(\S+))?\s+(.*)$/
+  VAR_RX  = / \$ \{ ([A-Z_]+) \} /x
+
+  # --
+
+  # parses optional `SIG*` prefix in command string;
+  # (e.g. `'SIGINT foo bar ...'`);
+  # if there is no prefix, signal is default
+  # @return [Hash] `{ command: command, signal: signal }`
+  def self.killsig(cmd, default = 'SIGTERM')                    # {{{1
+    if m = cmd.match(SIG_RX)
+      { command: m[2], signal: m[1] }
+    else
+      { command: cmd, signal: default }
+    end
+  end                                                           # }}}1
+
+  # parses optional `SHELL[=...]` prefix in command string
+  # (e.g. `'SHELL=bash foo bar ...'`, `'SHELL foo bar ...'`);
+  # if there is no prefix, shell is nil;
+  # if there is no `=...`, shell is default
+  # @return [Hash] `{ command: command, shell: shell }`
+  def self.shell(cmd, default = 'bash')                         # {{{1
+    if m = cmd.match(SH_RX)
+      { command: m[3], shell: (m[2] || default) }
+    else
+      { command: cmd, shell: nil }
+    end
+  end                                                           # }}}1
+
+  # --
+
+  # prepend nohup to args
+  def self.nohup(*args)
+    ['nohup'] + args
+  end
+
+  # replaces `${VAR}s` in command string using vars hash;
+  # missing values are replaced with empty strings
+  def self.set_vars(cmd, vars)
+    cmd.gsub(VAR_RX) { |m| vars[$1] }
+  end
+
+  # --
+
+  # env hash as array (w/o nil values)
+  # @return [<String>] `['k1="v1"', ...]`
+  def self.env_to_a(h)
+    h.reject { |k,v| v.nil? } .map { |k,v| "#{k}=#{v.inspect}" }
+  end
+
+end; end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/data.rb

@@ -0,0 +1,53 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/data.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+# my namespace
+module Obfusk; module Util
+
+  # assoc key(s) w/ value(s); array keys represent nested keys;
+  # will autovivivy missing (if false/nil) nested objects as hashes
+  #
+  # ```
+  # x = { x: { y: 0 } }; assoc(x, [:x,:y] => 1); x[:x][:y] == 1
+  # ```
+  def self.assoc(x, h = {})                                   # {{{1
+    h.each do |k,v|
+      if k.is_a? Array
+        case k.length
+        when 0; raise ArgumentError, 'empty array key'
+        when 1; x[k.first] = v
+        else    h, *t = k; assoc (x[h] ||= {}), t => v
+        end
+      else
+        x[k] = v
+      end
+    end
+    x
+  end                                                         # }}}1
+
+  # deep copy using Marshal
+  def self.deepdup(obj)
+    Marshal.load Marshal.dump obj
+  end
+
+  # nil if x is `.empty?`, x otherwise
+  def self.empty_as_nil(x)
+    x && x.empty? ? nil : x
+  end
+
+  # hash to struct
+  def self.h_to_struct(h = {})
+    Struct.new(*h.keys).new(*h.values)
+  end
+
+end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/die.rb

@@ -0,0 +1,45 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/die.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+# my namespace
+module Obfusk; module Util
+
+  # print msgs to stderr and exit 1;
+  # pass `{ status: code }` as last argument to use other statuscode
+  def self.die!(*msgs)
+    code = _die_msgs msgs; exit code
+  end
+
+  # print msgs to stderr, show usage, exit
+  def self.udie!(usage, *msgs)
+    code = _die_msgs msgs; $stderr.puts "Usage: #{usage}"; exit code
+  end
+
+  # --
+
+  # onoe, exit; requires `obfusk/util/message`
+  def self.odie!(msg, opts = {})
+    o = opts.dup; c = o.delete(:status) || 1
+    ::Obfusk::Util.onoe msg, o; exit c
+  end
+
+  # --
+
+  # helper; modifies msgs -> OK b/c comes from *msgs
+  def self._die_msgs(msgs)
+    code = (msgs.last.is_a?(Hash) && msgs.pop[:status]) || 1
+    msgs.each { |m| $stderr.puts "Error: #{m}" }
+    code
+  end
+
+end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/fs.rb

@@ -0,0 +1,35 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/fs.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+require 'fileutils'
+
+# my namespace
+module Obfusk; module Util; module FS
+
+  # append to file
+  def self.append(file, *lines)
+    File.open(file, 'a') { |f| f.puts lines }
+  end
+
+  # does file/dir or symlink exists?
+  def self.exists?(path)
+    File.exists?(path) || File.symlink?(path)
+  end
+
+  # ohai + mkdir_p; requires `obfusk/util/message`
+  def self.omkdir_p(*paths)
+    ::Obfusk::Util.ohai "mkdir -p #{paths*' '}"
+    FileUtils.mkdir_p paths
+  end
+
+end; end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/message.rb

@@ -0,0 +1,73 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/message.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+require 'obfusk/util/term'
+
+# my namespace
+module Obfusk; module Util
+
+  # info message w/ colours:
+  # ```
+  # "==> <msg>"
+  # ```
+  def self.ohai(msg)
+    puts _tcol(:lbl) + '==> ' + _tcol(:whi) + msg + _tcol(:non)
+  end
+
+  # info message w/ colours:
+  # ```
+  # "==> <msg>: <a>[, <b>, ...]"
+  # ```
+  def self.onow(msg, *what)
+    puts _tcol(:lgn) + '==> ' + _tcol(:whi) + msg + _tcol(:non) +
+      (what.empty? ? '' : _owhat(what))
+  end
+
+  # --
+
+  # error message w/ colours:
+  # ```
+  # "<label>: <msg>"
+  # ```
+  #
+  # `opts[:label]` defaults to 'Error';
+  # set `opts[:log]` to a lambda to pass message on to a logger
+  def self.onoe(msg, opts = {})
+    l = opts[:label] || 'Error'
+    $stderr.puts _tcole(:lrd) + l + _tcole(:non) + ': ' + msg
+    opts[:log]["#{l}: #{msg}"] if opts[:log]
+  end
+
+  # warning message (onoe w/ label 'Warning')
+  def self.opoo(msg, opts = {})
+    onoe msg, opts.merge(label: 'Warning')
+  end
+
+  # --
+
+  # (helper for onow)
+  def self._owhat(what)
+    ': ' + what.map { |x| _tcol(:lgn) + x + _tcol(:non) } *', '
+  end
+
+  # Term.colour
+  def self._tcol(*a)
+    Term.colour *a
+  end
+
+  # Term.colour_e
+  def self._tcole(*a)
+    Term.colour_e *a
+  end
+
+end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/misc.rb

@@ -0,0 +1,19 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/misc.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-17
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+# my namespace
+module Obfusk; module Util
+
+  # ...
+
+end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/module.rb

@@ -0,0 +1,41 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/module.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+# my namespace
+module Obfusk; module Util
+
+  # load `dir/*` (by searching for `dir/*.rb` in `$LOAD_PATH`)
+  #
+  # ```
+  # require_all('napp/types') ~> require 'napp/types/*'
+  # ```
+  #
+  # @return [Hash] `{ module => result-of-require }`
+  def self.require_all(dir)
+    Hash[ $LOAD_PATH.map { |x| Dir["#{x}/#{dir}/*.rb"] } .flatten \
+            .map { |x| "#{dir}/" + File.basename(x, '.rb') } .uniq \
+            .map { |x| y = require x; [x,y] } ]
+  end
+
+  # get submodules as hash
+  #
+  # ```
+  # submodules(Foo) -> { 'bar' => Foo::Bar, ... }
+  # ```
+  def self.submodules(mod)
+    Hash[ mod.constants \
+          .map { |x| [x.downcase.to_s, mod.const_get(x)] } \
+          .select { |k,v| v.class == Module } ]
+  end
+
+end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/opt.rb

@@ -0,0 +1,37 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/opt.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+require 'optparse'
+
+# my namespace
+module Obfusk; module Util; module Opt
+
+  # better OptionParser
+  class Parser < OptionParser
+    # do nothing!
+    def add_officious; end
+
+    # parse options, return remaining args
+    def parse_r(args)
+      as = args.dup; parse! as; as
+    end
+  end
+
+  # --
+
+  # parse options, return remaining args
+  def self.parse(op, args)
+    as = args.dup; op.parse! as; as
+  end
+
+end; end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/os.rb

@@ -0,0 +1,36 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/os.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+require 'etc'
+
+# my namespace
+module Obfusk; module Util; module OS
+
+  # home dir of (current) user
+  def self.home(user = nil)
+    user ? Etc.getpwnam(user).dir : Dir.home
+  end
+
+  # user name
+  def self.user
+    Etc.getlogin
+  end
+
+  # --
+
+  # current time ('%F %T')
+  def self.now(fmt = '%F %T')
+    Time.now.strftime fmt
+  end
+
+end; end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/process.rb

@@ -0,0 +1,41 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/process.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+# my namespace
+module Obfusk; module Util; module Process
+
+  GET_AGE = ->(pid) { "ps -p #{pid} -o etime=" }
+
+  # --
+
+  # get process age information from ps
+  def self.age(pid)
+    ispid! pid; %x[#{GET_AGE[pid]}].gsub(/\s/, '')
+  end
+
+  # process alive?
+  # @return [Boolean] false if not alive
+  # @return [Boolean] true if alive and mine
+  # @return [Symbol]  :not_mine if alive and not mine
+  def self.alive?(pid)
+    ::Process.kill 0, pid; true
+  rescue Errno::EPERM; :not_mine
+  rescue Errno::ESRCH; false
+  end
+
+  # @raise ArgumentError if pid is not an integer
+  def self.ispid!(pid)
+    pid.is_a? Integer or raise ArgumentError, 'invalid PID'
+  end
+
+end; end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/run.rb

@@ -0,0 +1,124 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/run.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+require 'open3'
+
+# my namespace
+module Obfusk; module Util
+
+  class RunError < RuntimeError; end
+
+  # --
+
+  # better Kernel.exec; should never return (if successful);
+  # see spawn, spawn_w, system
+  # @raise RunError on ENOENT
+  def self.exec(*args)
+    _enoent_to_run('exec', args) do |a|
+      Kernel.exec *_spawn_args(*a)
+    end
+  end
+
+  # better Kernel.spawn; options can be passed as last arg like w/
+  # Kernel.spawn, but instead of env as optional first arg, options
+  # takes an :env key as well; also, no shell is ever used;
+  # returns PID; see exec, spawn_w, system
+  # @raise RunError on ENOENT
+  def self.spawn(*args)
+    _enoent_to_run('spawn', args) do |a|
+      Kernel.spawn *_spawn_args(*a)
+    end
+  end
+
+  # better system: spawn + wait; returns $?; see exec, spawn, system
+  def self.spawn_w(*args)
+    pid = spawn(*args); ::Process.wait pid; $?
+  end
+
+  # better Kernel.system; returns true/false; see exec, spawn, spawn_w
+  # @raise RunError on failure (Kernel.system -> nil)
+  def self.system(*args)
+    r = Kernel.system *_spawn_args(*args)
+    raise RunError, "failed to run command #{args} (#$?)" if r.nil?
+    r
+  end
+
+  # --
+
+  # better Open3.popen3; see exec, spawn, spawn_w, system
+  # @raise RunError on ENOENT
+  def self.popen3(*args, &b)
+    _enoent_to_run('popen3', args) do |a|
+      Open3.popen3 *_spawn_args(*a), &b
+    end
+  end
+
+  # --
+
+  # ohai + spawn; requires `obfusk/util/message`
+  def self.ospawn(*args)
+    ::Obfusk::Util.ohai _spawn_rm_opts(args)*' '; spawn *args
+  end
+
+  # ohai + spawn_w; requires `obfusk/util/message`
+  def self.ospawn_w(*args)
+    ::Obfusk::Util.ohai _spawn_rm_opts(args)*' '; spawn_w *args
+  end
+
+  # --
+
+  # run block w/ args, check `.exitstatus`
+  # @raise RunError if Process::Status's exitstatus is non-zero
+  def self.chk_exit(args, &b)
+    chk_exitstatus args, b[args].exitstatus
+  end
+
+  # @raise RunError if c != 0
+  def self.chk_exitstatus(args, c)
+    exit_non_zero! args, c if c != 0
+  end
+
+  # @raise RunError command returned non-zero
+  def self.exit_non_zero!(args, c)
+    raise RunError, "command returned non-zero: #{args} -> #{c}"
+  end
+
+  # --
+
+  # helper
+  def self._enoent_to_run(what, args, &b)                       # {{{1
+    begin
+      b[args]
+    rescue Errno::ENOENT => e
+      raise RunError,
+        "failed to #{what} command #{args}: #{e.message}"
+    end
+  end                                                           # }}}1
+
+  # helper
+  def self._spawn_args(cmd, *args)                              # {{{1
+    c = [cmd, cmd]
+    if args.last && (l = args.last.dup).is_a?(Hash) \
+                 && e = l.delete(:env)
+      [e, c] + args[0..-2] + [l]
+    else
+      [c] + args
+    end
+  end                                                           # }}}1
+
+  # helper
+  def self._spawn_rm_opts(args)
+    args.last.is_a?(Hash) ? args[0..-2] : args
+  end
+
+end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/spec.rb

@@ -0,0 +1,55 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/spec.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+require 'stringio'
+
+# my namespace
+module Obfusk; module Util
+
+  # use StringIO to provide $stdin to block
+  def self.provide_stdin(str, isatty = false, &b)               # {{{1
+    old = $stdin
+    begin
+      StringIO.open(str, 'r') do |s|
+        def s.isatty; true; end if isatty; $stdin = s; b[]
+      end
+    ensure
+      $stdin = old
+    end
+  end                                                           # }}}1
+
+  # use StringIO to capture $stdout from block
+  def self.capture_stdout(isatty = false, &b)                   # {{{1
+    old = $stdout
+    begin
+      StringIO.open('', 'w') do |s|
+        def s.isatty; true; end if isatty; $stdout = s; b[]; s.string
+      end
+    ensure
+      $stdout = old
+    end
+  end                                                           # }}}1
+
+  # use StringIO to capture $stderr from block
+  def self.capture_stderr(isatty = false, &b)                   # {{{1
+    old = $stderr
+    begin
+      StringIO.open('', 'w') do |s|
+        def s.isatty; true; end if isatty; $stderr = s; b[]; s.string
+      end
+    ensure
+      $stderr = old
+    end
+  end                                                           # }}}1
+
+end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/struct.rb

@@ -0,0 +1,83 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/struct.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+# my namespace
+module Obfusk; module Util
+
+  # better Struct; create using Obfusk::Util.struct
+  module BetterStruct                                           # {{{1
+
+    class IncompleteError < RuntimeError; end
+
+    # --
+
+    # include class methods as well
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods                                         # {{{2
+
+      # new, block, freeze, return
+      def build(h = {}, &b)
+        x = new h; b[x] if b; x.freeze
+      end
+
+    end                                                         # }}}2
+
+    # checks for missing fields, returns self
+    # @raise IncompleteError if any fields are nil
+    def check!
+      members.each do |f|
+        self[f].nil? and raise IncompleteError, "empty field: #{f}"
+      end; self
+    end
+
+    # def with(h = {}, &b)
+    #   x = dup
+    #   h.each {
+    # end
+
+    unless Struct.method_defined? :to_h
+      # convert to hash (ruby 2 has this already)
+      def to_h
+        Hash[each_pair.to_a]
+      end
+    end
+
+    # convert to hash w/ string keys
+    def to_str_h
+      Hash[to_h.map { |k,v| [k.to_s,v] }]
+    end
+
+  end                                                           # }}}1
+
+  # --
+
+  # better struct; see examples in README.md
+  def self.struct(*fields, &b)                                  # {{{1
+    Class.new(Struct.new(*fields.map(&:to_sym))) do
+
+      include BetterStruct
+
+      # init w/ hash
+      def initialize(h = {})
+        h.each { |k,v| self[k] = v }
+      end
+
+      self.class_eval &b if b
+
+    end
+  end                                                           # }}}1
+
+end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/term.rb

@@ -0,0 +1,94 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/term.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+require 'io/console'
+
+# my namespace
+module Obfusk; module Util; module Term
+
+  # ansi colour codes
+  TERM_COLOUR_CODES = {                                         # {{{1
+    black:      '0;30', dark_gray:    '1;30',
+    blue:       '0;34', light_blue:   '1;34',
+    green:      '0;32', light_green:  '1;32',
+    cyan:       '0;36', light_cyan:   '1;36',
+    red:        '0;31', light_red:    '1;31',
+    purple:     '0;35', light_purple: '1;35',
+    brown:      '0;33', yellow:       '1;33',
+    light_gray: '0;37', white:        '1;37',
+    none:       '0'
+  }                                                             # }}}1
+
+  # some colour aliases
+  TERM_COLOUR_ALIASES = {                                       # {{{1
+    bla: :black,      dgr: :dark_gray,
+    blu: :blue,       lbl: :light_blue,
+    grn: :green,      lgn: :light_green,
+    cyn: :cyan,       lcy: :light_cyan,   lrd: :light_red,
+    pur: :purple,     lpu: :light_purple,
+    bro: :brown,      yel: :yellow,
+    lgr: :light_gray, whi: :white,        non: :none,
+  }                                                             # }}}1
+
+  # ansi colour escapes
+  TERM_COLOUR_ESCAPES = (->(;a,b) {
+    a = Hash[TERM_COLOUR_CODES.map   { |k,v| [k,"\e[#{v}m"] }]
+    b = Hash[TERM_COLOUR_ALIASES.map { |k,v| [k,    a[v]  ] }]
+    a.merge b
+  })[]
+
+  GET_COLS  = 'TERM=${TERM:-dumb} tput cols'
+  GET_LINES = 'TERM=${TERM:-dumb} tput lines'
+
+  # --
+
+  # colour code (or '' if not tty)
+  def self.colour(x, what = :out)
+    c = TERM_COLOUR_ESCAPES[x] or raise ArgumentError,
+          "No such colour: #{x}"
+    tty?(what) ? c : ''
+  end
+
+  # colour code for $stderr
+  def self.colour_e(x)
+    colour x, :err
+  end
+
+  # --
+
+  # terminal columns
+  def self.columns
+    %x[#{GET_COLS}].to_i
+  end
+
+  # terminal lines
+  def self.lines
+    %x[#{GET_LINES}].to_i
+  end
+
+  # is $stdout (or $stderr) a tty?
+  def self.tty?(what = :out)
+    (what == :out ? $stdout : $stderr).isatty
+  end
+
+  # --
+
+  # prompt for line; optionally hide input
+  def self.prompt(prompt, hide = false)
+    print prompt; $stdout.flush
+    line = hide ? $stdin.noecho { |i| i.gets } .tap { puts } :
+                  $stdin.gets
+    line && line.chomp
+  end
+
+end; end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/valid.rb

@@ -0,0 +1,43 @@
+# --                                                            ; {{{1
+#
+# File        : obfusk/util/valid.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-07-24
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
+# my namespace
+module Obfusk; module Util; module Valid
+
+  class ArgumentError < RuntimeError; end
+  class ValidationError < RuntimeError; end
+
+  # --
+
+  # validate #args in min..max (min.. if max is nil)
+  # @return [Array] args
+  # @raise ArgumentError on out of bounds
+  def self.args(what, args, min, max = min)
+    if (l = args.length) < min || (max && l > max)
+      raise ArgumentError,
+        "#{what} expected #{min}..#{max} arguments, got #{l}"
+    end; args
+  end
+
+  # @raise ValidationError
+  def self.invalid!(msg)
+    raise ValidationError, msg
+  end
+
+  # validate value against regex
+  # @raise ValidationError on no match
+  def self.validate!(x, rx, name)
+    x.to_s.match /^(#{rx})$/ or invalid! "invalid #{name}"
+  end
+
+end; end; end
+
+# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/obfusk/util/version.rb

@@ -0,0 +1,5 @@
+# my namespace
+module Obfusk; module Util
+  VERSION = '0.0.1.SNAPSHOT.20130724234552'
+  DATE    = '2013-07-24'
+end; end

data/obfusk-util.gemspec

@@ -0,0 +1,27 @@
+require File.expand_path('../lib/obfusk/util/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = 'obfusk-util'
+  s.homepage    = 'https://github.com/obfusk/rb-obfusk-util'
+  s.summary     = 'miscellaneous utility library for ruby'
+
+  s.description = <<-END.gsub(/^ {4}/, '')
+    ...
+  END
+
+  s.version     = Obfusk::Util::VERSION
+  s.date        = Obfusk::Util::DATE
+
+  s.authors     = [ 'Felix C. Stegerman' ]
+  s.email       = %w{ flx@obfusk.net }
+
+  s.license     = 'GPLv2'
+
+  s.files       = %w{ README.md obfusk-util.gemspec }\
+                + Dir['lib/**/*.rb']
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec'
+
+  s.required_ruby_version = '>= 1.9.1'
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: obfusk-util
+version: !ruby/object:Gem::Version
+  version: 0.0.1.SNAPSHOT.20130724234552
+  prerelease: 6
+platform: ruby
+authors:
+- Felix C. Stegerman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &15323640 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *15323640
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &15321480 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *15321480
+description: ! '...
+
+'
+email:
+- flx@obfusk.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- obfusk-util.gemspec
+- lib/obfusk/util/message.rb
+- lib/obfusk/util/struct.rb
+- lib/obfusk/util/spec.rb
+- lib/obfusk/util/os.rb
+- lib/obfusk/util/version.rb
+- lib/obfusk/util/process.rb
+- lib/obfusk/util/run.rb
+- lib/obfusk/util/data.rb
+- lib/obfusk/util/opt.rb
+- lib/obfusk/util/fs.rb
+- lib/obfusk/util/term.rb
+- lib/obfusk/util/misc.rb
+- lib/obfusk/util/valid.rb
+- lib/obfusk/util/all.rb
+- lib/obfusk/util/die.rb
+- lib/obfusk/util/module.rb
+- lib/obfusk/util/cmd.rb
+homepage: https://github.com/obfusk/rb-obfusk-util
+licenses:
+- GPLv2
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: miscellaneous utility library for ruby
+test_files: []
+has_rdoc: