Class: RDoc::RI::Driver

Inherits:
Object
  • Object
show all
Defined in:
lib/rdoc/ri/driver.rb

Overview

The RI driver implements the command-line ri tool.

The driver supports:

  • loading RI data from:

    • Ruby’s standard library

    • RubyGems

    • ~/.rdoc

    • A user-supplied directory

  • Paging output (uses RI_PAGER environment variable, PAGER environment variable or the less, more and pager programs)

  • Interactive mode with tab-completion

  • Abbreviated names (ri Zl shows Zlib documentation)

  • Colorized output

  • Merging output from multiple RI data sources

Defined Under Namespace

Classes: Error, NotFoundError

Constant Summary collapse

RDOC_REFS_REGEXP = 
/\[rdoc-ref:([\w.]+)(@.*)?\]/

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(initial_options = {}) ⇒ Driver

Creates a new driver using initial_options from ::process_args



402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
 
# File 'lib/rdoc/ri/driver.rb', line 402

def initialize initial_options = {}
  @paging = false
  @classes = nil

  options = self.class.default_options.update(initial_options)

  @formatter_klass = options[:formatter]

  require 'profile' if options[:profile]

  @names = options[:names]
  @list = options[:list]

  @doc_dirs = []
  @stores   = []

  RDoc::RI::Paths.each(options[:use_system], options[:use_site],
                       options[:use_home], options[:use_gems],
                       *options[:extra_doc_dirs]) do |path, type|
    @doc_dirs << path

    store = RDoc::RI::Store.new path, type
    store.load_cache
    @stores << store
  end

  @list_doc_dirs = options[:list_doc_dirs]

  @interactive = options[:interactive]
  @server      = options[:server]
  @use_stdout  = options[:use_stdout]
  @show_all    = options[:show_all]
  @width       = options[:width]
  @expand_refs = options[:expand_refs]
end

Instance Attribute Details

#show_all ⇒ Object

Show all method documentation following a class or module



62
63
64
 
# File 'lib/rdoc/ri/driver.rb', line 62

def show_all
  @show_all
end

#stores ⇒ Object

An RDoc::RI::Store for each entry in the RI path



67
68
69
 
# File 'lib/rdoc/ri/driver.rb', line 67

def stores
  @stores
end

#use_stdout ⇒ Object

Controls the user of the pager vs $stdout



72
73
74
 
# File 'lib/rdoc/ri/driver.rb', line 72

def use_stdout
  @use_stdout
end

Class Method Details

.default_options ⇒ Object

Default options for ri



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/rdoc/ri/driver.rb', line 77

def self.default_options
  options = {}
  options[:interactive] = false
  options[:profile]     = false
  options[:show_all]    = false
  options[:expand_refs] = true
  options[:use_stdout]  = !$stdout.tty?
  options[:width]       = 72

  # By default all standard paths are used.
  options[:use_system]     = true
  options[:use_site]       = true
  options[:use_home]       = true
  options[:use_gems]       = true
  options[:extra_doc_dirs] = []

  return options
end

.dump(data_path) ⇒ Object

Dump data_path using pp



99
100
101
102
103
104
105
 
# File 'lib/rdoc/ri/driver.rb', line 99

def self.dump data_path
  require 'pp'

  File.open data_path, 'rb' do |io|
    pp Marshal.load(io.read)
  end
end

.process_args(argv) ⇒ Object

Parses argv and returns a Hash of options



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
 
# File 'lib/rdoc/ri/driver.rb', line 110

def self.process_args argv
  options = default_options

  opts = OptionParser.new do |opt|
    opt.program_name = File.basename $0
    opt.version = RDoc::VERSION
    opt.release = nil
    opt.summary_indent = ' ' * 4

    opt.banner = <<-EOT
Usage: #{opt.program_name} [options] [name ...]

Where name can be:

Class | Module | Module::Class

Class::method | Class#method | Class.method | method

gem_name: | gem_name:README | gem_name:History

ruby: | ruby:NEWS | ruby:globals

All class names may be abbreviated to their minimum unambiguous form.
If a name is ambiguous, all valid options will be listed.

A '.' matches either class or instance methods, while #method
matches only instance and ::method matches only class methods.

README and other files may be displayed by prefixing them with the gem name
they're contained in.  If the gem name is followed by a ':' all files in the
gem will be shown.  The file name extension may be omitted where it is
unambiguous.

'ruby' can be used as a pseudo gem name to display files from the Ruby
core documentation. Use 'ruby:' by itself to get a list of all available
core documentation files.

For example:

  #{opt.program_name} Fil
  #{opt.program_name} File
  #{opt.program_name} File.new
  #{opt.program_name} zip
  #{opt.program_name} rdoc:README
  #{opt.program_name} ruby:comments

Note that shell quoting or escaping may be required for method names
containing punctuation:

  #{opt.program_name} 'Array.[]'
  #{opt.program_name} compact\\!

To see the default directories #{opt.program_name} will search, run:

  #{opt.program_name} --list-doc-dirs

Specifying the --system, --site, --home, --gems, or --doc-dir options
will limit ri to searching only the specified directories.

ri options may be set in the RI environment variable.

