yard 0.9.18 → 0.9.19

data/lib/yard/options.rb

@@ -1,217 +1,217 @@
-# frozen_string_literal: true
-module YARD
-  # 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 (<tt>opts[:key]</tt>), 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
-  class Options
-    # @!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.
-    def self.default_attr(key, default)
-      (@defaults ||= {})[key] = default
-      attr_accessor(key)
-    end
-
-    # 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+
-    def [](key) send(key) end
-
-    # 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
-    def []=(key, value) send("#{key}=", value) end
-
-    # 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]
-    def update(opts)
-      opts = opts.to_hash if Options === opts
-      opts.each do |key, value|
-        self[key] = value
-      end
-      self
-    end
-
-    # 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
-    def merge(opts)
-      dup.update(opts)
-    end
-
-    # @return [Hash] Converts options object to an options hash. All keys
-    #   will be symbolized.
-    def to_hash
-      opts = {}
-      instance_variables.each do |ivar|
-        name = ivar.to_s.sub(/^@/, '')
-        opts[name.to_sym] = send(name)
-      end
-      opts
-    end
-
-    # 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]
-    def each
-      instance_variables.each do |ivar|
-        name = ivar.to_s.sub(/^@/, '')
-        yield(name.to_sym, send(name))
-      end
-    end
-
-    # Inspects the object
-    def inspect
-      "<#{self.class}: #{to_hash.inspect}>"
-    end
-
-    # @return [Boolean] whether another Options object equals the
-    #   keys and values of this options object
-    def ==(other)
-      case other
-      when Options; to_hash == other.to_hash
-      when Hash; to_hash == other
-      else false
-      end
-    end
-
-    # 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.
-    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
-
-    # 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]
-    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
-
-    # Deletes an option value for +key+
-    #
-    # @param [Symbol, String] key the key to delete a value for
-    # @return [Object] the value that was deleted
-    def delete(key)
-      val = self[key]
-      if instance_variable_defined?("@#{key}")
-        remove_instance_variable("@#{key}")
-      end
-      val
-    end
-
-    def tap; yield(self); self end unless defined?(tap) # only for 1.8.6
-  end
-end
+# frozen_string_literal: true
+module YARD
+  # 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 (<tt>opts[:key]</tt>), 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
+  class Options
+    # @!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.
+    def self.default_attr(key, default)
+      (@defaults ||= {})[key] = default
+      attr_accessor(key)
+    end
+
+    # 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+
+    def [](key) send(key) end
+
+    # 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
+    def []=(key, value) send("#{key}=", value) end
+
+    # 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]
+    def update(opts)
+      opts = opts.to_hash if Options === opts
+      opts.each do |key, value|
+        self[key] = value
+      end
+      self
+    end
+
+    # 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
+    def merge(opts)
+      dup.update(opts)
+    end
+
+    # @return [Hash] Converts options object to an options hash. All keys
+    #   will be symbolized.
+    def to_hash
+      opts = {}
+      instance_variables.each do |ivar|
+        name = ivar.to_s.sub(/^@/, '')
+        opts[name.to_sym] = send(name)
+      end
+      opts
+    end
+
+    # 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]
+    def each
+      instance_variables.each do |ivar|
+        name = ivar.to_s.sub(/^@/, '')
+        yield(name.to_sym, send(name))
+      end
+    end
+
+    # Inspects the object
+    def inspect
+      "<#{self.class}: #{to_hash.inspect}>"
+    end
+
+    # @return [Boolean] whether another Options object equals the
+    #   keys and values of this options object
+    def ==(other)
+      case other
+      when Options; to_hash == other.to_hash
+      when Hash; to_hash == other
+      else false
+      end
+    end
+
+    # 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.
+    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
+
+    # 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]
+    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
+
+    # Deletes an option value for +key+
+    #
+    # @param [Symbol, String] key the key to delete a value for
+    # @return [Object] the value that was deleted
+    def delete(key)
+      val = self[key]
+      if instance_variable_defined?("@#{key}")
+        remove_instance_variable("@#{key}")
+      end
+      val
+    end
+
+    def tap; yield(self); self end unless defined?(tap) # only for 1.8.6
+  end
+end

