123456789_123456789_123456789_123456789_123456789_

Class: YARD::Options Abstract

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
CLI::GraphOptions, CLI::YardocOptions, Templates::TemplateOptions, Server::Commands::LibraryIndexOptions, Server::Commands::LibraryOptions
Inherits: Object
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

Class Method Summary

Instance Method Summary

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(meth, *args, &block)

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.

[ GitHub ] 

  


# 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)  
  



  

    
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.
    

    
  
    • 





  [ GitHub ]


  

  


# 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:


    
  
  • 
    (Boolean)
—    
    whether another Options object equals the
keys and values of this options object
    

    
  
    • 





  [ GitHub ]


  

  


# 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
    

    
  
    • 





  [ GitHub ]


  

  


# 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
    

    
  
    • 





  [ GitHub ]


  

  


# 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
    

    
  
    • 





  [ GitHub ]


  

  


# 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
    

    
  
    • 





  [ GitHub ]


  

  


# 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  
  



  

    
Inspects the object


  



  [ GitHub ]


  

  


# 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:

  



  [ GitHub ]


  

  


# 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.


  





  


  [ GitHub ]


  

  


# 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| ... } 
  



  

    
only for 1.8.6


  





  
Yields:


    
  
  • 
    (_self)
  
    • 



Yield Parameters:


    
  
  • 
    _self
    (Options)
—    
    the object that the method was called on
    

    
  
    • 





  [ GitHub ]


  

  


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



def tap; yield(self); self end unless defined?(tap) # only for 1.8.6


  








  

    #to_hash  ⇒ Hash 
  



  

    
  





  
Returns:


    
  
  • 
    (Hash)
—    
    Converts options object to an options hash. All keys
will be symbolized.
    

    
  
    • 





  [ GitHub ]


  

  


# 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)
  
    • 





  [ GitHub ]


  

  


# 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