ori 0.1.0

data/lib/ori/auto_config.rb

@@ -0,0 +1,78 @@
+module ORI
+  # Propose config defaults based on OS and environment.
+  class AutoConfig    #:nodoc:
+    # Value of <tt>RbConfig::Config["host_os"]</tt>.
+    #
+    #   linux-gnu
+    #   mswin32
+    #   cygwin
+    attr_reader :host_os
+
+    def initialize(attrs = {})
+      attrs.each {|k, v| send("#{k}=", v)}
+      clear_cache
+    end
+
+    #--------------------------------------- Accessors and pseudo-accessors
+
+    def has_less?
+      @cache[:has_less] ||= begin
+        require_host_os
+        !!@host_os.match(/cygwin|darwin|freebsd|gnu|linux/i)
+      end
+    end
+
+    def host_os=(s)
+      @host_os = s
+      clear_cache
+    end
+
+    def unix?
+      @cache[:is_unix] ||= begin
+        require_host_os
+        !!@host_os.match(/cygwin|darwin|freebsd|gnu|linux|sunos|solaris/i)
+      end
+    end
+
+    def windows?
+      @cache[:is_windows] ||= begin
+        require_host_os
+        !!@host_os.match(/mswin|windows/i)
+      end
+    end
+
+    #--------------------------------------- Defaults
+
+    def color
+      @cache[:color] ||= unix?? true : false
+    end
+
+    def frontend
+      @cache[:frontend] ||= unix?? "ri -T -f ansi %s" : "ri -T %s"
+    end
+
+    def pager
+      @cache[:pager] ||= has_less?? "less -R" : "more"
+    end
+
+    def shell_escape
+      @cache[:shell_escape] ||= if unix?
+        :unix
+      elsif windows?
+        :windows
+      else
+        nil
+      end
+    end
+
+    private
+
+    def clear_cache
+      @cache = {}
+    end
+
+    def require_host_os
+      raise "`host_os` is not set" if not @host_os
+    end
+  end
+end

data/lib/ori/colorize.rb

@@ -0,0 +1,62 @@
+module ORI
+  # Simplistic ANSI colorizer.
+  module Colorize   #:nodoc:
+    # Issue an ANSI color sequence.
+    #
+    #   puts [Colorize.seq(:message, :error), "Error!", Colorize.seq(:reset)].join
+    def self.seq(*spec)
+      Tools.ansi(*case spec
+        when [:choice, :title]
+          [:green]
+        when [:choice, :index]
+          [:yellow, :bold]
+        when [:choice, :label]
+          [:cyan]
+        when [:choice, :prompt]
+          [:yellow, :bold]
+
+        # These go in sequence, each knows who's before. Thus we minimize ANSI.
+        when [:list_method, :own_marker]
+          [:reset, :bold]
+        when [:list_method, :not_own_marker]
+          [:reset]
+        when [:list_method, :obj_module_name]
+          [:cyan, :bold]
+        when [:list_method, :owner_name]
+          [:reset]
+        when [:list_method, :access]
+          [:reset, :cyan]
+        when [:list_method, :name]
+          [:reset, :bold]
+        when [:list_method, :visibility]
+          [:reset, :yellow]
+
+        # These go in sequence.
+        when [:mam, :module_name]
+          [:cyan, :bold]
+        when [:mam, :access]
+          [:reset, :cyan]
+        when [:mam, :method_name]
+          [:reset, :bold]
+
+        when [:message, :action]
+          [:green]
+        when [:message, :error]
+          [:red, :bold]
+        when [:message, :info]
+          [:green]
+
+        when [:reset]
+          [:reset]
+
+        else
+          raise ArgumentError, "Unknown spec: #{spec.inspect}"
+        end
+      ) # Tools.ansi
+    end
+
+    def self.colorize(*args)
+      args.map {|v| v.is_a?(Array) ? seq(*v) : v}.join
+    end
+  end # Colorize
+end

data/lib/ori/config.rb

@@ -0,0 +1,27 @@
+module ORI
+  # Configuration object.
+  class Config
+    # Enable color. Example:
+    #
+    #   true
+    attr_accessor :color
+
+    # RI frontend command to use. <tt>%s</tt> is replaced with sought topic. Example:
+    #
+    #   ri -T -f ansi %s
+    attr_accessor :frontend
+
+    # Paging program to use. Examples:
+    #
+    #   less -R
+    #   more
+    attr_accessor :pager
+
+    # Shell escape mode. <tt>:unix</tt> or <tt>:windows</tt>.
+    attr_accessor :shell_escape
+
+    def initialize(attrs = {})
+      attrs.each {|k, v| send("#{k}=", v)}
+    end
+  end
+end

