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/*

HISTORY: |
  3.1.0:
    - patches from @headius

  3.0.0
    - move to github

  2.4.0:
    - added ability to specify stdin for Session::Bash and Session::Sh

        sh = Session::new

        sh.execute 'cat', :stdin => io
        sh.execute 'cat', :stdin => string
        sh.execute 'cat', :stdin => stringio

  2.3.0:
    - fixed warning of @debug being un-initialized

  2.2.0:
    - added a private munged version of Open3::open3.  the builtin one causes
      the child process to become a child of init, this was very inconvenient
      because it was sometimes hard to crawl proces trees - the parent was lost.
      now the seesion is a child process that has been detached using
      Process::detach.  this results in less suprising behaviour; for instance
      sending signal TERM to a process results in any sessions it had open dying
      as well.  you can use Session::use_open3=true or
      ENV['SESSION_USE_OPEN3']='1' for the old behaviour if you need it.
    - added Session::Bash::Login class.  this class opens a session which has
      all the normal settings of a bash loging shell (.bashrc is sourced).  this
      if often convenient as paths, aliases, etc. are set as normal.
    - moved the Spawn module inside the Session module.  now the Session module
      is the namespace for everything so using session pollutes namespace less.

  2.1.9:
    - fixed bug where setting track history after creation caused later failure in
      execute (@history =[] only in ctor).  thanks leon breedt
      <bitserf@gmail.com>!
    - updates to README
    - included session-x.x.x.rpa file - thanks batsman <batsman.geo@yahoo.com>
    - to_str/to_s/to_yaml for History/Command is now valid yaml (updated samples
      to reflect this)
    - inspect for History/Command is now ruby's default 

  2.1.8:
    - greatly simplified read loop using two reader threads, one for stderr and
      one for stdout alongside a mutex to protect data.  this streamlined the code
      alot vs. the old select method including allowing removal of the linbuffer
      class.  the interface remains exactly as before however.

  2.1.7:
    - improved thread safe non-blocking read method
    - gemspec 

  2.1.6:
    - wrapped send_command in a Thread (send async) so output processing can
      commend immeadiately.  this was o.k. before, but had strange behaviour when
      using popen3 from threads.  thanks to tanaka akira for this suggestion.
    - iff ENV['SESSION_USE_SPAWN'] is set Session uses Spawn::spawn instead of
      Open3::popen3.  also noted that spawn seems to be a bit faster.
    - added tests for threads.
    - run 'sh SESSION_USE_SPAWN=1 ruby test/session.rb' to test using spawn
    - added test for idl so it's test is not run if system doesn't have it, all
      that should be required for 'ruby test/session.rb' is should be sh'
    - removed sample/tcsh and note about Tcsh and Csh in README - stderr
      redirection/separation is flaky in those shells

  2.1.5:
    - added Session.use_spawn=, AbstractSession.use_spawn=, and an :use_session=>
      option to AbstractSession#initialize.  if any of them are set the code uses
      Spawn::spawn to create external processes instead of Open3::popen3.
      Spawn::spawn uses named pipes (fifos) for IPC instead of forking and pipes.
      the fork used in popen3 can cause strange behaviour with multi-threaded apps
      (like a tk app).  see source for details

  2.1.4:
    - added Thread.exclusive{} wrapper when io is read to works in multi
      threaded apps


AUTHOR: |

  ara.t.howard@noaa.gov