/tools/Ruby/lib/ruby/1.8/rdoc/ri/ri_display.rb

  1require 'rdoc/ri/ri_util'
  2require 'rdoc/ri/ri_formatter'
  3require 'rdoc/ri/ri_options'
  4
  5
  6# This is a kind of 'flag' module. If you want to write your
  7# own 'ri' display module (perhaps because you'r writing
  8# an IDE or somesuch beast), you simply write a class
  9# which implements the various 'display' methods in 'DefaultDisplay',
 10# and include the 'RiDisplay' module in that class. 
 11#
 12# To access your class from the command line, you can do
 13#
 14#    ruby -r <your source file>  ../ri ....
 15#
 16# If folks _really_ want to do this from the command line,
 17# I'll build an option in
 18
 19module RiDisplay
 20  @@display_class = nil
 21
 22  def RiDisplay.append_features(display_class)
 23    @@display_class = display_class
 24  end
 25
 26  def RiDisplay.new(*args)
 27    @@display_class.new(*args)
 28  end
 29end
 30
 31######################################################################
 32#
 33# A paging display module. Uses the ri_formatter class to do the
 34# actual presentation
 35#
 36
 37class  DefaultDisplay
 38
 39  include RiDisplay
 40
 41  def initialize(options)
 42    @options = options
 43    @formatter = @options.formatter.new(@options, "     ")
 44  end    
 45  
 46  
 47  ######################################################################
 48  
 49  def display_usage
 50    page do
 51      RI::Options::OptionList.usage(short_form=true)
 52    end
 53  end
 54
 55
 56  ######################################################################
 57  
 58  def display_method_info(method)
 59    page do
 60      @formatter.draw_line(method.full_name)
 61      display_params(method)
 62      @formatter.draw_line
 63      display_flow(method.comment)
 64      if method.aliases && !method.aliases.empty?
 65        @formatter.blankline
 66        aka = "(also known as "
 67        aka << method.aliases.map {|a| a.name }.join(", ") 
 68        aka << ")"
 69        @formatter.wrap(aka)
 70      end
 71    end
 72  end
 73  
 74  ######################################################################
 75  
 76  def display_class_info(klass, ri_reader)
 77    page do 
 78      superclass = klass.superclass_string
 79      
 80      if superclass
 81        superclass = " < " + superclass
 82      else
 83        superclass = ""
 84      end
 85      
 86      @formatter.draw_line(klass.display_name + ": " +
 87                           klass.full_name + superclass)
 88      
 89      display_flow(klass.comment)
 90      @formatter.draw_line 
 91    
 92      unless klass.includes.empty?
 93        @formatter.blankline
 94        @formatter.display_heading("Includes:", 2, "")
 95        incs = []
 96        klass.includes.each do |inc|
 97          inc_desc = ri_reader.find_class_by_name(inc.name)
 98          if inc_desc
 99            str = inc.name + "("
100            str << inc_desc.instance_methods.map{|m| m.name}.join(", ")
101            str << ")"
102            incs << str
103          else
104            incs << inc.name
105          end
106      end
107        @formatter.wrap(incs.sort.join(', '))
108      end
109      
110      unless klass.constants.empty?
111        @formatter.blankline
112        @formatter.display_heading("Constants:", 2, "")
113        len = 0
114        klass.constants.each { |c| len = c.name.length if c.name.length > len }
115        len += 2
116        klass.constants.each do |c|
117          @formatter.wrap(c.value, 
118                          @formatter.indent+((c.name+":").ljust(len)))
119        end 
120      end
121      
122      unless klass.class_methods.empty?
123        @formatter.blankline
124        @formatter.display_heading("Class methods:", 2, "")
125        @formatter.wrap(klass.class_methods.map{|m| m.name}.sort.join(', '))
126      end
127      
128      unless klass.instance_methods.empty?
129        @formatter.blankline
130        @formatter.display_heading("Instance methods:", 2, "")
131        @formatter.wrap(klass.instance_methods.map{|m| m.name}.sort.join(', '))
132      end
133      
134      unless klass.attributes.empty?
135        @formatter.blankline
136        @formatter.wrap("Attributes:", "")
137        @formatter.wrap(klass.attributes.map{|a| a.name}.sort.join(', '))
138      end
139    end
140  end
141  
142  ######################################################################
143  
144  # Display a list of method names
145  
146  def display_method_list(methods)
147    page do
148      puts "More than one method matched your request. You can refine"
149      puts "your search by asking for information on one of:\n\n"
150      @formatter.wrap(methods.map {|m| m.full_name} .join(", "))
151    end
152  end
153  
154  ######################################################################
155  
156  def display_class_list(namespaces)
157    page do
158      puts "More than one class or module matched your request. You can refine"
159      puts "your search by asking for information on one of:\n\n"
160      @formatter.wrap(namespaces.map {|m| m.full_name}.join(", "))
161    end
162  end
163  
164  ######################################################################
165
166  def list_known_classes(classes)
167    if classes.empty?
168      warn_no_database
169    else
170      page do 
171        @formatter.draw_line("Known classes and modules")
172        @formatter.blankline
173        @formatter.wrap(classes.sort.join(", "))
174      end
175    end
176  end
177
178  ######################################################################
179
180  def list_known_names(names)
181    if names.empty?
182      warn_no_database
183    else
184      page do 
185        names.each {|n| @formatter.raw_print_line(n)}
186      end
187    end
188  end
189
190  ######################################################################
191
192  private
193
194  ######################################################################
195
196  def page
197    return yield unless pager = setup_pager
198    begin
199      save_stdout = STDOUT.clone
200      STDOUT.reopen(pager)
201      yield
202    ensure
203      STDOUT.reopen(save_stdout)
204      save_stdout.close
205      pager.close
206    end
207  end
208
209  ######################################################################
210
211  def setup_pager
212    unless @options.use_stdout
213      for pager in [ ENV['PAGER'], "less", "more", 'pager' ].compact.uniq
214        return IO.popen(pager, "w") rescue nil
215      end
216      @options.use_stdout = true
217      nil
218    end
219  end
220
221  ######################################################################
222  
223  def display_params(method)
224
225    params = method.params
226
227    if params[0,1] == "("
228      if method.is_singleton
229        params = method.full_name + params
230      else
231        params = method.name + params
232      end
233    end
234    params.split(/\n/).each do |p|
235      @formatter.wrap(p) 
236      @formatter.break_to_newline
237    end
238  end
239  ######################################################################
240  
241  def display_flow(flow)
242    if !flow || flow.empty?
243      @formatter.wrap("(no description...)")
244    else
245      @formatter.display_flow(flow)
246    end
247  end
248
249  ######################################################################
250  
251  def warn_no_database
252    puts "Before using ri, you need to generate documentation"
253    puts "using 'rdoc' with the --ri option"
254  end
255end  # class RiDisplay