data/lib/ori/extensions.rb

@@ -0,0 +1,4 @@
+module ORI
+  module Extensions   #:nodoc:
+  end
+end

data/lib/ori/extensions/object/ri.rb

@@ -0,0 +1,88 @@
+module ORI
+  module Extensions
+    module Object
+      # View RI pages on module, class, method. Interactively list receiver's methods.
+      #
+      # == Request RI on a Class
+      #
+      #   Array.ri
+      #   String.ri
+      #   [].ri
+      #   "".ri
+      #   5.ri
+      #
+      # So that's fairly straightforward -- grab a class or class instance and call <tt>ri</tt> on it:
+      #
+      #   obj = SomeKlass.new
+      #   obj.ri
+      #
+      # == Request RI on a Method
+      #
+      #   String.ri :upcase
+      #   "".ri :upcase
+      #   [].ri :sort
+      #   Hash.ri :[]
+      #   Hash.ri "::[]"
+      #   Hash.ri "#[]"
+      #
+      # == Request Interactive Method List
+      #
+      #   # Regular expression argument denotes list request.
+      #   String.ri //
+      #   "".ri //
+      #
+      #   # Show method names matching a regular expression.
+      #   "".ri /case/
+      #   "".ri /^to_/
+      #   [].ri /sort/
+      #   {}.ri /each/
+      #
+      #   # Show ALL methods, including those private of Kernel.
+      #   Hash.ri //, :all => true
+      #   Hash.ri //, :all
+      #
+      #   # Show class methods or instance methods only.
+      #   Module.ri //, :access => "::"
+      #   Module.ri //, :access => "#"
+      #
+      #   # Show own methods only.
+      #   Time.ri //, :own => true
+      #   Time.ri //, :own
+      #
+      #   # Specify visibility: public, protected or private.
+      #   Module.ri //, :visibility => :private
+      #   Module.ri //, :visibility => [:public, :protected]
+      #
+      #   # Filter fully formatted name by given regexp.
+      #   Module.ri //, :fullre => /\(Object\)::/
+      #
+      #   # Combine options.
+      #   Module.ri //, :fullre => /\(Object\)::/, :access => "::", :visibility => :private
+      #
+      # == Request Interactive Method List for More Than 1 Object at Once
+      #
+      # By using the <tt>:join</tt> option it's possible to fetch methods for more
+      # than 1 object at once. Value of <tt>:join</tt> (which can be an object or an array)
+      # is joined with the original receiver, and then a combined set is queried.
+      #
+      #   # List all division-related methods from numeric classes.
+      #   Fixnum.ri /div/, :join => [Float, Rational]
+      #   5.ri /div/, :join => [5.0, 5.to_r]
+      #
+      #   # List all ActiveSupport extensions to numeric classes.
+      #   5.ri //, :join => [5.0, 5.to_r], :fullre => /ActiveSupport/
+      #
+      #   # Query entire Rails family for methods having the word "javascript".
+      #   rails_modules = ObjectSpace.each_object(Module).select {|mod| mod.to_s.match /Active|Action/}
+      #   "".ri /javascript/, :join => rails_modules
+      def ri(*args)
+        ::ORI::Internals.do_history
+        ::ORI::Internals.ri(self, *args)
+      end
+    end
+  end
+end
+
+class Object    #:nodoc:
+  include ::ORI::Extensions::Object
+end

data/lib/ori/internals.rb

