Class: RDoc::Context

Inherits:
CodeObject show all
Defined in:
lib/rdoc/code_objects.rb

Overview

A Context is something that can hold modules, classes, methods, attributes, aliases, requires, and includes. Classes, modules, and files are all Contexts.

Direct Known Subclasses

ClassModule, TopLevel

Defined Under Namespace

Classes: Section

Instance Attribute Summary collapse

Attributes inherited from CodeObject

#comment, #document_children, #document_self, #done_documenting, #force_documentation, #parent, #section, #viewer

Instance Method Summary collapse

Methods inherited from CodeObject

attr_overridable, #start_doc, #stop_doc

Constructor Details

#initialize ⇒ Context

Returns a new instance of Context.



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/rdoc/code_objects.rb', line 163

def initialize
  super()

  @in_files    = []

  @name    ||= "unknown"
  @comment ||= ""
  @parent  = nil
  @visibility = :public

  @current_section = Section.new(nil, nil)
  @sections = [ @current_section ]

  initialize_methods_etc
  initialize_classes_and_modules
end

Instance Attribute Details

#aliases ⇒ Object (readonly)

Returns the value of attribute aliases



115
116
117
 
# File 'lib/rdoc/code_objects.rb', line 115

def aliases
  @aliases
end

#attributes ⇒ Object (readonly)

Returns the value of attribute attributes



115
116
117
 
# File 'lib/rdoc/code_objects.rb', line 115

def attributes
  @attributes
end

#constants ⇒ Object (readonly)

Returns the value of attribute constants



115
116
117
 
# File 'lib/rdoc/code_objects.rb', line 115

def constants
  @constants
end

#in_files ⇒ Object (readonly)

Returns the value of attribute in_files



116
117
118
 
# File 'lib/rdoc/code_objects.rb', line 116

def in_files
  @in_files
end

#includes ⇒ Object (readonly)

Returns the value of attribute includes



116
117
118
 
# File 'lib/rdoc/code_objects.rb', line 116

def includes
  @includes
end

#method_list ⇒ Object (readonly)

Returns the value of attribute method_list



115
116
117
 
# File 'lib/rdoc/code_objects.rb', line 115

def method_list
  @method_list
end

#name ⇒ Object (readonly)

Returns the value of attribute name



115
116
117
 
# File 'lib/rdoc/code_objects.rb', line 115

def name
  @name
end

#requires ⇒ Object (readonly)

Returns the value of attribute requires



116
117
118
 
# File 'lib/rdoc/code_objects.rb', line 116

def requires
  @requires
end

#sections ⇒ Object (readonly)

Returns the value of attribute sections



118
119
120
 
# File 'lib/rdoc/code_objects.rb', line 118

def sections
  @sections
end

#visibility ⇒ Object (readonly)

Returns the value of attribute visibility



116
117
118
 
# File 'lib/rdoc/code_objects.rb', line 116

def visibility
  @visibility
end

Instance Method Details

#<=>(other) ⇒ Object

allow us to sort modules by name



370
371
372
 
# File 'lib/rdoc/code_objects.rb', line 370

def <=>(other)
  name <=> other.name
end

#add_alias(an_alias) ⇒ Object 



247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/rdoc/code_objects.rb', line 247

def add_alias(an_alias)
  meth = find_instance_method_named(an_alias.old_name)
  if meth
    new_meth = AnyMethod.new(an_alias.text, an_alias.new_name)
    new_meth.is_alias_for = meth
    new_meth.singleton    = meth.singleton
    new_meth.params       = meth.params
    new_meth.comment = "Alias for \##{meth.name}"
    meth.add_alias(new_meth)
    add_method(new_meth)
  else
    add_to(@aliases, an_alias)
  end
end

#add_attribute(an_attribute) ⇒ Object 



243
244
245
 
# File 'lib/rdoc/code_objects.rb', line 243

def add_attribute(an_attribute)
  add_to(@attributes, an_attribute)
end

#add_class(class_type, name, superclass) ⇒ Object 



229
230
231
 
# File 'lib/rdoc/code_objects.rb', line 229

