# Class: YARD::CodeObjects::NamespaceObject

Inherits:
  Base
  - Object
  - Base
  - YARD::CodeObjects::NamespaceObject
  show all

Defined in:
  lib/yard/code_objects/namespace_object.rb

## Overview

A “namespace” is any object that can store other objects within itself. The two main Ruby objects that can act as namespaces are modules (ModuleObject) and classes (ClassObject).

## Direct Known Subclasses

ClassObject, ModuleObject

## Instance Attribute Summary collapse

- #aliases ⇒ Hash readonly

  A hash containing two keys, :class and :instance, each containing a hash of objects and their alias names.

- #attributes ⇒ Hash readonly

  A hash containing two keys, class and instance, each containing the attribute name with a { :read, :write } hash for the read and write objects respectively.

- #children ⇒ Array<Base> readonly

  The list of objects defined in this namespace.

- #class_mixins ⇒ Array<ModuleObject> readonly

  Class mixins.

- #groups ⇒ Array<String>

  A list of ordered group names inside the namespace.

- #instance_mixins ⇒ Array<ModuleObject> readonly

  Instance mixins.

## Instance Method Summary collapse

- #child(opts = {}) ⇒ Base?

  Looks for a child that matches the attributes specified by `opts`.

- #class_attributes ⇒ Hash

  Only the class attributes.

- #constants(opts = {}) ⇒ Array<ConstantObject>

  Returns all constants in the namespace.

- #cvars ⇒ Array<ClassVariableObject>

  Returns class variables defined in this namespace.

- #included_constants ⇒ Array<ConstantObject>

  Returns constants included from any mixins.

- #included_meths(opts = {}) ⇒ Object

  Returns methods included from any mixins that match the attributes specified by `opts`.

- #initialize(namespace, name, *args, &block) ⇒ NamespaceObject constructor

  Creates a new namespace object inside `namespace` with `name`.

- #instance_attributes ⇒ Hash

  Only the instance attributes.

- #meths(opts = {}) ⇒ Array<MethodObject>

  Returns all methods that match the attributes specified by `opts`.

- #mixins(*scopes) ⇒ Array<ModuleObject>

  Returns for specific scopes.

## Constructor Details

### #initialize(namespace, name, *args, &block) ⇒ `NamespaceObject`

Creates a new namespace object inside `namespace` with `name`.

See Also:

- Base#initialize

    56
    57
    58
    59
    60
    61
    62
    63
    64

    # File 'lib/yard/code_objects/namespace_object.rb', line 56

    def initialize(namespace, name, *args, &block)
      @children = CodeObjectList.new(self)
      @class_mixins = CodeObjectList.new(self)
      @instance_mixins = CodeObjectList.new(self)
      @attributes = SymbolHash[:class => SymbolHash.new, :instance => SymbolHash.new]
      @aliases = {}
      @groups = []
      super
    end

## Dynamic Method Handling

This class handles dynamic methods through the `method_missing` method in the class YARD::CodeObjects::Base

## Instance Attribute Details

### #aliases ⇒ `Hash` (readonly)

A hash containing two keys, :class and :instance, each containing a hash of objects and their alias names.

Returns:

- (`Hash`) —

  a list of methods

    44
    45
    46

    # File 'lib/yard/code_objects/namespace_object.rb', line 44

    def aliases
      @aliases
    end

### #attributes ⇒ `Hash` (readonly)

A hash containing two keys, class and instance, each containing the attribute name with a { :read, :write } hash for the read and write objects respectively.

#### Examples:

#####

The attributes of an object

    >> Registry.at('YARD::Docstring').attributes
    => {
          :class => { },
          :instance => {
            :ref_tags => {
              :read => #<yardoc method YARD::Docstring#ref_tags>,
              :write => nil
            },
            :object => {
              :read => #<yardoc method YARD::Docstring#object>,
              :write => #<yardoc method YARD::Docstring#object=>
             },
             ...
          }
        }

Returns:

