bri 0.4.4 → 1.0.0.pre.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74b87ae62d01b5be9164734271754be0cc3a1ef68ad3b35bd78b633d829a529a
-  data.tar.gz: 27fdfe717c1cea3b49525ff5e9c59b462757d1d86db440bd4dc1fd9719f47c70
+  metadata.gz: 2a26dfbcd940347c2bf68246c1223702a30ae82cc6ff032fd9160f4f6cd2587f
+  data.tar.gz: ad88f5eb0b894300eb1f8073da1baf4444ebebd07aa992d772465044f1a6d444
 SHA512:
-  metadata.gz: e0d96c3ae752ec0b5b3fb59ad58da596869fd91665282eeb588ba8c03041b3f26040f331189b9db84a6d55aaf5e5540430dddbd07c925a7dde198ed6939bc7f0
-  data.tar.gz: 4f3cc64561cb91cc53caf689611c32f6daf8d0482eb2bee3407358fad32fd808e0b70ce613c979b57917c0c2afe4b135f48f46e19de8888a167591d205aadecc
+  metadata.gz: c258a7980e40af727d7d543f70d14398df03019be7496116180d6c6812e5becbad29bde410d26983b49ec6617cbb477c73ed357ef18cf60e72ab362fce914ec1
+  data.tar.gz: 9cbe6dc1a11b9cc745ce75b8f602416dbba701bcb0a22f0c973d15375875cf23d67faa1b03836d63595752a189cbccacb4c6d943a0464a2ef616cf4254b2b6a0

data/TODO

@@ -1,7 +1,4 @@
 - Extend unqualified search to include class methods and case insensitive searches
