bri 0.5.0 → 1.0.0.pre.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a88edaf5dc38f84306db04f904d1fb32859536587b7fa5ce84f3be687c5d1638
-  data.tar.gz: 1d8ace29c2676219311960e6729bc8b0e453ae00fd5a88294f809be65955024f
+  metadata.gz: 2a26dfbcd940347c2bf68246c1223702a30ae82cc6ff032fd9160f4f6cd2587f
+  data.tar.gz: ad88f5eb0b894300eb1f8073da1baf4444ebebd07aa992d772465044f1a6d444
 SHA512:
-  metadata.gz: 3e7eb14da6bd17fdff9e5db187fe086f9592dcb682c18e082248ab61ef37685fd81e16cbe49198fbf9446cf3eccb1ac5f163ba7da906ef1b67a38329cfdb3eb2
-  data.tar.gz: 91fef7322fd718245385929888a5dcf48616c07c247621d4e22f8369b625e77185969af70fff295bc1538c0bcb5b2651a716143d15b54ee8f830f71439bbe317
+  metadata.gz: c258a7980e40af727d7d543f70d14398df03019be7496116180d6c6812e5becbad29bde410d26983b49ec6617cbb477c73ed357ef18cf60e72ab362fce914ec1
+  data.tar.gz: 9cbe6dc1a11b9cc745ce75b8f602416dbba701bcb0a22f0c973d15375875cf23d67faa1b03836d63595752a189cbccacb4c6d943a0464a2ef616cf4254b2b6a0

data/Changelog

@@ -1,5 +1,3 @@
-0.5.0
-  - Update rdoc requirement to 6.13
 0.4.4
   - No longer display all found class/module documentation found. If core
   documentation is available, output only that, otherwise falls back to gem

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,13 +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( "-v", "--version", "0.5.0.beta1")
-    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 )
 
@@ -46,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/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,23 +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
-      options = RDoc::Options.new
-      @stores = RDoc::RI::Paths.each( true, true, true, true ).
-                                each_with_object( [] ) do |(path, type), stores|
-                  stores << RDoc::Store.new( options, path: path, type: type ).
-                                        tap { |store| store.load_cache }
-                end
-    end
   end
 end

data/lib/bri/match/base.rb

@@ -2,18 +2,13 @@ module Bri
   module Match
     class Base
       def to_s
-        ERB.new( self.class.const_get( :TEMPLATE ), trim_mode: '<>' ).
+        ERB.new( self.class.const_get( :TEMPLATE ), nil, '<>' ).
             result( binding )
       end
 
       private 
-      def build_description_from_comment( comment )
-        document = comment.instance_variable_get( :@document )
-        build_description( document.parts )
-      end
-
       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,
@@ -18,8 +22,7 @@ module Bri
         @type                   = rdoc_result.type
         @name                   = "#{rdoc_result.full_name}"
         @name                   << " < #{rdoc_result.superclass}" if @type == "class" && rdoc_result.superclass
-
-        @description_paragraphs = build_description_from_comment( rdoc_result.comment )
+        @description_paragraphs = build_description( rdoc_result.comment.parts )
         @includes               = rdoc_result.includes.map(&:full_name)
         @extends                = rdoc_result.extends.map(&:full_name)
         @attributes             = rdoc_result.attributes.map { |a| "#{a.name} (#{a.rw})" }

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
@@ -11,8 +12,7 @@ module Bri
         @call_syntaxes = rdoc_method.arglists.lines( chomp: true ).
                                               map { |e| e.prepend( "  " ) }.
                                               join( "\n" ) + "\n" rescue ''
-
-        @description_paragraphs = build_description_from_comment( rdoc_method.comment )
+        @description_paragraphs = build_description( rdoc_method.comment.parts )
         @origin = store&.friendly_path
       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

data/lib/bri/renderer/default.rb

