ori 0.1.0

data/lib/ori/library.rb

@@ -0,0 +1,59 @@
+require "set"
+
+module ORI
+  # ri lookup library.
+  class Library   #:nodoc:
+    # Mask of ri command to fetch content. Example:
+    #
+    #   ri -T -f ansi %s
+    attr_accessor :frontend
+
+    # Shell escape mode. <tt>:unix</tt> or <tt>:windows</tt>.
+    attr_accessor :shell_escape
+
+    def initialize(attrs = {})
+      @cache = {}
+      attrs.each {|k, v| send("#{k}=", v)}
+    end
+
+    # Lookup an article.
+    #
+    #   lookup("Kernel#puts")     # => content or nil.
+    def lookup(topic)
+      if @cache.has_key? topic
+        @cache[topic]
+      else
+        require_frontend
+
+        etopic = case @shell_escape
+        when :unix
+          Tools.shell_escape(topic)
+        when :windows
+          Tools.win_shell_escape(topic)
+        else
+          topic
+        end
+
+        cmd = @frontend % etopic
+        ##p "cmd", cmd
+        content = `#{cmd} 2>&1`
+        ##p "content", content
+
+        # NOTES:
+        # * Windows' ri always returns 0 even if article is not found. Work around it with a hack.
+        # * Unix's ri sometimes returns 0 when it offers suggestions. Try `ri Object#is_ax?`.
+        @cache[topic] = if $?.exitstatus != 0 or content.lines.count < 4
+          nil
+        else
+          content
+        end
+      end
+    end
+
+    protected
+
+    def require_frontend
+      raise "`frontend` is not set" if not @frontend
+    end
+  end # Library
+end # ORI

data/lib/ori/list_method.rb