-- {multi word label}[links] won't display correctly if the label is right where
-  a line wrap occurs
-- Refactor the convoluted rendering of lists and list items
 - Detect ansi capabilities and use what is possible with graceful degradation?
 - Potentially try to detect method references in documentation prose and 
   highlight these (e.g. Object#send and Object.new)
@@ -9,3 +6,5 @@
 - Add display of module constant aliases
 - Rewrite the search code into something understandable and maintainable
   (sleep deprivation is one hell of a drug)
+- Add UTF8 rendering mode
+- Add --stats switch to see timing data

data/bin/bri

@@ -20,12 +20,26 @@ def parse_options
     opts.separator "  * #instance_method_name"
     opts.separator "  * .class_method_name"
     opts.separator ""
-    opts.on( nil, "--classes", "List known classes" ) { |v| @options[:list_classes] = true }
-    opts.on( nil, "--methods", "List known methods" ) { |v| @options[:list_methods] = true }
-    opts.on( "-l", "--list-names", "List known namespaces/methods" ) { |v| @options[:list_names] = true }
-    opts.on( "-w", "--width [COLUMNS]", "Set the output width", Integer ) { |v| Bri.width = v.to_i - 8 }
-    opts.on( "-a", "--all", "Output all documentation for the term. Prefers core documents otherwise") { |v| @options[:show_all] = true }
-    opts.on_tail( "-h", "--help", "This help text" ) { puts opts; exit }
+    opts.on( nil, "--classes", "List known classes" ) do |v|
+      @options[:list_classes] = true
+    end
+    opts.on( nil, "--methods", "List known methods" ) do |v|
+      @options[:list_methods] = true
+    end
+    opts.on( "-l", "--list-names", "List known namespaces/methods" ) do |v|
+      @options[:list_names] = true
+    end
+    opts.on( "-w", "--width [COLUMNS]", "Set the output width", Integer ) do |v|
+      Bri.width = v.to_i - 8
+    end
+    opts.on( "-a", "--all", 
+            "Output gem documentation in addition to core documents" ) do |v|
+      @options[:show_all] = true
+    end
+    opts.on_tail( "-h", "--help", "This help text" ) do 
+      puts opts
+      exit
+    end
   end
   parser.parse!( ARGV )
 
@@ -45,5 +59,5 @@ elsif @options[:list_methods]
 elsif @options[:list_names]
   puts Bri.list_names
 else
-  puts Bri.ri( ARGV[0], show_all: @options[:show_all] )
+  puts Bri.ri( ARGV[0], @options )
 end

data/lib/bri.rb

@@ -1,6 +1,7 @@
 require 'erb'
 require 'term/ansicolor'
 
+require_relative 'bri/text_formatting_utils'
 require_relative 'bri/renderer'
 require_relative 'bri/mall'
 require_relative 'bri/matcher'
@@ -11,22 +12,24 @@ require_relative 'bri/match'
 module Bri
   DEFAULT_WIDTH = 72
 
-  def self.ri( query, show_all: false )
+  def self.ri( query, options )
+    if options[:show_all]
+      Bri::Mall.ri_paths( system: true, site: true, home: true, gems: true )
+    else
+      Bri::Mall.ri_paths( system: true, site: true, home: true, gems: false )
+    end
+
     results = Bri::Matcher.new( query ).find
 
     if results.size == 0
       "No matching results found"
+
     elsif results.size == 1
       results.first.to_s
+
     elsif results.all? { |r| r.is_a?(Bri::Match::Class) }
-      if show_all
-        results.map(&:to_s)
-      else
-        gem_docs, core_docs = results.partition { |r| r.origin =~ %r{gem\b} }
-
-        docs_to_output = core_docs.empty? ? gem_docs : core_docs
-        docs_to_output.map(&:to_s)
-      end
+      results.map(&:to_s)
+
     else
       qualified_methods = results.map(&:full_name).sort
       ERB.new( Bri::Templates::MULTIPLE_CHOICES, nil, '<>' ).result( binding )
@@ -47,18 +50,18 @@ module Bri
   end
 
   def self.list_classes
-    Bri::Mall.instance.classes.join("\n" )
+    Bri::Mall.classes.join("\n" )
   end
 
   def self.list_methods
-    ( Bri::Mall.instance.instance_methods + 
-      Bri::Mall.instance.class_methods ).sort.join( "\n" )
+    ( Bri::Mall.instance_methods + 
+      Bri::Mall.class_methods ).sort.join( "\n" )
   end
 
   def self.list_names
-    ( Bri::Mall.instance.classes +
-      Bri::Mall.instance.instance_methods +
-      Bri::Mall.instance.class_methods ).sort.join( "\n" )
+    ( Bri::Mall.classes +
+      Bri::Mall.instance_methods +
+      Bri::Mall.class_methods ).sort.join( "\n" )
   end
 
 end

data/lib/bri/mall.rb

@@ -1,18 +1,24 @@
 require 'rdoc/ri/paths'
 require 'rdoc/ri/store'
-require 'singleton'
 
 module Bri
   class Mall
-    include Singleton
 
-    attr_reader :stores
+    def self.ri_paths( system: true, site: true, home: true, gems: true )
+      @ri_paths ||= RDoc::RI::Paths.each( system, site, home, gems )
+    end
+
+    def self.stores
+      @stores ||= ri_paths.each_with_object( [] ) do |(path, type), stores|
+                    stores << RDoc::Store.new( path, type ).tap { |store| store.load_cache }
+                  end
+    end
 
-    def classes
+    def self.classes
       stores.flat_map(&:module_names).uniq.sort
     end
 
-    def class_methods
+    def self.class_methods
       stores.each_with_object( [] ) do |store, result|
         store.class_methods.each do |klass, methods|
           methods.each { |method| result << "#{klass}.#{method}" }
@@ -20,20 +26,12 @@ module Bri
       end.uniq
     end
 
-    def instance_methods
+    def self.instance_methods
       stores.each_with_object( [] ) do |store, result|
         store.instance_methods.each do |klass, methods|
           methods.each { |method| result << "#{klass}##{method}" }
         end
       end.uniq
     end
-
-    private
-    def initialize
-      # We want: system, site, home and gem documentation
-      @stores = RDoc::RI::Paths.each( true, true, true, true ).each_with_object( [] ) do |(path, type), stores|
-                  stores << RDoc::Store.new( path, type ).tap { |store| store.load_cache }
-                end
-    end
   end
 end

data/lib/bri/match/base.rb

@@ -8,7 +8,7 @@ module Bri
 
       private 
       def build_description( source )
-        source.map { |element| Bri::Renderer.render( element ) }.compact
+        source.map { |element| Bri::Renderer.new( element ).render }.compact.map(&:output)
       end
     end
   end

data/lib/bri/match/class.rb

@@ -4,7 +4,11 @@ require 'rdoc/markup/paragraph'
 module Bri
   module Match
     class Class < Base
-      include Bri::Templates::Helpers
+      # FIXME This should not be part of this class; the template may need 
+      #       a modiified binding.
+      #
+      include Bri::TextFormattingUtils  
+
       TEMPLATE = Bri::Templates::CLASS_DESCRIPTION
 
       attr_reader :type, :name, :description_paragraphs,

data/lib/bri/match/method.rb

@@ -1,7 +1,8 @@
 module Bri
   module Match
     class Method < Base
-      include Bri::Templates::Helpers
+      include Bri::TextFormattingUtils
+
       TEMPLATE = Bri::Templates::METHOD_DESCRIPTION
 
       attr_accessor :full_name, :call_syntaxes, :description_paragraphs, :origin

data/lib/bri/renderer.rb

@@ -1,195 +1,35 @@
 require 'strscan'
+require 'rdoc'
+require 'rdoc/markup'
+
+require_relative 'renderer/default'
+require_relative 'renderer/blank_line'
+require_relative 'renderer/document'
+require_relative 'renderer/heading'
+require_relative 'renderer/list_item'
+require_relative 'renderer/list'
+require_relative 'renderer/paragraph'
+require_relative 'renderer/rule'
+require_relative 'renderer/verbatim'
+require_relative 'renderer/result'
 
 module Bri
   module Renderer
-    Color = ::Term::ANSIColor
-
-    INDENT = ' ' * 2
-    INDENT_WIDTH = 2
-    LOWER_ALPHABET = ('a'..'z').to_a.map { |char| "#{char}." }.freeze
-    UPPER_ALPHABET = ('A'..'Z').to_a.map { |char| "#{char}." }.freeze
-
-    def self.render( element, width = Bri.width, alignment_width = 0 )
-      case element
-        when RDoc::Markup::Verbatim 
-          text = extract_text( element, width )
-          styled_text = replace_markup( text )
-          "#{indent( styled_text )}\n"
-
-        when RDoc::Markup::List
-          item_width = width - INDENT_WIDTH
-          case element.type
-            when :BULLET 
-              rendered_items = element.items.map { |item| render( item, item_width ) }
-              rendered_items.map! { |item| item.gsub( /\n/, "\n#{INDENT}" ) }
-              rendered_items.map! { |item| item.prepend( ' *' ) }
-
-            when :NUMBER
-              rendered_items = element.items.map { |item| render( item, item_width ) }
-              rendered_items.map! { |item| item.gsub( /\n/, "\n#{INDENT}" ) }
-              rendered_items.map!.with_index( 1 ) { |item, i| item.prepend( "#{i}." ) }
-
-            when :LALPHA
-              rendered_items = element.items.map { |item| render( item, item_width ) }
-              rendered_items.map! { |item| item.gsub( /\n/, "\n#{INDENT}" ) }
-              rendered_items.map!.with_index { |item, i| item.prepend( LOWER_ALPHABET[i] ) }
-
-            when :UALPHA
-              rendered_items = element.items.map { |item| render( item, item_width ) }
-              rendered_items.map! { |item| item.gsub( /\n/, "\n#{INDENT}" ) }
-              rendered_items.map!.with_index { |item, index| item.prepend( UPPER_ALPHABET[i] ) }
-              
-            when :LABEL
-              # do nothing
-              rendered_items = element.items.map { |item| render( item, item_width ) }
-              rendered_items.map! { |item| item.gsub( /\n/, "\n#{INDENT}" ) }
-
-            when :NOTE
-              alignment_width = element.items.flat_map(&:label).map(&:size).max + 1
-              rendered_items = element.items.map { |item| render( item, item_width, alignment_width ) }
-              rendered_items.map! { |item| item.gsub( /\n/, "\n#{INDENT}" ) }
-          end
-
-          "#{rendered_items.join( "\n" )}\n"
-
-        else
-          text = extract_text( element, width, alignment_width )
-
-          if text == "\n"
-            nil
-          else
-            styled_text = replace_markup( text )
-            wrapped_text = wrap_to_width( styled_text, width )
-            indent( wrapped_text )
-          end
-      end
-    end
-
-    def self.extract_text( element, width, label_alignment_width = 0, conserve_newlines = false )
-      case element
-        when RDoc::Markup::Paragraph
-          join_char = conserve_newlines ? "\n" : " "
-          element.parts.map(&:strip).join( join_char ) + "\n"
-
-        when RDoc::Markup::BlankLine
-          "\n"
-
-        when RDoc::Markup::Rule
-          "-" * width + "\n"
-
-        when RDoc::Markup::Verbatim
-          element.parts.map { |part| part.prepend( "  " ) }.join + "\n"
-
-        when RDoc::Markup::Heading
-          "<h>#{element.text}</h>\n" 
-
-        when RDoc::Markup::ListItem
-          parts = element.parts.map { |part| extract_text( part, width, 0, true ) }.join
-
-          if element.label
-            labels = element.label.map { |l| "#{l}:" }.join("\n")
-            sprintf( "%*s %s", -label_alignment_width, labels, parts )
-          else
-            parts
-          end
-
-        when RDoc::Markup::List
-          render( element, width - INDENT_WIDTH ) + "\n"
-
-         when RDoc::Markup::Document
-           element.parts.
-                   map { |part| extract_text( part, width, label_alignment_width, conserve_newlines ) }.
-                   join + "\n"
-        else  
-          raise "Don't know how to handle type #{element.class}: #{element.inspect}"
-      end
-    end
-
-    def self.replace_markup( text )
-      text.gsub!( /(?<!\\)<(?:tt|code)>/, Color.cyan )
-      text.gsub!( /(?<!\\)<\/(?:tt|code)>/, Color.reset )
-
-      text.gsub!( /(?<!\\)<b>/, Color.bold )
-      text.gsub!( /(?<!\\)<\/b>/, Color.reset )
-
-      text.gsub!( /(?<!\\)<(?:em|i)>/, Color.yellow )
-      text.gsub!( /(?<!\\)<\/(?:em|i)>/, Color.reset )
-
-      text.gsub!( "<h>", Color.green )
-      text.gsub!( "</h>", Color.reset )
-
-      text.gsub!( "\\<", "<" )
-
-      text.gsub!( /(#\s*=>)(.*)/,
-                  "#{Color.dark}\\1#{Color.reset}#{Color.bold}\\2#{Color.reset}" )
-
-      text.gsub!( /(^|\s)\*(.*?[a-zA-Z0-9]+.*?)\*/, 
-                  "\\1#{Color.bold}\\2#{Color.reset}" )
-      text.gsub!( /(^|\s)\+(.*?[a-zA-Z0-9]+.*?)\+/, 
-                  "\\1#{Color.cyan}\\2#{Color.reset}" )
-      text.gsub!( /(^|\s)_(.*?[a-zA-Z0-9]+.*?)_/, 
-                  "\\1#{Color.yellow}\\2#{Color.reset}" )
-
-      text.gsub!( %r{\b((?:https?|ftp)://[-\w.?%&=/]+)\b}, 
-                  "#{Color.underline}\\1#{Color.reset}" )
-
-      text.gsub!( %r{\b(mailto:[-\w.%]+@[-\w.]+)\b}, 
-                  "#{Color.underline}\\1#{Color.reset}" )
-
-      text.gsub!( %r{\b((?<!:\/\/)www.[-\w.?%&=]+)\b}, 
-                  "#{Color.underline}\\1#{Color.reset}" )
-
-      text.gsub!( %r{\blink:(.*?)(\s|$)}, 
-                  "#{Color.underline}\\1#{Color.reset}\\2" )
-
-      text.gsub!( %r{\{(.*?)\}\[(.*?)\]}, "\\1 (\\2)" )
-      text.gsub!( %r{\[(#{Regexp.escape( Color.underline )}.*?#{Regexp.escape( Color.reset )})\]}, 
-                  " (\\1)" )
-      text
-    end
-
-    def self.printable_length( text )
-      Term::ANSIColor.uncolored( text ).length
-    end
-
-    def self.wrap_list( array, width = Bri.width )
-      indent( wrap_to_width( array.join("  "), width ) )
-    end
-
-    def self.wrap_to_width( styled_text, width )
-      styled_text.split( "\n" ).map { |row| wrap_row( row, width ) }.join
-    end
-
-    def self.wrap_row( physical_row, width )
-      output_text = ''
-      logical_row = ''
-      printable_row_length = 0
-
-      scanner = StringScanner.new( physical_row )
-
-      while( !scanner.eos? ) 
-        token = scanner.scan( /\S+/ ).to_s
-        printable_token_length = printable_length( token )
-
-        if printable_token_length + printable_row_length > width
-          output_text << logical_row << "\n"
-          logical_row = ''
-          printable_row_length = 0
-        end
-
-        logical_row << token
-        printable_row_length += printable_token_length
-
-        token = scanner.scan( /\s*/ ).to_s
-        logical_row << token
-        printable_row_length += token.length
-      end
-
-      output_text << logical_row << "\n"
-    end
-
-    def self.indent( text )
-      text.split( "\n" ).map { |row| "#{INDENT}#{row}" }.join("\n" )
+    RDOC_TO_BRI_RENDERER_CLASS_MAP = {
+      ::RDoc::Markup::Document  => ::Bri::Renderer::Document,
+      ::RDoc::Markup::Paragraph => ::Bri::Renderer::Paragraph,
+      ::RDoc::Markup::BlankLine => ::Bri::Renderer::BlankLine,
+      ::RDoc::Markup::Rule      => ::Bri::Renderer::Rule,
+      ::RDoc::Markup::Verbatim  => ::Bri::Renderer::Verbatim,
+      ::RDoc::Markup::Heading   => ::Bri::Renderer::Heading,
+      ::RDoc::Markup::ListItem  => ::Bri::Renderer::ListItem,
+      ::RDoc::Markup::List      => ::Bri::Renderer::List,
+    }
+    RDOC_TO_BRI_RENDERER_CLASS_MAP.default = ::Bri::Renderer::Default
+
+    def self.new( element )
+      renderer_class = RDOC_TO_BRI_RENDERER_CLASS_MAP[element.class]
+      renderer_class.new( element )
     end
   end
 end

data/lib/bri/renderer/blank_line.rb

@@ -0,0 +1,9 @@
+module Bri
+  module Renderer
+    class BlankLine < Default
+      def extract_text( width, conserve_newlines = false )
+        "\n"
+      end
+    end
+  end
+end