Class: RDoc::Parser::Ruby

Inherits:
RDoc::Parser show all
Includes:
RubyTools, TokenStream
Defined in:
lib/rdoc/parser/ruby.rb

Constant Summary collapse

NORMAL =

RDoc::NormalClass type

"::"
SINGLE =

RDoc::SingleClass type

"<<"

Instance Attribute Summary

Attributes inherited from RDoc::Parser

#file_name

Instance Method Summary collapse

Methods included from RubyTools

#add_token_listener, #get_tk, #get_tk_until, #get_tkread, #peek_read, #peek_tk, #remove_token_listener, #reset, #skip_tkspace, #skip_tkspace_without_nl, #token_listener, #unget_tk

Methods included from TokenStream

#add_token, #add_tokens, #collect_tokens, #pop_token, to_html, #token_stream, #tokens_to_s

Methods inherited from RDoc::Parser

alias_extension, binary?, can_parse, can_parse_by_name, check_modeline, for, parse_files_matching, remove_modeline, use_markup, zip?

Constructor Details

#initialize(top_level, file_name, content, options, stats) ⇒ Ruby

Creates a new Ruby parser.



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
 
# File 'lib/rdoc/parser/ruby.rb', line 164

def initialize(top_level, file_name, content, options, stats)
  super

  if /\t/ =~ content then
    tab_width = @options.tab_width
    content = content.split(/\n/).map do |line|
      1 while line.gsub!(/\t+/) {
        ' ' * (tab_width*$&.length - $`.length % tab_width)
      }  && $~
      line
    end.join("\n")
  end

  @size = 0
  @token_listeners = nil
  content = RDoc::Encoding.remove_magic_comment content
  @scanner = RDoc::Parser::RipperStateLex.parse(content)
  @content = content
  @scanner_point = 0
  @prev_seek = nil
  @markup = @options.markup
  @track_visibility = :nodoc != @options.visibility
  @encoding = @options.encoding

  reset
end

Instance Method Details

#collect_first_comment ⇒ Object

Look for the first comment in a file that isn’t a shebang line.



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
 
# File 'lib/rdoc/parser/ruby.rb', line 241

def collect_first_comment
  skip_tkspace
  comment = ''.dup
  comment = RDoc::Encoding.change_encoding comment, @encoding if @encoding
  first_line = true
  first_comment_tk_kind = nil
  line_no = nil

  tk = get_tk

  while tk && (:on_comment == tk[:kind] or :on_embdoc == tk[:kind])
    comment_body = retrieve_comment_body(tk)
    if first_line and comment_body =~ /\A#!/ then
      skip_tkspace
      tk = get_tk
    elsif first_line and comment_body =~ /\A#\s*-\*-/ then
      first_line = false
      skip_tkspace
      tk = get_tk
    else
      break if first_comment_tk_kind and not first_comment_tk_kind === tk[:kind]
      first_comment_tk_kind = tk[:kind]

      line_no = tk[:line_no] if first_line
      first_line = false
      comment << comment_body
      tk = get_tk

      if :on_nl === tk then
        skip_tkspace_without_nl
        tk = get_tk
      end
    end
  end

  unget_tk tk

  new_comment comment, line_no
end

#consume_trailing_spaces ⇒ Object

Consumes trailing whitespace from the token stream



284
285
286
 
# File 'lib/rdoc/parser/ruby.rb', line 284

def consume_trailing_spaces # :nodoc:
  skip_tkspace_without_nl
end

#create_attr(container, single, name, rw, comment) ⇒ Object

Creates a new attribute in container with name.



291
292
293
294
295
296
297
298
299
 
# File 'lib/rdoc/parser/ruby.rb', line 291

def create_attr container, single, name, rw, comment # :nodoc:
  att = RDoc::Attr.new get_tkread, name, rw, comment, single == SINGLE
  record_location att

  container.add_attribute att
  @stats.add_attribute att

  att
end

#create_module_alias(container, constant, rhs_name) ⇒ Object

Creates a module alias in container at rhs_name (or at the top-level for “::”) with the name from constant.



305
306
307
308
309
310
311
312
313
 
# File 'lib/rdoc/parser/ruby.rb', line 305

def create_module_alias container, constant, rhs_name # :nodoc:
  mod = if rhs_name =~ /^::/ then
          @store.find_class_or_module rhs_name
        else
          container.find_module_named rhs_name
        end

  container.add_module_alias mod, rhs_name, constant, @top_level
end

#error(msg) ⇒ Object

Aborts with msg



318
319
320
321
322
 
# File 'lib/rdoc/parser/ruby.rb', line 318

def error(msg)
  msg = make_message msg

  abort msg
end

#get_bool ⇒ Object

Looks for a true or false token.



327
328
329
330
331
332
333
334
335
336
337
338
 
# File 'lib/rdoc/parser/ruby.rb', line 327

def get_bool
  skip_tkspace
  tk = get_tk
  if :on_kw == tk[:kind] && 'true' == tk[:text]
    true
  elsif :on_kw == tk[:kind] && ('false' == tk[:text] || 'nil' == tk[:text])
    false
  else
    unget_tk tk
    true
  end
end

#get_class_or_module(container, ignore_constants = false) ⇒ Object

Look for the name of a class of module (optionally with a leading

or

with

separated named) and return the ultimate name, the associated

container, and the given name (with the ::).



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
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
 
# File 'lib/rdoc/parser/ruby.rb', line 345

def get_class_or_module container, ignore_constants = false
  skip_tkspace
  name_t = get_tk
  given_name = ''.dup

  # class ::A -> A is in the top level
  if :on_op == name_t[:kind] and '::' == name_t[:text] then # bug
    name_t = get_tk
    container = @top_level
    given_name << '::'
  end

  skip_tkspace_without_nl
  given_name << name_t[:text]

  is_self = name_t[:kind] == :on_op && name_t[:text] == '<<'
  new_modules = []
  while !is_self && (tk = peek_tk) and :on_op == tk[:kind] and '::' == tk[:text] do
    prev_container = container
    container = container.find_module_named name_t[:text]
    container ||=
      if ignore_constants then
        c = RDoc::NormalModule.new name_t[:text]
        c.store = @store
        new_modules << [prev_container, c]
        c
      else
        c = prev_container.add_module RDoc::NormalModule, name_t[:text]
        c.ignore unless prev_container.document_children
        @top_level.add_to_classes_or_modules c
        c
      end

    record_location container

    get_tk
    skip_tkspace
    if :on_lparen == peek_tk[:kind] # ProcObjectInConstant::()
      parse_method_or_yield_parameters
      break
    end
    name_t = get_tk
    unless :on_const == name_t[:kind] || :on_ident == name_t[:kind]
      raise RDoc::Error, "Invalid class or module definition: #{given_name}"
    end
    if prev_container == container and !ignore_constants
      given_name = name_t[:text]
    else
      given_name << '::' + name_t[:text]
    end
  end

  skip_tkspace_without_nl

  return [container, name_t, given_name, new_modules]
end

#get_class_specification ⇒ Object

Return a superclass, which can be either a constant of an expression



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
 
# File 'lib/rdoc/parser/ruby.rb', line 405

def get_class_specification
  tk = peek_tk
  if tk.nil?
    return ''
  elsif :on_kw == tk[:kind] && 'self' == tk[:text]
    return 'self'
  elsif :on_gvar == tk[:kind]
    return ''
  end

  res = get_constant

  skip_tkspace_without_nl

  get_tkread # empty out read buffer

  tk = get_tk
  return res unless tk

  case tk[:kind]
  when :on_nl, :on_comment, :on_embdoc, :on_semicolon then
    unget_tk(tk)
    return res
  end

  res += parse_call_parameters(tk)
  res
end

#get_constant ⇒ Object

Parse a constant, which might be qualified by one or more class or module names



438
439
440
441
442
443
444
445
446
447
448
449
450
 
# File 'lib/rdoc/parser/ruby.rb', line 438

def get_constant
  res = ""
  skip_tkspace_without_nl
  tk = get_tk

  while tk && ((:on_op == tk[:kind] && '::' == tk[:text]) || :on_const == tk[:kind]) do
    res += tk[:text]
    tk = get_tk
  end

  unget_tk(tk)
  res
end

#get_end_token(tk) ⇒ Object

Little hack going on here. In the statement:

f = 2*(1+yield)

We see the RPAREN as the next token, so we need to exit early. This still won’t catch all cases (such as “a = yield + 1”



540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
 
# File 'lib/rdoc/parser/ruby.rb', line 540

def get_end_token tk # :nodoc:
  case tk[:kind]
  when :on_lparen
    token = RDoc::Parser::RipperStateLex::Token.new
    token[:kind] = :on_rparen
    token[:text] = ')'
    token
  when :on_rparen
    nil
  else
    token = RDoc::Parser::RipperStateLex::Token.new
    token[:kind] = :on_nl
    token[:text] = "\n"
    token
  end
end

#get_included_module_with_optional_parens ⇒ Object

Get an included module that may be surrounded by parens



455
456
457
458
459
460
461
462
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
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
 
# File 'lib/rdoc/parser/ruby.rb', line 455

def get_included_module_with_optional_parens
  skip_tkspace_without_nl
  get_tkread
  tk = get_tk
  end_token = get_end_token tk
  return '' unless end_token

  nest = 0
  continue = false
  only_constant = true

  while tk != nil do
    is_element_of_constant = false
    case tk[:kind]
    when :on_semicolon then
      break if nest == 0
    when :on_lbracket then
      nest += 1
    when :on_rbracket then
      nest -= 1
    when :on_lbrace then
      nest += 1
    when :on_rbrace then
      nest -= 1
      if nest <= 0
        # we might have a.each { |i| yield i }
        unget_tk(tk) if nest < 0
        break
      end
    when :on_lparen then
      nest += 1
    when end_token[:kind] then
      if end_token[:kind] == :on_rparen
        nest -= 1
        break if nest <= 0
      else
        break if nest <= 0
      end
    when :on_rparen then
      nest -= 1
    when :on_comment, :on_embdoc then
      @read.pop
      if :on_nl == end_token[:kind] and "\n" == tk[:text][-1] and
        (!continue or (tk[:state] & RDoc::Parser::RipperStateLex::EXPR_LABEL) != 0) then
        break if !continue and nest <= 0
      end
    when :on_comma then
      continue = true
    when :on_ident then
      continue = false if continue
    when :on_kw then
      case tk[:text]
      when 'def', 'do', 'case', 'for', 'begin', 'class', 'module'
        nest += 1
      when 'if', 'unless', 'while', 'until', 'rescue'
        # postfix if/unless/while/until/rescue must be EXPR_LABEL
        nest += 1 unless (tk[:state] & RDoc::Parser::RipperStateLex::EXPR_LABEL) != 0
      when 'end'
        nest -= 1
        break if nest == 0
      end
    when :on_const then
      is_element_of_constant = true
    when :on_op then
      is_element_of_constant = true if '::' == tk[:text]
    end
    only_constant = false unless is_element_of_constant
    tk = get_tk
  end

  if only_constant
    get_tkread_clean(/\s+/, ' ')
  else
    ''
  end
end

#get_method_container(container, name_t) ⇒ Object

Retrieves the method container for a singleton method.



560
561
562
563
564
565
566
567
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
 
# File 'lib/rdoc/parser/ruby.rb', line 560

def get_method_container container, name_t # :nodoc:
  prev_container = container
  container = container.find_module_named(name_t[:text])

  unless container then
    constant = prev_container.constants.find do |const|
      const.name == name_t[:text]
    end

    if constant then
      parse_method_dummy prev_container
      return
    end
  end

  unless container then
    # TODO seems broken, should starting at Object in @store
    obj = name_t[:text].split("::").inject(Object) do |state, item|
      state.const_get(item)
    end rescue nil

    type = obj.class == Class ? RDoc::NormalClass : RDoc::NormalModule

    unless [Class, Module].include?(obj.class) then
      warn("Couldn't find #{name_t[:text]}. Assuming it's a module")
    end

    if type == RDoc::NormalClass then
      sclass = obj.superclass ? obj.superclass.name : nil
      container = prev_container.add_class type, name_t[:text], sclass
    else
      container = prev_container.add_module type, name_t[:text]
    end

    record_location container
  end

  container
end

#get_symbol_or_name ⇒ Object

Extracts a name or symbol from the token stream.



603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
 
# File 'lib/rdoc/parser/ruby.rb', line 603

def get_symbol_or_name
  tk = get_tk
  case tk[:kind]
  when :on_symbol then
    text = tk[:text].sub(/^:/, '')

    next_tk = peek_tk
    if next_tk && :on_op == next_tk[:kind] && '=' == next_tk[:text] then
      get_tk
      text << '='
    end

    text
  when :on_ident, :on_const, :on_gvar, :on_cvar, :on_ivar, :on_op, :on_kw then
    tk[:text]
  when :on_tstring, :on_dstring then
    tk[:text][1..-2]
  else
    raise RDoc::Error, "Name or symbol expected (got #{tk})"
  end
end

#get_tkread_clean(pattern, replacement) ⇒ Object

Retrieves the read token stream and replaces pattern with replacement using gsub. If the result is only a “;” returns an empty string.



199
200
201
202
203
 
# File 'lib/rdoc/parser/ruby.rb', line 199

def get_tkread_clean pattern, replacement # :nodoc:
  read = get_tkread.gsub(pattern, replacement).strip
  return '' if read == ';'
  read
end

#get_visibility_information(tk, single) ⇒ Object

Extracts the visibility information for the visibility token tk and single class type identifier.

Returns the visibility type (a string), the visibility (a symbol) and singleton if the methods following should be converted to singleton methods.



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/rdoc/parser/ruby.rb', line 213

def get_visibility_information tk, single # :nodoc:
  vis_type  = tk[:text]
  singleton = single == SINGLE

  vis =
    case vis_type
    when 'private'   then :private
    when 'protected' then :protected
    when 'public'    then :public
    when 'private_class_method' then
      singleton = true
      :private
    when 'public_class_method' then
      singleton = true
      :public
    when 'module_function' then
      singleton = true
      :public
    else
      raise RDoc::Error, "Invalid visibility: #{tk.name}"
    end

  return vis_type, vis, singleton
end

#look_for_directives_in(container, comment) ⇒ Object

Look for directives in a normal comment block:

# :stopdoc:
# Don't display comment from this point forward

This routine modifies its comment parameter.



643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
 
# File 'lib/rdoc/parser/ruby.rb', line 643

def look_for_directives_in container, comment
  @preprocess.handle comment, container do |directive, param|
    case directive
    when 'method', 'singleton-method',
         'attr', 'attr_accessor', 'attr_reader', 'attr_writer' then
      false # handled elsewhere
    when 'section' then
      break unless container.kind_of?(RDoc::Context)
      container.set_current_section param, comment.dup
      comment.text = ''
      break
    end
  end

  comment.remove_private
end

#make_message(message) ⇒ Object

Adds useful info about the parser to message



663
664
665
666
667
668
669
670
 
# File 'lib/rdoc/parser/ruby.rb', line 663

def make_message message
  prefix = "#{@file_name}:".dup

  tk = peek_tk
  prefix << "#{tk[:line_no]}:#{tk[:char_no]}:" if tk

  "#{prefix} #{message}"
end

#new_comment(comment, line_no = nil) ⇒ Object

Creates a comment with the correct format



675
676
677
678
679
680
 
# File 'lib/rdoc/parser/ruby.rb', line 675

def new_comment comment, line_no = nil
  c = RDoc::Comment.new comment, @top_level, :ruby
  c.line = line_no
  c.format = @markup
  c
end

#parse_alias(context, single, tk, comment) ⇒ Object

Parses an alias in context with comment



744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
 
# File 'lib/rdoc/parser/ruby.rb', line 744

def parse_alias(context, single, tk, comment)
  line_no = tk[:line_no]

  skip_tkspace

  if :on_lparen === peek_tk[:kind] then
    get_tk
    skip_tkspace
  end

  new_name = get_symbol_or_name

  skip_tkspace
  if :on_comma === peek_tk[:kind] then
    get_tk
    skip_tkspace
  end

  begin
    old_name = get_symbol_or_name
  rescue RDoc::Error
    return
  end

  al = RDoc::Alias.new(get_tkread, old_name, new_name, comment,
                       single == SINGLE)
  record_location al
  al.line   = line_no

  read_documentation_modifiers al, RDoc::ATTR_MODIFIERS
  context.add_alias al
  @stats.add_alias al

  al
end

#parse_attr(context, single, tk, comment) ⇒ Object

Creates an RDoc::Attr for the name following tk, setting the comment to comment.



686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
 
# File 'lib/rdoc/parser/ruby.rb', line 686

def parse_attr(context, single, tk, comment)
  line_no = tk[:line_no]

  args = parse_symbol_arg 1
  if args.size > 0 then
    name = args[0]
    rw = "R"
    skip_tkspace_without_nl
    tk = get_tk

    if :on_comma == tk[:kind] then
      rw = "RW" if get_bool
    else
      unget_tk tk
    end

    att = create_attr context, single, name, rw, comment
    att.line   = line_no

    read_documentation_modifiers att, RDoc::ATTR_MODIFIERS
  else
    warn "'attr' ignored - looks like a variable"
  end
end

#parse_attr_accessor(context, single, tk, comment) ⇒ Object

Creates an RDoc::Attr for each attribute listed after tk, setting the comment for each to comment.



715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
 
# File 'lib/rdoc/parser/ruby.rb', line 715

def parse_attr_accessor(context, single, tk, comment)
  line_no = tk[:line_no]

  args = parse_symbol_arg
  rw = "?"

  tmp = RDoc::CodeObject.new
  read_documentation_modifiers tmp, RDoc::ATTR_MODIFIERS
  # TODO In most other places we let the context keep track of document_self
  # and add found items appropriately but here we do not.  I'm not sure why.
  return if @track_visibility and not tmp.document_self

  case tk[:text]
  when "attr_reader"   then rw = "R"
  when "attr_writer"   then rw = "W"
  when "attr_accessor" then rw = "RW"
  else
    rw = '?'
  end

  for name in args
    att = create_attr context, single, name, rw, comment
    att.line   = line_no
  end
end

#parse_call_parameters(tk) ⇒ Object

Extracts call parameters from the token stream.



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
820
821
 
# File 'lib/rdoc/parser/ruby.rb', line 783

def parse_call_parameters(tk)
  end_token = case tk[:kind]
              when :on_lparen
                :on_rparen
              when :on_rparen
                return ""
              else
                :on_nl
              end
  nest = 0

  loop do
    break if tk.nil?
    case tk[:kind]
    when :on_semicolon
      break
    when :on_lparen
      nest += 1
    when end_token
      if end_token == :on_rparen
        nest -= 1
        break if RDoc::Parser::RipperStateLex.end?(tk) and nest <= 0
      else
        break if RDoc::Parser::RipperStateLex.end?(tk)
      end
    when :on_comment, :on_embdoc
      unget_tk(tk)
      break
    when :on_op
      if tk[:text] =~ /^(.{1,2})?=$/
        unget_tk(tk)
        break
      end
    end
    tk = get_tk
  end

  get_tkread_clean "\n", " "
end

#parse_class(container, single, tk, comment) ⇒ Object

Parses a class in context with comment



826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
 
# File 'lib/rdoc/parser/ruby.rb', line 826

def parse_class container, single, tk, comment
  line_no = tk[:line_no]

  declaration_context = container
  container, name_t, given_name, = get_class_or_module container

  if name_t[:kind] == :on_const
    cls = parse_class_regular container, declaration_context, single,
      name_t, given_name, comment
  elsif name_t[:kind] == :on_op && name_t[:text] == '<<'
    case name = get_class_specification
    when 'self', container.name
      read_documentation_modifiers cls, RDoc::CLASS_MODIFIERS
      parse_statements container, SINGLE
      return # don't update line
    else
      cls = parse_class_singleton container, name, comment
    end
  else
    warn "Expected class name or '<<'. Got #{name_t[:kind]}: #{name_t[:text].inspect}"
    return
  end

  cls.line   = line_no

  # after end modifiers
  read_documentation_modifiers cls, RDoc::CLASS_MODIFIERS

  cls
end

#parse_class_regular(container, declaration_context, single, name_t, given_name, comment) ⇒ Object

Parses and creates a regular class



860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
 
# File 'lib/rdoc/parser/ruby.rb', line 860

def parse_class_regular container, declaration_context, single, # :nodoc:
                        name_t, given_name, comment
  superclass = '::Object'

  if given_name =~ /^::/ then
    declaration_context = @top_level
    given_name = $'
  end

  tk = peek_tk
  if tk[:kind] == :on_op && tk[:text] == '<' then
    get_tk
    skip_tkspace
    superclass = get_class_specification
    superclass = '(unknown)' if superclass.empty?
  end

  cls_type = single == SINGLE ? RDoc::SingleClass : RDoc::NormalClass
  cls = declaration_context.add_class cls_type, given_name, superclass
  cls.ignore unless container.document_children

  read_documentation_modifiers cls, RDoc::CLASS_MODIFIERS
  record_location cls

  cls.add_comment comment, @top_level

  @top_level.add_to_classes_or_modules cls
  @stats.add_class cls

  suppress_parents container, declaration_context unless cls.document_self

  parse_statements cls

  cls
end

#parse_class_singleton(container, name, comment) ⇒ Object

Parses a singleton class in container with the given name and comment.



900
901
902
903
904
905
906
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
 
# File 'lib/rdoc/parser/ruby.rb', line 900

def parse_class_singleton container, name, comment # :nodoc:
  other = @store.find_class_named name

  unless other then
    if name =~ /^::/ then
      name = $'
      container = @top_level
    end

    other = container.add_module RDoc::NormalModule, name
    record_location other

    # class << $gvar
    other.ignore if name.empty?

    other.add_comment comment, @top_level
  end

  # notify :nodoc: all if not a constant-named class/module
  # (and remove any comment)
  unless name =~ /\A(::)?[A-Z]/ then
    other.document_self = nil
    other.document_children = false
    other.clear_comment
  end

  @top_level.add_to_classes_or_modules other
  @stats.add_class other

  read_documentation_modifiers other, RDoc::CLASS_MODIFIERS
  parse_statements(other, SINGLE)

  other
end

#parse_comment(container, tk, comment) ⇒ Object

Generates an RDoc::Method or RDoc::Attr from comment by looking for :method: or :attr: directives in comment.



1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
 
# File 'lib/rdoc/parser/ruby.rb', line 1065

def parse_comment container, tk, comment
  return parse_comment_tomdoc container, tk, comment if @markup == 'tomdoc'
  column  = tk[:char_no]
  line_no = comment.line.nil? ? tk[:line_no] : comment.line

  comment.text = comment.text.sub(/(^# +:?)(singleton-)(method:)/, '\1\3')
  singleton = !!$~

  co =
    if (comment.text = comment.text.sub(/^# +:?method: *(\S*).*?\n/i, '')) && !!$~ then
      line_no += $`.count("\n")
      parse_comment_ghost container, comment.text, $1, column, line_no, comment
    elsif (comment.text = comment.text.sub(/# +:?(attr(_reader|_writer|_accessor)?): *(\S*).*?\n/i, '')) && !!$~ then
      parse_comment_attr container, $1, $3, comment
    end

  if co then
    co.singleton = singleton
    co.line      = line_no
  end

  true
end

#parse_comment_attr(container, type, name, comment) ⇒ Object

Parse a comment that is describing an attribute in container with the given name and comment.



1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
 
# File 'lib/rdoc/parser/ruby.rb', line 1093

def parse_comment_attr container, type, name, comment # :nodoc:
  return if name.empty?

  rw = case type
       when 'attr_reader' then 'R'
       when 'attr_writer' then 'W'
       else 'RW'
       end

  create_attr container, NORMAL, name, rw, comment
end

#parse_comment_ghost(container, text, name, column, line_no, comment) ⇒ Object

:nodoc:



1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
 
# File 'lib/rdoc/parser/ruby.rb', line 1105

def parse_comment_ghost container, text, name, column, line_no, # :nodoc:
                        comment
  name = nil if name.empty?

  meth = RDoc::GhostMethod.new get_tkread, name
  record_location meth

  meth.start_collecting_tokens
  indent = RDoc::Parser::RipperStateLex::Token.new(1, 1, :on_sp, ' ' * column)
  position_comment = RDoc::Parser::RipperStateLex::Token.new(line_no, 1, :on_comment)
  position_comment[:text] = "# File #{@top_level.relative_name}, line #{line_no}"
  newline = RDoc::Parser::RipperStateLex::Token.new(0, 0, :on_nl, "\n")
  meth.add_tokens [position_comment, newline, indent]

  meth.params =
    if text.sub!(/^#\s+:?args?:\s*(.*?)\s*$/i, '') then
      $1
    else
      ''
    end

  comment.normalize
  comment.extract_call_seq meth

  return unless meth.name

  container.add_method meth

  meth.comment = comment

  @stats.add_method meth

  meth
end

#parse_comment_tomdoc(container, tk, comment) ⇒ Object

Creates an RDoc::Method on container from comment if there is a Signature section in the comment



1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
 
# File 'lib/rdoc/parser/ruby.rb', line 1144

def parse_comment_tomdoc container, tk, comment
  return unless signature = RDoc::TomDoc.signature(comment)
  column  = tk[:char_no]
  line_no = tk[:line_no]

  name, = signature.split %r%[ \(]%, 2

  meth = RDoc::GhostMethod.new get_tkread, name
  record_location meth
  meth.line      = line_no

  meth.start_collecting_tokens
  indent = RDoc::Parser::RipperStateLex::Token.new(1, 1, :on_sp, ' ' * column)
  position_comment = RDoc::Parser::RipperStateLex::Token.new(line_no, 1, :on_comment)
  position_comment[:text] = "# File #{@top_level.relative_name}, line #{line_no}"
  newline = RDoc::Parser::RipperStateLex::Token.new(0, 0, :on_nl, "\n")
  meth.add_tokens [position_comment, newline, indent]

  meth.call_seq = signature

  comment.normalize

  return unless meth.name

  container.add_method meth

  meth.comment = comment

  @stats.add_method meth
end

#parse_constant(container, tk, comment, ignore_constants = false) ⇒ Object

Parses a constant in context with comment. If ignore_constants is true, no found constants will be added to RDoc.



939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
 
# File 'lib/rdoc/parser/ruby.rb', line 939

def parse_constant container, tk, comment, ignore_constants = false
  line_no = tk[:line_no]

  name = tk[:text]
  skip_tkspace_without_nl

  return unless name =~ /^\w+$/

  new_modules = []
  if :on_op == peek_tk[:kind] && '::' == peek_tk[:text] then
    unget_tk tk

    container, name_t, _, new_modules = get_class_or_module container, true

    name = name_t[:text]
  end

  is_array_or_hash = false
  if peek_tk && :on_lbracket == peek_tk[:kind]
    get_tk
    nest = 1
    while bracket_tk = get_tk
      case bracket_tk[:kind]
      when :on_lbracket
        nest += 1
      when :on_rbracket
        nest -= 1
        break if nest == 0
      end
    end
    skip_tkspace_without_nl
    is_array_or_hash = true
  end

  unless peek_tk && :on_op == peek_tk[:kind] && '=' == peek_tk[:text] then
    return false
  end
  get_tk

  unless ignore_constants
    new_modules.each do |prev_c, new_module|
      prev_c.add_module_by_normal_module new_module
      new_module.ignore unless prev_c.document_children
      @top_level.add_to_classes_or_modules new_module
    end
  end

  value = ''
  con = RDoc::Constant.new name, value, comment

  body = parse_constant_body container, con, is_array_or_hash

  return unless body

  con.value = body
  record_location con
  con.line   = line_no
  read_documentation_modifiers con, RDoc::CONSTANT_MODIFIERS

  return if is_array_or_hash

  @stats.add_constant con
  container.add_constant con

  true
end

#parse_constant_body(container, constant, is_array_or_hash) ⇒ Object

:nodoc:



1006
1007
1008
1009
1010
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
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
 
# File 'lib/rdoc/parser/ruby.rb', line 1006

def parse_constant_body container, constant, is_array_or_hash # :nodoc:
  nest     = 0
  rhs_name = ''.dup

  get_tkread

  tk = get_tk

  body = nil
  loop do
    break if tk.nil?
    if :on_semicolon == tk[:kind] then
      break if nest <= 0
    elsif [:on_tlambeg, :on_lparen, :on_lbrace, :on_lbracket].include?(tk[:kind]) then
      nest += 1
    elsif (:on_kw == tk[:kind] && 'def' == tk[:text]) then
      nest += 1
    elsif (:on_kw == tk[:kind] && %w{do if unless case begin}.include?(tk[:text])) then
      if (tk[:state] & RDoc::Parser::RipperStateLex::EXPR_LABEL) == 0
        nest += 1
      end
    elsif [:on_rparen, :on_rbrace, :on_rbracket].include?(tk[:kind]) ||
          (:on_kw == tk[:kind] && 'end' == tk[:text]) then
      nest -= 1
    elsif (:on_comment == tk[:kind] or :on_embdoc == tk[:kind]) then
      unget_tk tk
      if nest <= 0 and RDoc::Parser::RipperStateLex.end?(tk) then
        body = get_tkread_clean(/^[ \t]+/, '')
        read_documentation_modifiers constant, RDoc::CONSTANT_MODIFIERS
        break
      else
        read_documentation_modifiers constant, RDoc::CONSTANT_MODIFIERS
      end
    elsif :on_const == tk[:kind] then
      rhs_name << tk[:text]

      next_tk = peek_tk
      if nest <= 0 and (next_tk.nil? || :on_nl == next_tk[:kind]) then
        create_module_alias container, constant, rhs_name unless is_array_or_hash
        break
      end
    elsif :on_nl == tk[:kind] then
      if nest <= 0 and RDoc::Parser::RipperStateLex.end?(tk) then
        unget_tk tk
        break
      end
    elsif :on_op == tk[:kind] && '::' == tk[:text]
      rhs_name << '::'
    end
    tk = get_tk
  end

  body ? body : get_tkread_clean(/^[ \t]+/, '')
end

#parse_constant_visibility(container, single, tk) ⇒ Object

Parses a Module#private_constant or Module#public_constant call from tk.



2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
 
# File 'lib/rdoc/parser/ruby.rb', line 2058

def parse_constant_visibility(container, single, tk)
  args = parse_symbol_arg
  case tk[:text]
  when 'private_constant'
    vis = :private
  when 'public_constant'
    vis = :public
  else
    raise RDoc::Error, 'Unreachable'
  end
  container.set_constant_visibility_for args, vis
end

#parse_extend_or_include(klass, container, comment) ⇒ Object

Parses an include or extend, indicated by the klass and adds it to container # with comment



1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
 
# File 'lib/rdoc/parser/ruby.rb', line 1179

def parse_extend_or_include klass, container, comment # :nodoc:
  loop do
    skip_tkspace_comment

    name = get_included_module_with_optional_parens

    unless name.empty? then
      obj = container.add klass, name, comment
      record_location obj
    end

    return if peek_tk.nil? || :on_comma != peek_tk[:kind]

    get_tk
  end
end

#parse_identifier(container, single, tk, comment) ⇒ Object

Parses identifiers that can create new methods or change visibility.

Returns true if the comment was not consumed.



1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
 
# File 'lib/rdoc/parser/ruby.rb', line 1201

def parse_identifier container, single, tk, comment # :nodoc:
  case tk[:text]
  when 'private', 'protected', 'public', 'private_class_method',
       'public_class_method', 'module_function' then
    parse_visibility container, single, tk
    return true
  when 'private_constant', 'public_constant'
    parse_constant_visibility container, single, tk
    return true
  when 'attr' then
    parse_attr container, single, tk, comment
  when /^attr_(reader|writer|accessor)$/ then
    parse_attr_accessor container, single, tk, comment
  when 'alias_method' then
    parse_alias container, single, tk, comment
  when 'require', 'include' then
    # ignore
  else
    if comment.text =~ /\A#\#$/ then
      case comment.text
      when /^# +:?attr(_reader|_writer|_accessor)?:/ then
        parse_meta_attr container, single, tk, comment
      else
        method = parse_meta_method container, single, tk, comment
        method.params = container.params if
          container.params
        method.block_params = container.block_params if
          container.block_params
      end
    end
  end

  false
end

#parse_meta_attr(context, single, tk, comment) ⇒ Object

Parses a meta-programmed attribute and creates an RDoc::Attr.

To create foo and bar attributes on class C with comment “My attributes”:

class C

  ##
  # :attr:
  #
  # My attributes

  my_attr :foo, :bar

end

To create a foo attribute on class C with comment “My attribute”:

class C

  ##
  # :attr: foo
  #
  # My attribute

  my_attr :foo, :bar

end



1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
 
# File 'lib/rdoc/parser/ruby.rb', line 1265

def parse_meta_attr(context, single, tk, comment)
  args = parse_symbol_arg
  rw = "?"

  # If nodoc is given, don't document any of them

  tmp = RDoc::CodeObject.new
  read_documentation_modifiers tmp, RDoc::ATTR_MODIFIERS

  regexp = /^# +:?(attr(_reader|_writer|_accessor)?): *(\S*).*?\n/i
  if regexp =~ comment.text then
    comment.text = comment.text.sub(regexp, '')
    rw = case $1
         when 'attr_reader' then 'R'
         when 'attr_writer' then 'W'
         else 'RW'
         end
    name = $3 unless $3.empty?
  end

  if name then
    att = create_attr context, single, name, rw, comment
  else
    args.each do |attr_name|
      att = create_attr context, single, attr_name, rw, comment
    end
  end

  att
end

#parse_meta_method(container, single, tk, comment) ⇒ Object

Parses a meta-programmed method



1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
 
# File 'lib/rdoc/parser/ruby.rb', line 1299

def parse_meta_method(container, single, tk, comment)
  column  = tk[:char_no]
  line_no = tk[:line_no]

  start_collecting_tokens
  add_token tk
  add_token_listener self

  skip_tkspace_without_nl

  comment.text = comment.text.sub(/(^# +:?)(singleton-)(method:)/, '\1\3')
  singleton = !!$~

  name = parse_meta_method_name comment, tk

  return unless name

  meth = RDoc::MetaMethod.new get_tkread, name
  record_location meth
  meth.line   = line_no
  meth.singleton = singleton

  remove_token_listener self

  meth.start_collecting_tokens
  indent = RDoc::Parser::RipperStateLex::Token.new(1, 1, :on_sp, ' ' * column)
  position_comment = RDoc::Parser::RipperStateLex::Token.new(line_no, 1, :on_comment)
  position_comment[:text] = "# File #{@top_level.relative_name}, line #{line_no}"
  newline = RDoc::Parser::RipperStateLex::Token.new(0, 0, :on_nl, "\n")
  meth.add_tokens [position_comment, newline, indent]
  meth.add_tokens @token_stream

  parse_meta_method_params container, single, meth, tk, comment

  meth.comment = comment

  @stats.add_method meth

  meth
end

#parse_meta_method_name(comment, tk) ⇒ Object

Parses the name of a metaprogrammed method. comment is used to determine the name while tk is used in an error message if the name cannot be determined.



1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
 
# File 'lib/rdoc/parser/ruby.rb', line 1345

def parse_meta_method_name comment, tk # :nodoc:
  if comment.text.sub!(/^# +:?method: *(\S*).*?\n/i, '') then
    return $1 unless $1.empty?
  end

  name_t = get_tk

  if :on_symbol == name_t[:kind] then
    name_t[:text][1..-1]
  elsif :on_tstring == name_t[:kind] then
    name_t[:text][1..-2]
  elsif :on_op == name_t[:kind] && '=' == name_t[:text] then # ignore
    remove_token_listener self

    nil
  else
    warn "unknown name token #{name_t.inspect} for meta-method '#{tk[:text]}'"
    'unknown'
  end
end

#parse_meta_method_params(container, single, meth, tk, comment) ⇒ Object

Parses the parameters and block for a meta-programmed method.



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
 
# File 'lib/rdoc/parser/ruby.rb', line 1369

def parse_meta_method_params container, single, meth, tk, comment # :nodoc:
  token_listener meth do
    meth.params = ''

    look_for_directives_in meth, comment
    comment.normalize
    comment.extract_call_seq meth

    container.add_method meth

    last_tk = tk

    while tk = get_tk do
      if :on_semicolon == tk[:kind] then
        break
      elsif :on_nl == tk[:kind] then
        break unless last_tk and :on_comma == last_tk[:kind]
      elsif :on_sp == tk[:kind] then
        # expression continues
      elsif :on_kw == tk[:kind] && 'do' == tk[:text] then
        parse_statements container, single, meth
        break
      else
        last_tk = tk
      end
    end
  end
end

#parse_method(container, single, tk, comment) ⇒ Object

Parses a normal method defined by def



1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
 
# File 'lib/rdoc/parser/ruby.rb', line 1401

def parse_method(container, single, tk, comment)
  singleton = nil
  added_container = false
  name = nil
  column  = tk[:char_no]
  line_no = tk[:line_no]

  start_collecting_tokens
  add_token tk

  token_listener self do
    prev_container = container
    name, container, singleton = parse_method_name container
    added_container = container != prev_container
  end

  return unless name

  meth = RDoc::AnyMethod.new get_tkread, name
  look_for_directives_in meth, comment
  meth.singleton = single == SINGLE ? true : singleton

  record_location meth
  meth.line   = line_no

  meth.start_collecting_tokens
  indent = RDoc::Parser::RipperStateLex::Token.new(1, 1, :on_sp, ' ' * column)
  token = RDoc::Parser::RipperStateLex::Token.new(line_no, 1, :on_comment)
  token[:text] = "# File #{@top_level.relative_name}, line #{line_no}"
  newline = RDoc::Parser::RipperStateLex::Token.new(0, 0, :on_nl, "\n")
  meth.add_tokens [token, newline, indent]
  meth.add_tokens @token_stream

  parse_method_params_and_body container, single, meth, added_container

  comment.normalize
  comment.extract_call_seq meth

  meth.comment = comment

  # after end modifiers
  read_documentation_modifiers meth, RDoc::METHOD_MODIFIERS

  @stats.add_method meth
end

#parse_method_dummy(container) ⇒ Object

Parses a method that needs to be ignored.



1480
1481
1482
1483
1484
1485
 
# File 'lib/rdoc/parser/ruby.rb', line 1480

def parse_method_dummy container
  dummy = RDoc::Context.new
  dummy.parent = container
  dummy.store  = container.store
  skip_method dummy
end

#parse_method_name(container) ⇒ Object

Parses the name of a method in container.

Returns the method name, the container it is in (for def Foo.name) and if it is a singleton or regular method.



1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
 
# File 'lib/rdoc/parser/ruby.rb', line 1493

def parse_method_name container # :nodoc:
  skip_tkspace
  name_t = get_tk
  back_tk = skip_tkspace_without_nl
  singleton = false

  dot = get_tk
  if dot[:kind] == :on_period || (dot[:kind] == :on_op && dot[:text] == '::') then
    singleton = true

    name, container = parse_method_name_singleton container, name_t
  else
    unget_tk dot
    back_tk.reverse_each do |token|
      unget_tk token
    end

    name = parse_method_name_regular container, name_t
  end

  return name, container, singleton
end

#parse_method_name_regular(container, name_t) ⇒ Object

For the given container and initial name token name_t the method name is parsed from the token stream for a regular method.



1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
 
# File 'lib/rdoc/parser/ruby.rb', line 1520

def parse_method_name_regular container, name_t # :nodoc:
  if :on_op == name_t[:kind] && (%w{* & [] []= <<}.include?(name_t[:text])) then
    name_t[:text]
  else
    unless [:on_kw, :on_const, :on_ident].include?(name_t[:kind]) then
      warn "expected method name token, . or ::, got #{name_t.inspect}"
      skip_method container
      return
    end
    name_t[:text]
  end
end

#parse_method_name_singleton(container, name_t) ⇒ Object

For the given container and initial name token name_t the method name and the new container (if necessary) are parsed from the token stream for a singleton method.



1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
 
# File 'lib/rdoc/parser/ruby.rb', line 1538

def parse_method_name_singleton container, name_t # :nodoc:
  skip_tkspace
  name_t2 = get_tk

  if (:on_kw == name_t[:kind] && 'self' == name_t[:text]) || (:on_op == name_t[:kind] && '%' == name_t[:text]) then
    # NOTE: work around '[' being consumed early
    if :on_lbracket == name_t2[:kind]
      get_tk
      name = '[]'
    else
      name = name_t2[:text]
    end
  elsif :on_const == name_t[:kind] then
    name = name_t2[:text]

    container = get_method_container container, name_t

    return unless container

    name
  elsif :on_ident == name_t[:kind] || :on_ivar == name_t[:kind] || :on_gvar == name_t[:kind] then
    parse_method_dummy container

    name = nil
  elsif (:on_kw == name_t[:kind]) && ('true' == name_t[:text] || 'false' == name_t[:text] || 'nil' == name_t[:text]) then
    klass_name = "#{name_t[:text].capitalize}Class"
    container = @store.find_class_named klass_name
    container ||= @top_level.add_class RDoc::NormalClass, klass_name

    name = name_t2[:text]
  else
    warn "unexpected method name token #{name_t.inspect}"
    # break
    skip_method container

    name = nil
  end

  return name, container
end

#parse_method_or_yield_parameters(method = nil, modifiers = RDoc::METHOD_MODIFIERS) ⇒ Object

Extracts yield parameters from method



1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
 
# File 'lib/rdoc/parser/ruby.rb', line 1582

def parse_method_or_yield_parameters(method = nil,
                                     modifiers = RDoc::METHOD_MODIFIERS)
  skip_tkspace_without_nl
  tk = get_tk
  end_token = get_end_token tk
  return '' unless end_token

  nest = 0
  continue = false

  while tk != nil do
    case tk[:kind]
    when :on_semicolon then
      break if nest == 0
    when :on_lbracket then
      nest += 1
    when :on_rbracket then
      nest -= 1
    when :on_lbrace then
      nest += 1
    when :on_rbrace then
      nest -= 1
      if nest <= 0
        # we might have a.each { |i| yield i }
        unget_tk(tk) if nest < 0
        break
      end
    when :on_lparen then
      nest += 1
    when end_token[:kind] then
      if end_token[:kind] == :on_rparen
        nest -= 1
        break if nest <= 0
      else
        break
      end
    when :on_rparen then
      nest -= 1
    when :on_comment, :on_embdoc then
      @read.pop
      if :on_nl == end_token[:kind] and "\n" == tk[:text][-1] and
        (!continue or (tk[:state] & RDoc::Parser::RipperStateLex::EXPR_LABEL) != 0) then
        if method && method.block_params.nil? then
          unget_tk tk
          read_documentation_modifiers method, modifiers
        end
        break if !continue and nest <= 0
      end
    when :on_comma then
      continue = true
    when :on_ident then
      continue = false if continue
    end
    tk = get_tk
  end

  get_tkread_clean(/\s+/, ' ')
end

#parse_method_parameters(method) ⇒ Object

Capture the method’s parameters. Along the way, look for a comment containing:

# yields: ....

and add this as the block_params for the method



1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
 
# File 'lib/rdoc/parser/ruby.rb', line 1649

def parse_method_parameters method
  res = parse_method_or_yield_parameters method

  res = "(#{res})" unless res =~ /\A\(/
  method.params = res unless method.params

  return if  method.block_params

  skip_tkspace_without_nl
  read_documentation_modifiers method, RDoc::METHOD_MODIFIERS
end

#parse_method_params_and_body(container, single, meth, added_container) ⇒ Object

Parses the parameters and body of meth



1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
 
# File 'lib/rdoc/parser/ruby.rb', line 1450

def parse_method_params_and_body container, single, meth, added_container
  token_listener meth do
    parse_method_parameters meth

    if meth.document_self or not @track_visibility then
      container.add_method meth
    elsif added_container then
      container.document_self = false
    end

    # Having now read the method parameters and documentation modifiers, we
    # now know whether we have to rename #initialize to ::new

    if meth.name == "initialize" && !meth.singleton then
      if meth.dont_rename_initialize then
        meth.visibility = :protected
      else
        meth.singleton = true
        meth.name = "new"
        meth.visibility = :public
      end
    end

    parse_statements container, single, meth
  end
end

#parse_module(container, single, tk, comment) ⇒ Object

Parses an RDoc::NormalModule in container with comment



1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
 
# File 'lib/rdoc/parser/ruby.rb', line 1664

def parse_module container, single, tk, comment
  container, name_t, = get_class_or_module container

  name = name_t[:text]

  mod = container.add_module RDoc::NormalModule, name
  mod.ignore unless container.document_children
  record_location mod

  read_documentation_modifiers mod, RDoc::CLASS_MODIFIERS
  mod.add_comment comment, @top_level
  parse_statements mod

  # after end modifiers
  read_documentation_modifiers mod, RDoc::CLASS_MODIFIERS

  @stats.add_module mod
end

#parse_require(context, comment) ⇒ Object

Parses an RDoc::Require in context containing comment



1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
 
# File 'lib/rdoc/parser/ruby.rb', line 1686

def parse_require(context, comment)
  skip_tkspace_comment
  tk = get_tk

  if :on_lparen == tk[:kind] then
    skip_tkspace_comment
    tk = get_tk
  end

  name = tk[:text][1..-2] if :on_tstring == tk[:kind]

  if name then
    @top_level.add_require RDoc::Require.new(name, comment)
  else
    unget_tk tk
  end
end

#parse_rescue ⇒ Object

Parses a rescue



1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
 
# File 'lib/rdoc/parser/ruby.rb', line 1707

def parse_rescue
  skip_tkspace_without_nl

  while tk = get_tk
    case tk[:kind]
    when :on_nl, :on_semicolon, :on_comment then
      break
    when :on_comma then
      skip_tkspace_without_nl

      get_tk if :on_nl == peek_tk[:kind]
    end

    skip_tkspace_without_nl
  end
end

#parse_statements(container, single = NORMAL, current_method = nil, comment = new_comment('')) ⇒ Object

The core of the Ruby parser.



1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
 
# File 'lib/rdoc/parser/ruby.rb', line 1738

def parse_statements(container, single = NORMAL, current_method = nil,
                     comment = new_comment(''))
  raise 'no' unless RDoc::Comment === comment
  comment = RDoc::Encoding.change_encoding comment, @encoding if @encoding

  nest = 1
  save_visibility = container.visibility

  non_comment_seen = true

  while tk = get_tk do
    keep_comment = false
    try_parse_comment = false

    non_comment_seen = true unless (:on_comment == tk[:kind] or :on_embdoc == tk[:kind])

    case tk[:kind]
    when :on_nl, :on_ignored_nl, :on_comment, :on_embdoc then
      if :on_nl == tk[:kind] or :on_ignored_nl == tk[:kind]
        skip_tkspace
        tk = get_tk
      else
        past_tokens = @read.size > 1 ? @read[0..-2] : []
        nl_position = 0
        past_tokens.reverse.each_with_index do |read_tk, i|
          if read_tk =~ /^\n$/ then
            nl_position = (past_tokens.size - 1) - i
            break
          elsif read_tk =~ /^#.*\n$/ then
            nl_position = ((past_tokens.size - 1) - i) + 1
            break
          end
        end
        comment_only_line = past_tokens[nl_position..-1].all?{ |c| c =~ /^\s+$/ }
        unless comment_only_line then
          tk = get_tk
        end
      end

      if tk and (:on_comment == tk[:kind] or :on_embdoc == tk[:kind]) then
        if non_comment_seen then
          # Look for RDoc in a comment about to be thrown away
          non_comment_seen = parse_comment container, tk, comment unless
            comment.empty?

          comment = ''
          comment = RDoc::Encoding.change_encoding comment, @encoding if @encoding
        end

        line_no = nil
        while tk and (:on_comment == tk[:kind] or :on_embdoc == tk[:kind]) do
          comment_body = retrieve_comment_body(tk)
          line_no = tk[:line_no] if comment.empty?
          comment += comment_body
          comment << "\n" unless comment_body =~ /\n\z/

          if comment_body.size > 1 && comment_body =~ /\n\z/ then
            skip_tkspace_without_nl # leading spaces
          end
          tk = get_tk
        end

        comment = new_comment comment, line_no

        unless comment.empty? then
          look_for_directives_in container, comment

          if container.done_documenting then
            throw :eof if RDoc::TopLevel === container
            container.ongoing_visibility = save_visibility
          end
        end

        keep_comment = true
      else
        non_comment_seen = true
      end

      unget_tk tk
      keep_comment = true
      container.current_line_visibility = nil

    when :on_kw then
      case tk[:text]
      when 'class' then
        parse_class container, single, tk, comment

      when 'module' then
        parse_module container, single, tk, comment

      when 'def' then
        parse_method container, single, tk, comment

      when 'alias' then
        parse_alias container, single, tk, comment unless current_method

      when 'yield' then
        if current_method.nil? then
          warn "Warning: yield outside of method" if container.document_self
        else
          parse_yield container, single, tk, current_method
        end

      when 'until', 'while' then
        if (tk[:state] & RDoc::Parser::RipperStateLex::EXPR_LABEL) == 0
          nest += 1
          skip_optional_do_after_expression
        end

      # Until and While can have a 'do', which shouldn't increase the nesting.
      # We can't solve the general case, but we can handle most occurrences by
      # ignoring a do at the end of a line.

      # 'for' is trickier
      when 'for' then
        nest += 1
        skip_for_variable
        skip_optional_do_after_expression

      when 'case', 'do', 'if', 'unless', 'begin' then
        if (tk[:state] & RDoc::Parser::RipperStateLex::EXPR_LABEL) == 0
          nest += 1
        end

      when 'super' then
        current_method.calls_super = true if current_method

      when 'rescue' then
        parse_rescue

      when 'end' then
        nest -= 1
        if nest == 0 then
          container.ongoing_visibility = save_visibility

          parse_comment container, tk, comment unless comment.empty?

          return
        end
      end

    when :on_const then
      unless parse_constant container, tk, comment, current_method then
        try_parse_comment = true
      end

    when :on_ident then
      if nest == 1 and current_method.nil? then
        keep_comment = parse_identifier container, single, tk, comment
      end

      case tk[:text]
      when "require" then
        parse_require container, comment
      when "include" then
        parse_extend_or_include RDoc::Include, container, comment
      when "extend" then
        parse_extend_or_include RDoc::Extend, container, comment
      end

    else
      try_parse_comment = nest == 1
    end

    if try_parse_comment then
      non_comment_seen = parse_comment container, tk, comment unless
        comment.empty?

      keep_comment = false
    end

    unless keep_comment then
      comment = new_comment ''
      comment = RDoc::Encoding.change_encoding comment, @encoding if @encoding
      container.params = nil
      container.block_params = nil
    end

    consume_trailing_spaces
  end

  container.params = nil
  container.block_params = nil
end

#parse_symbol_arg(no = nil) ⇒ Object

Parse up to no symbol arguments



1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
 
# File 'lib/rdoc/parser/ruby.rb', line 1926

def parse_symbol_arg(no = nil)
  skip_tkspace_comment

  tk = get_tk
  if tk[:kind] == :on_lparen
    parse_symbol_arg_paren no
  else
    parse_symbol_arg_space no, tk
  end
end

#parse_symbol_arg_paren(no) ⇒ Object

Parses up to no symbol arguments surrounded by () and places them in args.



1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
 
# File 'lib/rdoc/parser/ruby.rb', line 1941

def parse_symbol_arg_paren no # :nodoc:
  args = []

  loop do
    skip_tkspace_comment
    if tk1 = parse_symbol_in_arg
      args.push tk1
      break if no and args.size >= no
    end

    skip_tkspace_comment
    case (tk2 = get_tk)[:kind]
    when :on_rparen
      break
    when :on_comma
    else
      warn("unexpected token: '#{tk2.inspect}'") if $DEBUG_RDOC
      break
    end
  end

  args
end

#parse_symbol_arg_space(no, tk) ⇒ Object

Parses up to no symbol arguments separated by spaces and places them in args.



1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
 
# File 'lib/rdoc/parser/ruby.rb', line 1969

def parse_symbol_arg_space no, tk # :nodoc:
  args = []

  unget_tk tk
  if tk = parse_symbol_in_arg
    args.push tk
    return args if no and args.size >= no
  end

  loop do
    skip_tkspace_without_nl

    tk1 = get_tk
    if tk1.nil? || :on_comma != tk1[:kind] then
      unget_tk tk1
      break
    end

    skip_tkspace_comment
    if tk = parse_symbol_in_arg
      args.push tk
      break if no and args.size >= no
    end
  end

  args
end

#parse_symbol_in_arg ⇒ Object

Returns symbol text from the next token



2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
 
# File 'lib/rdoc/parser/ruby.rb', line 2000

def parse_symbol_in_arg
  tk = get_tk
  if :on_symbol == tk[:kind] then
    tk[:text].sub(/^:/, '')
  elsif :on_tstring == tk[:kind] then
    tk[:text][1..-2]
  elsif :on_dstring == tk[:kind] or :on_ident == tk[:kind] then
    nil # ignore
  else
    warn("Expected symbol or string, got #{tk.inspect}") if $DEBUG_RDOC
    nil
  end
end

#parse_top_level_statements(container) ⇒ Object

Parses statements in the top-level container



2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
 
# File 'lib/rdoc/parser/ruby.rb', line 2017

def parse_top_level_statements container
  comment = collect_first_comment

  look_for_directives_in container, comment

  throw :eof if container.done_documenting

  @markup = comment.format

  # HACK move if to RDoc::Context#comment=
  container.comment = comment if container.document_self unless comment.empty?

  parse_statements container, NORMAL, nil, comment
end

#parse_visibility(container, single, tk) ⇒ Object

Determines the visibility in container from tk



2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
 
# File 'lib/rdoc/parser/ruby.rb', line 2035

def parse_visibility(container, single, tk)
  vis_type, vis, singleton = get_visibility_information tk, single

  skip_tkspace_comment false

  ptk = peek_tk
  # Ryan Davis suggested the extension to ignore modifiers, because he
  # often writes
  #
  #   protected unless $TESTING
  #
  if [:on_nl, :on_semicolon].include?(ptk[:kind]) || (:on_kw == ptk[:kind] && (['if', 'unless'].include?(ptk[:text]))) then
    container.ongoing_visibility = vis
  elsif :on_kw == ptk[:kind] && 'def' == ptk[:text]
    container.current_line_visibility = vis
  else
    update_visibility container, vis_type, vis, singleton
  end
end

#parse_yield(context, single, tk, method) ⇒ Object

Determines the block parameter for context



2074
2075
2076
2077
2078
2079
 
# File 'lib/rdoc/parser/ruby.rb', line 2074

def parse_yield(context, single, tk, method)
  return if method.block_params

  get_tkread
  method.block_params = parse_method_or_yield_parameters
end

#read_directive(allowed) ⇒ Object

Directives are modifier comments that can appear after class, module, or method names. For example:

def fred # :yields: a, b

or:

class MyClass # :nodoc:

We return the directive name and any parameters as a two element array if the name is in allowed. A directive can be found anywhere up to the end of the current line.



2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
 
# File 'lib/rdoc/parser/ruby.rb', line 2095

def read_directive allowed
  tokens = []

  while tk = get_tk do
    tokens << tk

    if :on_nl == tk[:kind] or (:on_kw == tk[:kind] && 'def' == tk[:text]) then
      return
    elsif :on_comment == tk[:kind] or :on_embdoc == tk[:kind] then
      return unless tk[:text] =~ /\s*:?([\w-]+):\s*(.*)/

      directive = $1.downcase

      return [directive, $2] if allowed.include? directive

      return
    end
  end
ensure
  unless tokens.length == 1 and (:on_comment == tokens.first[:kind] or :on_embdoc == tokens.first[:kind]) then
    tokens.reverse_each do |token|
      unget_tk token
    end
  end
end

#read_documentation_modifiers(context, allowed) ⇒ Object

Handles directives following the definition for context (any RDoc::CodeObject) if the directives are allowed at this point.

See also RDoc::Markup::PreProcess#handle_directive



2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
 
# File 'lib/rdoc/parser/ruby.rb', line 2127

def read_documentation_modifiers context, allowed
  skip_tkspace_without_nl
  directive, value = read_directive allowed

  return unless directive

  @preprocess.handle_directive '', directive, value, context do |dir, param|
    if %w[notnew not_new not-new].include? dir then
      context.dont_rename_initialize = true

      true
    end
  end
end

#record_location(container) ⇒ Object

Records the location of this container in the file for this parser and adds it to the list of classes and modules in the file.



2146
2147
2148
2149
2150
2151
2152
2153
 
# File 'lib/rdoc/parser/ruby.rb', line 2146

def record_location container # :nodoc:
  case container
  when RDoc::ClassModule then
    @top_level.add_to_classes_or_modules container
  end

  container.record_location @top_level
end

#retrieve_comment_body(tk) ⇒ Object

Retrieve comment body without =begin/=end



1727
1728
1729
1730
1731
1732
1733
 
# File 'lib/rdoc/parser/ruby.rb', line 1727

def retrieve_comment_body(tk)
  if :on_embdoc == tk[:kind]
    tk[:text].gsub(/\A=begin.*\n/, '').gsub(/=end\n?\z/, '')
  else
    tk[:text]
  end
end

#scan ⇒ Object

Scans this Ruby file for Ruby constructs



2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
 
# File 'lib/rdoc/parser/ruby.rb', line 2158

def scan
  reset

  catch :eof do
    begin
      parse_top_level_statements @top_level

    rescue StandardError => e
      if @content.include?('<%') and @content.include?('%>') then
        # Maybe, this is ERB.
        $stderr.puts "\033[2KRDoc detects ERB file. Skips it for compatibility:"
        $stderr.puts @file_name
        return
      end

      if @scanner_point >= @scanner.size
        now_line_no = @scanner[@scanner.size - 1][:line_no]
      else
        now_line_no = peek_tk[:line_no]
      end
      first_tk_index = @scanner.find_index { |tk| tk[:line_no] == now_line_no }
      last_tk_index = @scanner.find_index { |tk| tk[:line_no] == now_line_no + 1 }
      last_tk_index = last_tk_index ? last_tk_index - 1 : @scanner.size - 1
      code = @scanner[first_tk_index..last_tk_index].map{ |t| t[:text] }.join

      $stderr.puts <<-EOF

#{self.class} failure around line #{now_line_no} of
#{@file_name}

      EOF

      unless code.empty? then
        $stderr.puts code
        $stderr.puts
      end

      raise e
    end
  end

  @top_level
end

#skip_for_variable ⇒ Object

skip the var [in] part of a ‘for’ statement



2246
2247
2248
2249
2250
2251
2252
 
# File 'lib/rdoc/parser/ruby.rb', line 2246

def skip_for_variable
  skip_tkspace_without_nl
  get_tk
  skip_tkspace_without_nl
  tk = get_tk
  unget_tk(tk) unless :on_kw == tk[:kind] and 'in' == tk[:text]
end

#skip_method(container) ⇒ Object

Skips the next method in container



2257
2258
2259
2260
2261
 
# File 'lib/rdoc/parser/ruby.rb', line 2257

def skip_method container
  meth = RDoc::AnyMethod.new "", "anon"
  parse_method_parameters meth
  parse_statements container, false, meth
end

#skip_optional_do_after_expression ⇒ Object

while, until, and for have an optional do



2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
 
# File 'lib/rdoc/parser/ruby.rb', line 2205

def skip_optional_do_after_expression
  skip_tkspace_without_nl
  tk = get_tk

  b_nest = 0
  nest = 0

  loop do
    break unless tk
    case tk[:kind]
    when :on_semicolon, :on_nl, :on_ignored_nl then
      break if b_nest.zero?
    when :on_lparen then
      nest += 1
    when :on_rparen then
      nest -= 1
    when :on_kw then
      case tk[:text]
      when 'begin'
        b_nest += 1
      when 'end'
        b_nest -= 1
      when 'do'
        break if nest.zero?
      end
    when :on_comment, :on_embdoc then
      if b_nest.zero? and "\n" == tk[:text][-1] then
        break
      end
    end
    tk = get_tk
  end

  skip_tkspace_without_nl

  get_tk if peek_tk && :on_kw == peek_tk[:kind] && 'do' == peek_tk[:text]
end

#skip_tkspace_comment(skip_nl = true) ⇒ Object

Skip spaces until a comment is found



2266
2267
2268
2269
2270
2271
2272
2273
 
# File 'lib/rdoc/parser/ruby.rb', line 2266

def skip_tkspace_comment(skip_nl = true)
  loop do
    skip_nl ? skip_tkspace : skip_tkspace_without_nl
    next_tk = peek_tk
    return if next_tk.nil? || (:on_comment != next_tk[:kind] and :on_embdoc != next_tk[:kind])
    get_tk
  end
end

#suppress_parents(container, ancestor) ⇒ Object

Marks containers between container and ancestor as ignored



628
629
630
631
632
633
 
# File 'lib/rdoc/parser/ruby.rb', line 628

def suppress_parents container, ancestor # :nodoc:
  while container and container != ancestor do
    container.suppress unless container.documented?
    container = container.parent
  end
end

#tk_nl?(tk) ⇒ Boolean

Returns:

  • (Boolean) 


191
192
193
 
# File 'lib/rdoc/parser/ruby.rb', line 191

def tk_nl?(tk)
  :on_nl == tk[:kind] or :on_ignored_nl == tk[:kind]
end

#update_visibility(container, vis_type, vis, singleton) ⇒ Object

Updates visibility in container from vis_type and vis.



2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
 
# File 'lib/rdoc/parser/ruby.rb', line 2278

def update_visibility container, vis_type, vis, singleton # :nodoc:
  new_methods = []

  case vis_type
  when 'module_function' then
    args = parse_symbol_arg
    container.set_visibility_for args, :private, false

    container.methods_matching args do |m|
      s_m = m.dup
      record_location s_m
      s_m.singleton = true
      new_methods << s_m
    end
  when 'public_class_method', 'private_class_method' then
    args = parse_symbol_arg

    container.methods_matching args, true do |m|
      if m.parent != container then
        m = m.dup
        record_location m
        new_methods << m
      end

      m.visibility = vis
    end
  else
    args = parse_symbol_arg
    container.set_visibility_for args, vis, singleton
  end

  new_methods.each do |method|
    case method
    when RDoc::AnyMethod then
      container.add_method method
    when RDoc::Attr then
      container.add_attribute method
    end
    method.visibility = vis
  end
end

#warn(message) ⇒ Object

Prints message to $stderr unless we’re being quiet



2323
2324
2325
 
# File 'lib/rdoc/parser/ruby.rb', line 2323

def warn message
  @options.warn make_message message
end