- (`Hash`) —

  a list of methods

    39
    40
    41

    # File 'lib/yard/code_objects/namespace_object.rb', line 39

    def attributes
      @attributes
    end

### #children ⇒ `Array<Base>` (readonly)

The list of objects defined in this namespace

Returns:

- (`Array<Base>`) —

  a list of objects

    16
    17
    18

    # File 'lib/yard/code_objects/namespace_object.rb', line 16

    def children
      @children
    end

### #class_mixins ⇒ `Array<ModuleObject>` (readonly)

Class mixins

Returns:

- (`Array<ModuleObject>`) —

  a list of mixins

    48
    49
    50

    # File 'lib/yard/code_objects/namespace_object.rb', line 48

    def class_mixins
      @class_mixins
    end

### #groups ⇒ `Array<String>`

Returns a list of ordered group names inside the namespace.

Returns:

- (`Array<String>`) —

  a list of ordered group names inside the namespace

Since:

- 0.6.0

    12
    13
    14

    # File 'lib/yard/code_objects/namespace_object.rb', line 12

    def groups
      @groups
    end

### #instance_mixins ⇒ `Array<ModuleObject>` (readonly)

Instance mixins

Returns:

- (`Array<ModuleObject>`) —

  a list of mixins

    52
    53
    54

    # File 'lib/yard/code_objects/namespace_object.rb', line 52

    def instance_mixins
      @instance_mixins
    end

## Instance Method Details

### #child(opts = {}) ⇒ `Base`?

Looks for a child that matches the attributes specified by `opts`.

#### Examples:

#####

Finds a child by name and scope

    namespace.child(:name => :to_s, :scope => :instance)
    # => #<yardoc method MyClass#to_s>

Returns:

- (`Base`, `nil`) —

  the first matched child object, or nil

    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97

    # File 'lib/yard/code_objects/namespace_object.rb', line 86

    def child(opts = {})
      if !opts.is_a?(Hash)
        children.find {|o| o.name == opts.to_sym }
      else
        opts = SymbolHash[opts]
        children.find do |obj|
          opts.each do |meth, value|
            break false unless value.is_a?(Array) ? value.include?(obj[meth]) : obj[meth] == value
          end
        end
      end
    end

### #class_attributes ⇒ `Hash`

Only the class attributes

Returns:

- (`Hash`) —

  a list of method names and their read/write objects

See Also:

- #attributes

    69
    70
    71

    # File 'lib/yard/code_objects/namespace_object.rb', line 69

    def class_attributes
      attributes[:class]
    end

### #constants(opts = {}) ⇒ `Array<ConstantObject>`

Returns all constants in the namespace

Parameters:

- opts (`Hash`) (defaults to: `{}`) —

  a customizable set of options

Options Hash (`opts`):

- :included (`Boolean`) — default: `true` —

  whether or not to include mixed in constants in list

Returns:

- (`Array<ConstantObject>`) —

  a list of constant objects

    164
    165
    166
    167
    168

    # File 'lib/yard/code_objects/namespace_object.rb', line 164

    def constants(opts = {})
      opts = SymbolHash[:included => true].update(opts)
      consts = children.select {|o| o.is_a? ConstantObject }
      consts + (opts[:included] ? included_constants : [])
    end

### #cvars ⇒ `Array<ClassVariableObject>`

Returns class variables defined in this namespace.

Returns:

- (`Array<ClassVariableObject>`) —

  a list of class variable objects

    186
    187
    188

    # File 'lib/yard/code_objects/namespace_object.rb', line 186

    def cvars
      children.select {|o| o.is_a? ClassVariableObject }
    end

### #included_constants ⇒ `Array<ConstantObject>`

Returns constants included from any mixins

Returns:

- (`Array<ConstantObject>`) —

  a list of constant objects

    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182

    # File 'lib/yard/code_objects/namespace_object.rb', line 172

    def included_constants
      instance_mixins.inject([]) do |list, mixin|
        if mixin.respond_to? :constants
          list += mixin.constants.reject do |o|
            child(:name => o.name) || list.find {|o2| o2.name == o.name }
          end
        else
          list
        end
      end
    end

