123456789_123456789_123456789_123456789_123456789_

Class: YARD::Handlers::Ruby::ClassHandler

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Base, ::YARD::Parser::Ruby, ::YARD::Handlers::Base
Instance Chain:
self, StructHandlerMethods, Base, ::YARD::Parser::Ruby, ::YARD::Handlers::Base, ::YARD::Parser, ::YARD::CodeObjects
Inherits: YARD::Handlers::Ruby::Base
Defined in: lib/yard/handlers/ruby/class_handler.rb

Overview

Handles class declarations

Constant Summary

::YARD::CodeObjects - Included

BUILTIN_ALL, BUILTIN_CLASSES, BUILTIN_EXCEPTIONS, BUILTIN_EXCEPTIONS_HASH, BUILTIN_MODULES, CONSTANTMATCH, CONSTANTSTART, CSEP, CSEPQ, ISEP, ISEPQ, METHODMATCH, METHODNAMEMATCH, NAMESPACEMATCH, NSEP, NSEPQ, PROXY_MATCH

Class Attribute Summary

::YARD::Handlers::Base - Inherited

.namespace_only

Declares that the handler should only be called when inside a ::YARD::CodeObjects::NamespaceObject, not a method body.
.namespace_only?

Class Method Summary

Base - Inherited

.handles?,
.meta_type

Matcher for handling a node with a specific meta-type.
.method_call

Matcher for handling any type of method call.

::YARD::Parser::Ruby - Extended

s

Builds and s-expression by creating AstNode objects with the type provided by the first argument.

::YARD::Handlers::Base - Inherited

.clear_subclasses

Clear all registered subclasses.
.handlers,
.handles

Declares the statement type which will be processed by this handler.
.handles?

This class is implemented by Base and Legacy::Base.
.in_file

Declares that a handler should only be called when inside a filename by its basename or a regex match for the full path.
.inherited, .matches_file?, .new,
.process

Generates a #process method, equivalent to +def process; ...
.subclasses

Returns all registered handler subclasses.

Instance Attribute Summary

::YARD::Handlers::Base - Inherited

#extra_state

Share state across different handlers inside of a file.
#globals

::YARD::Handlers can share state for the entire post processing stage through this attribute.
#namespace, #namespace=, #owner, #owner=, #parser, #scope, #scope=, #statement, #visibility, #visibility=

Instance Method Summary

StructHandlerMethods - Included

#add_reader_tags

Creates the auto-generated docstring for the getter method of a struct's member.
#add_writer_tags

Creates the auto-generated docstring for the setter method of a struct's member.
#create_attributes

Creates the given member methods and attaches them to the given ClassObject.
#create_class

Creates and registers a class object with the given name and superclass name.
#create_member_method?

Determines whether to create an attribute method based on the class's tags.
#create_reader

Creates the getter (reader) method and attaches it to the class as an attribute.
#create_writer

Creates the setter (writer) method and attaches it to the class as an attribute.
#member_tag_for_member

Extracts the user's defined @member tag for a given class and its member.
#members_from_tags

Retrieves all members defined in @attr* tags.
#return_type_from_tag

Gets the return type for the member in a nicely formatted string.

Base - Inherited

#call_params, #caller_method, #parse_block

::YARD::Parser::Ruby - Included

#s

Builds and s-expression by creating AstNode objects with the type provided by the first argument.

::YARD::Handlers::Base - Inherited

#abort!

Aborts a handler by raising ::YARD::Handlers::HandlerAborted.
#call_params, #caller_method,
#ensure_loaded!

Ensures that a specific object has been parsed and loaded into the registry.
#parse_block

Parses the semantic "block" contained in the statement node.
#process

The main handler method called by the parser on a statement that matches the handles declaration.
#push_state

Executes a given block with specific state values for #owner, #namespace and #scope.
#register

Do some post processing on a list of code objects.
#register_docstring

Registers any docstring found for the object and expands macros.
#register_dynamic

Registers the object as dynamic if the object is defined inside a method or block (owner != namespace).
#register_ensure_loaded

Ensures that the object's namespace is loaded before attaching it to the namespace.
#register_file_info

Registers the file/line of the declaration with the object.
#register_group

Registers the object as being inside a specific group.
#register_module_function

Registers the same method information on the module function, if the object was defined as a module function.
#register_source,
#register_transitive_tags

Registers any transitive tags from the namespace on the object.
#register_visibility

Registers visibility on a method object.

Constructor Details

This class inherits a constructor from YARD::Handlers::Base

Instance Method Details

#create_struct_superclass(superclass, superclass_def) (private)

[ GitHub ] 

  


# File 'lib/yard/handlers/ruby/class_handler.rb', line 73



