Class: RDoc::RI::Driver

Inherits:
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

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Driver) initialize(initial_options = {})

Creates a new driver using initial_options from ::process_args



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
 
# File 'lib/rdoc/ri/driver.rb', line 325

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]

  @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]
  @use_stdout  = options[:use_stdout]
end

Instance Attribute Details

- (Object) stores

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



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

def stores
  @stores
end

- (Object) use_stdout

Controls the user of the pager vs $stdout



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

def use_stdout
  @use_stdout
end

Class Method Details

+ (Object) default_options

Default options for ri



76
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 76

def self.default_options
  options = {}
  # XXX Because of a bug in IO.popen, MacRuby is unable to use the pager facility.
  #options[:use_stdout] = !$stdout.tty?
  options[:use_stdout] = true
  options[:width] = 72
  options[:interactive] = false
  options[:use_cache] = true
  options[:profile] = false

  # 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

+ (Object) dump(data_path)

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'

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

+ (Object) process_args(argv)

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
 
# File 'lib/rdoc/ri/driver.rb', line 110

def self.process_args argv
  options = default_options

  opts = OptionParser.new do |opt|
    opt.accept File do |file,|
      File.readable?(file) and not File.directory?(file) and file
    end

    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] [names...]

Where name can be:

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

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.

For example:

  #{opt.program_name} Fil
  #{opt.program_name} File
  #{opt.program_name} File.new
  #{opt.program_name} zip

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 ri 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.

Options may also be set in the 'RI' environment variable.
    EOT

    opt.separator nil
    opt.separator "Options:"

    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

    opt.on("--format=NAME", "-f",
           "Uses 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-pager", "-T",
           "Send output directly to stdout,",
           "rather than to a pager.") do
      options[:use_stdout] = true
    end

    opt.separator nil

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

    opt.separator nil

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

    opt.separator nil

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

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

    opt.on("--list-doc-dirs",
           "List the directories from which ri will",
           "source documentation on stdout and exit.") do
      options[:list_doc_dirs] = true
    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("--dump=CACHE", File,
           "Dumps data from an ri cache or data file") do |value|
      options[:dump_path] = 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

+ (Object) run(argv = ARGV)

Runs the ri command line executable using argv



310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/rdoc/ri/driver.rb', line 310

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

- (Object) add_also_in(out, also_in)

Adds paths for undocumented classes also_in to out



359
360
361
362
363
364
365
366
367
368
369
370
 
# File 'lib/rdoc/ri/driver.rb', line 359

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

- (Object) add_class(out, name, classes)

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



376
377
378
379
380
381
382
383
384
385
386
387
388
389
 
# File 'lib/rdoc/ri/driver.rb', line 376

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'

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

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

- (Object) add_from(out, store)

Adds "(from ...)" to out for store



394
395
396
 
# File 'lib/rdoc/ri/driver.rb', line 394

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

- (Object) add_includes(out, includes)

Adds includes to out



401
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
437
438
439
440
441
442
 
# File 'lib/rdoc/ri/driver.rb', line 401

def add_includes out, includes
  return if includes.empty?

  out << RDoc::Markup::Rule.new(1)
  out << RDoc::Markup::Heading.new(1, "Includes:")

  includes.each do |modules, store|
    if modules.length == 1 then
      include = modules.first
      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
    else
      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
  end
end

- (Object) add_method_list(out, methods, name)

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



447
448
449
450
451
452
453
454
455
456
457
458
 
# File 'lib/rdoc/ri/driver.rb', line 447

def add_method_list out, methods, name
  return unless methods

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

  out.push(*methods.map do |method|
    RDoc::Markup::Verbatim.new method
  end)

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

- (Object) ancestors_of(klass)

Returns ancestor classes of klass



463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
 
# File 'lib/rdoc/ri/driver.rb', line 463

def ancestors_of klass
  ancestors = []

  unexamined = [klass]
  seen = []

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

    stores = classes[current]

    break unless stores and not stores.empty?

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

    klasses = klasses - seen

    ancestors.push(*klasses)
    unexamined.push(*klasses)
  end

  ancestors.reverse
end

- (Object) class_cache

For RubyGems backwards compatibility



494
495
 
# File 'lib/rdoc/ri/driver.rb', line 494

def class_cache # :nodoc:
end

- (Object) classes

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



500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
 
# File 'lib/rdoc/ri/driver.rb', line 500

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

- (Object) complete(name)

Completes name based on the caches. For Readline



519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
 
# File 'lib/rdoc/ri/driver.rb', line 519

def complete name
  klasses = classes.keys
  completions = []

  klass, selector, method = parse_name name

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

  if name !~ /#|\./ then
    completions.push(*klasses.grep(/^#{klass_name}/))
  elsif selector then
    completions << klass if classes.key? klass
  elsif classes.key? klass_name then
    completions << klass_name
  end

  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.push(*methods)
  end

  completions.sort
end

- (Object) display(document)

Converts document to text and writes it to the pager



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

def display document
  page do |io|
    text = document.accept formatter(io)

    io.write text
  end
end

- (Object) display_class(name)

Outputs formatted RI data for class name. Groups undocumented classes



568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
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
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
 
# File 'lib/rdoc/ri/driver.rb', line 568

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

  klasses = []
  includes = []

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

  return if found.empty?

  also_in = []

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

  out = RDoc::Markup::Document.new

  add_class out, name, klasses

  add_includes out, includes

  found.each do |store, klass|
    comment = klass.comment
    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 or class_methods) then
      also_in << store
      next
    end

    add_from out, store

    unless comment.empty? then
      out << RDoc::Markup::Rule.new(1)
      out << comment
    end

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

    unless klass.constants.empty? then
      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.push(*constants.map do |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)
      end)

      out << list
    end

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

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

  add_also_in out, also_in

  display out
