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?, #initialize_visibility, #parent_file_name, #record_location, #start_doc, #stop_doc

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



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

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

#==(other) ⇒ Object

:nodoc:



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

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) 


193
194
195
 
# File 'lib/rdoc/method_attr.rb', line 193

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



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

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) 


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

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) 


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

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:



162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/rdoc/method_attr.rb', line 162

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:



150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/rdoc/method_attr.rb', line 150

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



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

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

#html_name ⇒ Object

HTML id-friendly method/attribute name



275
276
277
278
279
 
# File 'lib/rdoc/method_attr.rb', line 275

def html_name
  require 'cgi'

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

#inspect ⇒ Object

:nodoc:



288
289
290
291
292
293
294
295
296
297
298
 
# File 'lib/rdoc/method_attr.rb', line 288

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.



303
304
305
 
# File 'lib/rdoc/method_attr.rb', line 303

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.



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

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



344
345
346
 
# File 'lib/rdoc/method_attr.rb', line 344

def parent_name
  @parent_name || super
end

#path ⇒ Object

Path to this method for use with HTML generator output.



337
338
339
 
# File 'lib/rdoc/method_attr.rb', line 337

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

#pretty_name ⇒ Object

Method/attribute name with class/instance indicator



323
324
325
 
# File 'lib/rdoc/method_attr.rb', line 323

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

#pretty_print(q) ⇒ Object

:nodoc:



348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
 
# File 'lib/rdoc/method_attr.rb', line 348

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.



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

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.



136
137
138
139
 
# File 'lib/rdoc/method_attr.rb', line 136

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.



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

def store= store
  super

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

#to_s ⇒ Object

:nodoc:



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

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)



330
331
332
 
# File 'lib/rdoc/method_attr.rb', line 330

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