# Class: YARD::Options Abstract

Inherits:
  Object
  - Object
  - YARD::Options
  show all

Defined in:
  lib/yard/options.rb

## Overview

This class is abstract.

Subclasses should define (and document) custom attributes that are expected to be made available as option keys.

Generalized options class for passing around large amounts of options between objects.

The options class exists for better visibility and documentability of options being passed through to other objects. Because YARD has parser and template architectures that are heavily reliant on options, it is necessary to make these option keys easily visible and understood by developers. Since the options class is more than just a basic Hash, the subclass can provide aliasing and convenience methods to simplify option property access, and, if needed, support backward-compatibility for deprecated key names.

## Hash and OpenStruct-like Access

Although the options class allows for Hash-like access (`opts[:key]`), the recommended mechanism for accessing an option key will be via standard method calls on attributes

The options class can also act as an open ended key value storage structure (like a Hash or OpenStruct), and allows for setting and getting of unregistered option keys. This methodology is not recommended, however, and is only supported for backward compatibility inside YARD. Whenever possible, developers should define all keys used by an options class.

## Declaring Default Values

Note that the options class can contain default value definitions for certain options, but to initialize these defaults, #reset_defaults must be called manually after initialization; the options object is always created empty until defaults are applied.

#### Examples:

#####

Defining an Options class with custom option keys

    class TemplateOptions < YARD::Options
      # @return [Symbol] the output format to generate templates in
      attr_accessor :format

      # @return [Symbol] the template to use when generating output
      attr_accessor :template
    end

#####

Initializing default option values

    class TemplateOptions < YARD::Options
      def reset_defaults
        super
        self.format = :html
        self.template = :default
        self.highlight = true
        # ...
      end
    end

#####

Using `default_attr` to create default attributes

    class TemplateOptions < YARD::Options
      default_attr :format, :html
      default_attr :template, :default
      default_attr :highlight, true
    end

#####

Deprecating an option while still supporting it

    class TemplateOptions < YARD::Options
      # @return [Boolean] if syntax highlighting should be performed on code blocks.
      #   Defaults to true.
      attr_accessor :highlight

      # @deprecated Use {#highlight} instead.
      # @return [Boolean] if no syntax highlighting should be performs on code blocks.
      #   Defaults to false.
      attr_accessor :no_highlight
      def no_highlight=(value) @highlight = !value end
      def no_highlight; !highlight end
    end

## Direct Known Subclasses

Templates::TemplateOptions

## Class Method Summary collapse

- .default_attr(key, default) ⇒ Object

  Defines an attribute named `key` and sets a default value for it.

## Instance Method Summary collapse

- #==(other) ⇒ Boolean

  Whether another Options object equals the keys and values of this options object.

- #[](key) ⇒ Object

  Delegates calls with Hash syntax to actual method with key name.

- #[]=(key, value) ⇒ Object

  Delegates setter calls with Hash syntax to the attribute setter with the key name.

- #delete(key) ⇒ Object

  Deletes an option value for `key`.

- #each {|key, value| ... } ⇒ void

  Yields over every option key and value.

- #inspect ⇒ Object

  Inspects the object.

- #merge(opts) ⇒ Options

  Creates a new options object and sets options hash or object value onto that object.

- #method_missing(meth, *args, &block) ⇒ Object

  Handles setting and accessing of unregistered keys similar to an OpenStruct object.

- #reset_defaults ⇒ void abstract

  Resets all values to their defaults.

- #tap {|_self| ... } ⇒ Object

  only for 1.8.6.

- #to_hash ⇒ Hash

  Converts options object to an options hash.

- #update(opts) ⇒ self

  Updates values from an options hash or options object on this object.

## Dynamic Method Handling

This class handles dynamic methods through the `method_missing` method

### #method_missing(meth, *args, &block) ⇒ `Object`

Note:

It is not recommended to set and access unregistered keys on an Options object. Instead, register the attribute before using it.

Handles setting and accessing of unregistered keys similar to an OpenStruct object.

    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180

    # File 'lib/yard/options.rb', line 170

    def method_missing(meth, *args, &block)
      if meth.to_s =~ /^(.+)=$/
        log.debug "Attempting to set unregistered key #{$1} on #{self.class}"
        instance_variable_set("@#{$1}", args.first)
      elsif args.empty?
        log.debug "Attempting to access unregistered key #{meth} on #{self.class}"
        instance_variable_defined?("@#{meth}") ? instance_variable_get("@#{meth}") : nil
      else
        super
      end
    end

## Class Method Details

### .default_attr(key, default) ⇒ `Object`

Defines an attribute named `key` and sets a default value for it

#### Examples:

#####

Defining a default option key

    default_attr :name, 'Default Name'
    default_attr :time, lambda { Time.now }

Parameters:

- key (`Symbol`) —

  the option key name

- default (`Object`, `Proc`) —

  the default object value. If the default value is a proc, it is executed upon initialization.

    80
    81
    82
    83

    # File 'lib/yard/options.rb', line 80

    def self.default_attr(key, default)
      (@defaults ||= {})[key] = default
      attr_accessor(key)
    end