@@ -0,0 +1,247 @@
+module ORI
+  # Our method representation suitable for listing.
+  class ListMethod    #:nodoc:
+    OWN_MARKER = ["~", " "]
+
+    # Object. Can be anything, including <em>nil</em>.
+    attr_reader :obj
+
+    attr_reader :method_name
+    attr_reader :inspector
+
+    def initialize(attrs = {})
+      attrs.each {|k, v| send("#{k}=", v)} 
+      clear_cache
+    end
+
+    #--------------------------------------- Accessors and pseudo accessors
+
+    # Return method access substring: "::" or "#".
+    def access
+      # NOTE: It is *WRONG* to rely on Ruby's `inspect` to handle things because
+      #       it doesn't work for cases when singleton methods are included from modules.
+      @cache[:access] ||= (module? and not inspector.match /instance/) ? "::" : "#"
+    end
+
+    def inspector=(s)
+      @inspector = s.to_s
+      clear_cache
+    end
+
+    def instance?
+      access == "#"
+    end
+
+    def method_name=(s)
+      @method_name = s.to_s
+      clear_cache
+    end
+
+    # Fetch method object.
+    def method_object
+      require_valid
+
+      @cache[:method_object] ||= if @inspector.match /instance/
+        @obj._ori_instance_method(@method_name)
+      else
+        @obj._ori_method(@method_name)
+      end
+    end
+
+    def module?
+      @cache[:is_module] ||= begin
+        require_obj
+        @obj.is_a? Module
+      end
+    end
+
+    def obj=(obj)
+      @obj = obj
+      @obj_present = true
+      clear_cache
+    end
+
+    def obj_module
+      @cache[:obj_module] ||= obj.is_a?(Module) ? obj : obj.class
+    end
+
+    def obj_module_name
+      @cache[:obj_module_name] ||= Tools.get_module_name(obj_module)
+    end
+
+    def owner
+      @cache[:owner] ||= method_object.owner
+    end
+
+    # Get, if possible, <tt>obj</tt> singleton class.
+    # Some objects, e.g. <tt>Fixnum</tt> instances, don't have a singleton class.
+    def obj_singleton_class
+      @cache[:obj_singleton] ||= begin
+        class << obj    #:nodoc:
+          self
+        end
+      rescue
+        nil
+      end
+    end
+
+    # Return <tt>true</tt> if method is natively owned by <tt>obj</tt> class.
+    def own?
+      @cache[:is_own] ||= begin
+        require_valid
+        owner == obj_module || owner == obj_singleton_class
+      end
+    end
+
+    def owner_name
+      @cache[:owner_name] ||= Tools.get_module_name(owner)
+    end
+
+    def private?
+      visibility == :private
+    end
+
+    def protected?
+      visibility == :protected
+    end
+
+    def public?
+      visibility == :public
+    end
+
+    def singleton?
+      access == "::"
+    end
+
+    # Return visibility: <tt>:public</tt>, <tt>:protected</tt>, <tt>:private</tt>.
+    def visibility
+      @cache[:visibility] ||= begin
+        require_valid
+
+        if @inspector.match /private/
+          :private
+        elsif @inspector.match /protected/
+          :protected
+        else
+          :public
+        end
+      end
+    end
+
+    #---------------------------------------
+
+    # Format self into a string.
+    # Options:
+    #
+    #   :color => true|false
+    def format(options = {})
+      options = options.dup
+      o = {}
+      o[k = :color] = (v = options.delete(k)).nil?? true : v
+      raise ArgumentError, "Unknown option(s): #{options.inspect}" if not options.empty?
+
+      require_valid
+
+      Colorize.colorize *[
+        (own?? [[:list_method, :own_marker], OWN_MARKER[0]] : [[:list_method, :not_own_marker], OWN_MARKER[1]]),
+        [[:list_method, :obj_module_name], obj_module_name],
+        ([[:list_method, :owner_name], "(#{owner_name})"] if not own?),
+        [[:list_method, :access], access],
+        [[:list_method, :name], method_name],
+        ([[:list_method, :visibility], " [#{visibility}]"] if not public?),
+        [[:reset]],
+      ].compact.flatten(1).reject {|v| v.is_a? Array and not o[:color]}
+    end
+
+    # Match entire formatted record against RE.
+    def fullmatch(re)
+      format(:color => false).match(re)
+    end
+
+    # Match method name against RE.
+    def match(re)
+      @method_name.match(re)
+    end
+
+    # Quick format. No options, no hashes, no checks.
+    def qformat
+      #"#{owner_name}#{access}#{@method_name} [#{visibility}]"        # Before multi-obj support.
+      "#{obj_module_name}#{access}#{@method_name} [#{visibility}]"
+    end
+
+    def ri_topics
+      @cache[:ri_topics] ||= begin
+        require_valid
+
+        # Build "hierarchy methods". Single record is:
+        #
+        #   ["Kernel", "#", "dup"]
+        hmethods = []
+
+        # Always stuff self in front of the line regardless of if we have method or not.
+        hmethods << [obj_module_name, access, method_name]
+
+        ancestors = []
+        ancestors += obj_module.ancestors
+        ancestors += obj_singleton_class.ancestors if obj_singleton_class     # E.g. when module extends class.
+
+        ancestors.each do |mod|
+          mav = Tools.get_methods(mod, :inspector_arg => false, :to_mav => true)
+          ##p "mav", mav
+          found = mav.select {|method_name,| method_name == self.method_name}
+          ##p "found", found
+          found.each do |method_name, access|
+            hmethods << [Tools.get_module_name(mod), access, method_name]
+          end
+        end
+
+        # Misdoc hack -- stuff Object#meth lookup if Kernel#meth is present. For methods like Kernel#is_a?.
+        if (found = hmethods.find {|mod, access| [mod, access] == ["Kernel", "#"]}) and not hmethods.find {|mod,| mod == "Object"}
+          hmethods << ["Object", "#", found.last]
+        end
+
+        hmethods.uniq
+      end
+    end
+
+    def valid?
+      [
+        @obj_present,
+        @method_name,
+        @inspector,
+      ].all?
+    end
+
+    #---------------------------------------
+
+    # Support <tt>Enumerable#sort</tt>.
+    def <=>(other)
+      [@method_name, access, obj_module_name] <=> [other.method_name, other.access, obj_module_name]
+    end
+
+    # Support <tt>Array#uniq</tt>.
+    def hash
+      @cache[:hash] ||= qformat.hash
+    end
+
+    # Support <tt>Array#uniq</tt>.
+    def eql?(other)
+      hash == other.hash
+    end
+
+    #---------------------------------------
+    private
+
+    def clear_cache
+      @cache = {}
+    end
+
+    def require_obj
+      raise "`obj` is not set" if not @obj_present
+    end
+
+    def require_valid
+      raise "Object is not valid" if not valid?
+    end
+  end # ListMethod
+end

