# Module: YARD::CodeObjects::NamespaceMapper

Included in:
  YARD::CodeObjects, Parser::Ruby::TokenResolver, RegistryResolver

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

## Overview

This module controls registration and accessing of namespace separators for Registry lookup.

Since:

- 0.9.1

## Registering a Separator for a Namespace collapse

- #clear_separators ⇒ void

  Clears the map of separators.

- #default_separator(value = nil) ⇒ Object

  Gets or sets the default separator value to use when no separator for the namespace can be determined.

- #register_separator(sep, *valid_types) ⇒ Object

  Registers a separator with an optional set of valid types that must follow the separator lexically.

- #unregister_separator_by_type(type) ⇒ Object

  Unregisters a separator by a type.

## Separator and Type Lookup Helpers collapse

- #separators ⇒ Array<String>

  All of the registered separators.

- #separators_for_type(type) ⇒ Array<Symbol>

  A list of separators registered to a type.

- #separators_match ⇒ Regexp

  The regexp match of all separators.

- #types_for_separator(sep) ⇒ Array<Symbol>

  A list of types registered to a separator.

## Invalidation callbacks collapse

- .on_invalidate(&block) ⇒ Object

  Adds a callback that triggers when a new separator is registered or the cache is cleared by invalidation.

## Class Method Details

### .on_invalidate(&block) ⇒ `Object`

Adds a callback that triggers when a new separator is registered or the cache is cleared by invalidation.

Since:

- 0.9.1

    107
    108
    109

    # File 'lib/yard/code_objects/namespace_mapper.rb', line 107

    def on_invalidate(&block)
      (@invalidation_callbacks ||= []).push(block)
    end

## Instance Method Details

### #clear_separators ⇒ `void`

This method returns an undefined value.

Clears the map of separators.

Since:

- 0.9.1

    55
    56
    57
    58
    59

    # File 'lib/yard/code_objects/namespace_mapper.rb', line 55

    def clear_separators
      NamespaceMapper.invalidate
      NamespaceMapper.map = {}
      NamespaceMapper.rev_map = {}
    end

### #default_separator(value = nil) ⇒ `Object`

Gets or sets the default separator value to use when no separator for the namespace can be determined.

#### Examples:

    default_separator "::"

Parameters:

- value (`String`, `nil`) (defaults to: `nil`) —

  the default separator, or nil to return the value

Since:

- 0.9.1

    68
    69
    70
    71
    72
    73
    74
    75

    # File 'lib/yard/code_objects/namespace_mapper.rb', line 68

    def default_separator(value = nil)
      if value
        NamespaceMapper.invalidate
        NamespaceMapper.default_separator = Regexp.quote value
      else
        NamespaceMapper.default_separator
      end
    end

### #register_separator(sep, *valid_types) ⇒ `Object`

Registers a separator with an optional set of valid types that must follow the separator lexically.

Calls all callbacks defined by on_invalidate after the separator is registered.

#### Examples:

#####

Registering separators for a method object

    # Anything after a "#" denotes a method object
    register_separator "#", :method
    # Anything after a "." denotes a method object
    register_separator ".", :method

Parameters:

- sep (`String`) —

  the separator string for the namespace

- valid_types (`Array<Symbol>`) —

  a list of object types that must follow the separator. If the list is empty, any type can follow the separator.

See Also:

- on_invalidate

Since:

- 0.9.1

    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37

    # File 'lib/yard/code_objects/namespace_mapper.rb', line 27

    def register_separator(sep, *valid_types)
      NamespaceMapper.invalidate

      valid_types.each do |t|
        NamespaceMapper.rev_map[t] ||= []
        NamespaceMapper.rev_map[t] << sep
      end

      NamespaceMapper.map[sep] ||= []
      NamespaceMapper.map[sep] += valid_types
    end

### #separators ⇒ `Array<String>`

Returns all of the registered separators.

Returns:

- (`Array<String>`) —

  all of the registered separators

Since:

- 0.9.1

    80
    81
    82

    # File 'lib/yard/code_objects/namespace_mapper.rb', line 80

    def separators
      NamespaceMapper.map.keys
    end

### #separators_for_type(type) ⇒ `Array<Symbol>`

Returns a list of separators registered to a type.

Parameters:

- type (`String`) —

  the type to return separators for

Returns:

- (`Array<Symbol>`) —

  a list of separators registered to a type

Since:

- 0.9.1

    97
    98
    99

    # File 'lib/yard/code_objects/namespace_mapper.rb', line 97

    def separators_for_type(type)
      NamespaceMapper.rev_map[type] || []
    end

### #separators_match ⇒ `Regexp`

Returns the regexp match of all separators.

Returns:

- (`Regexp`) —

  the regexp match of all separators

Since:

- 0.9.1

    85
    86
    87

    # File 'lib/yard/code_objects/namespace_mapper.rb', line 85

    def separators_match
      NamespaceMapper.map_match
    end

### #types_for_separator(sep) ⇒ `Array<Symbol>`

Returns a list of types registered to a separator.

Parameters:

- sep (`String`) —

  the separator to return types for

Returns:

- (`Array<Symbol>`) —

  a list of types registered to a separator

Since:

- 0.9.1

    91
    92
    93

    # File 'lib/yard/code_objects/namespace_mapper.rb', line 91

    def types_for_separator(sep)
      NamespaceMapper.map[sep] || []
    end

### #unregister_separator_by_type(type) ⇒ `Object`

Unregisters a separator by a type.

Parameters:

- type (`Symbol`) —

  the type to unregister

See Also:

- #register_separator

Since:

- 0.9.1

    43
    44
    45
    46
    47
    48
    49
    50

    # File 'lib/yard/code_objects/namespace_mapper.rb', line 43

    def unregister_separator_by_type(type)
      seps = NamespaceMapper.rev_map[type]
      return unless seps

      seps.each {|s| NamespaceMapper.map.delete(s) }
      NamespaceMapper.rev_map.delete(type)
      NamespaceMapper.invalidate
    end