## Instance Method Details

### #==(other) ⇒ `Boolean`

Returns whether another Options object equals the keys and values of this options object.

Returns:

- (`Boolean`) —

  whether another Options object equals the keys and values of this options object

    157
    158
    159
    160
    161
    162
    163

    # File 'lib/yard/options.rb', line 157

    def ==(other)
      case other
      when Options; to_hash == other.to_hash
      when Hash; to_hash == other
      else false
      end
    end

### #[](key) ⇒ `Object`

Delegates calls with Hash syntax to actual method with key name

#### Examples:

#####

Calling on an option key with Hash syntax

    options[:format] # equivalent to: options.format

Parameters:

- key (`Symbol`, `String`) —

  the option name to access

Returns:

- the value of the option named `key`

    91

    # File 'lib/yard/options.rb', line 91

    def [](key) send(key) end

### #[]=(key, value) ⇒ `Object`

Delegates setter calls with Hash syntax to the attribute setter with the key name

#### Examples:

#####

Setting an option with Hash syntax

    options[:format] = :html # equivalent to: options.format = :html

Parameters:

- key (`Symbol`, `String`) —

  the option to set

- value (`Object`) —

  the value to set for the option

Returns:

- (`Object`) —

  the value being set

    100

    # File 'lib/yard/options.rb', line 100

    def []=(key, value) send("#{key}=", value) end

### #delete(key) ⇒ `Object`

Deletes an option value for `key`

Parameters:

- key (`Symbol`, `String`) —

  the key to delete a value for

Returns:

- (`Object`) —

  the value that was deleted

    207
    208
    209
    210
    211
    212
    213

    # File 'lib/yard/options.rb', line 207

    def delete(key)
      val = self[key]
      if instance_variable_defined?("@#{key}")
        remove_instance_variable("@#{key}")
      end
      val
    end

### #each {|key, value| ... } ⇒ `void`

This method returns an undefined value.

Yields over every option key and value

Yields:

- (`key`, `value`) —

  every option key and value

Yield Parameters:

- key (`Symbol`) —

  the option key

- value (`Object`) —

  the option value

    143
    144
    145
    146
    147
    148

    # File 'lib/yard/options.rb', line 143

    def each
      instance_variables.each do |ivar|
        name = ivar.to_s.sub(/^@/, '')
        yield(name.to_sym, send(name))
      end
    end

### #inspect ⇒ `Object`

Inspects the object

    151
    152
    153

    # File 'lib/yard/options.rb', line 151

    def inspect
      "<#{self.class}: #{to_hash.inspect}>"
    end

### #merge(opts) ⇒ `Options`

Creates a new options object and sets options hash or object value onto that object.

Parameters:

- opts (`Options`, `Hash`)

Returns:

- (`Options`) —

  the newly created options object

See Also:

- #update

    123
    124
    125

    # File 'lib/yard/options.rb', line 123

    def merge(opts)
      dup.update(opts)
    end

### #reset_defaults ⇒ `void`

This method is abstract.

Subclasses should override this method to perform custom value initialization if not using default_attr. Be sure to call `super` so that default initialization can take place.

This method returns an undefined value.

Resets all values to their defaults.

    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201

    # File 'lib/yard/options.rb', line 188

    def reset_defaults
      names_set = {}
      self.class.ancestors.each do |klass| # look at all ancestors
        defaults =
          klass.instance_variable_defined?("@defaults") &&
          klass.instance_variable_get("@defaults")
        next unless defaults
        defaults.each do |key, value|
          next if names_set[key]
          names_set[key] = true
          self[key] = Proc === value ? value.call : value
        end
      end
    end

### #tap {|_self| ... } ⇒ `Object`

only for 1.8.6

Yields:

- (`_self`)

Yield Parameters:

- _self (`YARD::Options`) —

  the object that the method was called on

    215

    # File 'lib/yard/options.rb', line 215

    def tap; yield(self); self end

### #to_hash ⇒ `Hash`

Returns Converts options object to an options hash. All keys will be symbolized.

Returns:

- (`Hash`) —

  Converts options object to an options hash. All keys will be symbolized.

    129
    130
    131
    132
    133
    134
    135
    136

    # File 'lib/yard/options.rb', line 129

    def to_hash
      opts = {}
      instance_variables.each do |ivar|
        name = ivar.to_s.sub(/^@/, '')
        opts[name.to_sym] = send(name)
      end
      opts
    end

### #update(opts) ⇒ `self`

Updates values from an options hash or options object on this object. All keys passed should be key names defined by attributes on the class.

#### Examples:

#####

Updating a set of options on an Options object

    opts.update(:template => :guide, :type => :fulldoc)

Parameters:

- opts (`Hash`, `Options`)

Returns:

- (`self`)

    109
    110
    111
    112
    113
    114
    115

    # File 'lib/yard/options.rb', line 109

    def update(opts)
      opts = opts.to_hash if Options === opts
      opts.each do |key, value|
        self[key] = value
      end
      self
    end