URLS: |

  http://raa.ruby-lang.org/project/session/
  http://www.codeforpeople.com/lib/ruby/session/


NAME: |

  Session
    ::Sh
    ::Bash
    ::Shell
    ::IDL

SYNOPSIS: |

  Session::* offers a set of classes built upon Open3::popen3 for driving
  external progams via pipes.  It offers a significant abstraction over
  Open3::popen in that the stdout/stderr of each command sent can be deliniated:

    open3:

        i.o,e = Open3::popen3 '/bin/sh'

        i.puts 'ls'
        i.puts 'echo 42'

    now, how to determine the boundry between the output from 'ls' and 'echo'?
    the only (simple) way is start a process for each command

        i.o,e = Open3::popen3 '/bin/sh'
        i.puts 'ls'
        i.close
        stdout, stderr = o.read, e.read

        i.o,e = Open3::popen3 '/bin/sh'
        i.puts 'echo 42'
        i.close
        stdout, stderr = o.read, e.read

    session:

      sh = Session::new

      stdout, stderr = sh.execute 'ls'
      stdout, stderr = sh.execute 'echo 42'

  Both stderr and stdout can be redirected, and the exit_status of each command
  is made available:

      bash = Session::Bash.new
      stdout, stderr = StringIO::new, StringIO::new

      bash.execute 'ls', :stdout => stdout, :stderr => stderr
      # bash.execute 'ls', 1 => stdout, 2 => stderr           # same thing
      # bash.execute 'ls', :o => stdout, :e => stderr         # same thing

      exit_status = bash.exit_status

  A block form can be used to specify a callback to be invoked whenever output
  has become availible:

    bash = Session::Bash.new

    bash.execute( 'long_running_command.exe' ) do |out, err|
      logger << out if out
      elogger << err if err
    end

  Sessions are Thread safe (in the sense that they do not block on io
  operations) allowing commands spawned from guis to update widgets with output
  while running in the background.

    button.configure 'action' => lambda do
      sh = Session::new
      sh.execute(cmd) do |o,e|
        out_widget.update o if o
        err_widget.update e if e
      end
    end

SAMPLES: |

  see samples/*


AUTHOR: |

  ara.t.howard@noaa.gov