The ri pager can be set with the RI_PAGER environment variable
or the PAGER environment variable.
    EOT

    opt.separator nil
    opt.separator "Options:"

    opt.separator nil

    opt.on("--[no-]interactive", "-i",
           "In interactive mode you can repeatedly",
           "look up methods with autocomplete.") do |interactive|
      options[:interactive] = interactive
    end

    opt.separator nil

    opt.on("--[no-]all", "-a",
           "Show all documentation for a class or",
           "module.") do |show_all|
      options[:show_all] = show_all
    end

    opt.separator nil

    opt.on("--[no-]list", "-l",
           "List classes ri knows about.") do |list|
      options[:list] = list
    end

    opt.separator nil

    opt.on("--[no-]pager",
           "Send output to a pager,",
           "rather than directly to stdout.") do |use_pager|
      options[:use_stdout] = !use_pager
    end

    opt.separator nil

    opt.on("-T",
           "Synonym for --no-pager.") do
      options[:use_stdout] = true
    end

    opt.separator nil

    opt.on("--width=WIDTH", "-w", OptionParser::DecimalInteger,
           "Set the width of the output.") do |width|
      options[:width] = width
    end

    opt.separator nil

    opt.on("--server[=PORT]", Integer,
           "Run RDoc server on the given port.",
           "The default port is 8214.") do |port|
      options[:server] = port || 8214
    end

    opt.separator nil

    formatters = RDoc::Markup.constants.grep(/^To[A-Z][a-z]+$/).sort
    formatters = formatters.sort.map do |formatter|
      formatter.to_s.sub('To', '').downcase
    end
    formatters -= %w[html label test] # remove useless output formats

    opt.on("--format=NAME", "-f",
           "Use the selected formatter.  The default",
           "formatter is bs for paged output and ansi",
           "otherwise.  Valid formatters are:",
           "#{formatters.join(', ')}.", formatters) do |value|
      options[:formatter] = RDoc::Markup.const_get "To#{value.capitalize}"
    end

    opt.separator nil

    opt.on("--[no-]expand-refs", "Expand rdoc-refs at the end of output") do |value|
      options[:expand_refs] = value
    end

    opt.separator nil

    opt.on("--help", "-h",
           "Show help and exit.") do
      puts opts
      exit
    end

    opt.separator nil

    opt.on("--version", "-v",
           "Output version information and exit.") do
      puts "#{opts.program_name} #{opts.version}"
      exit
    end

    opt.separator nil
    opt.separator "Data source options:"
    opt.separator nil

    opt.on("--[no-]list-doc-dirs",
           "List the directories from which ri will",
           "source documentation on stdout and exit.") do |list_doc_dirs|
      options[:list_doc_dirs] = list_doc_dirs
    end

    opt.separator nil

    opt.on("--doc-dir=DIRNAME", "-d", Array,
           "List of directories from which to source",
           "documentation in addition to the standard",
           "directories.  May be repeated.") do |value|
      value.each do |dir|
        unless File.directory? dir then
          raise OptionParser::InvalidArgument, "#{dir} is not a directory"
        end

        options[:extra_doc_dirs] << File.expand_path(dir)
      end
    end

    opt.separator nil

    opt.on("--no-standard-docs",
           "Do not include documentation from",
           "the Ruby standard library, site_lib,",
           "installed gems, or ~/.rdoc.",
           "Use with --doc-dir.") do
      options[:use_system] = false
      options[:use_site] = false
      options[:use_gems] = false
      options[:use_home] = false
    end

    opt.separator nil

    opt.on("--[no-]system",
           "Include documentation from Ruby's",
           "standard library.  Defaults to true.") do |value|
      options[:use_system] = value
    end

    opt.separator nil

    opt.on("--[no-]site",
           "Include documentation from libraries",
           "installed in site_lib.",
           "Defaults to true.") do |value|
      options[:use_site] = value
    end

    opt.separator nil

    opt.on("--[no-]gems",
           "Include documentation from RubyGems.",
           "Defaults to true.") do |value|
      options[:use_gems] = value
    end

    opt.separator nil

    opt.on("--[no-]home",
           "Include documentation stored in ~/.rdoc.",
           "Defaults to true.") do |value|
      options[:use_home] = value
    end

    opt.separator nil
    opt.separator "Debug options:"
    opt.separator nil

    opt.on("--[no-]profile",
           "Run with the ruby profiler.") do |value|
      options[:profile] = value
    end

    opt.separator nil

    opt.on("--dump=CACHE",
           "Dump data from an ri cache or data file.") do |value|
      unless File.readable?(value)
        abort "#{value.inspect} is not readable"
      end

      if File.directory?(value)
        abort "#{value.inspect} is a directory"
      end

      options[:dump_path] = File.new(value)
    end
  end

  argv = ENV['RI'].to_s.split(' ').concat argv

  opts.parse! argv

  options[:names] = argv

  options[:use_stdout] ||= !$stdout.tty?
  options[:use_stdout] ||= options[:interactive]
  options[:width] ||= 72

  options

rescue OptionParser::InvalidArgument, OptionParser::InvalidOption => e
  puts opts
  puts
  puts e
  exit 1
end

.run(argv = ARGV) ⇒ Object

Runs the ri command line executable using argv



387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/rdoc/ri/driver.rb', line 387

def self.run argv = ARGV
  options = process_args argv

  if options[:dump_path] then
    dump options[:dump_path]
    return
  end

  ri = new options
  ri.run
end

Instance Method Details

#add_also_in(out, also_in) ⇒ Object