def create_struct_superclass(superclass, superclass_def)
  return if superclass == "Struct"
  the_super = register ClassObject.new(P("Struct"), superclass[8..-1]) do |o|
    o.superclass = "Struct"
  end
  parse_struct_superclass(the_super, superclass_def)
  the_super
end


  








  

    #extract_parameters(superclass)  ⇒ Array<String>  (private)
  



  

    
Extract the parameters from the Struct.new AST node, returning them as a list
of strings


  





  
Parameters:


    
  
  • 
    superclass
    (MethodCallNode)
—    
    the AST node for the Struct.new call
    

    
  
    • 



Returns:


    
  
  • 
    (Array<String>)
—    
    the member names to generate methods for
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/handlers/ruby/class_handler.rb', line 67



def extract_parameters(superclass)
  members = superclass.parameters.select {|x| x && x.type == :symbol_literal }
  members.map! {|x| x.source.strip[1..-1] }
  members
end


  








  

    #parse_struct_superclass(klass, superclass)   (private)
  

  [ GitHub ]


  

  


# File 'lib/yard/handlers/ruby/class_handler.rb', line 92



def parse_struct_superclass(klass, superclass)
  return unless superclass.call? && superclass.parameters
  members = extract_parameters(superclass)
  create_attributes(klass, members)
end


  








  

    #parse_superclass(superclass)   (private)
  

  [ GitHub ]


  

  


# File 'lib/yard/handlers/ruby/class_handler.rb', line 98



def parse_superclass(superclass)
  return nil unless superclass

  case superclass.type
  when :var_ref
    return namespace.path if superclass.first == s(:kw, "self")
    return superclass.source if superclass.first.type == :const
  when :const, :const_ref, :const_path_ref, :top_const_ref
    return superclass.source
  when :fcall, :command
    methname = superclass.method_name.source
    return superclass.parameters.first.source if methname == "DelegateClass"
    return methname if superclass.method_name.type == :const
  when :call, :command_call
    cname = superclass.namespace.source
    if cname =~ /^O?Struct$/ && superclass.method_name(true) == :new
      return cname
    end
  end
  nil
end


  








  

    #process  ⇒ void 
  



  

    
This method returns an undefined value.
Main processing callback


  





  


  [ GitHub ]


  

  


# File 'lib/yard/handlers/ruby/class_handler.rb', line 8



process do
  classname = statement[0].source.gsub(/\s/, '')
  if statement.type == :class
    superclass = parse_superclass(statement[1])
    if superclass == "Struct"
      is_a_struct = true
      superclass = struct_superclass_name(statement[1]) # refine the superclass if possible
      create_struct_superclass(superclass, statement[1])
    end
    undocsuper = statement[1] && superclass.nil?
    klass = register ClassObject.new(namespace, classname) do |o|
      o.superclass = superclass if superclass
      o.superclass.type = :class if o.superclass.is_a?(Proxy)
    end
    if is_a_struct
      parse_struct_superclass(klass, statement[1])
    elsif klass
      create_attributes(klass, members_from_tags(klass))
    end
    parse_block(statement[2], :namespace => klass)

    if undocsuper
      raise YARD::Parser::UndocumentableError, 'superclass (class was added without superclass)'
    end
  elsif statement.type == :sclass
    if statement[0] == s(:var_ref, s(:kw, "self"))
      parse_block(statement[1], :namespace => namespace, :scope => :class)
    else
      proxy = Proxy.new(namespace, classname)

      # Allow constants to reference class names
      if ConstantObject === proxy
        if proxy.value =~ /\A#{NAMESPACEMATCH}\Z/
          proxy = Proxy.new(namespace, proxy.value)
        else
          raise YARD::Parser::UndocumentableError, "constant class reference '#{classname}'"
        end
      end

      if classname[0, 1] =~ /[A-Z]/
        register ClassObject.new(namespace, classname) if Proxy === proxy
        parse_block(statement[1], :namespace => proxy, :scope => :class)
      else
        raise YARD::Parser::UndocumentableError, "class '#{classname}'"
      end
    end
  else
    sig_end = (statement[1] ? statement[1].source_end : statement[0].source_end) - statement.source_start
    raise YARD::Parser::UndocumentableError, "class: #{statement.source[0..sig_end]}"
  end
end


  








  

    #struct_superclass_name(superclass)   (private)
  

  [ GitHub ]


  

  


# File 'lib/yard/handlers/ruby/class_handler.rb', line 82



def struct_superclass_name(superclass)
  if superclass.call?
    first = superclass.parameters.first
    if first.type == :string_literal && first[0].type == :string_content && first[0].size == 1
      return "Struct::#{first[0][0][0]}"
    end
  end
  "Struct"
end