Module: TocDoc::Configurable

Included in:
TocDoc, Client
Defined in:
lib/toc_doc/core/configurable.rb

Overview

Mixin providing shared configuration behaviour for both the top-level TocDoc module and individual Client instances.

Include this module to gain attribute accessors for every configurable key, a block-based #configure helper, and a #reset! method to restore defaults from Default.

Examples:

Module-level configuration

TocDoc.configure do |config|
  config.api_endpoint = 'https://www.doctolib.de'
  config.per_page     = 10
end

Per-client configuration

client = TocDoc::Client.new(api_endpoint: 'https://www.doctolib.it')

See Also:

Constant Summary collapse

VALID_CONFIG_KEYS =

Returns all recognised configuration keys.

Returns:

  • (Array<Symbol>) —

    all recognised configuration keys

%i[
  api_endpoint
  user_agent
  middleware
  connection_options
  default_media_type
  per_page
  connect_timeout
  read_timeout
  logger
  pagination_depth
  rate_limit
  cache
].freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.keys ⇒ Array<Symbol>

Returns the list of recognised configurable attribute names.

Returns:

  • (Array<Symbol>) 


100
101
102
 
# File 'lib/toc_doc/core/configurable.rb', line 100

def self.keys
  VALID_CONFIG_KEYS
end

Instance Method Details

#configure {|config| ... } ⇒ self

Yields +self+ so callers can set options in a block.

Examples:

TocDoc.configure do |config|
  config.api_endpoint = 'https://www.doctolib.de'
end

Yields:

  • (config) —

    the object being configured

Yield Parameters:

Returns:

  • (self) 


114
115
116
117
 
# File 'lib/toc_doc/core/configurable.rb', line 114

def configure
  yield self
  self
end

#options ⇒ Hash{Symbol => Object}

Returns a frozen snapshot of the current configuration as a Hash.

Returns:

  • (Hash{Symbol => Object}) 


137
138
139
 
# File 'lib/toc_doc/core/configurable.rb', line 137

def options
  Configurable.keys.to_h { |key| [key, public_send(key)] }
end

#pagination_depth=(value) ⇒ Integer

Set the number of +next_slot+ hops to follow automatically, clamped to 0 when a negative value is given.

Emits a warning on +$stderr+ when +value+ is negative so callers are not silently surprised.

Parameters:

  • value (Integer, #to_i) —

    desired pagination depth

Returns:

  • (Integer) —

    the effective depth after clamping



88
89
90
91
92
93
94
95
 
# File 'lib/toc_doc/core/configurable.rb', line 88

def pagination_depth=(value)
  int = value.to_i
  if int.negative?
    warn "[TocDoc] pagination_depth #{int} is negative; clamped to 0."
    int = 0
  end
  @pagination_depth = int
end

#per_page=(value) ⇒ Integer

Set the number of results per page, clamped to Default::MAX_PER_PAGE.

Emits a warning on +$stderr+ when +value+ exceeds the hard cap so callers are not silently surprised by the lower effective value.

Parameters:

  • value (Integer, #to_i) —

    desired page size

Returns:

  • (Integer) —

    the effective page size after clamping



72
73
74
75
76
77
78
 
# File 'lib/toc_doc/core/configurable.rb', line 72

def per_page=(value)
  int = value.to_i
  if int > TocDoc::Default::MAX_PER_PAGE
    warn "[TocDoc] per_page #{int} exceeds MAX_PER_PAGE (#{TocDoc::Default::MAX_PER_PAGE}); clamped."
  end
  @per_page = [int, TocDoc::Default::MAX_PER_PAGE].min
end

#reset! ⇒ self

Reset all configuration options to their Default values.

Calls Default.reset! first so that memoized values such as Default.middleware are cleared and rebuilt fresh on the next access, preventing stale middleware stacks from being reused.

Returns:

  • (self) 


126
127
128
129
130
131
132
 
# File 'lib/toc_doc/core/configurable.rb', line 126

def reset!
  TocDoc::Default.reset!
  TocDoc::Default.options.each do |key, value|
    public_send("#{key}=", value)
  end
  self
end

#same_options?(other_options) ⇒ Boolean

Compares the given options to the current configuration.

Used internally for memoising the TocDoc.client instance — a new client is created only when the options have actually changed.

Parameters:

  • other_options (Hash{Symbol => Object}) —

    options to compare

Returns:

  • (Boolean) —

    +true+ when both option sets are equal



148
149
150
151
152
153
154
155
156
157
 
# File 'lib/toc_doc/core/configurable.rb', line 148

def same_options?(other_options)
  candidate =
    if other_options.respond_to?(:to_hash)
      other_options.to_hash.transform_keys!(&:to_sym)
    else
      other_options
    end

  candidate == options
end