RubyGems - bri - Versions diffs - 0.1.5 → 0.2.0 - Mend

bri 0.1.5 → 0.2.0

Files changed (22) hide show

data/Changelog +14 -0
data/README +3 -3
data/TODO +4 -2
data/bin/bri +2 -1
data/lib/bri/mall.rb +2 -1
data/lib/bri/match/class.rb +1 -1
data/lib/bri/renderer.rb +55 -13
data/lib/bri/search/class_method.rb +2 -0
data/lib/bri/search/instance_method.rb +2 -0
data/lib/bri/search/method.rb +8 -2
data/lib/bri/templates.rb +1 -1
data/spec/bri_dummy_spec_class.rb +132 -0
data/spec/lib/bri/match/class_spec.rb +125 -0
data/spec/lib/bri/match/method_spec.rb +112 -0
data/spec/lib/bri/renderer_spec.rb +338 -0
data/spec/lib/bri/search/{class_method_search_spec.rb → class_method_spec.rb} +80 -0
data/spec/lib/bri/search/class_spec.rb +52 -19
data/spec/lib/bri/search/instance_method_spec.rb +81 -0
data/spec/spec_helper.rb +7 -1
metadata +8 -6
data/spec/lib/bri/match/class_match_spec.rb +0 -90
data/spec/lib/bri/match/method_match_spec.rb +0 -25

data/Changelog CHANGED

@@ -1,3 +1,17 @@
+0.2.0
+  - Add extensive specs for matching, searching and rendering
+  - Fix bug with rendering very narrow horizontal rules
+  - Fix bug with wrong color for +monospaced+ vs <tt>monospaced</tt> styles
+  - Recognize <tt> as an alias for <code>
+  - Recognize <i> as an alias for <em>
+  - Add ANSI bold sequences for *bold* and <b>bold</b> text
+  - Add recognition and styling of links
+  - Correctly indent the second and further parts of a list item
+  - Correctly display lettered lists
+  - Correctly display aligned labeled lists
+  - Allow escaping of \<html> tags
+  - Be more robust when missing encountering a missing ri file reference
 0.1.5
   - Fix rendering of nested lists
   - Fix highlighting of sequences of + and _ characters

data/README CHANGED

@@ -3,9 +3,9 @@ During the days of Ruby 1.8, the ri command was slow. I mean really slow. Glacia
 Then Mauricio Fernandez produced fastri and qri that produced results a whole lot faster than the native ri tool. Unfortunately, Mauricio seems to have lost interest and didn't port fastri to ruby 1.9. There are patches porting fastri to 1.9.1, but they are iffy and don't work well with 1.9.2 and the new rdoc cache format.
-Now with ruby 1.9 and the rdoc 2.x gem ri is very responsive. However the output format looks like darkfish without the HTML and uses up a lot of space. And subjectively, it's ugly.
+Now with ruby 1.9 and the rdoc 2.x/3.x gem ri is very responsive. However the output format looks like darkfish without the HTML and uses up a lot of space. And subjectively, it's ugly.
-This is where bri comes in: it tries to emulate fastri/qris output format and lookup patterns while using the new rdoc 2.x infrastructure.
+This is where bri comes in: it tries to emulate fastri/qris output format and lookup patterns while using the new rdoc 2.x/3.x infrastructure.
 To compare, do 'ri Array' and 'bri Array' and see which appeals more to you.
@@ -31,7 +31,7 @@ Bri is a Beautiful RI formatter.
 = Requirements
  * Ruby 1.9.2
- * rdoc 2.5.x
+ * rdoc 3.5.3 and above
  * term-ansicolor

data/TODO CHANGED

@@ -1,3 +1,5 @@
 - Extend unqualified search to include class methods and case insensitive searches
