iruby 0.6.0 → 0.7.3

data/lib/iruby/kernel.rb

@@ -8,10 +8,26 @@ module IRuby
     @events = EventManager.new([:initialized])
 
     class << self
+      # Return the event manager defined in the `IRuby::Kernel` class.
+      # This event manager can handle the following event:
+      #
+      # - `initialized`: The event occurred after the initialization of
+      #   a `IRuby::Kernel` instance is finished
+      #
+      # @example Registering initialized event
+      #   IRuby::Kernel.events.register(:initialized) do |result|
+      #     STDERR.puts "IRuby kernel has been initialized"
+      #   end
+      #
+      # @see IRuby::EventManager
+      # @see IRuby::Kernel#events
       attr_reader :events
+
+      # Returns the singleton kernel instance
       attr_accessor :instance
     end
 
+    # Returns a session object
     attr_reader :session
 
     EVENTS = [
@@ -34,21 +50,77 @@ module IRuby
 
       @events = EventManager.new(EVENTS)
       @execution_count = 0
-      @backend = create_backend
+      @backend = PlainBackend.new
       @running = true
 
       self.class.events.trigger(:initialized, self)
     end
 
+    # Returns the event manager defined in a `IRuby::Kernel` instance.
+    # This event manager can handle the following events:
+    #
+    # - `pre_execute`: The event occurred before running the code
+    #
+    # - `pre_run_cell`: The event occurred before running the code and
+    #   if the code execution is not silent
+    #
+    # - `post_execute`: The event occurred after running the code
+    #
+    # - `post_run_cell`: The event occurred after running the code and
+    #   if the code execution is not silent
+    #
+    # The callback functions of `pre_run_cell` event must take one argument
+    # to get an `ExecutionInfo` object.
+    # The callback functions of `post_run_cell` event must take one argument
+    # to get the result of the code execution.
+    #
+    # @example Registering post_run_cell event
+    #   IRuby::Kernel.instance.events.register(:post_run_cell) do |result|
+    #     STDERR.puts "The result of the last execution: %p" % result
+    #   end
+    #
+    # @see IRuby::EventManager
+    # @see IRuby::ExecutionInfo
+    # @see IRuby::Kernel.events
     attr_reader :events
 
-    def create_backend
-      PryBackend.new
-    rescue Exception => e
-      IRuby.logger.warn "Could not load PryBackend: #{e.message}\n#{e.backtrace.join("\n")}" unless LoadError === e
-      PlainBackend.new
+    # Switch the backend (interactive shell) system
+    #
+    # @param backend [:irb,:plain,:pry] Specify the backend name switched to
+    #
+    # @return [true,false] true if the switching succeeds, otherwise false
+    def switch_backend!(backend)
+      name = case backend
+             when String, Symbol
+               name = backend.downcase
+             else
+               name = backend
+             end
+
+      backend_class = case name
+                      when :irb, :plain
+                        PlainBackend
+                      when :pry
+                        PryBackend
+                      else
+                        raise ArgumentError,
+                          "Unknown backend name: %p" % backend
+                      end
+
+      begin
+        new_backend = backend_class.new
+        @backend = new_backend
+        true
+      rescue Exception => e
+        unless LoadError === e
+          IRuby.logger.warn "Could not load #{backend_class}: " +
+                            "#{e.message}\n#{e.backtrace.join("\n")}"
+        end
+        return false
+      end
     end
 
+    # @private
     def run
       send_status :starting
       while @running
@@ -56,6 +128,7 @@ module IRuby
       end
     end
 
+    # @private
     def dispatch
       msg = @session.recv(:reply)
       IRuby.logger.debug "Kernel#dispatch: msg = #{msg}"
@@ -72,6 +145,7 @@ module IRuby
       @session.send(:publish, :error, error_content(e))
     end
 
+    # @private
     def kernel_info_request(msg)
       @session.send(:reply, :kernel_info_reply,
                     protocol_version: '5.0',
@@ -93,11 +167,13 @@ module IRuby
                     status: :ok)
     end
 
+    # @private
     def send_status(status)
       IRuby.logger.debug "Send status: #{status}"
       @session.send(:publish, :status, execution_state: status)
     end
 
+    # @private
     def execute_request(msg)
       code = msg[:content]['code']
       store_history = msg[:content]['store_history']
@@ -134,16 +210,20 @@ module IRuby
         content[:execution_count] = @execution_count
       end
 
+      unless result.nil? || silent
+        @session.send(:publish, :execute_result,
+                      data: Display.display(result),
+                      metadata: {},
+                      execution_count: @execution_count)
+      end
+
       events.trigger(:post_execute)
       events.trigger(:post_run_cell, result) unless silent
 
       @session.send(:reply, :execute_reply, content)
-      @session.send(:publish, :execute_result,
-                    data: Display.display(result),
-                    metadata: {},
-                    execution_count: @execution_count) unless result.nil? || msg[:content]['silent']
     end
 
+    # @private
     def error_content(e)
       rindex = e.backtrace.rindex{|line| line.start_with?(@backend.eval_path)} || -1
       backtrace = SyntaxError === e  && rindex == -1 ? [] : e.backtrace[0..rindex]
@@ -152,12 +232,14 @@ module IRuby
         traceback: ["#{RED}#{e.class}#{RESET}: #{e.message}", *backtrace] }
     end
 
