Class: RDoc::MethodAttr

Inherits:
CodeObject show all
Includes:
Comparable
Defined in:
lib/rdoc/code_object/method_attr.rb,
lib/rdoc/generator/markup.rb

Overview

Abstract class representing either a method or an attribute.

Direct Known Subclasses

AnyMethod, Attr

Constant Summary

Constants included from Text

Text::MARKUP_FORMAT, Text::SPACE_SEPARATED_LETTER_CLASS, Text::TO_HTML_CHARACTERS

Instance Attribute Summary collapse

Attributes inherited from CodeObject

#comment, #document_children, #document_self, #done_documenting, #file, #force_documentation, #line, #metadata, #mixin_from, #parent, #received_nodoc, #section, #store

Attributes included from Text

#language

Instance Method Summary collapse

Methods inherited from CodeObject

#display?, #file_name, #full_name=, #ignore, #ignored?, #options, #record_location, #start_doc, #stop_doc, #suppress, #suppressed?

Methods included from Generator::Markup

#aref_to, #as_href, #canonical_url, #cvs_url, #description, #formatter

Methods included from Text

encode_fallback, #expand_tabs, #flush_left, #markup, #normalize_comment, #parse, #snippet, #strip_hashes, #strip_newlines, #strip_stars, #to_html, #wrap

Constructor Details

#initialize(text, name, singleton: false) ⇒ MethodAttr

Creates a new MethodAttr from token stream text and method or attribute name name.

Usually this is called by super from a subclass.



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/rdoc/code_object/method_attr.rb', line 72

def initialize(text, name, singleton: false)
  super()

  @text = text
  @name = name

  @aliases      = []
  @is_alias_for = nil
  @parent_name  = nil
  @singleton    = singleton
  @visibility   = :public
  @see = false

  @arglists     = nil
  @block_params = nil
  @call_seq     = nil
  @params       = nil
end

Instance Attribute Details

#aliases ⇒ Object (readonly)

Array of other names for this method/attribute



32
33
34
 
# File 'lib/rdoc/code_object/method_attr.rb', line 32

def aliases
  @aliases
end

#arglists ⇒ Object (readonly)

The call_seq or the param_seq with method name, if there is no call_seq.



64
65
66
 
# File 'lib/rdoc/code_object/method_attr.rb', line 64

def arglists
  @arglists
end

#block_params ⇒ Object

Parameters yielded by the called block



49
50
51
 
# File 'lib/rdoc/code_object/method_attr.rb', line 49

def block_params
  @block_params
end

#call_seq ⇒ Object

Different ways to call this method



59
60
61
 
# File 'lib/rdoc/code_object/method_attr.rb', line 59

def call_seq
  @call_seq
end

#is_alias_for ⇒ Object

The method/attribute we’re aliasing



37
38
39
 
# File 'lib/rdoc/code_object/method_attr.rb', line 37

def is_alias_for
  @is_alias_for
end

#name ⇒ Object

Name of this method/attribute.



12
13
14
 
# File 'lib/rdoc/code_object/method_attr.rb', line 12

def name
  @name
end

#params ⇒ Object

Parameters for this method



54
55
56
 
# File 'lib/rdoc/code_object/method_attr.rb', line 54

def params
  @params
end

#singleton ⇒ Object

Is this a singleton method/attribute?



22
23
24
 
# File 'lib/rdoc/code_object/method_attr.rb', line 22

def singleton
  @singleton
end

#text ⇒ Object (readonly)

Source file token stream



27
28
29
 
# File 'lib/rdoc/code_object/method_attr.rb', line 27

def text
  @text
end

#visibility ⇒ Object

public, protected, private



17
18
19
 
# File 'lib/rdoc/code_object/method_attr.rb', line 17

def visibility
  @visibility
end

Instance Method Details

#<=>(other) ⇒ Object

Order by #singleton then #name



106
107
108
109
110
111
112
 
# File 'lib/rdoc/code_object/method_attr.rb', line 106

def <=>(other)
  return unless other.respond_to?(:singleton) &&
                other.respond_to?(:name)

  [@singleton      ? 0 : 1, name_ord_range,       name] <=>
  [other.singleton ? 0 : 1, other.name_ord_range, other.name]
end

#==(other) ⇒ Object

:nodoc:



114
115
116
 
# File 'lib/rdoc/code_object/method_attr.rb', line 114

def ==(other) # :nodoc:
  equal?(other) or self.class == other.class and full_name == other.full_name
end

#add_alias(an_alias, context) ⇒ Object

Abstract method. Contexts in their building phase call this to register a new alias for this known method/attribute.

  • creates a new AnyMethod/Attribute named an_alias.new_name;

  • adds self as an alias for the new method or attribute

  • adds the method or attribute to #aliases

  • adds the method or attribute to context.

