Class: RDoc::MethodAttr

Inherits:
CodeObject show all
Includes:
Comparable
Defined in:
lib/rdoc/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::TO_HTML_CHARACTERS

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes inherited from CodeObject

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

Instance Method Summary collapse

Methods inherited from CodeObject

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

Methods included from Generator::Markup

#aref_to, #as_href, #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) ⇒ MethodAttr

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

Usually this is called by super from a subclass.



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

def initialize text, name
  super()

  @text = text
  @name = name

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

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

Class Attribute Details

.add_line_numbers ⇒ Object

Allows controlling whether #markup_code adds line numbers to the source code.



74
75
76
 
# File 'lib/rdoc/generator/markup.rb', line 74

def add_line_numbers
  @add_line_numbers
end

Instance Attribute Details

#aliases ⇒ Object (readonly)

Array of other names for this method/attribute



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

def aliases
  @aliases
end

#arglists ⇒ Object (readonly)

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



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

def arglists
  @arglists
end

#block_params ⇒ Object

Parameters yielded by the called block



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

def block_params
  @block_params
end

#call_seq ⇒ Object

Different ways to call this method



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

def call_seq
  @call_seq
end

#is_alias_for ⇒ Object

The method/attribute we’re aliasing



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

def is_alias_for
  @is_alias_for
end

#name ⇒ Object

Name of this method/attribute.



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

def name
  @name
end

#param_seq ⇒ Object (readonly)

Pretty parameter list for this method



68
69
70
 
# File 'lib/rdoc/method_attr.rb', line 68

def param_seq
  @param_seq
end

#params ⇒ Object

Parameters for this method



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

def params
  @params
end

#singleton ⇒ Object

Is this a singleton method/attribute?



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

def singleton
  @singleton
end

#text ⇒ Object (readonly)

Source file token stream



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

def text
  @text
end

#visibility ⇒ Object

public, protected, private



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

def visibility
  @visibility
end

Instance Method Details

#<=>(other) ⇒ Object

Order by #singleton then #name



112
113
114
115
 
# File 'lib/rdoc/method_attr.rb', line 112

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

#==(other) ⇒ Object

:nodoc:



117
118
119
 
# File 'lib/rdoc/method_attr.rb', line 117

def == other # :nodoc:
  super 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) 


205
206
207
 
# File 'lib/rdoc/method_attr.rb', line 205

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.



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

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



212
213
214
215
216
 
# File 'lib/rdoc/method_attr.rb', line 212

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) 


221
222
223
 
# File 'lib/rdoc/method_attr.rb', line 221

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) 


128
129
130
131
132
 
# File 'lib/rdoc/method_attr.rb', line 128

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:



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

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 parent == ancestor
    next if String === ancestor

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

    return other if other
  end

  nil
end

#find_see ⇒ Object

:nodoc:



162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/rdoc/method_attr.rb', line 162

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



296
297
298
 
# File 'lib/rdoc/method_attr.rb', line 296

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

#html_name ⇒ Object

HTML id-friendly method/attribute name



287
288
289
290
291
 
# File 'lib/rdoc/method_attr.rb', line 287

def html_name
  require 'cgi'

  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



100
101
102
 
# File 'lib/rdoc/method_attr.rb', line 100

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

#initialize_visibility ⇒ Object

:nodoc:



104
105
106
107
 
# File 'lib/rdoc/method_attr.rb', line 104

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

#inspect ⇒ Object

:nodoc:



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

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 add_line_numbers is true.



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

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 = $&.length
      indent = n if n < indent
      break if n == 0
    end
  end
  src.gsub!(/^#{' ' * indent}/, '') if indent > 0

  add_line_numbers(src) if RDoc::MethodAttr.add_line_numbers

  src
end

#name_prefix ⇒ Object

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



315
316
317
 
# File 'lib/rdoc/method_attr.rb', line 315

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

#output_name(context) ⇒ Object

Name for output to HTML. For class methods the full name with a “.” is used like SomeClass.method_name. For instance methods the class name is used if context does not match the parent.

This is to help prevent people from using

to call class methods.



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

def output_name context
  return "#{name_prefix}#{@name}" if context == parent

  "#{parent_name}#{@singleton ? '.' : '#'}#{@name}"
end

#parent_name ⇒ Object

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



356
357
358
 
# File 'lib/rdoc/method_attr.rb', line 356

def parent_name
  @parent_name || super
end

#path ⇒ Object

Path to this method for use with HTML generator output.



349
350
351
 
# File 'lib/rdoc/method_attr.rb', line 349

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

#pretty_name ⇒ Object

Method/attribute name with class/instance indicator



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

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

#pretty_print(q) ⇒ Object

:nodoc:



360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
 
# File 'lib/rdoc/method_attr.rb', line 360

def pretty_print q # :nodoc:
  alias_for = @is_alias_for ? "alias for #{@is_alias_for.name}" : nil

  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.



389
390
391
392
393
394
395
396
397
398
399
 
# File 'lib/rdoc/method_attr.rb', line 389

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.



148
149
150
151
 
# File 'lib/rdoc/method_attr.rb', line 148

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.



156
157
158
159
160
 
# File 'lib/rdoc/method_attr.rb', line 156

def store= store
  super

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

#to_s ⇒ Object

:nodoc:



401
402
403
404
405
406
407
 
# File 'lib/rdoc/method_attr.rb', line 401

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)



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

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