-- Misc. error handlings
-- Do more specs
+- {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?

data/bin/bri CHANGED

@@ -27,7 +27,8 @@ def parse_options
   end
   parser.parse!( ARGV )
-  if ARGV.size == 0
+  if ARGV.size == 0 &&
+    !( @options[:list_classes] || @options[:list_methods] || @options[:list_names] )
     puts parser.summarize
     exit 0
   end

data/lib/bri/mall.rb CHANGED

@@ -34,7 +34,8 @@ module Bri
       # We want: system, site, home and gem documentation
       RDoc::RI::Paths.each( true, true, true, true ) do |path, type|
-        @stores << RDoc::RI::Store.new( path, type ).tap { |store| store.load_cache }
+        @stores << RDoc::RI::Store.new( path, type ).
+                                   tap { |store| store.load_cache }
       end
     end

data/lib/bri/match/class.rb CHANGED

@@ -13,7 +13,7 @@ module Bri
       def initialize( rdoc_result )
         @type = rdoc_result.type
-        @name = rdoc_result.name
+        @name = rdoc_result.full_name
         @description_paragraphs = build_description( rdoc_result.comment.parts )
         @includes = rdoc_result.includes.collect { |i| i.full_name }
         @constants = rdoc_result.constants.collect do |c|

data/lib/bri/renderer.rb CHANGED

@@ -3,8 +3,10 @@ require 'strscan'
 module Bri
   module Renderer
     INDENT = ' ' * 2
+    ALPHABET = ('a'..'z').to_a
-    def self.render( element, width = Bri.width )
+    def self.render( element, width = Bri.width, alignment_width = 0 )
+      # STDERR.puts "Rendering #{element.inspect}"
       case element
         when RDoc::Markup::Verbatim
           text = extract_text( element, width )
@@ -13,32 +15,49 @@ module Bri
         when RDoc::Markup::List
           item_width = width - INDENT.length
-          rendered_items = element.items.collect { |item| render item, item_width }
-          rendered_items.map! { |item| item.gsub( /\n/, "\n#{INDENT}" ) }
           case element.type
             when :BULLET
+              rendered_items = element.items.collect { |item| render item, item_width }
+              rendered_items.map! { |item| item.gsub( /\n/, "\n#{INDENT}" ) }
               rendered_items.map! { |item| ' *' + item }
             when :NUMBER
               i = 0
+              rendered_items = element.items.collect { |item| render item, item_width }
+              rendered_items.map! { |item| item.gsub( /\n/, "\n#{INDENT}" ) }
               rendered_items.map! { |item| i+=1; sprintf "%d.%s", i, item }
-            when :NOTE, :LABEL
+            when :LALPHA
+              i = -1
+              rendered_items = element.items.collect { |item| render item, item_width }
+              rendered_items.map! { |item| item.gsub( /\n/, "\n#{INDENT}" ) }
+              rendered_items.map! { |item| i+=1; sprintf "%s.%s", ALPHABET[i], item }
+            when :LABEL
               # do nothing
+              rendered_items = element.items.collect { |item| render item, item_width }
+              rendered_items.map! { |item| item.gsub( /\n/, "\n#{INDENT}" ) }
+            when :NOTE
+              alignment_width = element.items.collect { |item| item.label.size }.max + 1
+              rendered_items = element.items.collect { |item| render item, item_width, alignment_width }
+              rendered_items.map! { |item| item.gsub( /\n/, "\n#{INDENT}" ) }
           end
           rendered_items.join( "\n\n" ) + "\n"
         else
-          text = extract_text( element, width )
+          text = extract_text( element, width, alignment_width )
           styled_text = replace_markup( text )
           wrapped_text = wrap_to_width( styled_text, width )
           indent( wrapped_text )
       end
     end
-    def self.extract_text( element, width )
+    def self.extract_text( element, width, label_alignment_width = 0 )
       text = case element
                when RDoc::Markup::Paragraph
-                 element.text
+                 element.parts.join( "\n" )
                when RDoc::Markup::BlankLine
                  ""
                when RDoc::Markup::Rule
@@ -49,7 +68,7 @@ module Bri
                  "<h>#{element.text}</h>"
                when RDoc::Markup::ListItem
                  parts = element.parts.collect { |part| extract_text part, width }.join
-                 element.label ? "#{element.label}: #{parts}" : parts
+                 element.label ? sprintf( "%*s %s", -label_alignment_width, "#{element.label}:", parts ) : parts
                when RDoc::Markup::List
                  render( element, width - INDENT.length )
                else
@@ -59,19 +78,42 @@ module Bri
     end
     def self.replace_markup( text )
-      text.gsub!( "<tt>", Term::ANSIColor::cyan )
-      text.gsub!( "</tt>", Term::ANSIColor::reset )
+      text.gsub!( /(?<!\\)<(?:tt|code)>/, Term::ANSIColor::cyan )
+      text.gsub!( /(?<!\\)<\/(?:tt|code)>/, Term::ANSIColor::reset )
+      text.gsub!( /(?<!\\)<b>/, Term::ANSIColor::bold )
+      text.gsub!( /(?<!\\)<\/b>/, Term::ANSIColor::reset )
-      text.gsub!( "<code>", Term::ANSIColor::cyan )
-      text.gsub!( "</code>", Term::ANSIColor::reset )
+      text.gsub!( /(?<!\\)<(?:em|i)>/, Term::ANSIColor::yellow )
+      text.gsub!( /(?<!\\)<\/(?:em|i)>/, Term::ANSIColor::reset )
       text.gsub!( "<h>", Term::ANSIColor::green )
       text.gsub!( "</h>", Term::ANSIColor::reset )
+      text.gsub!( "\\<", "<" )
+      text.gsub!( /(^|\s)\*(.*?[a-zA-Z0-9]+.*?)\*/,
+                  "\\1#{Term::ANSIColor::bold}\\2#{Term::ANSIColor::reset}" )
       text.gsub!( /(^|\s)\+(.*?[a-zA-Z0-9]+.*?)\+/,
-                  "\\1#{Term::ANSIColor::yellow}\\2#{Term::ANSIColor::reset}" )
+                  "\\1#{Term::ANSIColor::cyan}\\2#{Term::ANSIColor::reset}" )
       text.gsub!( /(^|\s)_(.*?[a-zA-Z0-9]+.*?)_/,
                   "\\1#{Term::ANSIColor::yellow}\\2#{Term::ANSIColor::reset}" )
