emonti-wxirb 1.0.1

data/README.rdoc

@@ -0,0 +1,173 @@
+
+= WxIRB
+
+This is a GUI "irb-alike" console based on WxRuby. I wrote this because I 
+needed a better way to prototype and debug my wxruby applications as I was
+developing them. WxIRB puts you "inside" a Wx::App.run event loop, which
+lets you easily play with window objects during run-time.
+
+This is mostly just a port of why_the_lucky_stiff's Shoes GUI irb example to 
+wxruby with the addition of a command history and a few other convenience 
+methods added in the window classes.
+
+Credit to Why.
+See: http://github.com/why/shoes/blob/master/samples/expert-irb.rb
+
+== Installation
+
+WxIRB is available as a gem from github.
+
+    gem sources -a http://gems.github.com #(you only have to do this once)
+    sudo gem install wxirb
+
+Or you can install it manually:
+
+    git clone git://github.com/emonti/wxirb.git
+    sudo cp wxirb/lib/wxirb.rb /usr/lib/ruby/1.8/site_ruby/1.8 # or wherever
+    sudo cp wxirb/bin/wxirb /usr/local/bin # or wherever
+
+== Keyboard Interaction
+
+WxIRB is designed to allow you to edit multi-line ruby statements in the
+input window. The keyboard commands in the input text area are what you'
+d expect in a multi-line text-box with some additional special keyboard 
+modifiers:
+
+*   ENTER : runs a statement through the mock IRB object. (what you'd expect)
+*   META+ENTER : sends a newline inside the window instead of running a command
+*   META+UP-ARROW : scroll up in history
+*   META+DOWN-ARROW : scroll down in history
+
+WxIRB does not have a "run" button. Thank goodness!
+
+The output text area is read-only from the UI. Tabbing focus from the output 
+text area should land you back in the input text area.
+
+
+== Interacting with the WxIRB Window Objects
+
+When running wx_irb.rb directly a global variable named '$wxirb' is created 
+for you which holds a reference to the WxIRB::BaseFrame window you are using.
+
+This is done so you can easily access the UI frame object and children from 
+within the actual interface. A few convenience methods and accessors are 
+exposed this way:
+
+* '$wxirb.clear' lets you clear the output window
+
+* '$wxirb.history' returns the command history object (basically an array)
+
+* '$wxirb.histdump(s=0, e=-1)' prints the history to the output text area.
+  to the output text area. Takes optional start and indexes for viewing just 
+  a slice of the history array.
+
+* '$wxirb.set_binding(bind)' sets the object binding to 'bind' which is used
+  when running eval() on user input. See also, 'Object Binding'.
+
+
+== WxIRB CommandHistory
+
+WxIRB maintains a persistent history log. The WxIRB history uses a separate 
+file from IRB which is defined by WxIRB::CommandHistory::HISTFILE. It is 
+actually just a YAMLized array.
+
+By default, this is $HOME/.wxirb_history (no way of 'convenient' way of 
+configuring this right now)
+
+History is implemented in the WxIRB::CommandHistory class. This is basically 
+an array with a few convenience methods and accessors:
+
+*   'hpos' is an accessor to the history array position.
+
+*   'prev' moves hpos back one and returns the history value at that position
+
+*   'next' does the same thing, but forward
+
+*   '<<' is an override for the Array superclass that just updates the history 
+    position variable.
+
+*   'save!' saves current history to the persistent history file
+
+*   'save' saves to the persistent history file only if the history has changed.
+    (this is used for an evt_idle event handler by the input text window)
+
+*   'clear' empties the history array and persistent history file
+
+
+== Output to WxIRB
+
+The WxIRB::BaseFrame object also has an 'output' accessor which returns a 
+reference to the OutputTextCtrl text window half of the display. This object 
+has a few methods to make it usable (in duck-typing cases) as an IO object. 
+Note: This doesn't actually inherit from or implement all of IO class, however.
+
+*   '<<' outputs to the output window
+
+*   'puts' prints directly to the output text area like 'IO.puts' and returns
+    nil.
+
+*   'print' prints directly to the output text area like 'IO.print'
+    and returns nil.
+
+*   'write' prints directly to the output text area like 'IO.write' and returns 
+    the number of bytes written.
+
+*   Note: write, print, and puts all use brown text to differentiate from other
+    output.
+
+*   'close', 'closed?' and 'flush' are also all defined but just emulate an
+    IO object with their return values. Other than that, they do nothing.
+
+
+== Object Binding
+
+Originally, WxIRB just ran 'eval' using the TOPLEVEL_BINDING (aka main)
+This is how you usually run IRB. However, it may be desirable to instantiate
+a wxirb console bound to a different namespace for debugging specific objects
+and whatnot.  So a few ways to manage bindings were added.
+
+* WxIRB::BaseFrame.new now accepts an optional binding parameter. For example:
+
+>>  WxIRB::BaseFrame.new(nil, :binding => TOPLEVEL_BINDING)
+
+By default, new WxIRB::BaseFrame objects will bind to themselves. Meaning,
+commands will run in the scope of the WxIRB::BaseFrame scope itself. 
+TOPLEVEL_BINDING makes the scope 'main'.
+
+When running 'wxirb.rb' directly, you will start with TOPLEVEL_BINDING, but
+you can use the 'set_binding' method of $wxirb to change the binding on the 
+fly.
+
+* As mentioned above, WxIRB::BaseFrame also has an instance method called
+  set_binding. This method lets you change WxIRB's binding on the fly.
+  Here's a short example from inside WxIRB running 'wxirb.rb' directly:
+
+    >> self
+    => main
+    >> $wxirb
+    => #<WxIRB::BaseFrame:0x51e8c0>
+    >> $wxirb.set_binding $wxirb.instance_eval { binding }
+    => #<Binding:0x17235fe8>
+    >> self
+    => #<WxIRB::BaseFrame:0x51e8c0>
+    >> @output
+    => #<WxIRB::InputTextCtrl:0x51d5b0>
+    >> @output.puts "hello self"
+    hello self
+    => nil
+    >> set_binding TOPLEVEL_BINDING
+    => #<Binding:0x296d0>
+    >> self
+    => main
+
+
+== BUGS
+
+*   Running statements gets slow when the Output window gets very full. Not
+    really sure why this is, but running 'wxirb.clear' periodically helps.
+
+*   An effort is made to rescue most exceptions, but sometimes wxirb will
+    close due to an un-handled exception. Regular 'irb' does this too 
+    sometimes... so I don't feel too bad.
+
+

data/bin/wxirb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+begin
+  require 'rubygems'
+rescue LoadError
+end
+
+require 'wx'
+require 'wxirb'
+
+Wx::App.run do 
+  $wxirb = WxIRB::BaseFrame.new(nil, :binding => TOPLEVEL_BINDING)
+  $wxirb.show
+end
+

data/lib/wxirb.rb

@@ -0,0 +1,393 @@
+#!/usr/bin/env ruby
+begin
+  require 'rubygems'
+rescue LoadError
+end
+require 'wx'
+require 'yaml'
+require 'irb/ruby-lex'
+require 'stringio'
+
+# This class is stolen almost verbatim from why_the_lucky_stiff's Shoes 
+# example. (http://github.com/why/shoes/blob/master/samples/expert-irb.rb)
+# He gets all the credit.
+class MimickIRB < RubyLex
+  attr_accessor :started
+ 
+  class Continue < StandardError; end
+  class Empty < StandardError; end
+ 
+  def initialize(bind=TOPLEVEL_BINDING)
+    set_binding(bind)
+    super()
+    set_input(StringIO.new)
+  end
+ 
+  def set_binding(bind)
+    if bind.is_a? Binding
+      @bind = bind
+    else
+      raise "Invalid binding #{bind.inspect}"
+    end
+  end
+
+  def run(str)
+    obj = nil
+    @io << str
+    @io.rewind
+    unless l = lex
+      raise Empty if @line == ''
+    else
+      case l.strip
+      when "reset"
+        @line = ""
+      else
+        @line << l << "\n"
+        if @ltype or @continue or @indent > 0
+          raise Continue
+        end
+      end
+    end
+    unless @line.empty?
+      obj = eval @line, @bind, "(irb)", @line_no
+    end
+    @line_no += @line.scan(/\n/).length
+    @line = ''
+    @exp_line_no = @line_no
+ 
+    @indent = 0
+    @indent_stack = []
+ 
+    $stdout.rewind
+    output = $stdout.read
+    $stdout.truncate(0)
+    $stdout.rewind
+    [output, obj]
+  rescue Object => e
+    case e when Empty, Continue
+    else @line = ""
+    end
+    raise e
+  ensure
+    set_input(StringIO.new)
+  end
+end
+
+
+# Docs say there's a KeyEvent.cmd_down which is platform independent. 
+# But they LIE so we create our own...
+class Wx::KeyEvent
+  case  Wx::PLATFORM
+  when "WXMAC"
+    def inputmod_down; meta_down; end
+  when "WXMSW"
+    def inputmod_down; alt_down; end
+  end
+end
+
+
+module WxIRB
+  # WxIRB maintains a persistent history log. The WxIRB history uses a separate 
+  # file from IRB which is defined by WxIRB::CommandHistory::HISTFILE. It is 
+  # actually just a YAMLized array.
+  #
+  # By default, the file is $HOME/.wxirb_history (no 'convenient' way of 
+  # configuring this right now aside from changing the constant)
+  #
+  # History is implemented in the WxIRB::CommandHistory class. This is 
+  # basically just an Array with a few convenience methods and accessors.
+  class CmdHistory < Array
+    # an accessor to the history array position.
+    attr_accessor :hpos
+
+    # location of the persistent history file
+    HISTFILE = "#{ENV["HOME"]}/.wxirb_history"
+
+    # Initializes a CommandHistory object and loads persistent history
+    # from the file specified in HISTFILE
+    def initialize(*opts)
+      super(*opts)
+      @hpos = nil
+      begin
+        self.replace YAML.load_file(HISTFILE)
+        @hpos = self.size-1
+      rescue
+        STDERR.puts "Note - error restoring history: #{$!.inspect}"
+      end
+    end
+
+    # moves hpos back one and returns the history value at that position
+    def prev
+      return nil if self.empty?
+      val = self[@hpos].to_s
+      @hpos -= 1 unless @hpos == 0
+      return val
+    end
+
+    # moves hpos forward one and returns the history value at that position
+    def next
+      if not self.empty? and @hpos != self.size-1
+        @hpos += 1 
+        self[@hpos].to_s
+      end
+    end
+
+    # An override for the Array superclass that just updates the history 
+    # position variable. This also ensures that history elements are appended
+    # as strings.
+    def << (val)
+      @hpos = self.size
+      @changed=true
+      super(val.to_s)
+    end
+
+    # empties the history array and persistent history file
+    def clear
+      self.replace([])
+      self.save!
+    end
+
+    # saves current history to the persistent history file
+    def save!
+      ret=nil
+      begin
+        ret=File.open(HISTFILE, "w") {|f| f.write(self.to_yaml) }
+      rescue Errno::ENOENT
+        STDERR.puts "Error: couldn't save history - #{$!}"
+      end
+      @changed=nil
+      ret
+    end
+
+    # saves to the persistent history file only if the history has changed.
+    # (this is used for an evt_idle event handler by the input text window)
+    def save(force=false)
+      return nil unless @changed or force
+      self.save!
+    end
+  end
+
+
+  # Keyboard commands in the input text area are what you'd expect in a 
+  # multi-line textbox with some additional special keyboard modifiers.
+  # See InputTextCtrl#on_char
+  class InputTextCtrl < Wx::TextCtrl
+    attr_accessor :history
+    include Wx
+    STYLE = TE_PROCESS_TAB|TE_PROCESS_ENTER|WANTS_CHARS|TE_MULTILINE
+
+    def initialize(parent, output, mirb)
+      super(parent, :style => STYLE)
+      @history = CmdHistory.new
+      @output = output
+
+      @stdout_save = $stdout
+      $stdout = StringIO.new
+      @mirb = mirb 
+      evt_idle :on_idle
+      evt_char  :on_char
+
+      @font = Wx::Font.new(10, Wx::MODERN, Wx::NORMAL, Wx::NORMAL)
+      set_default_style Wx::TextAttr.new(Wx::BLACK, Wx::WHITE, @font)
+
+      paint do |dc| 
+        b_height = dc.get_text_extent("@", @font)[1] * 4
+        cache_best_size Wx::Size.new(self.size.width, b_height)
+      end
+    end
+
+    # Fires on Wx::IdleEvent - saves persistent history if history has changed
+    def on_idle(evt)
+      history.save
+    end
+
+    # Fires on text input events.
+    # Implements a few special keyboard handlers
+    # *   META+ENTER : sends a newline inside the input window instead of 
+    #     actually running a command
+    # *   META+UP-ARROW : scroll up in history
+    # *   META+DOWN-ARROW : scroll down in history
+    def on_char(evt)
+      k = evt.key_code
+      mflag = evt.modifiers
+
+      if [MOD_NONE, MOD_SHIFT].include?(mflag) and (0x20..0x7f).include?(k)
+        evt.skip()
+        return
+      end
+
+      case k
+      when K_RETURN
+        if evt.inputmod_down
+          # multi-line command uses meta-down-arrow for newline
+          self.write_text("\n")
+        else
+          @history << self.value
+          run self.value
+          self.clear
+        end
+        return
+      when (evt.inputmod_down and K_UP)
+        if hist=history.prev
+          self.value = hist
+          self.set_insertion_point_end
+          return
+        end
+      when (evt.inputmod_down and K_DOWN)
+        if hist=history.next
+          self.value = hist
+          self.set_insertion_point_end
+          return
+        else
+          self.clear
+        end
+      end
+      evt.skip()
+    end
+
+    # Runs a command through the mock irb class, handles display details.
+    def run(cmd)
+      (lines = cmd.split(/\r?\n/)).each_index do |idx|
+        begin
+          line = lines[idx] + "\n"
+          @output.default_style = Wx::TextAttr.new(Wx::BLUE)
+          @output << ">> #{line}"
+
+          out, obj = @mirb.run(line)
+          @output.default_style = Wx::TextAttr.new(Wx::BLACK)
+          @output << out
+          @output.default_style = Wx::TextAttr.new(Wx::Colour.new(100,100,100))
+          @output << "=> #{obj.inspect}\n"
+        rescue MimickIRB::Empty
+        rescue MimickIRB::Continue
+          if idx == lines.size-1
+            @output.default_style = Wx::TextAttr.new(Wx::LIGHT_GREY)
+            @output << "...\n"
+          end
+        rescue Exception => se
+          @output.default_style = Wx::TextAttr.new(Wx::RED)
+          @output << (se.inspect + "\n" + se.backtrace.join("\n") + "\n")
+        end
+      end
+    end
+  end
+
+
+  # The output textbox.
+  # This object has a few methods to make it usable (in duck-typing cases) as 
+  # an IO object. This doesn't actually inherit or implement from the IO 
+  # class, however.
+  class OutputTextCtrl < Wx::TextCtrl
+    include Wx
+    STYLE = TE_READONLY|TE_MULTILINE|TE_RICH|TE_RICH2|TE_CHARWRAP
+
+    def initialize(parent)
+      super(parent, :style => STYLE)
+
+      font = Wx::Font.new(10, Wx::MODERN, Wx::NORMAL, Wx::NORMAL)
+      set_default_style Wx::TextAttr.new(Wx::BLACK, Wx::WHITE, font)
+
+      @io_style=Wx::TextAttr.new(Wx::Colour.new(180, 104, 52))
+    end
+
+    #----------------------------------------------------------------------
+    # some methods (as i think of/need them) to make it possible to use 
+    # the output text area as a fake IO object
+    #----------------------------------------------------------------------
+
+    # '<<' outputs to the output window
+    alias :<< :append_text
+
+    # 'close', 'closed?' and 'flush' are also all defined but just emulate 
+    # an IO object with their return values. Other than that, they do nothing.
+    def close ; nil;  end
+    def closed? ; false ; end
+    def flush; self; end
+
+    # prints directly to the output text area like 'IO.print'
+    # and returns nil.
+    def print(*args)
+      set_default_style @io_style
+      self << args.flatten.join
+      nil
+    end
+
+    # Displays directly to the output text area like 'IO.puts' and returns nil.
+    def puts(*args)
+      set_default_style @io_style
+      self << args.flatten.map do |o| 
+        s=o.to_s
+        (s[-1,1]=="\n") ? s : s + "\n"
+      end.join
+      nil
+    end
+
+    # Displays directly to the output text area like 'IO.write' and returns 
+    # the number of bytes written.
+    def write(dat)
+      set_default_style @io_style
+      out = dat.to_s
+      self << out
+      out.size
+    end
+  end
+
+  # This window object is parent to the Input and Output text areas. It
+  # provides a sliding splitter control between the top and bottom text boxes.
+  class TerminalSplitter < Wx::SplitterWindow
+    def initialize(parent)
+      super(parent, :style => Wx::SP_LIVE_UPDATE)
+      self.set_sash_gravity(1.0)
+      evt_splitter_dclick self, :on_dclick
+    end
+
+    def on_dclick(evt)
+      set_sash_position(- @bottom.best_size.height)
+    end
+
+    def split_horizontally(top, bottom, pos=nil)
+      @top ||= top
+      @bottom ||= bottom
+      minsz = @bottom.best_size.height
+      set_minimum_pane_size(minsz) # this also prevents unsplitting.
+      pos ||= - minsz
+      super(@top, @bottom, pos)
+    end
+  end
+
+
+  # Parent and top-level window for all the wxirb controls.
+  class BaseFrame < Wx::Frame
+    attr_reader :output, :input
+
+    def initialize(parent, opts={})
+      bind = (opts.delete(:binding) || binding)
+      @mirb=MimickIRB.new(bind)
+
+      opts[:title] ||= "WxIRB"
+      super(parent, opts)
+
+      @splitter = TerminalSplitter.new(self)
+      @output = OutputTextCtrl.new(@splitter)
+      @input = InputTextCtrl.new(@splitter, @output, @mirb)
+      @splitter.split_horizontally(@output, @input)
+      @input.set_focus()
+    end
+
+    # Allow our binding to be changed on the fly
+    def set_binding(bind);  @mirb.set_binding(bind); end
+
+    # Clears the output window
+    def clear; @output.clear ; end
+
+    # Returns the window's command history object (see WxIRB::CommandHistory)
+    def history; @input.history ; end
+
+    # Prints the history to the output text area. Takes optional start and 
+    # end position indexes for viewing just a slice of the history array.
+    def histdump(s=0, e=-1)
+      puts self.history[s..e]
+    end
+  end
+end
+

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification 
+name: emonti-wxirb
+version: !ruby/object:Gem::Version 
+  version: 1.0.1
+platform: ruby
+authors: 
+- Eric Monti
+autorequire: wxirb
+bindir: bin
+cert_chain: []
+
+date: 2009-02-13 00:00:00 -08:00
+default_executable: wxirb
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: wxruby
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.9.9
+    version: 
+description: 
+email: emonti@matasano.com
+executables: 
+- wxirb
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- bin/wxirb
+- lib/wxirb.rb
+has_rdoc: true
+homepage: http://www.matasano.com
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A GUI IRB-like console based on WxRuby
+test_files: []
+