end

- (Object) display_method(name)

Outputs formatted RI data for method name

Raises:



651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
 
# File 'lib/rdoc/ri/driver.rb', line 651

def display_method name
  found = load_methods_matching name

  raise NotFoundError, name if found.empty?

  filtered = filter_methods found, name

  out = RDoc::Markup::Document.new

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

  filtered.each do |store, methods|
    methods.each do |method|
      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)

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

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

  display out
end

- (Object) display_name(name)

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.



694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
 
# File 'lib/rdoc/ri/driver.rb', line 694

def display_name name
  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(/^#{name}/) if matches.empty?

  raise if matches.empty?

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

  false
end

- (Object) display_names(names)

Displays each name in name



718
719
720
721
722
723
724
 
# File 'lib/rdoc/ri/driver.rb', line 718

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

    display_name name
  end
end

- (Object) expand_class(klass)

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



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

def expand_class klass
  klass.split('::').inject '' do |expanded, klass_part|
    expanded << '::' unless expanded.empty?
    short = expanded << klass_part

    subset = classes.keys.select do |klass_name|
      klass_name =~ /^#{expanded}[^:]*$/
    end

    abbrevs = Abbrev.abbrev subset

    expanded = abbrevs[short]

    raise NotFoundError, short unless expanded

    expanded.dup
  end
end

- (Object) expand_name(name)

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



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

def expand_name name
  klass, selector, method = parse_name name

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

  "#{expand_class klass}#{selector}#{method}"
end

- (Object) filter_methods(found, name)

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



763
764
765
766
767
768
769
770
771
772
773
 
# File 'lib/rdoc/ri/driver.rb', line 763

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

- (Object) find_methods(name)

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



781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
 
# File 'lib/rdoc/ri/driver.rb', line 781

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

- (Object) formatter(io)

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.



825
826
827
828
829
830
831
832
833
 
# File 'lib/rdoc/ri/driver.rb', line 825

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

- (Boolean) in_path?(file)

Is file in ENV?

Returns:

  • (Boolean) 


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

def in_path? file
  return true if file =~ %r%\A/% and File.exist? file

  ENV['PATH'].split(File::PATH_SEPARATOR).any? do |path|
    File.exist? File.join(path, file)
  end
end

- (Object) interactive

Runs ri interactively using Readline if it is available.



838
839
840
841
842
843
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
869
 
# File 'lib/rdoc/ri/driver.rb', line 838

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

  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 ">> "
           else
             print ">> "
             $stdin.gets
           end

    return if name.nil? or name.empty?

    name = expand_name name.strip

    begin
      display_name name
    rescue NotFoundError => e
      puts e.message
    end
  end

rescue Interrupt
  exit
end

- (Object) list_known_classes

Lists classes known to ri



885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
 
# File 'lib/rdoc/ri/driver.rb', line 885

def list_known_classes
  classes = []

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

  classes = classes.flatten.uniq.sort

  page do |io|
    if paging? or io.tty? then
      io.puts "Classes and Modules known to ri:"
      io.puts
    end

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

- (Object) list_methods_matching(name)

Returns an Array of methods matching name



907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
 
# File 'lib/rdoc/ri/driver.rb', line 907

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(/^#{method}/)

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

        found.push(*matches)
      end
    end

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

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

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

      found.push(*matches)
    end
  end

  found.uniq
end

- (Object) load_method(store, cache, klass, type, name)

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



946
947
948
949
950
951
952
953
954
955
956
957
958
 
# File 'lib/rdoc/ri/driver.rb', line 946

def load_method store, cache, klass, type, name
  methods = store.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}"
end

- (Object) load_methods_matching(name)

Returns an Array of RI data for methods matching name



963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
 
# File 'lib/rdoc/ri/driver.rb', line 963

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

- (Object) method_type(selector)

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



984
985
986
987
988
989
990
 
# File 'lib/rdoc/ri/driver.rb', line 984

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

- (Object) name_regexp(name)

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



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

def name_regexp name
  klass, type, name = parse_name name

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

- (Object) page

Paginates output through a pager program.



1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
 
# File 'lib/rdoc/ri/driver.rb', line 1010

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

- (Boolean) paging?

Are we using a pager?

Returns:

  • (Boolean) 


1028
1029
1030
 
# File 'lib/rdoc/ri/driver.rb', line 1028

def paging?
  @paging
end

- (Object) parse_name(name)

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


1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
 
# File 'lib/rdoc/ri/driver.rb', line 1039

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[-2] != '::' or parts.last !~ /^[A-Z]/ then
    meth = parts.pop
    type = parts.pop
  end

  klass = parts.join

  [klass, type, meth]
end

- (Object) run

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



1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
 
# File 'lib/rdoc/ri/driver.rb', line 1066

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

- (Object) setup_pager

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



1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
 
# File 'lib/rdoc/ri/driver.rb', line 1084

def setup_pager
  return if @use_stdout

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

  pagers.compact.uniq.each do |pager|
    next unless pager

    pager_cmd = pager.split.first

    next unless in_path? pager_cmd

    io = IO.popen(pager, 'w') rescue next

    next if $? and $?.exited? # pager didn't work

    @paging = true

    return io
  end

  @use_stdout = true

  nil
end