Raises:

  • (NotImplementedError) 


202
203
204
 
# File 'lib/rdoc/code_object/method_attr.rb', line 202

def add_alias(an_alias, context)
  raise NotImplementedError
end

#add_line_numbers(src) ⇒ Object

Prepend src with line numbers. Relies on the first line of a source code listing having:

# File xxxxx, line dddd

If it has this comment then line numbers are added to src and the , line dddd portion of the comment is removed.



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/rdoc/generator/markup.rb', line 89

def add_line_numbers(src)
  return unless src.sub!(/\A(.*)(, line (\d+))/, '\1')
  first = $3.to_i - 1
  last  = first + src.count("\n")
  size = last.to_s.length

  line = first
  src.gsub!(/^/) do
    res = if line == first then
            " " * (size + 1)
          else
            "<span class=\"line-num\">%2$*1$d</span> " % [size, line]
          end

    line += 1
    res
  end
end

#aref ⇒ Object

HTML fragment reference for this method



209
210
211
212
213
 
# File 'lib/rdoc/code_object/method_attr.rb', line 209

def aref
  type = singleton ? 'c' : 'i'
  # % characters are not allowed in html names => dash instead
  "#{aref_prefix}-#{type}-#{html_name}"
end

#aref_prefix ⇒ Object

Prefix for aref, defined by subclasses.

Raises:

  • (NotImplementedError) 


218
219
220
 
# File 'lib/rdoc/code_object/method_attr.rb', line 218

def aref_prefix
  raise NotImplementedError
end

#documented? ⇒ Boolean

A method/attribute is documented if any of the following is true:

  • it was marked with :nodoc:;

  • it has a comment;

  • it is an alias for a documented method;

  • it has a #see method that is documented.

Returns:

  • (Boolean) 


125
126
127
128
129
 
# File 'lib/rdoc/code_object/method_attr.rb', line 125

def documented?
  super or
    (is_alias_for and is_alias_for.documented?) or
    (see and see.documented?)
end

#find_method_or_attribute(name) ⇒ Object

:nodoc:



171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/rdoc/code_object/method_attr.rb', line 171

def find_method_or_attribute(name) # :nodoc:
  return nil unless parent.respond_to? :ancestors

  searched = parent.ancestors
  kernel = @store.modules_hash['Kernel']

  searched << kernel if kernel &&
    parent != kernel && !searched.include?(kernel)

  searched.each do |ancestor|
    next if String === ancestor
    next if parent == ancestor

    other = ancestor.find_method_named('#' + name) ||
            ancestor.find_attribute_named(name)

    return other if other
  end

  nil
end

#find_see ⇒ Object

:nodoc:



159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/rdoc/code_object/method_attr.rb', line 159

def find_see # :nodoc:
  return nil if singleton || is_alias_for

  # look for the method
  other = find_method_or_attribute name
  return other if other

  # if it is a setter, look for a getter
  return nil unless name =~ /[a-z_]=$/i   # avoid == or ===
  return find_method_or_attribute name[0..-2]
end

#full_name ⇒ Object

Full method/attribute name including namespace



294
295
296
 
# File 'lib/rdoc/code_object/method_attr.rb', line 294

def full_name
  @full_name ||= "#{parent_name}#{pretty_name}"
end

#html_name ⇒ Object

HTML id-friendly method/attribute name



284
285
286
287
288
289
 
# File 'lib/rdoc/code_object/method_attr.rb', line 284

def html_name
  require 'cgi/escape'
  require 'cgi/util' unless defined?(CGI::EscapeExt)

  CGI.escape(@name.gsub('-', '-2D')).gsub('%', '-').sub(/^-/, '')
end

#initialize_copy(other) ⇒ Object

Resets cached data for the object so it can be rebuilt by accessor methods



94
95
96
 
# File 'lib/rdoc/code_object/method_attr.rb', line 94

def initialize_copy(other) # :nodoc:
  @full_name = nil
end

#initialize_visibility ⇒ Object

:nodoc:



98
99
100
101
 
# File 'lib/rdoc/code_object/method_attr.rb', line 98

def initialize_visibility # :nodoc:
  super
  @see = nil
end

#inspect ⇒ Object

:nodoc:



298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/rdoc/code_object/method_attr.rb', line 298

def inspect # :nodoc:
  alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
  visibility = self.visibility
  visibility = "forced #{visibility}" if force_documentation
  "#<%s:0x%x %s (%s)%s>" % [
    self.class, object_id,
    full_name,
    visibility,
    alias_for,
  ]
end

