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
136 def self.simple_array_validator(val, name, size = nil)
137   if String === val
138     val = val.split(/,/)
139   elsif !(Array === val)
140     raise Kramdown::Error, "Invalid type #{val.class} for option #{name}"
141   end
142   if size && val.size != size
143     raise Kramdown::Error, "Option #{name} needs exactly #{size} values"
144   end
145   val
146 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
153 def self.simple_hash_validator(val, name)
154   if String === val
155     begin
156       val = YAML.safe_load(val)
157     rescue RuntimeError, ArgumentError, SyntaxError
158       raise Kramdown::Error, "Invalid YAML value for option #{name}"
159     end
160   end
161   raise Kramdown::Error, "Invalid type #{val.class} for option #{name}" unless Hash === val
162   val
163 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
69 def self.defaults
70   temp = {}
71   @options.each {|_n, o| temp[o.name] = o.default }
72   temp
73 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
49 def self.define(name, type, default, desc, &block)
50   name = name.to_sym
51   raise ArgumentError, "Option name #{name} is already used" if @options.key?(name)
52   raise ArgumentError, "Invalid option type #{type} specified" unless ALLOWED_TYPES.include?(type)
53   raise ArgumentError, "Invalid type for default value" if !(type === default) && !default.nil?
54   raise ArgumentError, "Missing validator block" if type == Object && block.nil?
55   @options[name] = Definition.new(name, type, default, desc, block)
56 end
defined?(name) click to toggle source

Return true if an option called name is defined.

   # File lib/kramdown/options.rb
64 def self.defined?(name)
65   @options.key?(name.to_sym)
66 end
definitions() click to toggle source

Return all option definitions.

   # File lib/kramdown/options.rb
59 def self.definitions
60   @options
61 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
77 def self.merge(hash)
78   temp = defaults
79   hash.each do |k, v|
80     k = k.to_sym
81     temp[k] = @options.key?(k) ? parse(k, v) : v
82   end
83   temp
84 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
 91 def self.parse(name, data)
 92   name = name.to_sym
 93   raise ArgumentError, "No option named #{name} defined" unless @options.key?(name)
 94   unless @options[name].type === data
 95     data = data.to_s
 96     data = if @options[name].type == String
 97              data
 98            elsif @options[name].type == Integer
 99              Integer(data) rescue raise Kramdown::Error, "Invalid integer value for option '#{name}': '#{data}'"
100            elsif @options[name].type == Float
101              Float(data) rescue raise Kramdown::Error, "Invalid float value for option '#{name}': '#{data}'"
102            elsif @options[name].type == Symbol
103              str_to_sym(data)
104            elsif @options[name].type == Boolean
105              data.downcase.strip != 'false' && !data.empty?
106            end
107   end
108   data = @options[name].validator[data] if @options[name].validator
109   data
110 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
117 def self.str_to_sym(data)
118   data = data.strip
119   data = data[1..-1] if data[0] == ':'
120   (data.empty? || data == 'nil' ? nil : data.to_sym)
121 end