Adds paths for undocumented classes also_in to out



441
442
443
444
445
446
447
448
449
450
451
452
 
# File 'lib/rdoc/ri/driver.rb', line 441

def add_also_in out, also_in
  return if also_in.empty?

  out << RDoc::Markup::Rule.new(1)
  out << RDoc::Markup::Paragraph.new("Also found in:")

  paths = RDoc::Markup::Verbatim.new
  also_in.each do |store|
    paths.parts.push store.friendly_path, "\n"
  end
  out << paths
end

#add_class(out, name, classes) ⇒ Object

Adds a class header to out for class name which is described in classes.



458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
 
# File 'lib/rdoc/ri/driver.rb', line 458

def add_class out, name, classes
  heading = if classes.all? { |klass| klass.module? } then
              name
            else
              superclass = classes.map do |klass|
                klass.superclass unless klass.module?
              end.compact.shift || 'Object'

              superclass = superclass.full_name unless String === superclass

              "#{name} < #{superclass}"
            end

  out << RDoc::Markup::Heading.new(1, heading)
  out << RDoc::Markup::BlankLine.new
end

#add_extends(out, extends) ⇒ Object

Adds extends to out



485
486
487
 
# File 'lib/rdoc/ri/driver.rb', line 485

def add_extends out, extends
  add_extension_modules out, 'Extended by', extends
end

#add_extension_modules(out, type, extensions) ⇒ Object

Adds a list of extensions to this module of the given type to out. add_includes and add_extends call this, so you should use those directly.



493
494
495
496
497
498
499
500
501
502
503
504
505
506
 
# File 'lib/rdoc/ri/driver.rb', line 493

def add_extension_modules out, type, extensions
  return if extensions.empty?

  out << RDoc::Markup::Rule.new(1)
  out << RDoc::Markup::Heading.new(1, "#{type}:")

  extensions.each do |modules, store|
    if modules.length == 1 then
      add_extension_modules_single out, store, modules.first
    else
      add_extension_modules_multiple out, store, modules
    end
  end
end

#add_extension_modules_multiple(out, store, modules) ⇒ Object

Renders multiple included modules from store to out.



511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
 
# File 'lib/rdoc/ri/driver.rb', line 511

def add_extension_modules_multiple out, store, modules # :nodoc:
  out << RDoc::Markup::Paragraph.new("(from #{store.friendly_path})")

  wout, with = modules.partition { |incl| incl.comment.empty? }

  out << RDoc::Markup::BlankLine.new unless with.empty?

  with.each do |incl|
    out << RDoc::Markup::Paragraph.new(incl.name)
    out << RDoc::Markup::BlankLine.new
    out << incl.comment
  end

  unless wout.empty? then
    verb = RDoc::Markup::Verbatim.new

    wout.each do |incl|
      verb.push incl.name, "\n"
    end

    out << verb
  end
end

#add_extension_modules_single(out, store, include) ⇒ Object

Adds a single extension module include from store to out



538
539
540
541
542
543
544
545
546
547
 
# File 'lib/rdoc/ri/driver.rb', line 538

def add_extension_modules_single out, store, include # :nodoc:
  name = include.name
  path = store.friendly_path
  out << RDoc::Markup::Paragraph.new("#{name} (from #{path})")

  if include.comment then
    out << RDoc::Markup::BlankLine.new
    out << include.comment
  end
end

#add_from(out, store) ⇒ Object

Adds “(from …)” to out for store



478
479
480
 
# File 'lib/rdoc/ri/driver.rb', line 478

def add_from out, store
  out << RDoc::Markup::Paragraph.new("(from #{store.friendly_path})")
end

#add_includes(out, includes) ⇒ Object

Adds includes to out



552
553
554
 
# File 'lib/rdoc/ri/driver.rb', line 552

def add_includes out, includes
  add_extension_modules out, 'Includes', includes
end

#add_method(out, name) ⇒ Object

Looks up the method name and adds it to out



559
560
561
562
 
# File 'lib/rdoc/ri/driver.rb', line 559

def add_method out, name
  filtered = lookup_method name
  method_document out, name, filtered
end

#add_method_documentation(out, klass) ⇒ Object

Adds documentation for all methods in klass to out



567
568
569
570
571
572
573
574
575
 
# File 'lib/rdoc/ri/driver.rb', line 567

def add_method_documentation out, klass
  klass.method_list.each do |method|
    begin
      add_method out, method.full_name
    rescue NotFoundError
      next
    end
  end
end

#add_method_list(out, methods, name) ⇒ Object

Adds a list of methods to out with a heading of name



580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
 
# File 'lib/rdoc/ri/driver.rb', line 580

def add_method_list out, methods, name
  return if methods.empty?

  out << RDoc::Markup::Heading.new(1, "#{name}:")
  out << RDoc::Markup::BlankLine.new

  if @use_stdout and !@interactive then
    out.concat methods.map { |method|
      RDoc::Markup::Verbatim.new method
    }
  else
    out << RDoc::Markup::IndentedParagraph.new(2, methods.join(', '))
  end

  out << RDoc::Markup::BlankLine.new
end

#ancestors_of(klass) ⇒ Object

Returns ancestor classes of klass



600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
 
# File 'lib/rdoc/ri/driver.rb', line 600