#markup_code ⇒ Object

Turns the method’s token stream into HTML.

Prepends line numbers if options.line_numbers is true.



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/rdoc/generator/markup.rb', line 113

def markup_code
  return '' unless @token_stream

  src = RDoc::TokenStream.to_html @token_stream

  # dedent the source
  indent = src.length
  lines = src.lines.to_a
  lines.shift if src =~ /\A.*#\ *File/i # remove '# File' comment
  lines.each do |line|
    if line =~ /^ *(?=\S)/
      n = $~.end(0)
      indent = n if n < indent
      break if n == 0
    end
  end
  src.gsub!(/^#{' ' * indent}/, '') if indent > 0

  add_line_numbers(src) if options.line_numbers

  src
end

#name_ord_range ⇒ Object

:nodoc:



399
400
401
402
403
404
405
406
407
408
409
410
 
# File 'lib/rdoc/code_object/method_attr.rb', line 399

def name_ord_range # :nodoc:
  case name.ord
  when 0..64 # anything below "A"
    1
  when 91..96 # the symbols between "Z" and "a"
    2
  when 123..126 # 7-bit symbols above "z": "{", "|", "}", "~"
    3
  else # everythig else can be sorted as normal
    4
  end
end

#name_prefix ⇒ Object

‘::’ for a class method/attribute, ‘#’ for an instance method.



313
314
315
 
# File 'lib/rdoc/code_object/method_attr.rb', line 313

def name_prefix
  @singleton ? '::' : '#'
end

#parent_name ⇒ Object

Name of our parent with special handling for un-marshaled methods



341
342
343
 
# File 'lib/rdoc/code_object/method_attr.rb', line 341

def parent_name
  @parent_name || super
end

#path ⇒ Object

Path to this method for use with HTML generator output.



334
335
336
 
# File 'lib/rdoc/code_object/method_attr.rb', line 334

def path
  "#{@parent.path}##{aref}"
end

#pretty_name ⇒ Object

Method/attribute name with class/instance indicator



320
321
322
 
# File 'lib/rdoc/code_object/method_attr.rb', line 320

def pretty_name
  "#{name_prefix}#{@name}"
end

#pretty_print(q) ⇒ Object

:nodoc:



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
 
# File 'lib/rdoc/code_object/method_attr.rb', line 345

def pretty_print(q) # :nodoc:
  alias_for =
    if @is_alias_for.respond_to? :name then
      "alias for #{@is_alias_for.name}"
    elsif Array === @is_alias_for then
      "alias for #{@is_alias_for.last}"
    end

  q.group 2, "[#{self.class.name} #{full_name} #{visibility}", "]" do
    if alias_for then
      q.breakable
      q.text alias_for
    end

    if text then
      q.breakable
      q.text "text:"
      q.breakable
      q.pp @text
    end

    unless comment.empty? then
      q.breakable
      q.text "comment:"
      q.breakable
      q.pp @comment
    end
  end
end

#search_record ⇒ Object

Used by RDoc::Generator::JsonIndex to create a record for the search engine.



379
380
381
382
383
384
385
386
387
388
389
 
# File 'lib/rdoc/code_object/method_attr.rb', line 379

def search_record
  [
    @name,
    full_name,
    @name,
    @parent.full_name,
    path,
    params,
    snippet(@comment),
  ]
end

#see ⇒ Object

A method/attribute to look at, in particular if this method/attribute has no documentation.

It can be a method/attribute of the superclass or of an included module, including the Kernel module, which is always appended to the included modules.

Returns nil if there is no such method/attribute. The #is_alias_for method/attribute, if any, is not included.

Templates may generate a “see also …” if this method/attribute has documentation, and “see …” if it does not.



145
146
147
148
 
# File 'lib/rdoc/code_object/method_attr.rb', line 145

def see
  @see = find_see if @see == false
  @see
end

#store=(store) ⇒ Object

Sets the store for this class or module and its contained code objects.



153
154
155
156
157
 
# File 'lib/rdoc/code_object/method_attr.rb', line 153

def store=(store)
  super

  @file = @store.add_file @file.full_name if @file
end

#to_s ⇒ Object

:nodoc:



391
392
393
394
395
396
397
 
# File 'lib/rdoc/code_object/method_attr.rb', line 391

def to_s # :nodoc:
  if @is_alias_for
    "#{self.class.name}: #{full_name} -> #{is_alias_for}"
  else
    "#{self.class.name}: #{full_name}"
  end
end

#type ⇒ Object

Type of method/attribute (class or instance)



327
328
329
 
# File 'lib/rdoc/code_object/method_attr.rb', line 327

def type
  singleton ? 'class' : 'instance'
end