Class: YARD::Options Abstract

Inherits:
Object
  • Object
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

Instance Method Summary collapse

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.



169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/yard/options.rb', line 169

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.size == 0
    log.debug "Attempting to access unregistered key #{meth} on #{self.class}"
    instance_variable_get("@#{meth}")
  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.



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

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



156
157
158
159
160
161
162
 
# File 'lib/yard/options.rb', line 156

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



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

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 optin to set

  • value (Object) —

    the value to set for the option

Returns:

  • (Object) —

    the value being set



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

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



204
205
206
207
208
209
210
 
# File 'lib/yard/options.rb', line 204

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



142
143
144
145
146
147
 
# File 'lib/yard/options.rb', line 142

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

#inspect ⇒ Object

Inspects the object



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

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:

Returns:

  • (Options) —

    the newly created options object

See Also:



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

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.



187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/yard/options.rb', line 187

def reset_defaults
  names_set = {}
  self.class.ancestors.each do |klass| # look at all ancestors
    defaults = klass.instance_variable_get("@defaults")
    return 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

Yields:

  • (_self)

Yield Parameters:

  • _self (YARD::Options) —

    the object that the method was called on



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

def tap(&block) 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.



128
129
130
131
132
133
134
135
 
# File 'lib/yard/options.rb', line 128

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:

Returns:

  • (self) 


108
109
110
111
112
113
114
 
# File 'lib/yard/options.rb', line 108

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