def ancestors_of klass
  ancestors = []

  unexamined = [klass]
  seen = []

  loop do
    break if unexamined.empty?
    current = unexamined.shift
    seen << current

    stores = classes[current]

    next unless stores and not stores.empty?

    klasses = stores.flat_map do |store|
      store.ancestors[current] || []
    end.uniq

    klasses = klasses - seen

    ancestors.concat klasses
    unexamined.concat klasses
  end

  ancestors.reverse
end

#check_did_you_mean ⇒ Object

:nodoc:



938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
 
# File 'lib/rdoc/ri/driver.rb', line 938

def check_did_you_mean # :nodoc:
  if defined? DidYouMean::SpellChecker
    true
  else
    begin
      require 'did_you_mean'
      if defined? DidYouMean::SpellChecker
        true
      else
        false
      end
    rescue LoadError
      false
    end
  end
end

#class_cache ⇒ Object

For RubyGems backwards compatibility



631
632
 
# File 'lib/rdoc/ri/driver.rb', line 631

def class_cache # :nodoc:
end

#class_document(name, found, klasses, includes, extends) ⇒ Object

Builds a RDoc::Markup::Document from found, klasess and includes



637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
 
# File 'lib/rdoc/ri/driver.rb', line 637

def class_document name, found, klasses, includes, extends
  also_in = []

  out = RDoc::Markup::Document.new

  add_class out, name, klasses

  add_includes out, includes
  add_extends  out, extends

  found.each do |store, klass|
    render_class out, store, klass, also_in
  end

  add_also_in out, also_in

  expand_rdoc_refs_at_the_bottom(out)
  out
end

#class_document_comment(out, comment) ⇒ Object

Adds the class comment to out.



660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
 
# File 'lib/rdoc/ri/driver.rb', line 660

def class_document_comment out, comment # :nodoc:
  unless comment.empty? then
    out << RDoc::Markup::Rule.new(1)

    if comment.merged? then
      parts = comment.parts
      parts = parts.zip [RDoc::Markup::BlankLine.new] * parts.length
      parts.flatten!
      parts.pop

      out.concat parts
    else
      out << comment
    end
  end
end

#class_document_constants(out, klass) ⇒ Object

Adds the constants from klass to the Document out.



680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
 
# File 'lib/rdoc/ri/driver.rb', line 680

def class_document_constants out, klass # :nodoc:
  return if klass.constants.empty?

  out << RDoc::Markup::Heading.new(1, "Constants:")
  out << RDoc::Markup::BlankLine.new
  list = RDoc::Markup::List.new :NOTE

  constants = klass.constants.sort_by { |constant| constant.name }

  list.items.concat constants.map { |constant|
    parts = constant.comment.parts if constant.comment
    parts << RDoc::Markup::Paragraph.new('[not documented]') if
      parts.empty?

    RDoc::Markup::ListItem.new(constant.name, *parts)
  }

  out << list
  out << RDoc::Markup::BlankLine.new
end

#classes ⇒ Object

Hash mapping a known class or module to the stores it can be loaded from



704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
 
# File 'lib/rdoc/ri/driver.rb', line 704

def classes
  return @classes if @classes

  @classes = {}

  @stores.each do |store|
    store.cache[:modules].each do |mod|
      # using default block causes searched-for modules to be added
      @classes[mod] ||= []
      @classes[mod] << store
    end
  end

  @classes
end

#classes_and_includes_and_extends_for(name) ⇒ Object

Returns the stores wherein name is found along with the classes, extends and includes that match it



724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
 
# File 'lib/rdoc/ri/driver.rb', line 724

def classes_and_includes_and_extends_for name
  klasses = []
  extends = []
  includes = []

  found = @stores.map do |store|
    begin
      klass = store.load_class name
      klasses  << klass
      extends  << [klass.extends,  store] if klass.extends
      includes << [klass.includes, store] if klass.includes
      [store, klass]
    rescue RDoc::Store::MissingFileError
    end
  end.compact

  extends.reject!  do |modules,| modules.empty? end
  includes.reject! do |modules,| modules.empty? end

  [found, klasses, includes, extends]
end

#complete(name) ⇒ Object

Completes name based on the caches. For Readline



749
750
751
752
753
754
755
756
757
758
 
# File 'lib/rdoc/ri/driver.rb', line 749

def complete name
  completions = []

  klass, selector, method = parse_name name

  complete_klass  name, klass, selector, method, completions
  complete_method name, klass, selector,         completions

  completions.sort.uniq
end

#complete_klass(name, klass, selector, method, completions) ⇒ Object

:nodoc:



760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
 
# File 'lib/rdoc/ri/driver.rb', line 760

