expect4r 0.0.1.dev

data/LICENSE

@@ -0,0 +1,53 @@
+Expect4r is copyrighted free software by Jean-Michel Esnault.
+
+You can redistribute it and/or modify it under either the terms of the GPL 
+(see the COPYING file), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+          modifications to Usenet or an equivalent medium, or by allowing
+          the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+          with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+          together with instructions (in the manual page or equivalent)
+          on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+          the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/README.rdoc

@@ -0,0 +1,126 @@
+Expect4r is a library that enables a ruby program to 'talk' to routers following a written ruby script.
+You talk to routers by connecting to them using ssh or telnet and send exec or config command and collect router output than can be parsed using ruby.
+
+* Connect to routers
+
+   ios = Ios.new_telnet :host=> "hostname", :user=> "username", :pwd => "password"
+   ios.login
+   
+   
+   iox = Iox.new_telnet 'host', 'username', 'password'
+   iox.login
+   
+   j = J.new_telnet :host=> '', :user=> 'lab', :pwd => 'lab'
+   j.login
+   
+* Push configigurations to routers
+
+   ios.config 'no logging console'
+   
+   ios.config %{
+     interface loopback0
+       shutdown
+   }
+   
+   
+   iox.config
+   iox.exp_send 'interface GigabitEthernet0/2/0/0'
+   iox.exp_send 'desc to switch port 13'
+   iox.exp_send 'ipv4 address 190.0.0.9 255.255.255.252'
+   iox.exp_send 'no shut'
+   iox.commit
+   
+   
+   j.config %{
+     edit logical-router Orleans protocols bgp
+       edit group session-to-200
+         set type external
+         set peer-as 200
+         set neighbor 40.0.2.1 peer-as 200
+   }
+
+* exec commands
+
+
+    j.exec 'set cli screen-length 0'
+
+    iox.exec "terminal len 0\nterminal width 0"
+
+
+* exec shell commands
+
+    iox.shell 'pidin'
+
+
+* interact with CLI.
+
+
+   irb> r.interact
+
+   #
+   # ^Z to terminate.
+   #
+
+   router#clear line 2
+   [confirm]
+    [OK]
+   router# ^Z
+   => nil
+   irb> 
+
+
+   irb(main):210:0* j.interact
+   
+   #
+   # ^Z to terminate.
+   #
+   
+   jme@router> configure 
+   Entering configuration mode
+   The configuration has been changed but not committed
+   
+   [edit]
+   jme@router# rollback 
+   load complete
+   
+   [edit]
+   jme@router# show | compare 
+   
+   [edit]
+   jme@router# ^Z
+   => nil
+   irb(main):211:0> 
+   
+* Parsing output
+
+   The output is returned as an array of arrays of responses to commands.
+   Each response is returned as an array of lines. 
+   Parsing a response becomes a matter of iterating an array using the 
+   Arrays's enumerator methods such as find, find_all ...
+
+   irb(main):025:0> output = ts.exec %{
+   irb(main):026:0" show terminal | include History
+   irb(main):027:0" show line | include AUX
+   irb(main):028:0" }
+   => [
+        ["show terminal | include History", "History is enabled, history size is 10.", "PEA#"], 
+        ["show line | include AUX", "    17 AUX   9600/9600  -           0/0       -", "PEA#"]
+      ]
+   
+   output[0] contains output for 1st command 'show terminal'.
+   output[1] contains output for 1st command 'show line'.
+    ...
+   output[n-1] contains output for nth command.
+
+
+
+
+
+
+
+
+
+
+
+
+

data/lib/expect/io.rb

@@ -0,0 +1,484 @@
+require 'thread'
+require 'pty'
+require 'set'
+
+Thread.abort_on_exception=true
+
+class IO
+  def _io_save(no_echo=false, match_string=nil, ch=nil)
+    s = _io_string!
+    exp_internal match_string
+    exp_internal s
+    return if no_echo
+    s = s.chomp(ch) if ch
+    _io_buf1 << s unless no_echo
+  end
+  def _io_more?   ; ! IO.select([self],nil,nil,0.20).nil? ; end
+  def _io_exit?   ; _io_buf0.last.nil?                    ; end
+  def _io_buf0    ; @_buf0_                               ; end
+  def _io_buf1    ; @_buf1_                               ; end
+  def _io_string  ; @_buf0_.join                          ; end
+  def _io_string!
+    b = _io_string
+    @_buf0_=[]
+    b
+  end
+  def _io_sync
+    @_buf0_ ||=[]
+    while _io_more?
+      break if _io_read_char.nil?
+    end
+  end
+  def _io_read_char
+    c = getc
+    @_buf0_ << c.chr unless c.nil?
+    exp_internal "buf0: [#{_io_string.gsub(/\n/,'\n').gsub(/\r/,'\r')}]"
+    c
+  end
+  def readbuf(ti=10)
+    @_buf0_, @_buf1_=[],[]
+    loop do
+      if IO.select([self],nil,nil,ti).nil?
+        exp_internal "IO.select is NIL (TIMEOUT=#{ti})"
+        @_buf0_ << nil
+      else
+        _io_read_char
+      end
+      yield(self)
+    end
+  end
+end
+
+module Expect4r
+
+  class ConnectionError < RuntimeError
+    def initialize(output)
+      @output = output
+    end
+    def err_msg
+      "Connection Error: #{@output}"
+    end
+  end
+
+  class ExpTimeoutError < RuntimeError
+    def initialize(output, elapsed)
+      @output, @elapsed = output, elapsed
+    end
+    def err_msg
+      "Timeout Error: #{@output}"
+    end
+  end
+
+  class NoChildError < RuntimeError
+  end
+  class SpawnError < RuntimeError
+    def initialize(cmd)
+      @cmd = cmd
+    end
+    def err_msg
+      "Error: #{msg}"
+    end
+  end
+  class Expect4rIO_Error < RuntimeError
+  end
+
+  def child_exit
+    if @pid
+      Process.kill(:KILL, @pid)
+      @thread.kill
+      @lp, @r, @w, @pid = [nil]*4
+    end
+  rescue Errno::ESRCH, Errno::ECHILD => e
+  ensure
+    @lp, @r, @w, @pid = [nil]*4
+  end
+  
+  def spawn(cmd)
+    begin
+      child_exited = false
+      # STDOUT.puts "*** FALSE ***"
+      @thread = Thread.new do
+        PTY.spawn(cmd) do |pipe_read, pipe_write, pid|
+          @r, @w, @pid = pipe_read, pipe_write, pid
+          begin 
+            Process.wait(@pid,0)
+          rescue
+          ensure
+            child_exited = true
+          end
+        end
+      end
+      @thread.priority = -2
+      # STDOUT.puts "*** #{child_exited} ***"
+      unless child_exited
+        while @r.nil?
+          sleep(0.05) 
+        end
+      end
+    rescue => e
+      raise SpawnError.new(cmd)
+    end
+  end
+  
+  def logout
+    child_exit
+  end
+  
+  def putc(c)
+    return unless @w || c.nil?
+    exp_internal "[#{c}]"
+    @w.putc(c) and flush
+  rescue Errno::EIO
+    child_exit
+    raise 
+  end
+  
+  def exp_puts(s)
+    exp_print "#{s}\r"
+  end
+  def exp_print(s)
+    exp_internal "print: #{s.inspect}, io_writer: #{@w}"
+    return unless @w
+    @w.print(s) and flush
+  rescue Errno::EIO, Errno::ECHILD
+    child_exit
+    raise
+  end
+  def getc
+    @r.getc if @r
+  rescue Errno::EIO, Errno::ECHILD
+    child_exit
+    raise
+  end
+
+  def interact(k=?\C-z)
+    STDOUT.puts "\n\#\n\# #{ctrl_key k} to terminate.\n\#\n"
+    reader :start
+    writer k
+  rescue
+  ensure
+    begin
+      reader :terminate
+      putline ' ', :no_trim=>true, :no_echo=>true
+    rescue => e
+      exp_internal e.to_s
+    end
+  end
+  
+  def putcr
+    putline '', :no_trim=>true, :no_echo=>true
+    nil
+  end
+  
+  def exp_send(lines, arg={})
+    r=[]
+    lines.each_line do |l|
+      l = l.chomp("\n").chomp("\r").strip
+      r << putline(l, arg) if l.size>0
+    end
+    lines.size==1 ? r[0] : r
+  end
+  
+  def expect(match, ti=5)
+    ev, buf = catch(:done) do
+      @r.readbuf(ti) do |r|
+        if r._io_exit?
+          throw :done, [ :timeout, r._io_string!]
+        end
+        case r._io_string
+        when match
+          throw :done, [:ok, r._io_string!.chomp("\r\n")]
+        end
+      end
+    end
+    exp_internal "#{ev.inspect} buf: #{buf.inspect}"
+    raise RuntimeError, buf if ev == :timeout
+    [buf, ev]
+  end
+
+  def readline(ti=2)
+    expect(/(.+)\r\n/, ti)
+  end
+
+  def connected?
+    @r && (not child_exited?)
+  end
+
+  def login(c, o={})
+    return if connected?
+
+    spawn c
+
+    o={:timeout=>13, :no_echo=>false}.merge(o)
+    timeout =   o[:timeout]
+    no_echo = o[:no_echo]
+
+    output=[]
+    t0 = Time.now
+    ev, buf = catch(:done) do
+      @r.readbuf(timeout) do |read_pipe|
+        if read_pipe._io_exit?
+          exp_internal "readbuf: _io_exit?"
+          throw :done, [ :abort,  output]
+        end
+        case read_pipe._io_string
+        when spawnee_prompt
+          read_pipe._io_save false, "match PROMPT"
+          throw(:done, [:ok, output])
+        when /(user\s*name\s*|login):\r*$/i
+          read_pipe._io_save no_echo, "match USERNAME"
+          exp_puts spawnee_username
+        when /password:\s*$/i
+          read_pipe._io_save no_echo, "match PASSWORD"
+          @w.print(spawnee_password+"\r") and flush
+        when /Escape character is/
+          read_pipe._io_save no_echo, "match Escape char"
+          io_escape_char_cb
+        when /.*\r\n/
+          exp_internal "match EOL"
+          read_pipe._io_save no_echo, "match EOL", "\r\n"
+        end
+      end
+    end
+    case ev
+    when :abort
+      elapsed = Time.now - t0
+      if elapsed < timeout
+        raise ConnectionError.new(c)
+      else
+        raise ExpTimeoutError.new(c, elapsed)
+      end
+    else
+      @lp = buf.last
+    end
+    [buf, ev]
+    
+  end
+  
+  private
+ 
+  #FIXME ? putline to send_cmd ? 
+  # hide putline and expose cmd
+  def putline(line, arg={})
+    raise NoChildError if child_exited?
+        
+    arg = {:ti=>13, :no_echo=>false, :debug=>0, :sync=> false, :no_trim=>false}.merge(arg)
+    no_echo = arg[:no_echo]
+    ti = arg[:ti]
+    unless arg[:no_trim]
+      line = line.gsub(/\s+/,' ').gsub(/^\s+/,'') unless arg[:no_trim]
+      return [[], :empty_line] unless line.size>0
+    end
+    sync if arg[:sync]
+    t0 = Time.now
+    exp_puts line
+    output=[]
+    rc, buf = catch(:done) do
+      @r.readbuf(arg[:ti]) do |r|
+        if r._io_exit?
+          r._io_save(no_echo)
+          throw :done, [ :abort,  r._io_buf1]
+        end
+        case r._io_string
+        when @ps1, @ps1_bis
+          unless r._io_more?
+            r._io_save false, "matching PROMPT"
+            throw(:done, [:ok, r._io_buf1])
+          end
+          exp_internal "more..."
+        when /(.+)\r\n/, "\r\n"
+          r._io_save no_echo, "matching EOL", "\r\n"
+        when @more
+          r._io_save no_echo, "matching MORE"
+          putc ' '
+        end
+        
+        @matches.each { |match, _send|  
+          if r._io_string =~ match
+             r._io_save no_echo, "match #{match}"
+            exp_puts _send
+          end
+        }
+        
+      end
+    end
+    case rc
+    when :abort
+      elapsed = Time.now - t0
+      if elapsed < ti
+        raise ConnectionError.new(line)
+      else
+        raise ExpTimeoutError.new(line, elapsed)
+      end
+    else
+      @lp = buf.last
+    end
+    [buf, rc]
+  end
+  def ctrl_key(k)
+    case k
+    when ?\C-c ; '^C'
+    when ?\C-q ; '^Q'
+    when ?\C-z ; '^Z'
+    end
+  end
+
+  def writer(k)
+    stty_raw
+    begin
+      loop do
+        break if (c = STDIN.getc) == k
+        putc(c)
+      end
+    rescue PTY::ChildExited => e
+      child_exit
+    ensure
+      stty_cooked
+    end
+  end
+
+  def reader(arg=:start)
+    case arg
+    when :start
+      stty_raw
+      @reader = Thread.new do
+        begin
+          loop do 
+            c = getc
+            break if c.nil?
+            STDOUT.putc c
+          end
+        rescue => e
+          p e
+          p '7777777'
+        ensure
+          stty_cooked
+        end
+      end
+    when :terminate
+      @reader.terminate if @reader
+      stty_cooked
+    end
+  end
+  
+  def sync
+    @r._io_sync
+  end
+  
+  def child_exited?
+    @pid == nil
+  end
+
+  def stty_cooked
+    system "stty echo -raw"
+  end
+
+  def stty_raw
+    system "stty -echo raw"
+  end
+
+  def flush
+    @w.flush
+  end
+ 
+end
+
+module Kernel
+  def exp_debug(state=:enable)
+    case state
+    when :disable, :off
+      Kernel.instance_eval {
+        define_method("exp_internal") do |s|
+        end
+      }
+      :disable
+    when :enable, :on
+      Kernel.instance_eval {
+        define_method("exp_internal") do |s|
+          STDOUT.print "\ndebug: #{s}"
+        end
+      }
+      :enable
+    else
+      nil
+    end
+  end
+  exp_debug :disable
+end
+
+module Expect4r
+  class BaseObject
+    class << self
+      def new_telnet(*args)
+        new :telnet, *args
+      end
+      def new_ssh(*args)
+        new :ssh, *args
+      end
+      attr_reader :routers
+      def add(r)
+        @routers ||=[]
+        @routers << r
+      end
+    end
+    attr_reader :host, :user, :method, :port
+    alias :username :user
+    alias :hostname :host
+    def initialize(*args)
+      ciphered_pwd=nil
+      if args.size>2 and args[1].is_a?(String)
+        @method, host, @user, pwd = args
+      elsif args.size == 2 and args[1].is_a?(Hash) and args[0].is_a?(Symbol)
+        @method = args[0]
+        host = args[1][:host] || args[1][:hostname]
+        @user = args[1][:user]|| args[1][:username]
+        pwd  = args[1][:pwd]  || args[1][:password]
+        ciphered_pwd  = args[1][:ciphered_pwd]
+      end
+      @host, port = host.split
+      @port = port.to_i
+      @pwd = if ciphered_pwd
+        ciphered_pwd
+      else
+        Expect4r.cipher(pwd) if pwd
+      end
+      @ps1 = /(.*)(>|#|\$)\s*$/
+      @more = / --More-- /
+      @matches=Set.new
+      BaseObject.add(self)
+      self
+    end
+  end
+end
+
+if __FILE__ != $0
+
+  at_exit { 
+    if Expect4r::BaseObject.routers
+      Expect4r::BaseObject.routers.each { |r| r.logout if r.respond_to? :logout }
+    end
+  }
+  
+else
+
+  require "test/unit"
+
+  class Expect4r::BaseObject
+    def initialize
+      Expect4r::BaseObject.add(self)
+    end
+  end
+
+  class TestRouterBaseObject < Test::Unit::TestCase
+    include Expect4r
+
+    def test_add
+      assert [], BaseObject.routers
+      BaseObject.new
+      assert 1, BaseObject.routers.size
+      BaseObject.new 
+      assert_equal 2, BaseObject.routers.size
+    end
+  end
+
+end