### Home Classes Methods

### In Files

- lib/yard/options.rb

### Parent

Object

### Methods

- ::default_attr
- #==
- #[]
- #[]=
- #delete
- #each
- #inspect
- #merge
- #method_missing
- #reset_defaults
- #tap
- #to_hash
- #update

### Files

- LICENSE.txt
- MIT.txt

### Class/Module Index

Quicksearch

- YARD
- YARD::CLI
- YARD::CLI::Command
- YARD::CLI::CommandParser
- YARD::CLI::Config
- YARD::CLI::Diff
- YARD::CLI::Display
- YARD::CLI::Gems
- YARD::CLI::Graph
- YARD::CLI::GraphOptions
- YARD::CLI::Help
- YARD::CLI::I18n
- YARD::CLI::List
- YARD::CLI::MarkupTypes
- YARD::CLI::Server
- YARD::CLI::Stats
- YARD::CLI::YRI
- YARD::CLI::Yardoc
- YARD::CLI::YardocOptions
- YARD::CLI::YardoptsCommand
- YARD::CodeObjects
- YARD::CodeObjects::Base
- YARD::CodeObjects::ClassObject
- YARD::CodeObjects::ClassVariableObject
- YARD::CodeObjects::CodeObjectList
- YARD::CodeObjects::ConstantObject
- YARD::CodeObjects::ExtendedMethodObject
- YARD::CodeObjects::ExtraFileObject
- YARD::CodeObjects::MacroObject
- YARD::CodeObjects::MethodObject
- YARD::CodeObjects::ModuleObject
- YARD::CodeObjects::NamespaceObject
- YARD::CodeObjects::Proxy
- YARD::CodeObjects::ProxyMethodError
- YARD::CodeObjects::RootObject
- YARD::Config
- YARD::Docstring
- YARD::DocstringParser
- YARD::Handlers
- YARD::Handlers::Base
- YARD::Handlers::C
- YARD::Handlers::C::AliasHandler
- YARD::Handlers::C::AttributeHandler
- YARD::Handlers::C::Base
- YARD::Handlers::C::ClassHandler
- YARD::Handlers::C::ConstantHandler
- YARD::Handlers::C::HandlerMethods
- YARD::Handlers::C::InitHandler
- YARD::Handlers::C::MethodHandler
- YARD::Handlers::C::MixinHandler
- YARD::Handlers::C::ModuleHandler
- YARD::Handlers::C::OverrideCommentHandler
- YARD::Handlers::C::PathHandler
- YARD::Handlers::C::StructHandler
- YARD::Handlers::C::SymbolHandler
- YARD::Handlers::HandlerAborted
- YARD::Handlers::NamespaceMissingError
- YARD::Handlers::Processor
- YARD::Handlers::Ruby
- YARD::Handlers::Ruby::AliasHandler
- YARD::Handlers::Ruby::AttributeHandler
- YARD::Handlers::Ruby::Base
- YARD::Handlers::Ruby::ClassConditionHandler
- YARD::Handlers::Ruby::ClassHandler
- YARD::Handlers::Ruby::ClassVariableHandler
- YARD::Handlers::Ruby::CommentHandler
- YARD::Handlers::Ruby::ConstantHandler
- YARD::Handlers::Ruby::DSLHandler
- YARD::Handlers::Ruby::DSLHandlerMethods
- YARD::Handlers::Ruby::ExceptionHandler
- YARD::Handlers::Ruby::ExtendHandler
- YARD::Handlers::Ruby::HandlesExtension
- YARD::Handlers::Ruby::Legacy
- YARD::Handlers::Ruby::Legacy::AliasHandler
- YARD::Handlers::Ruby::Legacy::AttributeHandler
- YARD::Handlers::Ruby::Legacy::Base
- YARD::Handlers::Ruby::Legacy::ClassConditionHandler
- YARD::Handlers::Ruby::Legacy::ClassHandler
- YARD::Handlers::Ruby::Legacy::ClassVariableHandler
- YARD::Handlers::Ruby::Legacy::CommentHandler
- YARD::Handlers::Ruby::Legacy::ConstantHandler
- YARD::Handlers::Ruby::Legacy::DSLHandler
- YARD::Handlers::Ruby::Legacy::ExceptionHandler
- YARD::Handlers::Ruby::Legacy::ExtendHandler
- YARD::Handlers::Ruby::Legacy::MethodHandler
- YARD::Handlers::Ruby::Legacy::MixinHandler
- YARD::Handlers::Ruby::Legacy::ModuleFunctionHandler
- YARD::Handlers::Ruby::Legacy::ModuleHandler
- YARD::Handlers::Ruby::Legacy::PrivateConstantHandler
- YARD::Handlers::Ruby::Legacy::VisibilityHandler
- YARD::Handlers::Ruby::Legacy::YieldHandler
- YARD::Handlers::Ruby::MethodCallWrapper
- YARD::Handlers::Ruby::MethodConditionHandler
- YARD::Handlers::Ruby::MethodHandler
- YARD::Handlers::Ruby::MixinHandler
- YARD::Handlers::Ruby::ModuleFunctionHandler
- YARD::Handlers::Ruby::ModuleHandler
- YARD::Handlers::Ruby::PrivateConstantHandler
- YARD::Handlers::Ruby::StructHandlerMethods
- YARD::Handlers::Ruby::TestNodeWrapper
- YARD::Handlers::Ruby::VisibilityHandler
- YARD::Handlers::Ruby::YieldHandler
- YARD::I18n
- YARD::I18n::Locale
- YARD::I18n::Message
- YARD::I18n::Messages
- YARD::I18n::PotGenerator
- YARD::I18n::Text
- YARD::Logger
- YARD::Options
- YARD::Parser
- YARD::Parser::Base
- YARD::Parser::C
- YARD::Parser::C::BodyStatement
- YARD::Parser::C::CParser
- YARD::Parser::C::Comment
- YARD::Parser::C::CommentParser
- YARD::Parser::C::Statement
- YARD::Parser::C::ToplevelStatement
- YARD::Parser::OrderedParser
- YARD::Parser::ParserSyntaxError
- YARD::Parser::Ruby
- YARD::Parser::Ruby::AstNode
- YARD::Parser::Ruby::ClassNode
- YARD::Parser::Ruby::CommentNode
- YARD::Parser::Ruby::ConditionalNode
- YARD::Parser::Ruby::KeywordNode
- YARD::Parser::Ruby::Legacy
- YARD::Parser::Ruby::Legacy::RubyLex
- YARD::Parser::Ruby::Legacy::RubyLex::BufferedReader
- YARD::Parser::Ruby::Legacy::RubyParser
- YARD::Parser::Ruby::Legacy::RubyToken
- YARD::Parser::Ruby::Legacy::RubyToken::TkBlockContents
- YARD::Parser::Ruby::Legacy::RubyToken::TkError
- YARD::Parser::Ruby::Legacy::RubyToken::TkId
- YARD::Parser::Ruby::Legacy::RubyToken::TkKW
- YARD::Parser::Ruby::Legacy::RubyToken::TkNode
- YARD::Parser::Ruby::Legacy::RubyToken::TkOPASGN
- YARD::Parser::Ruby::Legacy::RubyToken::TkOp
- YARD::Parser::Ruby::Legacy::RubyToken::TkStatementEnd
- YARD::Parser::Ruby::Legacy::RubyToken::TkUnknownChar
- YARD::Parser::Ruby::Legacy::RubyToken::TkVal
- YARD::Parser::Ruby::Legacy::RubyToken::TkWhitespace
- YARD::Parser::Ruby::Legacy::RubyToken::Token
- YARD::Parser::Ruby::Legacy::Statement
- YARD::Parser::Ruby::Legacy::StatementList
- YARD::Parser::Ruby::Legacy::TokenList
- YARD::Parser::Ruby::LiteralNode
- YARD::Parser::Ruby::LoopNode
- YARD::Parser::Ruby::MethodCallNode
- YARD::Parser::Ruby::MethodDefinitionNode
- YARD::Parser::Ruby::ModuleNode
- YARD::Parser::Ruby::ParameterNode
- YARD::Parser::Ruby::ReferenceNode
- YARD::Parser::Ruby::RipperParser
- YARD::Parser::Ruby::RubyParser
- YARD::Parser::SourceParser
- YARD::Parser::UndocumentableError
- YARD::Rake
- YARD::Rake::YardocTask
- YARD::Registry
- YARD::RegistryStore
- YARD::Serializers
- YARD::Serializers::Base
- YARD::Serializers::FileSystemSerializer
- YARD::Serializers::ProcessSerializer
- YARD::Serializers::StdoutSerializer
- YARD::Serializers::YardocSerializer
- YARD::Server
- YARD::Server::Adapter
- YARD::Server::Commands
- YARD::Server::Commands::Base
- YARD::Server::Commands::DisplayFileCommand
- YARD::Server::Commands::DisplayObjectCommand
- YARD::Server::Commands::FramesCommand
- YARD::Server::Commands::LibraryCommand
- YARD::Server::Commands::LibraryIndexCommand
- YARD::Server::Commands::LibraryOptions
- YARD::Server::Commands::ListCommand
- YARD::Server::Commands::SearchCommand
- YARD::Server::Commands::StaticFileCommand
- YARD::Server::DocServerHelper
- YARD::Server::DocServerSerializer
- YARD::Server::FinishRequest
- YARD::Server::LibraryNotPreparedError
- YARD::Server::LibraryVersion
- YARD::Server::NotFoundError
- YARD::Server::RackAdapter
- YARD::Server::RackMiddleware
- YARD::Server::Router
- YARD::Server::StaticCaching
- YARD::Server::WebrickAdapter
- YARD::Server::WebrickServlet
- YARD::StubProxy
- YARD::Tags
- YARD::Tags::AttributeDirective
- YARD::Tags::DefaultFactory
- YARD::Tags::DefaultTag
- YARD::Tags::Directive
- YARD::Tags::EndGroupDirective
- YARD::Tags::GroupDirective
- YARD::Tags::Library
- YARD::Tags::MacroDirective
- YARD::Tags::MethodDirective
- YARD::Tags::OptionTag
- YARD::Tags::OverloadTag
- YARD::Tags::ParseDirective
- YARD::Tags::RefTag
- YARD::Tags::RefTagList
- YARD::Tags::ScopeDirective
- YARD::Tags::Tag
- YARD::Tags::TagFormatError
- YARD::Tags::VisibilityDirective
- YARD::Templates
- YARD::Templates::Engine
- YARD::Templates::ErbCache
- YARD::Templates::Helpers
- YARD::Templates::Helpers::BaseHelper
- YARD::Templates::Helpers::FilterHelper
- YARD::Templates::Helpers::HtmlHelper
- YARD::Templates::Helpers::HtmlSyntaxHighlightHelper
- YARD::Templates::Helpers::Markup
- YARD::Templates::Helpers::Markup::RDocMarkdown
- YARD::Templates::Helpers::Markup::RDocMarkup
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkup
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkup::RDocMarkupToHtml
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkupToHtml
- YARD::Templates::Helpers::MarkupHelper
- YARD::Templates::Helpers::MethodHelper
- YARD::Templates::Helpers::ModuleHelper
- YARD::Templates::Helpers::TextHelper
- YARD::Templates::Helpers::UMLHelper
- YARD::Templates::Section
- YARD::Templates::Template
- YARD::Templates::Template::ClassMethods
- YARD::Templates::TemplateOptions
- YARD::Verifier
- Gem
- Gem::DocManager
- Gem::SourceIndex
- Gem::Specification
- Rack
- Rack::Request
- WEBrick
- WEBrick::HTTPRequest
- Array
- File
- Hash
- Insertion
- Module
- Object
- String
- SymbolHash