def complete_klass name, klass, selector, method, completions # :nodoc:
  klasses = classes.keys

  # may need to include Foo when given Foo::
  klass_name = method ? name : klass

  if name !~ /#|\./ then
    completions.replace klasses.grep(/^#{Regexp.escape klass_name}[^:]*$/)
    completions.concat klasses.grep(/^#{Regexp.escape name}[^:]*$/) if
      name =~ /::$/

    completions << klass if classes.key? klass # to complete a method name
  elsif selector then
    completions << klass if classes.key? klass
  elsif classes.key? klass_name then
    completions << klass_name
  end
end

#complete_method(name, klass, selector, completions) ⇒ Object

:nodoc:



779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
 
# File 'lib/rdoc/ri/driver.rb', line 779

def complete_method name, klass, selector, completions # :nodoc:
  if completions.include? klass and name =~ /#|\.|::/ then
    methods = list_methods_matching name

    if not methods.empty? then
      # remove Foo if given Foo:: and a method was found
      completions.delete klass
    elsif selector then
      # replace Foo with Foo:: as given
      completions.delete klass
      completions << "#{klass}#{selector}"
    end

    completions.concat methods
  end
end

#display(document) ⇒ Object

Converts document to text and writes it to the pager



799
800
801
802
803
804
805
806
807
 
# File 'lib/rdoc/ri/driver.rb', line 799

def display document
  page do |io|
    f = formatter(io)
    f.width = @width if @width and f.respond_to?(:width)
    text = document.accept f

    io.write text
  end
end

#display_class(name) ⇒ Object

Outputs formatted RI data for class name. Groups undocumented classes



812
813
814
815
816
817
818
819
820
821
822
823
 
# File 'lib/rdoc/ri/driver.rb', line 812

def display_class name
  return if name =~ /#|\./

  found, klasses, includes, extends =
    classes_and_includes_and_extends_for name

  return if found.empty?

  out = class_document name, found, klasses, includes, extends

  display out
end

#display_method(name) ⇒ Object

Outputs formatted RI data for method name



828
829
830
831
832
833
834
835
836
 
# File 'lib/rdoc/ri/driver.rb', line 828

def display_method name
  out = RDoc::Markup::Document.new

  add_method out, name

  expand_rdoc_refs_at_the_bottom(out)

  display out
end

#display_name(name) ⇒ Object

Outputs formatted RI data for the class or method name.

Returns true if name was found, false if it was not an alternative could be guessed, raises an error if name couldn’t be guessed.



844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
 
# File 'lib/rdoc/ri/driver.rb', line 844

def display_name name
  if name =~ /\w:(\w|$)/ then
    display_page name
    return true
  end

  return true if display_class name

  display_method name if name =~ /::|#|\./

  true
rescue NotFoundError
  matches = list_methods_matching name if name =~ /::|#|\./
  matches = classes.keys.grep(/^#{Regexp.escape name}/) if matches.empty?

  raise if matches.empty?

  page do |io|
    io.puts "#{name} not found, maybe you meant:"
    io.puts
    io.puts matches.sort.join("\n")
  end

  false
end

#display_names(names) ⇒ Object

Displays each name in name



873
874
875
876
877
878
879
 
# File 'lib/rdoc/ri/driver.rb', line 873

def display_names names
  names.each do |name|
    name = expand_name name

    display_name name
  end
end

#display_page(name) ⇒ Object

Outputs formatted RI data for page name.



884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
 
# File 'lib/rdoc/ri/driver.rb', line 884

def display_page name
  store_name, page_name = name.split ':', 2

  store = @stores.find { |s| s.source == store_name }

  return display_page_list store if page_name.empty?

  pages = store.cache[:pages]

  unless pages.include? page_name then
    found_names = pages.select do |n|
      n =~ /#{Regexp.escape page_name}\.[^.]+$/
    end

    if found_names.length.zero? then
      return display_page_list store, pages
    elsif found_names.length > 1 then
      return display_page_list store, found_names, page_name
    end

    page_name = found_names.first
  end

  page = store.load_page page_name

  display page.comment
end

#display_page_list(store, pages = , search = nil) ⇒ Object

Outputs a formatted RI page list for the pages in store.



915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
 
# File 'lib/rdoc/ri/driver.rb', line 915

def display_page_list store, pages = store.cache[:pages], search = nil
  out = RDoc::Markup::Document.new

  title = if search then
            "#{search} pages"
          else
            'Pages'
          end

  out << RDoc::Markup::Heading.new(1, "#{title} in #{store.friendly_path}")
  out << RDoc::Markup::BlankLine.new

  list = RDoc::Markup::List.new(:BULLET)

  pages.each do |page|
    list << RDoc::Markup::Paragraph.new(page)
  end

  out << list

  display out
end

#expand_class(klass) ⇒ Object

Expands abbreviated klass klass into a fully-qualified class. “Zl::Da” will be expanded to Zlib::DataError.



959
960
961
962
963
964
965
966
967
968
969
970
971
 
# File 'lib/rdoc/ri/driver.rb', line 959

def expand_class klass
  class_names = classes.keys
  ary = class_names.grep(Regexp.new("\\A#{klass.gsub(/(?=::|\z)/, '[^:]*')}\\z"))
  if ary.length != 1 && ary.first != klass
    if check_did_you_mean
      suggestion_proc = -> { DidYouMean::SpellChecker.new(dictionary: class_names).correct(klass) }
      raise NotFoundError.new(klass, suggestion_proc)
    else
      raise NotFoundError, klass
    end
  end
  ary.first
end

#expand_name(name) ⇒ Object

Expands the class portion of name into a fully-qualified class. See #expand_class.



977
978
979
980
981
982
983
984
985
986
987
988
 
# File 'lib/rdoc/ri/driver.rb', line 977

def expand_name name
  klass, selector, method = parse_name name

  return [selector, method].join if klass.empty?

  case selector
  when ':' then
    [find_store(klass),   selector, method]
  else
    [expand_class(klass), selector, method]
  end.join
end

#expand_rdoc_refs_at_the_bottom(out) ⇒ Object 



1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
 
# File 'lib/rdoc/ri/driver.rb', line 1525

def expand_rdoc_refs_at_the_bottom(out)
  return unless @expand_refs

  extracted_rdoc_refs = []

  out.each do |part|
    content = if part.respond_to?(:text)
      part.text
    else
      next
    end

    rdoc_refs = content.scan(RDOC_REFS_REGEXP).uniq.map do |file_name, _anchor|
      file_name
    end

    extracted_rdoc_refs.concat(rdoc_refs)
  end

  found_pages = extracted_rdoc_refs.map do |ref|
    begin
      @stores.first.load_page(ref)
    rescue RDoc::Store::MissingFileError
    end
  end.compact

  found_pages.each do |page|
    out << RDoc::Markup::Heading.new(4, "Expanded from #{page.full_name}")
    out << RDoc::Markup::BlankLine.new
    out << page.comment
  end
end

#filter_methods(found, name) ⇒ Object

Filters the methods in found trying to find a match for name.



993
994
995
996
997
998
999
1000
1001
1002
1003
 
# File 'lib/rdoc/ri/driver.rb', line 993

def filter_methods found, name
  regexp = name_regexp name

  filtered = found.find_all do |store, methods|
    methods.any? { |method| method.full_name =~ regexp }
  end

  return filtered unless filtered.empty?

  found
end

#find_methods(name) ⇒ Object

Yields items matching name including the store they were found in, the class being searched for, the class they were found in (an ancestor) the types of methods to look up (from #method_type), and the method name being searched for



1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
 
# File 'lib/rdoc/ri/driver.rb', line 1011

def find_methods name
  klass, selector, method = parse_name name

  types = method_type selector

  klasses = nil
  ambiguous = klass.empty?

  if ambiguous then
    klasses = classes.keys
  else
    klasses = ancestors_of klass
    klasses.unshift klass
  end

  methods = []

  klasses.each do |ancestor|
    ancestors = classes[ancestor]

    next unless ancestors

    klass = ancestor if ambiguous

    ancestors.each do |store|
      methods << [store, klass, ancestor, types, method]
    end
  end

  methods = methods.sort_by do |_, k, a, _, m|
    [k, a, m].compact
  end

  methods.each do |item|
    yield(*item) # :yields: store, klass, ancestor, types, method
  end

  self
end

#find_store(name) ⇒ Object

Finds a store that matches name which can be the name of a gem, “ruby”, “home” or “site”.

See also RDoc::Store#source

Raises:



1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
 
# File 'lib/rdoc/ri/driver.rb', line 1057

def find_store name
  @stores.each do |store|
    source = store.source

    return source if source == name

    return source if
      store.type == :gem and source =~ /^#{Regexp.escape name}-\d/
  end

  raise RDoc::RI::Driver::NotFoundError, name
end

#formatter(io) ⇒ Object

Creates a new RDoc::Markup::Formatter. If a formatter is given with -f, use it. If we’re outputting to a pager, use bs, otherwise ansi.



1074
1075
1076
1077
1078
1079
1080
1081
1082
 
# File 'lib/rdoc/ri/driver.rb', line 1074

def formatter(io)
  if @formatter_klass then
    @formatter_klass.new
  elsif paging? or !io.tty? then
    RDoc::Markup::ToBs.new
  else
    RDoc::Markup::ToAnsi.new
  end
end

#interactive ⇒ Object

Runs ri interactively using Readline if it is available.



1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
 
# File 'lib/rdoc/ri/driver.rb', line 1087

def interactive
  puts "\nEnter the method name you want to look up."

  begin
    require 'readline'
  rescue LoadError
  end
  if defined? Readline then
    Readline.completion_proc = method :complete
    puts "You can use tab to autocomplete."
  end

  puts "Enter a blank line to exit.\n\n"

  loop do
    name = if defined? Readline then
             Readline.readline ">> ", true
           else
             print ">> "
             $stdin.gets
           end

    return if name.nil? or name.empty?

    begin
      display_name expand_name(name.strip)
    rescue NotFoundError => e
      puts e.message
    end
  end

rescue Interrupt
  exit
end

#list_known_classes(names = []) ⇒ Object

Lists classes known to ri starting with names. If names is empty all known classes are shown.



1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
 
# File 'lib/rdoc/ri/driver.rb', line 1126

def list_known_classes names = []
  classes = []

  stores.each do |store|
    classes << store.module_names
  end

  classes = classes.flatten.uniq.sort

  unless names.empty? then
    filter = Regexp.union names.map { |name| /^#{name}/ }

    classes = classes.grep filter
  end

  page do |io|
    if paging? or io.tty? then
      if names.empty? then
        io.puts "Classes and Modules known to ri:"
      else
        io.puts "Classes and Modules starting with #{names.join ', '}:"
      end
      io.puts
    end

    io.puts classes.join("\n")
  end
end

#list_methods_matching(name) ⇒ Object

Returns an Array of methods matching name



1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
 
# File 'lib/rdoc/ri/driver.rb', line 1158

def list_methods_matching name
  found = []

  find_methods name do |store, klass, ancestor, types, method|
    if types == :instance or types == :both then
      methods = store.instance_methods[ancestor]

      if methods then
        matches = methods.grep(/^#{Regexp.escape method.to_s}/)

        matches = matches.map do |match|
          "#{klass}##{match}"
        end

        found.concat matches
      end
    end

    if types == :class or types == :both then
      methods = store.class_methods[ancestor]

      next unless methods
      matches = methods.grep(/^#{Regexp.escape method.to_s}/)

      matches = matches.map do |match|
        "#{klass}::#{match}"
      end

      found.concat matches
    end
  end

  found.uniq
end

#load_method(store, cache, klass, type, name) ⇒ Object

Loads RI data for method name on klass from store. type and cache indicate if it is a class or instance method.



1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
 
# File 'lib/rdoc/ri/driver.rb', line 1197

def load_method store, cache, klass, type, name
  methods = store.public_send(cache)[klass]

  return unless methods

  method = methods.find do |method_name|
    method_name == name
  end

  return unless method

  store.load_method klass, "#{type}#{method}"
rescue RDoc::Store::MissingFileError => e
  comment = RDoc::Comment.new("missing documentation at #{e.file}").parse

  method = RDoc::AnyMethod.new nil, name
  method.comment = comment
  method
end

#load_methods_matching(name) ⇒ Object

Returns an Array of RI data for methods matching name



1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
 
# File 'lib/rdoc/ri/driver.rb', line 1220

def load_methods_matching name
  found = []

  find_methods name do |store, klass, ancestor, types, method|
    methods = []

    methods << load_method(store, :class_methods, ancestor, '::',  method) if
      [:class, :both].include? types

    methods << load_method(store, :instance_methods, ancestor, '#',  method) if
      [:instance, :both].include? types

    found << [store, methods.compact]
  end

  found.reject do |path, methods| methods.empty? end
end

#lookup_method(name) ⇒ Object

Returns a filtered list of methods matching name



1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
 
# File 'lib/rdoc/ri/driver.rb', line 1241

def lookup_method name
  found = load_methods_matching name

  if found.empty?
    if check_did_you_mean
      methods = []
      _, _, method_name = parse_name name
      find_methods name do |store, klass, ancestor, types, method|
        methods.push(*store.class_methods[klass]) if [:class, :both].include? types
        methods.push(*store.instance_methods[klass]) if [:instance, :both].include? types
      end
      methods = methods.uniq
      suggestion_proc = -> { DidYouMean::SpellChecker.new(dictionary: methods).correct(method_name) }
      raise NotFoundError.new(name, suggestion_proc)
    else
      raise NotFoundError, name
    end
  end

  filter_methods found, name
end

#method_document(out, name, filtered) ⇒ Object

Builds a RDoc::Markup::Document from found, klasses and includes



1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
 
# File 'lib/rdoc/ri/driver.rb', line 1266

def method_document out, name, filtered
  out << RDoc::Markup::Heading.new(1, name)
  out << RDoc::Markup::BlankLine.new

  filtered.each do |store, methods|
    methods.each do |method|
      render_method out, store, method, name
    end
  end

  out
end

#method_type(selector) ⇒ Object

Returns the type of method (:both, :instance, :class) for selector



1282
1283
1284
1285
1286
1287
1288
 
# File 'lib/rdoc/ri/driver.rb', line 1282

def method_type selector
  case selector
  when '.', nil then :both
  when '#'      then :instance
  else               :class
  end
end

#name_regexp(name) ⇒ Object

Returns a regular expression for name that will match an RDoc::AnyMethod’s name.



1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
 
# File 'lib/rdoc/ri/driver.rb', line 1294

def name_regexp name
  klass, type, name = parse_name name

  case type
  when '#', '::' then
    /^#{klass}#{type}#{Regexp.escape name}$/
  else
    /^#{klass}(#|::)#{Regexp.escape name}$/
  end
end

#page ⇒ Object

Paginates output through a pager program.



1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
 
# File 'lib/rdoc/ri/driver.rb', line 1308

def page
  if pager = setup_pager then
    begin
      yield pager
    ensure
      pager.close
    end
  else
    yield $stdout
  end
rescue Errno::EPIPE
ensure
  @paging = false
end

#paging? ⇒ Boolean

Are we using a pager?

Returns:

  • (Boolean) 


1326
1327
1328
 
# File 'lib/rdoc/ri/driver.rb', line 1326

def paging?
  @paging
end

#parse_name(name) ⇒ Object

Extracts the class, selector and method name parts from name like Foo::Bar#baz.

NOTE: Given Foo::Bar, Bar is considered a class even though it may be a method



1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
 
# File 'lib/rdoc/ri/driver.rb', line 1337

def parse_name name
  parts = name.split(/(::?|#|\.)/)

  if parts.length == 1 then
    if parts.first =~ /^[a-z]|^([%&*+\/<>^`|~-]|\+@|-@|<<|<=>?|===?|=>|=~|>>|\[\]=?|~@)$/ then
      type = '.'
      meth = parts.pop
    else
      type = nil
      meth = nil
    end
  elsif parts.length == 2 or parts.last =~ /::|#|\./ then
    type = parts.pop
    meth = nil
  elsif parts[1] == ':' then
    klass = parts.shift
    type  = parts.shift
    meth  = parts.join
  elsif parts[-2] != '::' or parts.last !~ /^[A-Z]/ then
    meth = parts.pop
    type = parts.pop
  end

  klass ||= parts.join

  [klass, type, meth]
end

#render_class(out, store, klass, also_in) ⇒ Object

Renders the klass from store to out. If the klass has no documentable items the class is added to also_in instead.



1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
 
# File 'lib/rdoc/ri/driver.rb', line 1369

def render_class out, store, klass, also_in # :nodoc:
  comment = klass.comment
  # TODO the store's cache should always return an empty Array
  class_methods    = store.class_methods[klass.full_name]    || []
  instance_methods = store.instance_methods[klass.full_name] || []
  attributes       = store.attributes[klass.full_name]       || []

  if comment.empty? and
     instance_methods.empty? and class_methods.empty? then
    also_in << store
    return
  end

  add_from out, store

  class_document_comment out, comment

  if class_methods or instance_methods or not klass.constants.empty? then
    out << RDoc::Markup::Rule.new(1)
  end

  class_document_constants out, klass

  add_method_list out, class_methods,    'Class methods'
  add_method_list out, instance_methods, 'Instance methods'
  add_method_list out, attributes,       'Attributes'

  add_method_documentation out, klass if @show_all
end

#render_method(out, store, method, name) ⇒ Object

:nodoc:



1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
 
# File 'lib/rdoc/ri/driver.rb', line 1399

def render_method out, store, method, name # :nodoc:
  out << RDoc::Markup::Paragraph.new("(from #{store.friendly_path})")

  unless name =~ /^#{Regexp.escape method.parent_name}/ then
    out << RDoc::Markup::Heading.new(3, "Implementation from #{method.parent_name}")
  end

  out << RDoc::Markup::Rule.new(1)

  render_method_arguments out, method.arglists
  render_method_superclass out, method
  if method.is_alias_for
    al = method.is_alias_for
    alias_for = store.load_method al.parent_name, "#{al.name_prefix}#{al.name}"
    render_method_comment out, method, alias_for
  else
    render_method_comment out, method
  end
end

#render_method_arguments(out, arglists) ⇒ Object

:nodoc:



1419
1420
1421
1422
1423
1424
1425
1426
 
# File 'lib/rdoc/ri/driver.rb', line 1419

def render_method_arguments out, arglists # :nodoc:
  return unless arglists

  arglists = arglists.chomp.split "\n"
  arglists = arglists.map { |line| line + "\n" }
  out << RDoc::Markup::Verbatim.new(*arglists)
  out << RDoc::Markup::Rule.new(1)
end

#render_method_comment(out, method, alias_for = nil) ⇒ Object

:nodoc:



1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
 
# File 'lib/rdoc/ri/driver.rb', line 1428

def render_method_comment out, method, alias_for = nil# :nodoc:
  if alias_for
    unless method.comment.nil? or method.comment.empty?
      out << RDoc::Markup::BlankLine.new
      out << method.comment
    end
    out << RDoc::Markup::BlankLine.new
    out << RDoc::Markup::Paragraph.new("(This method is an alias for #{alias_for.full_name}.)")
    out << RDoc::Markup::BlankLine.new
    out << alias_for.comment
    out << RDoc::Markup::BlankLine.new
  else
    out << RDoc::Markup::BlankLine.new
    out << method.comment
    out << RDoc::Markup::BlankLine.new
  end
end

#render_method_superclass(out, method) ⇒ Object

:nodoc:



1446
1447
1448
1449
1450
1451
1452
1453
 
# File 'lib/rdoc/ri/driver.rb', line 1446

def render_method_superclass out, method # :nodoc:
  return unless
    method.respond_to?(:superclass_method) and method.superclass_method

  out << RDoc::Markup::BlankLine.new
  out << RDoc::Markup::Heading.new(4, "(Uses superclass method #{method.superclass_method})")
  out << RDoc::Markup::Rule.new(1)
end

#run ⇒ Object

Looks up and displays ri data according to the options given.



1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
 
# File 'lib/rdoc/ri/driver.rb', line 1458

def run
  if @list_doc_dirs then
    puts @doc_dirs
  elsif @list then
    list_known_classes @names
  elsif @server then
    start_server
  elsif @interactive or @names.empty? then
    interactive
  else
    display_names @names
  end
rescue NotFoundError => e
  abort e.message
end

#setup_pager ⇒ Object

Sets up a pager program to pass output through. Tries the RI_PAGER and PAGER environment variables followed by pager, less then more.



1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
 
# File 'lib/rdoc/ri/driver.rb', line 1478

def setup_pager
  return if @use_stdout

  pagers = [ENV['RI_PAGER'], ENV['PAGER'], 'pager', 'less', 'more']

  require 'shellwords'
  pagers.compact.uniq.each do |pager|
    pager = Shellwords.split(pager)
    next if pager.empty?

    io = IO.popen(pager, 'w') rescue next
    next if $? and $?.pid == io.pid and $?.exited? # pager didn't work

    @paging = true

    return io
  end

  @use_stdout = true

  nil
end

#start_server ⇒ Object

Starts a WEBrick server for ri.



1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
 
# File 'lib/rdoc/ri/driver.rb', line 1504

def start_server
  begin
    require 'webrick'
  rescue LoadError
    abort "webrick is not found. You may need to `gem install webrick` to install webrick."
  end

  server = WEBrick::HTTPServer.new :Port => @server

  extra_doc_dirs = @stores.map {|s| s.type == :extra ? s.path : nil}.compact

  server.mount '/', RDoc::Servlet, nil, extra_doc_dirs

  trap 'INT'  do server.shutdown end
  trap 'TERM' do server.shutdown end

  server.start
end