### #included_meths(opts = {}) ⇒ `Object`

Returns methods included from any mixins that match the attributes specified by `opts`. If no options are specified, returns all included methods.

Parameters:

- opts (`Hash`) (defaults to: `{}`) —

  a customizable set of options

Options Hash (`opts`):

- :visibility (`Array<Symbol>`, `Symbol`) — default: `[:public`, `:private`, `:protected]` —

  the visibility of the methods to list. Can be an array or single value.

- :scope (`Array<Symbol>`, `Symbol`) — default: `[:class`, `:instance]` —

  the scope of the methods to list. Can be an array or single value.

- :included (`Boolean`) — default: `true` —

  whether to include mixed in methods in the list.

See Also:

- #meths

    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157

    # File 'lib/yard/code_objects/namespace_object.rb', line 144

    def included_meths(opts = {})
      opts = SymbolHash[:scope => [:instance, :class]].update(opts)
      [opts[:scope]].flatten.map do |scope|
        mixins(scope).inject([]) do |list, mixin|
          next list if mixin.is_a?(Proxy)
          arr = mixin.meths(opts.merge(:scope => :instance)).reject do |o|
            next false if opts[:all]
            child(:name => o.name, :scope => scope) || list.find {|o2| o2.name == o.name }
          end
          arr.map! {|o| ExtendedMethodObject.new(o) } if scope == :class
          list + arr
        end
      end.flatten
    end

### #instance_attributes ⇒ `Hash`

Only the instance attributes

Returns:

- (`Hash`) —

  a list of method names and their read/write objects

See Also:

- #attributes

    76
    77
    78

    # File 'lib/yard/code_objects/namespace_object.rb', line 76

    def instance_attributes
      attributes[:instance]
    end

### #meths(opts = {}) ⇒ `Array<MethodObject>`

Returns all methods that match the attributes specified by `opts`. If no options are provided, returns all methods.

#### Examples:

#####

Finds all private and protected class methods

    namespace.meths(:visibility => [:private, :protected], :scope => :class)
    # => [#<yardoc method MyClass.privmeth>, #<yardoc method MyClass.protmeth>]

Parameters:

- opts (`Hash`) (defaults to: `{}`) —

  a customizable set of options

Options Hash (`opts`):

- :visibility (`Array<Symbol>`, `Symbol`) — default: `[:public`, `:private`, `:protected]` —

  the visibility of the methods to list. Can be an array or single value.

- :scope (`Array<Symbol>`, `Symbol`) — default: `[:class`, `:instance]` —

  the scope of the methods to list. Can be an array or single value.

- :included (`Boolean`) — default: `true` —

  whether to include mixed in methods in the list.

Returns:

- (`Array<MethodObject>`) —

  a list of method objects

    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130

    # File 'lib/yard/code_objects/namespace_object.rb', line 113

    def meths(opts = {})
      opts = SymbolHash[
        :visibility => [:public, :private, :protected],
        :scope => [:class, :instance],
        :included => true
      ].update(opts)

      opts[:visibility] = [opts[:visibility]].flatten
      opts[:scope] = [opts[:scope]].flatten

      ourmeths = children.select do |o|
        o.is_a?(MethodObject) &&
          opts[:visibility].include?(o.visibility) &&
          opts[:scope].include?(o.scope)
      end

      ourmeths + (opts[:included] ? included_meths(opts) : [])
    end

### #mixins(*scopes) ⇒ `Array<ModuleObject>`

Returns for specific scopes. If no scopes are provided, returns all mixins.

Parameters:

- scopes (`Array<Symbol>`) —

  a list of scopes (:class, :instance) to return mixins for. If this is empty, all scopes will be returned.

Returns:

- (`Array<ModuleObject>`) —

  a list of mixins

    194
    195
    196
    197
    198

    # File 'lib/yard/code_objects/namespace_object.rb', line 194

    def mixins(*scopes)
      return class_mixins if scopes == [:class]
      return instance_mixins if scopes == [:instance]
      class_mixins | instance_mixins
    end