def add_class(class_type, name, superclass)
  add_class_or_module(@classes, class_type, name, superclass)
end

#add_class_or_module(collection, class_type, name, superclass = nil) ⇒ Object 



279
280
281
282
283
284
285
286
287
288
289
290
291
292
 
# File 'lib/rdoc/code_objects.rb', line 279

def add_class_or_module(collection, class_type, name, superclass=nil)
  cls = collection[name]
  if cls
    puts "Reusing class/module #{name}" if $DEBUG
  else
    cls = class_type.new(name, superclass)
    puts "Adding class/module #{name} to #@name" if $DEBUG
#        collection[name] = cls if @document_self  && !@done_documenting
    collection[name] = cls if !@done_documenting
    cls.parent = self
    cls.section = @current_section
  end
  cls
end

#add_constant(const) ⇒ Object 



266
267
268
 
# File 'lib/rdoc/code_objects.rb', line 266

def add_constant(const)
  add_to(@constants, const)
end

#add_include(an_include) ⇒ Object 



262
263
264
 
# File 'lib/rdoc/code_objects.rb', line 262

def add_include(an_include)
  add_to(@includes, an_include)
end

#add_method(a_method) ⇒ Object 



237
238
239
240
241
 
# File 'lib/rdoc/code_objects.rb', line 237

def add_method(a_method)
  puts "Adding #@visibility method #{a_method.name} to #@name" if $DEBUG
  a_method.visibility = @visibility
  add_to(@method_list, a_method)
end

#add_module(class_type, name) ⇒ Object 



233
234
235
 
# File 'lib/rdoc/code_objects.rb', line 233

def add_module(class_type, name)
  add_class_or_module(@modules, class_type, name, nil)
end

#add_require(a_require) ⇒ Object

Requires always get added to the top-level (file) context



271
272
273
274
275
276
277
 
# File 'lib/rdoc/code_objects.rb', line 271

def add_require(a_require)
  if self.kind_of? TopLevel
    add_to(@requires, a_require)
  else
    parent.add_require(a_require)
  end
end

#add_to(array, thing) ⇒ Object 



294
295
296
297
298
 
# File 'lib/rdoc/code_objects.rb', line 294

def add_to(array, thing)
  array <<  thing if @document_self  && !@done_documenting
  thing.parent = self
  thing.section = @current_section
end

#classes ⇒ Object

map the class hash to an array externally



181
182
183
 
# File 'lib/rdoc/code_objects.rb', line 181

def classes
  @classes.values
end

#defined_in?(file) ⇒ Boolean

Return true if at least part of this thing was defined in file

Returns:

  • (Boolean) 


225
226
227
 
# File 'lib/rdoc/code_objects.rb', line 225

def defined_in?(file)
  @in_files.include?(file)
end

#each_attribute ⇒ Object 



352
353
354
 
# File 'lib/rdoc/code_objects.rb', line 352

def each_attribute 
  @attributes.each {|a| yield a}
end

#each_classmodule ⇒ Object

Iterate over all the classes and modules in this object



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

def each_classmodule
  @modules.each_value {|m| yield m}
  @classes.each_value {|c| yield c}
end

#each_constant ⇒ Object 



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

def each_constant
  @constants.each {|c| yield c}
end

#each_method ⇒ Object 



348
349
350
 
# File 'lib/rdoc/code_objects.rb', line 348

def each_method
  @method_list.each {|m| yield m}
end

#find_enclosing_module_named(name) ⇒ Object

find a module at a higher scope



336
337
338
 
# File 'lib/rdoc/code_objects.rb', line 336

def find_enclosing_module_named(name)
  parent && parent.find_module_named(name)
end

#find_local_symbol(symbol) ⇒ Object 



422
423
424
425
426
427
 
# File 'lib/rdoc/code_objects.rb', line 422

def find_local_symbol(symbol)
  res = find_method_named(symbol) ||
        find_constant_named(symbol) ||
        find_attribute_named(symbol) ||
        find_module_named(symbol) 
end

#find_module_named(name) ⇒ Object

Find a named module



328
329
330
331
332
333
 