+    # @private
     def is_complete_request(msg)
       # FIXME: the code completeness should be judged by using ripper or other Ruby parser
       @session.send(:reply, :is_complete_reply,
                     status: :unknown)
     end
 
+    # @private
     def complete_request(msg)
       # HACK for #26, only complete last line
       code = msg[:content]['code']
@@ -173,36 +255,43 @@ module IRuby
                     status: :ok)
     end
 
+    # @private
     def connect_request(msg)
       @session.send(:reply, :connect_reply, Hash[%w(shell_port iopub_port stdin_port hb_port).map {|k| [k, @config[k]] }])
     end
 
+    # @private
     def shutdown_request(msg)
       @session.send(:reply, :shutdown_reply, msg[:content])
       @running = false
     end
 
+    # @private
     def history_request(msg)
       # we will just send back empty history for now, pending clarification
       # as requested in ipython/ipython#3806
       @session.send(:reply, :history_reply, history: [])
     end
 
+    # @private
     def inspect_request(msg)
       # not yet implemented. See (#119).
       @session.send(:reply, :inspect_reply, status: :ok, found: false, data: {}, metadata: {})
     end
 
+    # @private
     def comm_open(msg)
       comm_id = msg[:content]['comm_id']
       target_name = msg[:content]['target_name']
       Comm.comm[comm_id] = Comm.target[target_name].new(target_name, comm_id)
     end
 
+    # @private
     def comm_msg(msg)
       Comm.comm[msg[:content]['comm_id']].handle_msg(msg[:content]['data'])
     end
 
+    # @private
     def comm_close(msg)
       comm_id = msg[:content]['comm_id']
       Comm.comm[comm_id].handle_close(msg[:content]['data'])

data/lib/iruby/session.rb

@@ -10,6 +10,7 @@ module IRuby
     def initialize(config, adapter_name=nil)
       @config = config
       @adapter = create_session_adapter(config, adapter_name)
+      @last_recvd_msg = nil
 
       setup
       setup_sockets

data/lib/iruby/utils.rb

@@ -4,37 +4,48 @@ module IRuby
       Display.convert(object, options)
     end
 
+    # Display the object
     def display(obj, options = {})
       Kernel.instance.session.send(:publish, :display_data,
                                    data: Display.display(obj, options),
                                    metadata: {}) unless obj.nil?
+      # The next `nil` is necessary to prevent unintentional displaying
+      # the result of Session#send
+      nil
     end
 
+    # Clear the output area
     def clear_output(wait=false)
       Display.clear_output(wait)
     end
 
+    # Format the given object into HTML table
     def table(s, **options)
-      html(HTML.table(s, options))
+      html(HTML.table(s, **options))
     end
 
+    # Treat the given string as LaTeX text
     def latex(s)
       convert(s, mime: 'text/latex')
     end
     alias tex latex
 
+    # Format the given string of TeX equation into LaTeX text
     def math(s)
       convert("$$#{s}$$", mime: 'text/latex')
     end
 
+    # Treat the given string as HTML
     def html(s)
       convert(s, mime: 'text/html')
     end
 
+    # Treat the given string as JavaScript code
     def javascript(s)
       convert(s, mime: 'application/javascript')
     end
 
+    # Treat the given string as SVG text
     def svg(s)
       convert(s, mime: 'image/svg+xml')
     end

data/lib/iruby/version.rb

@@ -1,3 +1,3 @@
 module IRuby
-  VERSION = '0.6.0'
+  VERSION = '0.7.3'
 end

data/test/helper.rb

@@ -1,5 +1,4 @@
 require "iruby"
-require "iruby/logger"
 require "json"
 require 'multi_json'
 require "pathname"
@@ -38,10 +37,14 @@ module IRubyTest
       @__config_path.to_s
     end
 
-    def teardown
+    def self.restore_kernel
       IRuby::Kernel.instance = @__original_kernel_instance
     end
 
+    def teardown
+      self.class.restore_kernel
+    end
+
     def with_session_adapter(session_adapter_name)
       IRuby::Kernel.new(self.class.test_config_filename, session_adapter_name)
       $stdout = STDOUT

data/test/iruby/backend_test.rb

@@ -8,6 +8,12 @@ module IRubyTest
       assert_equal 3, @plainbackend.eval('1+2', false)
     end
 
+    def test_include_module
+      assert_nothing_raised do
+        @plainbackend.eval("include Math, Comparable", false)
+      end
+    end
+
     def test_complete_req
       assert_includes @plainbackend.complete('req'), 'require'
     end
@@ -26,6 +32,12 @@ module IRubyTest
       assert_equal 3, @prybackend.eval('1+2', false)
     end
 