data/lib/yard/parser/base.rb

@@ -1,57 +1,57 @@
-# frozen_string_literal: true
-module YARD
-  module Parser
-    # Represents the abstract base parser class that parses source code in
-    # a specific way. A parser should implement {#parse}, {#tokenize} and
-    # {#enumerator}.
-    #
-    # == Registering a Custom Parser
-    # To register a parser, see {SourceParser.register_parser_type}
-    #
-    # @abstract
-    # @see #parse
-    # @see #tokenize
-    # @see #enumerator
-    # @since 0.5.6
-    class Base
-      # Convenience method to create a new parser and {#parse}
-      def self.parse(source, filename = nil)
-        new(source, filename).parse
-      end
-
-      # This default constructor does nothing. The subclass is responsible for
-      # storing the source contents and filename if they are required.
-      # @param [String] source the source contents
-      # @param [String] filename the name of the file if from disk
-      def initialize(source, filename) # rubocop:disable Lint/UnusedMethodArgument
-        raise NotImplementedError, "invalid parser implementation"
-      end
-
-      # This method should be implemented to parse the source and return itself.
-      # @abstract
-      # @return [Base] this method should return itself
-      def parse
-        raise NotImplementedError, "#{self.class} must implement #parse"
-      end
-
-      # This method should be implemented to tokenize given source
-      # @abstract
-      # @return [Array] a list/tree of lexical tokens
-      def tokenize
-        raise NotImplementedError, "#{self.class} does not support tokenization"
-      end
-
-      # This method should be implemented to return a list of semantic tokens
-      # representing the source code to be post-processed. Otherwise the method
-      # should return nil.
-      #
-      # @abstract
-      # @return [Array] a list of semantic tokens representing the source code
-      #   to be post-processed
-      # @return [nil] if no post-processing should be done
-      def enumerator
-        nil
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+module YARD
+  module Parser
+    # Represents the abstract base parser class that parses source code in
+    # a specific way. A parser should implement {#parse}, {#tokenize} and
+    # {#enumerator}.
+    #
+    # == Registering a Custom Parser
+    # To register a parser, see {SourceParser.register_parser_type}
+    #
+    # @abstract
+    # @see #parse
+    # @see #tokenize
+    # @see #enumerator
+    # @since 0.5.6
+    class Base
+      # Convenience method to create a new parser and {#parse}
+      def self.parse(source, filename = nil)
+        new(source, filename).parse
+      end
+
+      # This default constructor does nothing. The subclass is responsible for
+      # storing the source contents and filename if they are required.
+      # @param [String] source the source contents
+      # @param [String] filename the name of the file if from disk
+      def initialize(source, filename) # rubocop:disable Lint/UnusedMethodArgument
+        raise NotImplementedError, "invalid parser implementation"
+      end
+
+      # This method should be implemented to parse the source and return itself.
+      # @abstract
+      # @return [Base] this method should return itself
+      def parse
+        raise NotImplementedError, "#{self.class} must implement #parse"
+      end
+
+      # This method should be implemented to tokenize given source
+      # @abstract
+      # @return [Array] a list/tree of lexical tokens
+      def tokenize
+        raise NotImplementedError, "#{self.class} does not support tokenization"
+      end
+
+      # This method should be implemented to return a list of semantic tokens
+      # representing the source code to be post-processed. Otherwise the method
+      # should return nil.
+      #
+      # @abstract
+      # @return [Array] a list of semantic tokens representing the source code
+      #   to be post-processed
+      # @return [nil] if no post-processing should be done
+      def enumerator
+        nil
+      end
+    end
+  end
+end