No matching classes.

# YARD::Options

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.

@abstract Subclasses should define (and document) custom attributes that are expected

    to be made available as option keys.

@example 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

@example Initializing default option values

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

@example Using `default_attr` to create default attributes

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

@example 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

### Public Class Methods

default_attr(key, default) click to toggle source

@!macro [attach] yard.default_attr

    @!attribute $1

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

@example Defining a default option key

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

@param [Symbol] key the option key name @param [Object, Proc] default the default object value. If the default

    value is a proc, it is executed upon initialization.

    # File lib/yard/options.rb, line 79
    def self.default_attr(key, default)
      (@defaults ||= {})[key] = default
      attr_accessor(key)
    end

### Public Instance Methods

==(other) click to toggle source

@return [Boolean] whether another Options object equals the

    keys and values of this options object

    # 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) click to toggle source

Delegates calls with Hash syntax to actual method with key name

@example Calling on an option key with Hash syntax

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

@param [Symbol, String] key the option name to access @return the value of the option named `key`

    # File lib/yard/options.rb, line 90
    def [](key) send(key) end

[]=(key, value) click to toggle source

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

@example Setting an option with Hash syntax

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

@param [Symbol, String] key the optin to set @param [Object] value the value to set for the option @return [Object] the value being set

    # File lib/yard/options.rb, line 99
    def []=(key, value) send("#{key}=", value) end