+    def test_include_module
+      assert_nothing_raised do
+        @prybackend.eval("include Math, Comparable", false)
+      end
+    end
+
     def test_complete_req
       assert_includes @prybackend.complete('req'), 'require'
     end

data/test/iruby/display_test.rb

@@ -0,0 +1,185 @@
+module IRubyTest
+  class DisplayTest < TestBase
+    def setup
+      @object = Object.new
+      @object.instance_variable_set(:@to_html_called, false)
+      @object.instance_variable_set(:@to_markdown_called, false)
+      @object.instance_variable_set(:@to_iruby_called, false)
+      @object.instance_variable_set(:@to_iruby_mimebundle_called, false)
+
+      class << @object
+        attr_reader :to_html_called
+        attr_reader :to_markdown_called
+        attr_reader :to_iruby_called
+        attr_reader :to_iruby_mimebundle_called
+
+        def html
+          "<b>html</b>"
+        end
+
+        def markdown
+          "*markdown*"
+        end
+
+        def inspect
+          "!!! inspect !!!"
+        end
+      end
+    end
+
+    def define_to_html
+      class << @object
+        def to_html
+          @to_html_called = true
+          html
+        end
+      end
+    end
+
+    def define_to_markdown
+      class << @object
+        def to_markdown
+          @to_markdown_called = true
+          markdown
+        end
+      end
+    end
+
+    def define_to_iruby
+      class << @object
+        def to_iruby
+          @to_iruby_called = true
+          ["text/html", "<b>to_iruby</b>"]
+        end
+      end
+    end
+
+    def define_to_iruby_mimebundle
+      class << @object
+        def to_iruby_mimebundle(include: [])
+          @to_iruby_mimebundle_called = true
+          mimes = if include.empty?
+                    ["text/markdown", "application/json"]
+                  else
+                    include
+                  end
+          formats = mimes.map { |mime|
+            result = case mime
+                     when "text/markdown"
+                       "**markdown**"
+                     when "application/json"
+                       %Q[{"mimebundle": "json"}]
+                     end
+            [mime, result]
+          }.to_h
+          metadata = {}
+          return formats, metadata
+        end
+      end
+    end
+
+    def assert_iruby_display(expected)
+      assert_equal(expected,
+                   {
+                     result: IRuby::Display.display(@object),
+                     to_html_called: @object.to_html_called,
+                     to_markdown_called: @object.to_markdown_called,
+                     to_iruby_called: @object.to_iruby_called,
+                     to_iruby_mimebundle_called: @object.to_iruby_mimebundle_called
+                   })
+    end
+
+    sub_test_case("the object cannot handle all the mime types") do
+      def test_display
+        assert_iruby_display({
+                               result: {"text/plain" => "!!! inspect !!!"},
+                               to_html_called: false,
+                               to_markdown_called: false,
+                               to_iruby_called: false,
+                               to_iruby_mimebundle_called: false
+                             })
+      end
+    end
+
+    sub_test_case("the object can respond to to_iruby") do
+      def setup
+        super
+        define_to_iruby
+      end
+
+      def test_display
+        assert_iruby_display({
+                               result: {
+                                 "text/html" => "<b>to_iruby</b>",
+                                 "text/plain" => "!!! inspect !!!"
+                               },
+                               to_html_called: false,
+                               to_markdown_called: false,
+                               to_iruby_called: true,
+                               to_iruby_mimebundle_called: false
+                             })
+      end
+
+      sub_test_case("the object can respond to to_markdown") do
+        def setup
+          super
+          define_to_markdown
+        end
+
+        def test_display
+          assert_iruby_display({
+                                 result: {
+                                   "text/markdown" => "*markdown*",
+                                   "text/plain" => "!!! inspect !!!"
+                                 },
+                                 to_html_called: false,
+                                 to_markdown_called: true,
+                                 to_iruby_called: false,
+                                 to_iruby_mimebundle_called: false
+                               })
+        end
+      end
+
+      sub_test_case("the object can respond to to_html") do
+        def setup
+          super
+          define_to_html
+        end
+
+        def test_display
+          assert_iruby_display({
+                                 result: {
+                                   "text/html" => "<b>html</b>",
+                                   "text/plain" => "!!! inspect !!!"
+                                 },
+                                 to_html_called: true,
+                                 to_markdown_called: false,
+                                 to_iruby_called: false,
+                                 to_iruby_mimebundle_called: false
+                               })
+        end
+
+        sub_test_case("the object can respond to to_iruby_mimebundle") do
+          def setup
+            super
+            define_to_iruby_mimebundle
+          end
+
+          def test_display
+            assert_iruby_display({
+                                   result: {
+                                     "text/markdown" => "**markdown**",
+                                     "application/json" => %Q[{"mimebundle": "json"}],
+                                     "text/plain" => "!!! inspect !!!"
+                                   },
+                                   to_html_called: false,
+                                   to_markdown_called: false,
+                                   to_iruby_called: false,
+                                   to_iruby_mimebundle_called: true
+                                 })
+          end
+        end
+      end
+    end
+  end
+end