@@ -0,0 +1,27 @@
+module Bri
+  module Renderer
+    class Default
+      include ::Bri::TextFormattingUtils
+
+      attr_reader :element
+
+      def initialize( element )
+        @element = element
+      end
+
+      def render( width = Bri.width )
+        text = extract_text( width )
+
+        if text.empty?
+          nil
+        else
+          ::Bri::Renderer::Result.new( text, width )
+        end
+      end
+
+      def extract_text( width, conserve_newslines = false )
+        raise "Don't know how to handle type #{element.class}: #{element.inspect}"
+      end
+    end
+  end
+end

data/lib/bri/renderer/document.rb

@@ -0,0 +1,11 @@
+module Bri
+  module Renderer
+    class Document < Default
+      def extract_text( width, conserve_newlines = false )
+         element.parts.
+                 map { |part| ::Bri::Renderer.new( part ).extract_text( width, conserve_newlines ) }.
+                 join
+      end
+    end
+  end
+end

data/lib/bri/renderer/heading.rb

@@ -0,0 +1,9 @@
+module Bri
+  module Renderer
+    class Heading < Default
+      def extract_text( width, conserve_newlines = false )
+        "<h>#{element.text.chomp}</h>" 
+      end
+    end
+  end
+end

data/lib/bri/renderer/list/base.rb

@@ -0,0 +1,18 @@
+module Bri
+  module Renderer
+    class List
+      class Base < ::Bri::Renderer::Default
+        def extract_text( width, conserve_newlines = false )
+          item_width = width - max_bullet_width
+          rendered_items = element.items.each_with_index.
+                                   map do |item, index|
+                                     bullet = next_bullet( item )
+                                     ::Bri::Renderer.new( item ).text( item_width, bullet )
+                                   end
+
+          rendered_items.join
+        end
+      end
+    end
+  end
+end

data/lib/bri/renderer/list/bullet.rb

@@ -0,0 +1,15 @@
+module Bri
+  module Renderer
+    class List
+      class Bullet < Base
+        def max_bullet_width
+          3
+        end
+
+        def next_bullet( item )
+          '* '
+        end
+      end
+    end
+  end
+end

data/lib/bri/renderer/list/labeled.rb

@@ -0,0 +1,15 @@
+module Bri
+  module Renderer
+    class List
+      class Labeled < Base
+        def max_bullet_width
+          @max_bullet_width ||= element.items.map(&:label).map(&:size).max
+        end
+
+        def next_bullet( item )
+          "#{item.label.first}: "
+        end
+      end
+    end
+  end
+end

data/lib/bri/renderer/list/lower_lettered.rb

@@ -0,0 +1,18 @@
+module Bri
+  module Renderer
+    class List
+      class LowerLettered < Base
+        def max_bullet_width
+          @max_bullet_width ||= ( Math.log10( element.items.size ) / Math.log10( 26 ) ).ceil + 3
+        end
+
+        def next_bullet( item )
+          @current_bullet ||= 'a'
+          result = "#{@current_bullet}. "
+          @current_bullet.succ!
+          result
+        end
+      end
+    end
+  end
+end

data/lib/bri/renderer/list/note.rb

@@ -0,0 +1,15 @@
+module Bri
+  module Renderer
+    class List
+      class Note < Base
+        def max_bullet_width
+          @max_bullet_width ||= element.items.flat_map(&:label).map(&:size).max
+        end
+
+        def next_bullet( item )
+          "#{item.label.first}:" + " " * (max_bullet_width - item.label.first.size + 1)
+        end
+      end
+    end
+  end
+end

data/lib/bri/renderer/list/numbered.rb

@@ -0,0 +1,18 @@
+module Bri
+  module Renderer
+    class List
+      class Numbered < Base
+        def next_bullet( item )
+          @current_bullet ||= '1'
+          result = "#{@current_bullet}. "
+          @current_bullet.succ!
+          result
+        end
+
+        def max_bullet_width
+          @max_bullet_width ||= Math.log10( element.items.size ).ceil + 3
+        end
+      end
+    end
+  end
+end

data/lib/bri/renderer/list/upper_lettered.rb