+      text.gsub!( %r{\b((?:https?|ftp)://[-\w.?%&=/]+)\b},
+                  "#{Term::ANSIColor::underline}\\1#{Term::ANSIColor::reset}" )
+      text.gsub!( %r{\b(mailto:[-\w.%]+@[-\w.]+)\b},
+                  "#{Term::ANSIColor::underline}\\1#{Term::ANSIColor::reset}" )
+      text.gsub!( %r{\b((?<!:\/\/)www.[-\w.?%&=]+)\b},
+                  "#{Term::ANSIColor::underline}\\1#{Term::ANSIColor::reset}" )
+      text.gsub!( %r{\blink:(.*?)(\s|$)},
+                  "#{Term::ANSIColor::underline}\\1#{Term::ANSIColor::reset}\\2" )
+      text.gsub!( %r{\{(.*?)\}\[(.*?)\]}, "\\1 (\\2)" )
+      text.gsub!( %r{\[(#{Regexp.escape( Term::ANSIColor::underline )}.*?#{Regexp.escape( Term::ANSIColor::reset )})\]},
+                  " (\\1)" )
       text
     end

data/lib/bri/search/class_method.rb CHANGED

@@ -8,6 +8,8 @@ module Bri
       def method_rdoc( store, klass = @class_term, method = @method_term )
         store.load_method( klass, method )
+      rescue Errno::ENOENT
+        nil
       end
     end
   end

data/lib/bri/search/instance_method.rb CHANGED

@@ -8,6 +8,8 @@ module Bri
       def method_rdoc( store, klass = @class_term, method = @method_term )
         store.load_method( klass, "#" + method )
+      rescue Errno::ENOENT
+        nil
       end
     end
   end

data/lib/bri/search/method.rb CHANGED

@@ -55,7 +55,10 @@ module Bri
       def partially_qualified_search
         Bri::Mall.instance.stores.each do |store|
           classes_with_method( store, @method_term ).each do |klass|
-            @matches << Bri::Match::Method.new( method_rdoc( store, klass, @method_term ) )
+            match_data = method_rdoc( store, klass, @method_term )
+            next unless match_data
+            @matches << Bri::Match::Method.new( match_data )
           end
         end
       end
@@ -73,7 +76,10 @@ module Bri
         Bri::Mall.instance.stores.each do |store|
           candidates_from_method_re( store, method_re ).each do |klass, methods|
             methods.each do |method|
-              @matches << Bri::Match::Method.new( method_rdoc( store, klass, method ) )
+              match_data = method_rdoc( store, klass, method )
+              next unless match_data
+              @matches << Bri::Match::Method.new( match_data )
             end
           end
         end

data/lib/bri/templates.rb CHANGED

@@ -68,7 +68,7 @@ module Bri
           '-' * width + "\n"
         else
           text = " " + text if text != ''
-          '-' * ( width - text.length ) + Term::ANSIColor::bold( text ) + "\n"
+          ( '-' * [ ( width - text.length ), 1 ].max ) + Term::ANSIColor::bold( text ) + "\n"
         end
       end
       module_function :hrule

data/spec/bri_dummy_spec_class.rb ADDED

@@ -0,0 +1,132 @@
+# This is a class description
+class BriDummySpecClassTwo
+  include BriDummySpecModule
+  extend BriDummySpecModuleTwo
+  CONSTANT = 'value'
+  OTHER_CONSTANT = nil
+  attr_reader :read_attr
+  attr_writer :write_attr
+  attr_accessor :access_attr
+  def self.bri_dummy_spec_second_singleton_method; end
+  def bri_dummy_spec_instance_method_with_arguments( a, b ); end
+end
+class BriDummySpecClassEmpty; end
+module BriDummySpecModule; end
+module BriDummySpecModuleTwo; end
+module BriDummySpec
+  class Class; end
+end
+class BriDummySpecClass
+  def self.bri_dummy_spec_singleton_method; end
+  def self.bri_dummy_spec_second_singleton_method; end
+  def bri_dummy_spec_instance_method; end
+  def bri_dummy_spec_instance_method_with_arguments( a, b ); end
+  def bri_dummy_spec_instance_method_with_default_arguments( a, b, c = nil ); end
+  def bri_dummy_spec_instance_method_which_yields
+    yield yield_param_one, yield_param_two
+  end
+  def bri_dummy_spec_instance_method_with_yield_override # :yields: foo, bar
+    yield yield_param_one, yield_param_two
+  end
+  # = This is a headline
+  #
+  # Followed by some introduction text.
+  def basic_headline_and_paragraph_rendering_test_method; end
+  # == This is a level two headline
+  # This is a paragraph with a really really really really really really really really really really long line that needs to be wrapped.
+  def level_two_headline_and_line_wrapping_rendering_test_method; end
+  # This is some text before a horizontal rule.
+  # ---
+  # After a horizontal rule, the text continues.
+  def horizontal_rule_rendering_test_method; end
+  # * First item in a bulleted list
+  #   With a second line
+  # * Second item in a bulleted list
+  #   * First item of a nested bulleted list
+  #   * Second item of a nested bulleted list
+  # * Ending a bulleted list with a really really really really really really really really long line that needs to be wrapped
+  def bulleted_list_rendering_test_method; end
+  # - A second bulleted list
+  # - Second item in second bulleted list
+  #   - Nested bulleted list
+  #   - Second nested bulleted list item
+  # - Ending the second bulleted list
+  def second_bulleted_list_rendering_test_method; end
+  # 1. First numbered list item
+  # 2. Second numbered list
+  #    1. Nested numbered list item
+  #    2. Second nested numbered list item
+  # 3. Ending the main numbered list item
+  def numbered_list_rendering_test_method; end
+  # a. Some goes for lettered lists
+  # b. Second item in a lettered list
+  #    a. And a nested lettered list item
+  #    c. Second nested lettered list item
+  # c. Ending the main lettered list item.
+  def lettered_list_rendering_test_method; end
+  # * A mixed list, containing
+  # * bullets in the main list
+  #   1. And numbers in a sublist
+  def mixed_list_rendering_test_method; end
+  # 1. Also in reverse
+  # 2. Second item
+  #    * Nested bulleted list
+  def second_mixed_list_rendering_test_method; end
+  # [First] And this is the list item body
+  #         With a second line containing more text
+  #
+  # [Second] Another labled list item
+  def labeled_list_rendering_test_method; end
+  # First:: With some text.
+  # Secondarily:: Lets see if this lines up.
+  def lined_up_labeled_list_rendering_test_method; end
+  # * a list item
+  #   with a long item text
+  #  Containing verbatim text
+  def list_containing_verbatim_text_rendering_test_method; end
+  # Text with stylings: *bold*, _emphasized_ and +monospaced+.
+  def simple_styling_rendering_test_method; end
+  # Also with html: <b>Bold</b>, <em>emphasized</em>, <i>also emphasized</i>
+  # and <tt>monospaced tt</tt> or <code>monospaced code</code>.
+  def html_styling_rendering_test_method; end
+  # These should not be styled: \<b>Not bold\</b>, \<em>not emphasized\</em>.
+  def escaped_styling_rendering_test_method; end
+  # Furthermore, this text contains links to raw links http://www.google.com mailto:spamidyspam@spam.com ftp://warez.teuto.de and plain web links: www.test.com .
+  #
+  # Then we have local links to other files: link:/etc/fstab
+  def raw_link_rendering_test_method; end
+  # Plus: Labled links SingleWordLabel[http://duckduckgo.com] and
+  # {Multi Word Labels}[http://www.github.com].
+  def labeled_link_rendering_test_method; end
+  # Conversion characters: this: -- or --- should be an em-dash. We also have an ellipsis: ... . Copyright: (c) and registered trademark (r).
+  def conversion_character_rendering_test_method; end
+end

data/spec/lib/bri/match/class_spec.rb ADDED

@@ -0,0 +1,125 @@
+require 'spec_helper'
+describe Bri::Match::Class do
+  let( :fully_developed_class ) do
+    search_instance = Bri::Search::Class.new( "BriDummySpecClassTwo" )
+    search_instance.search
+    search_instance.matches.first
+  end
+  let( :empty_class ) do
+    search_instance = Bri::Search::Class.new( "BriDummySpecClassEmpty" )
+    search_instance.search
+    search_instance.matches.first
+  end
+  let( :empty_module ) do
+    search_instance = Bri::Search::Class.new( "BriDummySpecModule" )
+    search_instance.search
+    search_instance.matches.first
+  end
+  let( :namespaced_class ) do
+    search_instance = Bri::Search::Class.new( "BriDummySpec::Class" )
+    search_instance.search
+    search_instance.matches.first
+  end
+  describe "#type" do
+    it "should be class for a class" do
+      empty_class.type.should == "class"
+    end
+    it "should be module for a module" do
+      empty_module.type.should == "module"
+    end
+  end
+  describe "#name" do
+    it "should contain the name of a class" do
+      empty_class.name.should == "BriDummySpecClassEmpty"
+    end
+    it "should contain the fully qualified name of a namespaced class" do
+      namespaced_class.name.should == "BriDummySpec::Class"
+    end
+  end
+  describe "#description_paragraphs" do
+    it "should be empty for an undocumented class" do
+      empty_class.description_paragraphs.should be_empty
+    end
+    it "should contain rendered text for a documented class" do
+      fully_developed_class.description_paragraphs.size.should == 1
+      fully_developed_class.description_paragraphs.first.should =~ /This is a class description/
+    end
+  end
+  describe "#includes" do
+    it "should be empty for a class without includes" do
+      empty_class.includes.should be_empty
+    end
+    it "should contain a list of includes for classes with includes" do
+      fully_developed_class.includes.size.should == 1
+      fully_developed_class.includes.should include( "BriDummySpecModule" )
+    end
+  end
+  describe "#constants" do
+    it "should be empty for a class without constants" do
+      empty_class.constants.should be_empty
+    end
+    it "should contain a list of constants for classes with constants" do
+      fully_developed_class.constants.size.should == 2
+      fully_developed_class.constants.should include( "CONSTANT" )
+      fully_developed_class.constants.should include( "OTHER_CONSTANT" )
+    end
+  end
+  describe "#attributes" do
+    it "should be empty for a class without attributes" do
+      empty_class.attributes.should be_empty
+    end
+    it "should contain a list of attributes for classes with attr_* declarations" do
+      fully_developed_class.attributes.should_not be_empty
+    end
+    it "should mark attr_readers as read only" do
+      fully_developed_class.attributes.should include( "read_attr (R)" )
+    end
+    it "should mark attr_writers as write only" do
+      fully_developed_class.attributes.should include( "write_attr (W)" )
+    end
+    it "should mark attr_accessors as read/writeable" do
+      fully_developed_class.attributes.should include( "access_attr (RW)" )
+    end
+  end
+  describe "#class_methods" do
+    it "should be empty for a class without class methods" do
+      empty_class.class_methods.should be_empty
+    end
+    it "should contain class methods for classes with class methods" do
+      fully_developed_class.class_methods.size.should == 1
+      fully_developed_class.class_methods.first.should == "bri_dummy_spec_second_singleton_method"
+    end
+  end
+  describe "#instance_methods" do
+    it "should be empty for a class without instance methods" do
+      empty_class.instance_methods.should be_empty
+    end
+    it "should contain class methods for classes with class methods" do
+      fully_developed_class.instance_methods.size.should == 1
+      fully_developed_class.instance_methods.first.should == "bri_dummy_spec_instance_method_with_arguments"
+    end
+  end
+end