lib/mcollective/vendor/systemu/README

   1 NAME
   2
   3   systemu
   4
   5 SYNOPSIS
   6
   7   universal capture of stdout and stderr and handling of child process pid for
   8   windows, *nix, etc.
   9
  10 URIS
  11
  12   http://github.com/ahoward/systemu
  13   http://rubyforge.org/projects/codeforpeople/
  14
  15 INSTALL
  16
  17   gem install systemu
  18
  19 HISTORY
  20   2.0.0
  21     - versioning issue.  new gem release.
  22
  23   1.3.1
  24     - updates for ruby 1.9.1
  25
  26   1.3.0
  27     - move to github
  28
  29   1.2.0
  30
  31     - fixed handling of background thread management - needed
  32       Thread.current.abort_on_exception = true
  33
  34     - fixed reporting of child pid, it was reported as the parent's pid before
  35
  36 SAMPLES
  37
  38
  39   <========< samples/a.rb >========>
  40
  41   ~ > cat samples/a.rb
  42
  43     #
  44     # systemu can be used on any platform to return status, stdout, and stderr of
  45     # any command.  unlike other methods like open3/popen4 there is zero danger of
  46     # full pipes or threading issues hanging your process or subprocess.
  47     #
  48       require 'systemu'
  49
  50       date = %q( ruby -e"  t = Time.now; STDOUT.puts t; STDERR.puts t  " )
  51
  52       status, stdout, stderr = systemu date
  53       p [ status, stdout, stderr ]
  54
  55   ~ > ruby samples/a.rb
  56
  57     [#<Process::Status: pid 50931 exit 0>, "2011-12-11 22:07:30 -0700\n", "2011-12-11 22:07:30 -0700\n"]
  58
  59
  60   <========< samples/b.rb >========>
  61
  62   ~ > cat samples/b.rb
  63
  64     #
  65     # quite a few keys can be passed to the command to alter it's behaviour.  if
  66     # either stdout or stderr is supplied those objects should respond_to? '<<'
  67     # and only status will be returned
  68     #
  69       require 'systemu'
  70
  71       date = %q( ruby -e"  t = Time.now; STDOUT.puts t; STDERR.puts t  " )
  72
  73       stdout, stderr = '', ''
  74       status = systemu date, 'stdout' => stdout, 'stderr' => stderr
  75       p [ status, stdout, stderr ]
  76
  77   ~ > ruby samples/b.rb
  78
  79     [#<Process::Status: pid 50936 exit 0>, "2011-12-11 22:07:30 -0700\n", "2011-12-11 22:07:30 -0700\n"]
  80
  81
  82   <========< samples/c.rb >========>
  83
  84   ~ > cat samples/c.rb
  85
  86     #
  87     # of course stdin can be supplied too.  synonyms for 'stdin' include '0' and
  88     # 0.  the other stdio streams have similar shortcuts
  89     #
  90       require 'systemu'
  91
  92       cat = %q( ruby -e"  ARGF.each{|line| puts line}  " )
  93
  94       status = systemu cat, 0=>'the stdin for cat', 1=>stdout=''
  95       puts stdout
  96
  97   ~ > ruby samples/c.rb
  98
  99     the stdin for cat
 100
 101
 102   <========< samples/d.rb >========>
 103
 104   ~ > cat samples/d.rb
 105
 106     #
 107     # the cwd can be supplied
 108     #
 109       require 'systemu'
 110       require 'tmpdir'
 111
 112       pwd = %q( ruby -e"  STDERR.puts Dir.pwd  " )
 113
 114       status = systemu pwd, 2=>(stderr=''), :cwd=>Dir.tmpdir
 115       puts stderr
 116
 117
 118   ~ > ruby samples/d.rb
 119
 120     /private/var/folders/sp/nwtflj890qnb6z4b53dqxvlw0000gp/T
 121
 122
 123   <========< samples/e.rb >========>
 124
 125   ~ > cat samples/e.rb
 126
 127     #
 128     # any environment vars specified are merged into the child's environment
 129     #
 130       require 'systemu'
 131
 132       env = %q( ruby -r yaml -e"  puts ENV[ 'answer' ] " )
 133
 134       status = systemu env, 1=>stdout='', 'env'=>{ 'answer' => 0b101010 }
 135       puts stdout
 136
 137   ~ > ruby samples/e.rb
 138
 139     42
 140
 141
 142   <========< samples/f.rb >========>
 143
 144   ~ > cat samples/f.rb
 145
 146     #
 147     # if a block is specified then it is passed the child pid and run in a
 148     # background thread.  note that this thread will __not__ be blocked during the
 149     # execution of the command so it may do useful work such as killing the child
 150     # if execution time passes a certain threshold
 151     #
 152       require 'systemu'
 153
 154       looper = %q( ruby -e" loop{ STDERR.puts Time.now.to_i; sleep 1 } " )
 155
 156       status, stdout, stderr =
 157         systemu looper do |cid|
 158           sleep 3
 159           Process.kill 9, cid
 160         end
 161
 162       p status
 163       p stderr
 164
 165   ~ > ruby samples/f.rb
 166
 167     #<Process::Status: pid 50956 SIGKILL (signal 9)>
 168     "1323666451\n1323666452\n1323666453\n"
 169
 170