delete(key) click to toggle source

Deletes an option value for `key`

@param [Symbol, String] key the key to delete a value for @return [Object] the value that was deleted

    # 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(&block) click to toggle source

Yields over every option key and value @yield [key, value] every option key and value @yieldparam [Symbol] key the option key @yieldparam [Object] value the option value @return [void]

    # 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() click to toggle source

Inspects the object

    # File lib/yard/options.rb, line 150
    def inspect
      "<#{self.class}: #{to_hash.inspect}>"
    end

merge(opts) click to toggle source

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

@param [Options, Hash] opts @return [Options] the newly created options object @see update

    # File lib/yard/options.rb, line 122
    def merge(opts)
      dup.update(opts)
    end

method_missing(meth, *args, &block) click to toggle source

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

@note It is not recommended to set and access unregistered keys on

    an Options object. Instead, register the attribute before using it.

    # 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

reset_defaults() click to toggle source

Resets all values to their defaults.

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

@return [void]

    # 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")
        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(&block) click to toggle source

    # File lib/yard/options.rb, line 213
    def tap(&block) yield(self); self end

to_hash() click to toggle source

@return [Hash] Converts options object to an options hash. All keys

    will be symbolized.

    # 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) click to toggle source

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.

@example Updating a set of options on an Options object

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

@param [Hash, Options] opts @return [self]

    # 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

[Validate]

Generated with the Darkfish Rdoc Generator 2.