# module Kramdown::Options

This module defines all options that are used by parsers and/or converters as well as providing methods to deal with the options.

## Option Definitions

↑ top

### Constants

SMART_QUOTES_ENTITIES
SMART_QUOTES_STR
TOC_LEVELS_ARRAY
TOC_LEVELS_RANGE

## Option Validators

↑ top

### Public Class Methods

simple_array_validator(val, name, size = nil) click to toggle source

Ensures that the option value `val` for the option called `name` is a valid array. The parameter `val` can be

- a comma separated string which is split into an array of values

- or an array.

Optionally, the array is checked for the correct size.

        # File lib/kramdown/options.rb
    140 def self.simple_array_validator(val, name, size = nil)
    141   if String === val
    142     val = val.split(/,/)
    143   elsif !(Array === val)
    144     raise Kramdown::Error, "Invalid type #{val.class} for option #{name}"
    145   end
    146   if size && val.size != size
    147     raise Kramdown::Error, "Option #{name} needs exactly #{size} values"
    148   end
    149   val
    150 end

simple_hash_validator(val, name) click to toggle source

Ensures that the option value `val` for the option called `name` is a valid hash. The parameter `val` can be

- a hash in YAML format

- or a Ruby Hash object.

        # File lib/kramdown/options.rb
    157 def self.simple_hash_validator(val, name)
    158   if String === val
    159     begin
    160       val = YAML.safe_load(val)
    161     rescue RuntimeError, ArgumentError, SyntaxError
    162       raise Kramdown::Error, "Invalid YAML value for option #{name}"
    163     end
    164   end
    165   raise Kramdown::Error, "Invalid type #{val.class} for option #{name}" unless Hash === val
    166   val
    167 end

## Option definitions

↑ top

### Constants

ALLOWED_TYPES

  Allowed option types.

Definition

  Struct class for storing the definition of an option.

### Public Class Methods

defaults() click to toggle source

Return a Hash with the default values for all options.

       # File lib/kramdown/options.rb
    71 def self.defaults
    72   @cached_defaults ||= begin
    73                          temp = {}
    74                          @options.each {|_n, o| temp[o.name] = o.default }
    75                          temp.freeze
    76                        end
    77 end

define(name, type, default, desc, &block) click to toggle source

Define a new option called `name` (a Symbol) with the given `type` (String, Integer, Float, Symbol, `Boolean`, Object), default value `default` and the description `desc`. If a block is specified, it should validate the value and either raise an error or return a valid value.

The type 'Object' should only be used for complex types for which none of the other types suffices. A block needs to be specified when using type 'Object' and it has to cope with a value given as string and as the opaque type.

       # File lib/kramdown/options.rb
    50 def self.define(name, type, default, desc, &block)
    51   name = name.to_sym
    52   raise ArgumentError, "Option name #{name} is already used" if @options.key?(name)
    53   raise ArgumentError, "Invalid option type #{type} specified" unless ALLOWED_TYPES.include?(type)
    54   raise ArgumentError, "Invalid type for default value" if !(type === default) && !default.nil?
    55   raise ArgumentError, "Missing validator block" if type == Object && block.nil?
    56   @options[name] = Definition.new(name, type, default, desc, block)
    57   @cached_defaults = nil
    58 end

defined?(name) click to toggle source

Return `true` if an option called `name` is defined.

       # File lib/kramdown/options.rb
    66 def self.defined?(name)
    67   @options.key?(name.to_sym)
    68 end

definitions() click to toggle source

Return all option definitions.

       # File lib/kramdown/options.rb
    61 def self.definitions
    62   @options
    63 end

merge(hash) click to toggle source

Merge the defaults Hash with the parsed options from the given Hash, i.e. only valid option names are considered and their value is run through the parse method.

       # File lib/kramdown/options.rb
    81 def self.merge(hash)
    82   temp = defaults.dup
    83   hash.each do |k, v|
    84     k = k.to_sym
    85     temp[k] = @options.key?(k) ? parse(k, v) : v
    86   end
    87   temp
    88 end

parse(name, data) click to toggle source

Parse the given value `data` as if it was a value for the option `name` and return the parsed value with the correct type.

If `data` already has the correct type, it is just returned. Otherwise it is converted to a String and then to the correct type.

        # File lib/kramdown/options.rb
     95 def self.parse(name, data)
     96   name = name.to_sym
     97   raise ArgumentError, "No option named #{name} defined" unless @options.key?(name)
     98   unless @options[name].type === data
     99     data = data.to_s
    100     data = if @options[name].type == String
    101              data
    102            elsif @options[name].type == Integer
    103              Integer(data) rescue raise Kramdown::Error, "Invalid integer value for option '#{name}': '#{data}'"
    104            elsif @options[name].type == Float
    105              Float(data) rescue raise Kramdown::Error, "Invalid float value for option '#{name}': '#{data}'"
    106            elsif @options[name].type == Symbol
    107              str_to_sym(data)
    108            elsif @options[name].type == Boolean
    109              data.downcase.strip != 'false' && !data.empty?
    110            end
    111   end
    112   data = @options[name].validator[data] if @options[name].validator
    113   data
    114 end

str_to_sym(data) click to toggle source

Converts the given String `data` into a Symbol or `nil` with the following provisions:

- A leading colon is stripped from the string.

- An empty value or a value equal to “nil” results in `nil`.

        # File lib/kramdown/options.rb
    121 def self.str_to_sym(data)
    122   data = data.strip
    123   data = data[1..-1] if data[0] == ':'
    124   (data.empty? || data == 'nil' ? nil : data.to_sym)
    125 end