@@ -0,0 +1,411 @@
+module ORI
+  # Tools used internally by ORI.
+  module Internals    #:nodoc:
+    GLM_ALL_ACCESSES = ["::", "#"]
+    GLM_ALL_VISIBILITIES = [:public, :protected, :private]
+
+    # Error message for the user. Sometimes it's CAUSED by the user, sometimes it's influenced by him.
+    class UserError < Exception   #:nodoc:
+    end    
+
+    # Non-destructive break request.
+    class Break < Exception   #:nodoc:
+    end
+
+    # Apply smart filters on array of <tt>ListMethod</tt>. Return filtered array.
+    def self.apply_smart_filters(obj, list_methods)
+      # Filters.
+      #
+      # * Filters return false if record is "bad". Any other return result means that record is "good".
+      filters = []
+
+      # Hide all methods starting with "_ori_".
+      filters << proc do |r|
+        if r.method_name.match /\A_ori_/
+          false
+        end
+      end
+
+      # Obj is not Kernel.
+      if (obj != Kernel rescue false)
+        filters << proc do |r|
+          # Chop off Kernel's non-public methods.
+          if r.owner == Kernel and not r.public?
+            false
+          end
+        end
+      end
+
+      # Obj is an object.
+      if not obj.is_a? Module
+        filters << proc do |r|
+          # Chop off non-public methods.
+          if not r.public?
+            false
+          end
+        end
+      end
+
+      # Obj is a module or a class.
+      if obj.is_a? Module
+        filters << proc do |r|
+          # Chop off others' private instance methods.
+          # NOTE: We shouldn't chop private singleton methods since they are callable from the context of our class. See Sample::BasicExtension::Klass.
+          if not r.own? and r.private? and r.instance?
+            false
+          end
+        end
+      end
+
+      # Go! If any filter rejects the record, it's rejected.
+      list_methods.reject do |r|
+        filters.any? {|f| f.call(r) == false}
+      end
+    end
+
+    # Process interactive choice.
+    # Return chosen item or <tt>nil</tt>.
+    #
+    #   choice [
+    #     ["wan", 1.0],
+    #     ["tew", 2.0],
+    #     ["free", 3.0],
+    #   ]
+    #
+    # Options:
+    #
+    #   :colorize_labels => T|F   # Default is true.
+    #   :item_indent => "  "      # Default is "  ".
+    #   :prompt => ">"            # Default is ">>".
+    #   :title => "my title"      # Dialog title. Default is nil (no title).
+    #
+    #   :on_abort => obj          # Result to return on abort (Ctrl-C). Default is nil.
+    #   :on_skip => obj           # Treat empty input as skip action. Default is nil.
+    def self.choice(items, options = {})
+      raise ArgumentError, "At least 1 item required" if items.size < 1
+
+      options = options.dup
+      o = {}
+
+      o[k = :colorize_labels] = (v = options.delete(k)).nil?? true : v
+      o[k = :item_indent] = (v = options.delete(k)).nil?? "  " : v
+      o[k = :prompt] = (v = options.delete(k)).nil?? ">>" : v
+      o[k = :title] = options.delete(k)
+
+      o[k = :on_abort] = options.delete(k)
+      o[k = :on_skip] = options.delete(k)
+
+      raise ArgumentError, "Unknown option(s): #{options.inspect}" if not options.empty?
+
+      # Convert `items` into an informative hash.
+      hitems = []
+      items.each_with_index do |item, i|
+        hitems << {
+          :index => (i + 1).to_s,     # Convert to string here, which eliminates the need to do String -> Integer after input.
+          :label => item[0],
+          :value => item[1],
+        }
+      end
+
+      ### Begin dialog. ###
+
+      if not (s = o[:title].to_s).empty?
+        puts colorize([:choice, :title], s, [:reset])
+        puts
+      end
+
+      # Print items.
+      index_nchars = hitems.size.to_s.size
+      hitems.each do |h|
+        puts colorize(*[
+          [
+            o[:item_indent],
+           [:choice, :index], "%*d" % [index_nchars, h[:index]],
+           " ",
+          ],
+          (o[:colorize_labels] ? [[:choice, :label], h[:label]] : [h[:label]]),
+          [[:reset]],
+        ].flatten(1))
+      end
+      puts
+
+      # Read input.
+
+      # Catch INT for a while.
+      old_sigint = trap("INT") do
+        puts "\nAborted"
+        return o[:on_abort]
+      end
+
+      # WARNING: Return result of `while` is return result of method.
+      while true
+        print colorize([:choice, :prompt], o[:prompt], " ", [:reset])
+
+        input = gets.strip
+        if input.empty?
+          if o[:on_skip]
+            break o[:on_skip]
+          else
+            next
+          end
+        end
+
+        # Something has been input.
+        found = hitems.find {|h| h[:index] == input}
+        break found[:value] if found
+
+        puts colorize([:message, :error], "Invalid input", [:reset])
+      end # while true
+    ensure
+      # NOTE: `old_sigint` is literally declared above, so it always exists here no matter when we gain control.
+      if not old_sigint.nil?
+        trap("INT", &old_sigint)
+      end
+    end # choice
+
+    # Same as <tt>ORI::Colorize.colorize</tt>, but this one produces
+    # plain output if color is turned off in <tt>ORI.conf</tt>.
+    def self.colorize(*args)
+      Colorize.colorize *args.reject {|v| v.is_a? Array and not ::ORI.conf.color}
+    end
+
+    # Colorize a MAM (module-access-method) array.
+    #
+    #   colorize_mam(["Kernel", "#", "dup"])
+    def self.colorize_mam(mam)
+      colorize(*[
+        [:mam, :module_name], mam[0],
+        [:mam, :access], mam[1],
+        [:mam, :method_name], mam[2],
+        [:reset],
+      ])
+    end
+
+    # Stuff a ready-made "<subject>.ri " command into Readline history if last request had an argument.
+    def self.do_history
+      # `cmd` is actually THIS command being executed.
+      cmd = Readline::HISTORY.to_a.last
+      if prefix = get_ri_arg_prefix(cmd)
+        Readline::HISTORY.pop
+        Readline::HISTORY.push "#{prefix} "
+        Readline::HISTORY.push cmd
+      end
+    end
+
+    # Fetch ListMethods from one or more objects (<tt>:obj => ...</tt>) and optionally filter them.
+    # Options:
+    #
+    #   :access => "#"            # "#" or "::".
+    #   :all => true|false        # Show all methods. Default is `false`.
+    #   :fullre => Regexp         # Full record filter.
+    #   :objs => Array            # Array of objects to fetch methods of. Must be specified.
+    #   :own => true|false        # Show own methods only.
+    #   :re => Regexp             # Method name filter.
+    #   :visibility => :protected # Symbol or [Symbol, Symbol, ...].
+    def self.get_list_methods(options = {})
+      options = options.dup
+      o = {}
+
+      o[k = :access] = if v = options.delete(k); v.to_s; end
+      o[k = :all] = (v = options.delete(k)).nil?? false : v
+      o[k = :fullre] = options.delete(k)
+      o[k = :objs] = options.delete(k)
+      o[k = :own] = (v = options.delete(k)).nil?? false : v
+      o[k = :re] = options.delete(k)
+      o[k = :visibility] = options.delete(k)
+      raise ArgumentError, "Unknown option(s): #{options.inspect}" if not options.empty?
+
+      k = :access; raise ArgumentError, "options[#{k.inspect}] must be in #{GLM_ALL_ACCESSES.inspect}, #{o[k].inspect} given" if o[k] and not GLM_ALL_ACCESSES.include? o[k]
+      k = :fullre; raise ArgumentError, "options[#{k.inspect}] must be Regexp, #{o[k].class} given" if o[k] and not o[k].is_a? Regexp
+
+      k = :objs
+      raise ArgumentError, "options[#{k.inspect}] must be set" if not o[k]
+      raise ArgumentError, "options[#{k.inspect}] must be Array, #{o[k].class} given" if o[k] and not o[k].is_a? Array
+
+      k = :re; raise ArgumentError, "options[#{k.inspect}] must be Regexp, #{o[k].class} given" if o[k] and not o[k].is_a? Regexp
+
+      if o[k = :visibility]
+        o[k] = [o[k]].flatten
+        o[k].each do |v|
+          raise ArgumentError, "options[#{k.inspect}] must be in #{GLM_ALL_VISIBILITIES.inspect}, #{v.inspect} given" if not GLM_ALL_VISIBILITIES.include? v
+        end
+      end
+
+      # NOTE: `:all` and `:own` are NOT mutually exclusive. They are mutually confusive. :)
+
+      # Build per-obj lists.
+      per_obj = o[:objs].uniq.map do |obj|
+        ar = []
+
+        Tools.get_methods(obj).each do |inspector, methods|
+          ar += methods.map {|method_name| ListMethod.new(:obj => obj, :inspector => inspector, :method_name => method_name)}
+        end
+
+        # Filter by access if requested.
+        ar.reject! {|r| r.access != o[:access]} if o[:access]
+
+        # Filter by visibility if requested.
+        ar.reject! {|r| o[:visibility].none? {|vis| r.visibility == vis}} if o[:visibility]
+
+        # Leave only own methods if requested.
+        ar.reject! {|r| not r.own?} if o[:own]
+
+        # Apply RE if requested.
+        ar.reject! {|r| not r.match(o[:re])} if o[:re]
+
+        # Apply full RE if requested
+        ar.reject! {|r| not r.fullmatch(o[:fullre])} if o[:fullre]
+
+        # Apply smart filters if requested.
+        ar = apply_smart_filters(obj, ar) if not o[:all]
+
+        # Important, return `ar` from block.
+        ar
+      end # o[:objs].each
+
+      out = per_obj.flatten(1)
+      ##p "out.size", out.size
+
+      # Chop off duplicates.
+      out.uniq!
+
+      # DO NOT sort by default. If required for visual listing, that's caller's responsibility!
+      #out.sort!
+
+      out
+    end
+
+    # Used in <tt>do_history</tt>.
+    # Get prefix of the last "subject.ri args" command.
+    # Return everything before " args" or <tt>nil</tt> if command didn't have arguments.
+    def self.get_ri_arg_prefix(cmd)
+      if (mat = cmd.match /\A(\s*.+?\.ri)\s+\S/)
+        mat[1]
+      end
+    end
+
+    # Return local library instance.
+    def self.library
+      @lib ||= Library.new
+
+      # Update sensitive attrs on every call.
+      @lib.frontend = ::ORI.conf.frontend
+      @lib.shell_escape = ::ORI.conf.shell_escape
+
+      @lib
+    end
+
+    # Show content in a configured pager.
+    #
+    #   pager do |f|
+    #     f.puts "Hello, world!"
+    #   end
+    def self.pager(&block)
+      IO.popen(::ORI.conf.pager, "w", &block)
+    end
+
+    # Do main job.
+    def self.ri(obj, *args)
+      # Most of the time return nil, for list modes return number of items. Could be useful. Don't return `false` on error, that's confusing.
+      out = nil
+
+      begin
+        # Build request.
+        req = ::ORI::Request.parse(*args)
+        raise UserError, "Bad request: #{req.message}" if req.error?
+        ##IrbHacks.break req
+
+        # List request.
+        #
+        #   Klass.ri //
+        if req.list?
+          begin
+            req.glm_options[:objs].unshift(obj)
+            list_methods = get_list_methods(req.glm_options).sort
+          rescue ArgumentError => e
+            raise UserError, "Bad request: #{e.message}"
+          end
+          raise UserError, "No methods found" if list_methods.size < 1
+
+          # Display.
+          pager do |f|
+            f.puts list_methods.map {|r| r.format(:color => ::ORI.conf.color)}
+          end
+
+          out = list_methods.size
+          raise Break
+        end # if req.list?
+
+        # Class or method request. Particular ri article should be displayed.
+        #
+        #   Klass.ri
+        #   Klass.ri :meth
+        mam_topics = if req.self?
+          [[Tools.get_module_name(obj.is_a?(Module) ? obj : obj.class)]]
+        elsif req.method?
+          begin
+            req.glm_options[:objs].unshift(obj)
+            list_methods = get_list_methods(req.glm_options)
+          rescue ArgumentError => e
+            raise UserError, "Bad request: #{e.message}"
+          end
+          raise UserError, "No methods found" if list_methods.size < 1
+
+          # Collect topics.
+          # NOTE: `uniq` is important. Take `Module#public` as an example.
+          list_methods.map {|r| r.ri_topics}.flatten(1).uniq
+        else
+          raise "Unrecognized request kind #{req.kind.inspect}, SE"
+        end # mam_topics =
+
+        # Lookup topics. Display progress -- 1 character per lookup.
+        print colorize([:message, :action], "Looking up topics [", [:reset], mam_topics.map {|ar| colorize_mam(ar)}.join(", "), [:message, :action], "] ", [:reset])
+
+        found = []
+        mam_topics.each do |mam|
+          topic = mam.join
+          content = library.lookup(topic)
+          if content
+            print "o"
+            found << {
+              :topic => colorize_mam(mam),
+              :content => content,
+            }
+          else
+            print "."
+          end
+        end
+        puts
+
+        raise UserError, "No articles found" if found.size < 1
+
+        # Decide which article to show.
+        content = if found.size == 1
+          found.first[:content]
+        else
+          items = found.map {|h| ["#{h[:topic]} (#{h[:content].size}b)", h[:content]]}
+          choice(items, {
+            :colorize_labels => false,
+            :title => "More than 1 article found",
+            :on_skip => items.first[1],
+          })
+        end
+
+        # Handle abort.
+        raise Break if not content
+
+        # Display.
+        pager do |f|
+          f.puts content
+        end
+      rescue UserError => e
+        puts colorize([:message, :error], e.message, [:reset])
+
+        out = nil
+      rescue Break
+      end
+
+      out
+    end
+  end # Internals
+end # ORI