# File 'lib/rdoc/code_objects.rb', line 328

def find_module_named(name)
  return self if self.name == name
  res = @modules[name] || @classes[name]
  return res if res
  find_enclosing_module_named(name)
end

#find_symbol(symbol, method = nil) ⇒ Object

Look up the given symbol. If method is non-nil, then we assume the symbol references a module that contains that method



377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
 
# File 'lib/rdoc/code_objects.rb', line 377

def find_symbol(symbol, method=nil)
  result = nil
  case symbol
  when /^::(.*)/
    result = toplevel.find_symbol($1)
  when /::/
    modules = symbol.split(/::/)
    unless modules.empty?
      module_name = modules.shift
      result = find_module_named(module_name)
      if result
        modules.each do |module_name|
          result = result.find_module_named(module_name)
          break unless result
        end
      end
    end
  else
    # if a method is specified, then we're definitely looking for
    # a module, otherwise it could be any symbol
    if method
      result = find_module_named(symbol)
    else
      result = find_local_symbol(symbol)
      if result.nil?
        if symbol =~ /^[A-Z]/
          result = parent
          while result && result.name != symbol
            result = result.parent
          end
        end
      end
    end
  end
  if result && method
    if !result.respond_to?(:find_local_symbol)
      p result.name
      p method
      fail
    end
    result = result.find_local_symbol(method)
  end
  result
end

#initialize_classes_and_modules ⇒ Object 



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

def initialize_classes_and_modules
  @classes     = {}
  @modules     = {}
end

#initialize_methods_etc ⇒ Object 



308
309
310
311
312
313
314
315
 
# File 'lib/rdoc/code_objects.rb', line 308

def initialize_methods_etc
  @method_list = []
  @attributes  = []
  @aliases     = []
  @requires    = []
  @includes    = []
  @constants   = []
end

#modules ⇒ Object

map the module hash to an array externally



186
187
188
 
# File 'lib/rdoc/code_objects.rb', line 186

def modules
  @modules.values
end

#ongoing_visibility=(vis) ⇒ Object

Change the default visibility for new methods



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

def ongoing_visibility=(vis)
  @visibility = vis
end

#record_location(toplevel) ⇒ Object

Record the file that we happen to find it in



220
221
222
 
# File 'lib/rdoc/code_objects.rb', line 220

def record_location(toplevel)
  @in_files << toplevel unless @in_files.include?(toplevel)
end

#remove_classes_and_modules ⇒ Object

and remove classes and modules when we see a :nodoc: all



318
319
320
 
# File 'lib/rdoc/code_objects.rb', line 318

def remove_classes_and_modules
  initialize_classes_and_modules
end

#remove_methods_etc ⇒ Object

If a class's documentation is turned off after we've started collecting methods etc., we need to remove the ones we have



304
305
306
 
# File 'lib/rdoc/code_objects.rb', line 304

def remove_methods_etc
  initialize_methods_etc
end

#set_current_section(title, comment) ⇒ Object

Handle sections



431
432
433
434
 
# File 'lib/rdoc/code_objects.rb', line 431

def set_current_section(title, comment)
  @current_section = Section.new(title, comment)
  @sections << @current_section
end

#set_visibility_for(methods, vis, singleton = false) ⇒ Object

Given an array methods of method names, set the visibility of the corresponding AnyMethod object



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/rdoc/code_objects.rb', line 198

def set_visibility_for(methods, vis, singleton=false)
  count = 0
  @method_list.each do |m|
    if methods.include?(m.name) && m.singleton == singleton
      m.visibility = vis
      count += 1
    end
  end

  return if count == methods.size || singleton

  # perhaps we need to look at attributes

  @attributes.each do |a|
    if methods.include?(a.name)
      a.visibility = vis
      count += 1
    end
  end
end

#toplevel ⇒ Object

Return the toplevel that owns us



362
363
364
365
366
367
 
# File 'lib/rdoc/code_objects.rb', line 362

def toplevel
  return @toplevel if defined? @toplevel
  @toplevel = self
  @toplevel = @toplevel.parent until TopLevel === @toplevel
  @toplevel
end