Class: RDoc::MethodAttr
Relationships & Source Files | |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
|
|
Super Chains via Extension / Inclusion / Inheritance | |
Class Chain:
self,
CodeObject
|
|
Instance Chain:
|
|
Inherits: |
RDoc::CodeObject
|
Defined in: | lib/rdoc/code_object/method_attr.rb, lib/rdoc/generator/markup.rb |
Overview
Abstract class representing either a method or an attribute.
Constant Summary
Text
- Included
MARKUP_FORMAT, SPACE_SEPARATED_LETTER_CLASS, TO_HTML_CHARACTERS
Class Method Summary
- .new(text, name) ⇒ MethodAttr constructor
CodeObject
- Inherited
.new | Creates a new |
Instance Attribute Summary
-
#aliases
readonly
Array of other names for this method/attribute.
-
#arglists
readonly
The call_seq or the param_seq with method name, if there is no call_seq.
-
#block_params
rw
Parameters yielded by the called block.
-
#block_params=(value)
rw
Attempts to sanitize the content passed by the Ruby parser: remove outer parentheses, etc.
-
#call_seq
rw
Different ways to call this method.
-
#documented? ⇒ Boolean
readonly
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.
-
#is_alias_for
rw
The method/attribute we’re aliasing.
-
#name
rw
Name of this method/attribute.
-
#param_seq
readonly
Pretty parameter list for this method.
-
#params
rw
Parameters for this method.
-
#singleton
rw
Is this a singleton method/attribute?
-
#store=(store)
writeonly
Sets the store for this class or module and its contained code objects.
-
#text
readonly
Source file token stream.
-
#visibility
rw
public, protected, private.
CodeObject
- Inherited
#comment | Our comment. |
#comment= | Replaces our comment with |
#display? | Should this |
#document_children | Do we document our children? |
#document_children= | Enables or disables documentation of this CodeObject’s children unless it has been turned off by :enddoc: |
#document_self | Do we document ourselves? |
#document_self= | Enables or disables documentation of this |
#documented? | Does this object have a comment with content or is |
#done_documenting | Are we done documenting (ie, did we come across a :enddoc:)? |
#done_documenting= | Turns documentation on/off, and turns on/off |
#file | Which file this code object was defined in. |
#force_documentation | Force documentation of this |
#force_documentation= | Force the documentation of this object unless documentation has been turned off by :enddoc: |
#full_name= | Sets the full_name overriding any computed full name. |
#ignored? | Has this class been ignored? |
#line | Line in |
#metadata | Hash of arbitrary metadata for this |
#mixin_from | When mixed-in to a class, this points to the |
#parent | Our parent |
#parent= | Sets the parent |
#received_nodoc | Did we ever receive a |
#section | The section this |
#section= | Set the section this |
#store | The |
#store= | Sets the |
#suppressed? | Has this class been suppressed? |
#viewer | We are the model of the code, but we know that at some point we will be worked on by viewers. |
Text
- Included
#language | The language for this text. |
Instance Method Summary
-
#<=>(other)
Order by #singleton then #name
-
#add_alias(an_alias, context)
Abstract method.
-
#add_line_numbers(src)
Prepend
src
with line numbers. -
#aref
HTML fragment reference for this method.
-
#aref_prefix
Prefix for #aref, defined by subclasses.
-
#full_name
Full method/attribute name including namespace.
-
#html_name
HTML id-friendly method/attribute name.
-
#markup_code
Turns the method’s token stream into HTML.
-
#name_prefix
‘::’ for a class method/attribute, ‘#’ for an instance method.
-
#output_name(context)
Name for output to HTML.
-
#parent_name
Name of our parent with special handling for un-marshaled methods.
-
#path
Path to this method for use with HTML generator output.
-
#pretty_name
Method/attribute name with class/instance indicator.
-
#search_record
Used by
Generator::JsonIndex
to create a record for the search engine. -
#see
A method/attribute to look at, in particular if this method/attribute has no documentation.
-
#type
Type of method/attribute (class or instance).
- #==(other) Internal use only
- #find_method_or_attribute(name) Internal use only
- #find_see Internal use only
-
#initialize_copy(other)
Internal use only
Resets cached data for the object so it can be rebuilt by accessor methods.
- #initialize_visibility Internal use only
- #inspect Internal use only
- #pretty_print(q) Internal use only
- #to_s Internal use only
CodeObject
- Inherited
#each_parent | Yields each parent of this |
#file_name | File name where this |
#ignore | Use this to ignore a |
#options | The options instance from the store this |
#parent_file_name | File name of our parent. |
#parent_name | Name of our parent. |
#record_location | Records the |
#start_doc | Enable capture of documentation unless documentation has been turned off by :enddoc: |
#stop_doc | Disable capture of documentation. |
#suppress | Use this to suppress a |
#initialize_visibility | Initializes state for visibility of this |
Generator::Markup
- Included
#aref_to | Generates a relative URL from this object’s path to |
#as_href | Generates a relative URL from |
#cvs_url | Build a webcvs URL starting for the given |
#description | Handy wrapper for marking up this object’s comment. |
#formatter | Creates an |
Text
- Included
#expand_tabs | Expands tab characters in #text to eight spaces. |
#flush_left | Flush #text left based on the shortest line. |
#markup | Convert a string in markup format into HTML. |
#normalize_comment | Strips hashes, expands tabs then flushes #text to the left. |
#parse | Normalizes #text then builds a |
#snippet | The first |
#strip_hashes | Strips leading # characters from #text |
#strip_newlines | Strips leading and trailing n characters from #text |
#strip_stars | Strips /* */ style comments. |
#to_html | Converts ampersand, dashes, ellipsis, quotes, copyright and registered trademark symbols in #text to properly encoded characters. |
#wrap | Wraps |
Constructor Details
.new(text, name) ⇒ MethodAttr
# File 'lib/rdoc/code_object/method_attr.rb', line 78
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
Instance Attribute Details
#aliases (readonly)
Array of other names for this method/attribute
# File 'lib/rdoc/code_object/method_attr.rb', line 32
attr_reader :aliases
#arglists (readonly)
The call_seq or the param_seq with method name, if there is no call_seq.
# File 'lib/rdoc/code_object/method_attr.rb', line 64
attr_reader :arglists
#block_params (rw)
Parameters yielded by the called block
# File 'lib/rdoc/code_object/method_attr.rb', line 49
attr_reader :block_params
#block_params=(value) (rw)
Attempts to sanitize the content passed by the Ruby parser: remove outer parentheses, etc.
# File 'lib/rdoc/code_object/method_attr.rb', line 233
def block_params=(value) # 'yield.to_s' or 'assert yield, msg' return @block_params = '' if value =~ /^[\.,]/ # remove trailing 'if/unless ...' return @block_params = '' if value =~ /^(if|unless)\s/ value = $1.strip if value =~ /^(.+)\s(if|unless)\s/ # outer parentheses value = $1 if value =~ /^\s*\((.*)\)\s*$/ value = value.strip # proc/lambda return @block_params = $1 if value =~ /^(proc|lambda)(\s*\{|\sdo)/ # surrounding ... or [...] value = $1.strip if value =~ /^\(.*)\$/ value = $1.strip if value =~ /^\[(.*)\]$/ return @block_params = '' if value.empty? # global variable return @block_params = 'str' if value =~ /^\$[&0-9]$/ # wipe out array/hash indices value.gsub!(/(\w)\[[^\[]+\]/, '\1') # remove @ from class/instance variables value.gsub!(/@@?([a-z0-9_]+)/, '\1') # method calls => method name value.gsub!(/([A-Z:a-z0-9_])\.([a-z0-9_])(\s*\(\s*[a-z0-9_.,\s]*\s*\)\s*)?/) do case $2 when 'to_s' then $1 when 'const_get' then 'const' when 'new' then $1.split('::').last. # ClassName => class_name gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2'). gsub(/([a-z\d])([A-Z])/, '\1_\2'). downcase else $2 end end # class prefixes value.gsub!(/[A-Za-z0-9_:]+::/, '') # simple expressions value = $1 if value =~ /^([a-z0-9_])\s*[-*\/]/ @block_params = value.strip end
#call_seq (rw)
Different ways to call this method
# File 'lib/rdoc/code_object/method_attr.rb', line 59
attr_accessor :call_seq
#documented? ⇒ Boolean
(readonly)
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.
# File 'lib/rdoc/code_object/method_attr.rb', line 132
def documented? super or (is_alias_for and is_alias_for.documented?) or (see and see.documented?) end
#is_alias_for (rw)
The method/attribute we’re aliasing
# File 'lib/rdoc/code_object/method_attr.rb', line 37
attr_accessor :is_alias_for
#name (rw)
Name of this method/attribute.
# File 'lib/rdoc/code_object/method_attr.rb', line 12
attr_accessor :name
#param_seq (readonly)
Pretty parameter list for this method
# File 'lib/rdoc/code_object/method_attr.rb', line 69
attr_reader :param_seq
#params (rw)
Parameters for this method
# File 'lib/rdoc/code_object/method_attr.rb', line 54
attr_accessor :params
#singleton (rw)
Is this a singleton method/attribute?
# File 'lib/rdoc/code_object/method_attr.rb', line 22
attr_accessor :singleton
#store=(store) (writeonly)
Sets the store for this class or module and its contained code objects.
# File 'lib/rdoc/code_object/method_attr.rb', line 160
def store= store super @file = @store.add_file @file.full_name if @file end
#text (readonly)
Source file token stream
# File 'lib/rdoc/code_object/method_attr.rb', line 27
attr_reader :text
#visibility (rw)
public, protected, private
# File 'lib/rdoc/code_object/method_attr.rb', line 17
attr_accessor :visibility
Instance Method Details
#<=>(other)
Order by #singleton then #name
#==(other)
#add_alias(an_alias, context)
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
.
# File 'lib/rdoc/code_object/method_attr.rb', line 209
def add_alias(an_alias, context) raise NotImplementedError end
#add_line_numbers(src)
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.
# File 'lib/rdoc/generator/markup.rb', line 77
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
HTML fragment reference for this method
# File 'lib/rdoc/code_object/method_attr.rb', line 216
def aref type = singleton ? 'c' : 'i' # % characters are not allowed in html names => dash instead "#{aref_prefix}-#{type}-#{html_name}" end
#aref_prefix
Prefix for #aref, defined by subclasses.
# File 'lib/rdoc/code_object/method_attr.rb', line 225
def aref_prefix raise NotImplementedError end
#find_method_or_attribute(name)
# File 'lib/rdoc/code_object/method_attr.rb', line 178
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
# File 'lib/rdoc/code_object/method_attr.rb', line 166
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
Full method/attribute name including namespace
# File 'lib/rdoc/code_object/method_attr.rb', line 300
def full_name @full_name ||= "#{parent_name}#{pretty_name}" end
#html_name
HTML id-friendly method/attribute name
# File 'lib/rdoc/code_object/method_attr.rb', line 291
def html_name require 'cgi/util' CGI.escape(@name.gsub('-', '-2D')).gsub('%', '-').sub(/^-/, '') end
#initialize_copy(other)
Resets cached data for the object so it can be rebuilt by accessor methods
# File 'lib/rdoc/code_object/method_attr.rb', line 101
def initialize_copy other # :nodoc: @full_name = nil end
#initialize_visibility
# File 'lib/rdoc/code_object/method_attr.rb', line 105
def initialize_visibility # :nodoc: super @see = nil end
#inspect
# File 'lib/rdoc/code_object/method_attr.rb', line 304
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
Turns the method’s token stream into HTML.
Prepends line numbers if options.line_numbers
is true.
# File 'lib/rdoc/generator/markup.rb', line 101
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 .line_numbers src end
#name_prefix
‘::’ for a class method/attribute, ‘#’ for an instance method.
# File 'lib/rdoc/code_object/method_attr.rb', line 319
def name_prefix @singleton ? '::' : '#' end
#output_name(context)
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.
# File 'lib/rdoc/code_object/method_attr.rb', line 330
def output_name context return "#{name_prefix}#{@name}" if context == parent "#{parent_name}#{@singleton ? '.' : '#'}#{@name}" end
#parent_name
Name of our parent with special handling for un-marshaled methods
# File 'lib/rdoc/code_object/method_attr.rb', line 360
def parent_name @parent_name || super end
#path
Path to this method for use with HTML generator output.
# File 'lib/rdoc/code_object/method_attr.rb', line 353
def path "#{@parent.path}##{aref}" end
#pretty_name
Method/attribute name with class/instance indicator
# File 'lib/rdoc/code_object/method_attr.rb', line 339
def pretty_name "#{name_prefix}#{@name}" end
#pretty_print(q)
# File 'lib/rdoc/code_object/method_attr.rb', line 364
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
Used by Generator::JsonIndex
to create a record for the search engine.
#see
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.
# File 'lib/rdoc/code_object/method_attr.rb', line 152
def see @see = find_see if @see == false @see end
#to_s
# File 'lib/rdoc/code_object/method_attr.rb', line 410
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
Type of method/attribute (class or instance)
# File 'lib/rdoc/code_object/method_attr.rb', line 346
def type singleton ? 'class' : 'instance' end