data/lib/ori/request.rb

@@ -0,0 +1,118 @@
+module ORI
+  # <tt>something.ri [something]</tt> request logic.
+  #
+  # NOTE: This class DOES NOT validate particular options to be passed to <tt>get_list_methods</tt>.
+  class Request   #:nodoc:
+    class ParseError < Exception    #:nodoc:
+    end
+
+    # Options for <tt>Internals::get_list_methods</tt>.
+    attr_accessor :glm_options
+
+    # <tt>:self</tt>, <tt>:list</tt>, <tt>:method</tt> or <tt>:error</tt>.
+    attr_accessor :kind
+
+    # Message. E.g. for <tt>:error</tt> kind this is the message for the user.
+    attr_accessor :message
+
+    def initialize(attrs = {})
+      @glm_options = {}
+      attrs.each {|k, v| send("#{k}=", v)}
+    end
+
+    def error?
+      @kind == :error
+    end
+
+    def list?
+      @kind == :list
+    end
+
+    def method?
+      @kind == :method
+    end
+
+    def self?
+      @kind == :self
+    end
+
+    #---------------------------------------
+
+    # Parse arguments into a new <tt>Request</tt> object.
+    #
+    #   parse()
+    #   parse(//)
+    #   parse(//, :all)
+    #   parse(//, :all => true, :access => "#")
+    #   parse(:puts)
+    #   parse("#puts")
+    #   parse("::puts")
+    def self.parse(*args)
+      r = new(:glm_options => {:objs => []})
+
+      begin
+        if args.size < 1
+          #   Fixnum.ri
+          #   5.ri
+          r.kind = :self
+        else
+          # At least 1 argument is present.
+          arg1 = args.shift
+
+          case arg1
+          when Symbol, String
+            #   ri :meth
+            #   ri "#meth"
+            #   ri "::meth"
+            r.kind = :method
+            if args.size > 0
+              raise ParseError, "Unexpected arguments after #{arg1.inspect}"
+            end
+
+            # This is important -- look through all available methods.
+            r.glm_options[:all] = true
+
+            method_name = if arg1.to_s.match /\A(::|#)(.+)\z/
+              r.glm_options[:access] = $1
+              $2
+            else
+              arg1.to_s
+            end
+
+            r.glm_options[:re] = /\A#{Regexp.escape(method_name)}\z/
+
+          when Regexp
+            #   ri //
+            #   ri //, :all
+            #   ri /kk/, :option => value etc.
+            r.kind = :list
+            r.glm_options[:re] = arg1
+            args.each do |arg|
+              if arg.is_a? Hash
+                if arg.has_key?(k = :join)
+                  r.glm_options[:objs] += [arg.delete(k)].flatten(1)
+                end
+
+                r.glm_options.merge! arg
+              elsif [String, Symbol].include? arg.class
+                r.glm_options.merge! arg.to_sym => true
+              else
+                raise ParseError, "Unsupported argument #{arg.inspect}"
+              end
+            end
+
+            # Don't bother making `objs` unique, we're just the request parser.
+
+          else
+            raise ParseError, "Unsupported argument #{arg1.inspect}"
+          end # case arg1
+        end # if args.size < 1
+      rescue ParseError => e
+        r.kind = :error
+        r.message = e.message
+      end
+
+      r
+    end
+  end
+end

data/lib/ori/tools.rb

@@ -0,0 +1,142 @@
+module ORI
+  # Generic tools.
+  module Tools    #:nodoc:
+    ANSI_ATTRS = {
+      :reset       => 0,
+      :bold        => 1,
+      :underscore  => 4,
+      :underline   => 4,
+      :blink       => 5,
+      :reverse     => 7,
+      :concealed   => 8,
+      :black       => 30,
+      :red         => 31,
+      :green       => 32,
+      :yellow      => 33,
+      :blue        => 34,
+      :magenta     => 35,
+      :cyan        => 36,
+      :white       => 37,
+      :on_black    => 40,
+      :on_red      => 41,
+      :on_green    => 42,
+      :on_yellow   => 43,
+      :on_blue     => 44,
+      :on_magenta  => 45,
+      :on_cyan     => 46,
+      :on_white    => 47,
+    }
+
+    # Default inspectors for <tt>get_methods</tt>.
+    GET_METHODS_INSPECTORS = [
+      :private_instance_methods,
+      :protected_instance_methods,
+      :public_instance_methods,
+      :private_methods,
+      :protected_methods,
+      :public_methods,
+    ]
+
+    # Build an ANSI sequence.
+    #
+    #   ansi()              # => ""
+    #   ansi(:red)          # => "\e[31m"
+    #   ansi(:red, :bold)   # => "\e[31;1m"
+    #   puts "Hello, #{ansi(:bold)}user#{ansi(:reset)}"
+    def self.ansi(*attrs)
+      codes = attrs.map {|attr| ANSI_ATTRS[attr.to_sym] or raise ArgumentError, "Unknown attribute #{attr.inspect}"}
+      codes.empty?? "" : "\e[#{codes.join(';')}m"
+    end
+
+    # Inspect an object with various inspectors.
+    # Options:
+    #
+    #   :inspectors => []         # Array of inspectors, e.g. [:public_instance_methods].
+    #   :inspector_arg => T|F     # Arg to pass to inspector. Default is <tt>true</tt>
+    #   :to_mav => T|F            # Post-transform list into [method_name, access, visibility] ("MAV"). Default is <tt>false</tt>.
+    #
+    # Examples:
+    #
+    #   get_methods(obj)
+    #   # => [[inspector, [methods]], [inspector, [methods]], ...]
+    #   get_methods(obj, :to_mav => true)
+    #   # => [[method_name, access, visibility], [method_name, access, visibility], ...]
+    def self.get_methods(obj, options = {})
+      options = options.dup
+      o = {}
+      o[k = :inspectors] = (v = options.delete(k)).nil?? GET_METHODS_INSPECTORS : v
+      o[k = :inspector_arg] = (v = options.delete(k)).nil?? true : v
+      o[k = :to_mav] = (v = options.delete(k)).nil?? false : v
+      raise ArgumentError, "Unknown option(s): #{options.inspect}" if not options.empty?
+
+      out = []
+
+      o[:inspectors].each do |inspector|
+        next if not obj.respond_to? inspector
+        out << [inspector.to_s, obj.send(inspector, o[:inspector_arg]).sort.map(&:to_s)]
+      end
+
+      if o[:to_mav]
+        mav = []
+
+        is_module = obj.is_a? Module
+
+        out.each do |inspector, methods|
+          ##puts "-- inspector-#{inspector.inspect}"
+          access = (is_module and not inspector.match /instance/) ? "::" : "#"
+
+          visibility = if inspector.match /private/
+            :private
+          elsif inspector.match /protected/
+            :protected
+          else
+            :public
+          end
+
+          methods.each do |method_name|
+            mav << [method_name, access, visibility]
+          end
+        end
+
+        out = mav.uniq    # NOTE: Dupes are possible, e.g. when custom inspectors are given.
+      end
+
+      out
+    end
+
+    # Return name of a module, even a "nameless" one.
+    def self.get_module_name(mod)
+      if mod.name.to_s.empty?
+        if mat = mod.inspect.match(/#<Class:.*?\b(.+?)(?:>|:[0#])/)
+          mat[1]
+        end
+      else
+        mod.name
+      end
+    end
+
+    # Escape string for use in Unix shell command.
+    # Credits http://stackoverflow.com/questions/1306680/shellwords-shellescape-implementation-for-ruby-1-8.
+    def self.shell_escape(s)
+      # An empty argument will be skipped, so return empty quotes.
+      return "''" if s.empty?
+
+      s = s.dup
+
+      # Process as a single byte sequence because not all shell
+      # implementations are multibyte aware.
+      s.gsub!(/([^A-Za-z0-9_\-.,:\/@\n])/n, "\\\\\\1")
+
+      # A LF cannot be escaped with a backslash because a backslash + LF
+      # combo is regarded as line continuation and simply ignored.
+      s.gsub!(/\n/, "'\n'")
+
+      s
+    end
+
+    # Escape string for use in Windows command. Word "shell" is used for similarity.
+    def self.win_shell_escape(s)
+      s
+    end
+  end # Tools
+end # ORI