@@ -0,0 +1,18 @@
+module Bri
+  module Renderer
+    class List
+      class UpperLettered < Base
+        def max_bullet_width
+          @max_bullet_width ||= ( Math.log10( element.items.size ) / Math.log10( 26 ) ).ceil + 3
+        end
+
+        def next_bullet( item )
+          @current_bullet ||= 'A'
+          result = "#{@current_bullet}. "
+          @current_bullet.succ!
+          result
+        end
+      end
+    end
+  end
+end

data/lib/bri/renderer/list.rb

@@ -0,0 +1,24 @@
+module Bri
+  module Renderer
+    class List < Default
+      def self.new( element )
+        case element.type
+          when :BULLET then ::Bri::Renderer::List::Bullet.new( element )
+          when :NUMBER then ::Bri::Renderer::List::Numbered.new( element )
+          when :LALPHA then ::Bri::Renderer::List::LowerLettered.new( element )
+          when :UALPHA then ::Bri::Renderer::List::UpperLettered.new( element )
+          when :LABEL  then ::Bri::Renderer::List::Labeled.new( element )
+          when :NOTE   then ::Bri::Renderer::List::Note.new( element )
+        end
+      end
+    end
+  end
+end
+
+require_relative 'list/base'
+require_relative 'list/bullet'
+require_relative 'list/numbered'
+require_relative 'list/lower_lettered'
+require_relative 'list/upper_lettered'
+require_relative 'list/labeled'
+require_relative 'list/note'

data/lib/bri/renderer/list_item.rb

@@ -0,0 +1,24 @@
+module Bri
+  module Renderer
+    class ListItem < Default
+      def text( total_width, bullet )
+        element.parts.map.with_index do |part, index|
+          part_is_list = part.is_a?(RDoc::Markup::List)
+          first_line_indent = ( part_is_list || index > 0 ) ? bullet.size : 0
+          following_line_indent = bullet.size
+
+          text = ::Bri::Renderer.new( part ).extract_text( total_width, true )
+          text.prepend( bullet ) if index == 0 && !part_is_list
+          lines = text.lines
+
+          result = indent( lines.first, indent_depth: first_line_indent )
+          lines.drop( 1 ).each do |line|
+            result << indent( line, indent_depth: following_line_indent )
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/bri/renderer/paragraph.rb

@@ -0,0 +1,11 @@
+module Bri
+  module Renderer
+    class Paragraph < Default
+      def extract_text( width, conserve_newlines = false )
+        join_char = conserve_newlines ? "\n" : " "
+        intermediate = element.parts.map(&:strip).join( join_char )
+        wrap_to_width( intermediate, width )
+      end
+    end
+  end
+end

data/lib/bri/renderer/result.rb

@@ -0,0 +1,73 @@
+module Bri
+  module Renderer
+    class Result
+      include ::Bri::TextFormattingUtils
+
+      Color = ::Term::ANSIColor
+
+      attr_reader :input, :width
+
+      def initialize(input, width )
+        @input = input
+        @width = width
+      end
+
+      def output
+        return @output if instance_variable_defined?( :@output )
+
+        @output = replace_markup( input ).
+                  then { |styled_text| width ? wrap_to_width( styled_text, width ) : styled_text }.
+                  then { |wrapped_text| indent( wrapped_text ) }
+      end
+
+      def concat( other )
+        output.concat( other.output )
+      end
+
+      private
+
+      def 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{\{(.*?)\}\[(.*?)\]}m, "\\1 (\\2)" )
+        text.gsub!( %r{\[(#{Regexp.escape( Color.underline )}.*?#{Regexp.escape( Color.reset )})\]}, 
+                    " (\\1)" )
+        text
+      end
+    end
+  end
+end

data/lib/bri/renderer/rule.rb

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

data/lib/bri/renderer/verbatim.rb

@@ -0,0 +1,14 @@
+module Bri
+  module Renderer
+    class Verbatim < Default
+      def render( width = Bri.width )
+        text = ::Bri::Renderer.new( element ).extract_text( width )
+        ::Bri::Renderer::Result.new( "#{text}\n", nil )
+      end
+
+      def extract_text( width, conserve_newlines = false )
+        element.parts.map { |part| indent(part) }.join + "\n"
+      end
+    end
+  end
+end