qonfig

Qonfig ·

Powerful configuration Ruby-framework with a support for many commonly used config formats with a multi-functional API, developer-friendly DSL and object-oriented behavior.

• Support for: YAML, TOML, JSON, ENV, __END__-instructions;
• Fully thread-safe;
• Object-oriented behavior (config as an object, inhertance, composition, etc), with an abilities of lazy-instantiation;
• Pluggable and extendable multi-functional API;
• Developer-friendly DSL :)

# in the past...:

Config. Defined as a class. Used as an instance. Support for inheritance and composition.
Lazy instantiation. Thread-safe. Command-style DSL. Validation layer. **Dot-notation**)
And pretty-print :) Support for **YAML**, **TOML**, **JSON**, **\_\_END\_\_**, **ENV**.
Extremely simple to define. Extremely simple to use. That's all? **Not** :)

Installation

gem 'qonfig'

$ bundle install
# --- or ---
$ gem install 'qonfig'

require 'qonfig'

Usage

• Definition
  • Definition and Settings Access
    • access via method
    • access via index-method []
    • .dig
    • .slice
    • .slice_value
    • .subset
  • Configuration
    • configure via proc
    • configure via settings object (by option name)
    • configure via settings object (by setting key)
    • instant configuration via proc
    • using a hash
    • using both hash and proc
  • Inheritance
  • Composition
  • Hash representation
    • Default behaviour (without options)
    • With transformations
    • Dot-style format
  • Smart Mixin (Qonfig::Configurable)
  • Instantiation without class definition (Qonfig::DataSet.build(&definitions))
• Compacted config
  • Definition and instantiation
    • by raw initialization
    • by existing Qonfig::DataSet class
    • by existing Qonfig::DataSet instance
    • instantiation without class definition
    • validation API
  • Setting readers and writers
    • reading
    • writing
    • precitaes
• Interaction
  • Iteration over setting keys (#each_setting, #deep_each_setting)
  • List of config keys (#keys, #root_keys)
  • Config reloading (reload config definitions and option values)
  • Clear options (set to nil)
  • Frozen state (.freeze_state!, #freeze!, #frozen?)
  • Settings as Predicates
  • Setting key existence (#key?/#option?/#setting?)
  • Run arbitrary code with temporary settings (#with(configs = {}, &arbitrary_code))
• Import settings / Export settings
  • Import config settings (as instance methods)
    • Import a set of setting keys (simple dot-noated key list)
    • Import with custom method names (mappings)
    • Prexify method name
    • Import nested settings as raw Qonfig::Settings objects
    • Import with pattern-matching
    • Support for predicate-like methods
  • Export config settings (as singleton methods)
• Validation
  • Introduction
  • Key search pattern
  • Proc-based validation
  • Method-based validation
  • Predefined validations
  • Custom predefined validators
  • Validation of potential setting values
• Work with files
  • Setting keys definition
    • (DSL methods for dynamic setting keys definition by reading them from a file)
    • Load from YAML file
    • Expose YAML (Rails-like environment-based YAML configs)
    • Load from JSON file
    • Expose JSON (Rails-like environment-based JSON configs)
    • Load from ENV
    • Load from __END__ (aka .load_from_self)
    • Expose __END__ (aka .expose_self)
  • Setting values
    • (instance methods for loading the setting values from a file to existing config object with already defined setting keys)
    • Default setting values file
    • Load setting values from YAML file
    • Load setting values from JSON file
    • Load setting values from __END__
    • Load setting values from file manually
  • Daily work
    • Save to JSON file (#save_to_json)
    • Save to YAML file (#save_to_yaml)
• Plugins
  • toml (support for TOML format)
  • pretty_print (beautified/prettified console output)
  • vault (support for Vault store)
• Roadmap
• Build

Definition

• Definition and Settings Access
• Configuration
• Inheritance
• Composition
• Hash representation
• Smart Mixin (Qonfig::Configurable)

Definition and Access

• setting(name, value = nil) - define setting with corresponding name and value;
• setting(name) { setting(name, value = nil); ... } - define nested settings OR reopen existing nested setting and define some new nested settings;
• re_setting(name, value = nil), re_setting(name) { ... } - re-define existing setting (or define new if the original does not exist);
• accessing: access via method, access via index-method [], .dig, .slice, .slice_value, .subset;

# --- definition ---
class Config < Qonfig::DataSet
  # nil by default
  setting :project_id

  # nested setting
  setting :vendor_api do
    setting :host, 'vendor.service.com'
  end

  setting :enable_graphql, false

  # nested setting reopening
  setting :vendor_api do
    setting :user, 'simple_user'
  end

  # re-definition of existing setting (drop the old - make the new)
  re_setting :vendor_api do
    setting :domain, 'api.service.com'
    setting :login, 'test_user'
  end

  # deep nesting
  setting :credentials do
    setting :user do
      setting :login, 'D@iVeR'
      setting :password, 'test123'
    end
  end
end

config = Config.new # your configuration object instance

access via method

# get option value via method
config.settings.project_id # => nil
config.settings.vendor_api.domain # => 'app.service.com'
config.settings.vendor_api.login # => 'test_user'
config.settings.enable_graphql # => false

access via index-method []

• without dot-notation:

# get option value via index (with indifferent (string / symbol / mixed) access)
config.settings[:project_id] # => nil
config.settings[:vendor_api][:domain] # => 'app.service.com'
config.settings[:vendor_api][:login] # => 'test_user'
config.settings[:enable_graphql] # => false

# get option value via index (with indifferent (string / symbol / mixed) access)
config.settings['project_id'] # => nil
config.settings['vendor_api']['domain'] # => 'app.service.com'
config.settings['vendor_api']['login'] # => 'test_user'
config.settings['enable_graphql'] # => false

# dig to value
config.settings[:vendor_api, :domain] # => 'app.service.com'
config.settings[:vendor_api, 'login'] # => 'test_user'

# get option value directly via index (with indifferent access)
config['project_id'] # => nil
config['enable_graphql'] # => false
config[:project_id] # => nil
config[:enable_graphql] # => false

• with dot-notation:

config.settings['vendor_api.domain'] # => 'app.service.com'
config.settings['vendor_api.login'] # => 'test_user'

config['vendor_api.domain'] # => 'app.service.com'
config['vendor_api.login'] # => 'test_user'

.dig

• without dot-notation:

# get option value in Hash#dig manner (and fail when the required key does not exist);
config.dig(:vendor_api, :domain) # => 'app.service.com' # (key exists)
config.dig(:vendor_api, :login) # => Qonfig::UnknownSettingError # (key does not exist)

• with dot-notation:

config.dig('vendor_api.domain') # => 'app.service.com' # (key exists)
config.dig('vendor_api.login') # => Qonfig::UnknownSettingError # (key does not exist)

.slice

• without dot-notation:

# get a hash slice of setting options (and fail when the required key does not exist);
config.slice(:vendor_api) # => { 'vendor_api' => { 'domain' => 'app_service', 'login' => 'test_user' } }
config.slice(:vendor_api, :login) # => { 'login' => 'test_user' }
config.slice(:project_api) # => Qonfig::UnknownSettingError # (key does not exist)
config.slice(:vendor_api, :port) # => Qonfig::UnknownSettingError # (key does not exist)

• with dot-notation:

config.slice('vendor_api.login') # => { 'loign' => 'test_user' }
config.slice('vendor_api.port') # => Qonfig::UnknownSettingError # (key does not exist)

.slice_value

• without dot-notaiton:

# get value from the slice of setting options using the given key set
# (and fail when the required key does not exist) (works in slice manner);

config.slice_value(:vendor_api) # => { 'domain' => 'app_service', 'login' => 'test_user' }
config.slice_value(:vendor_api, :login) # => 'test_user'
config.slice_value(:project_api) # => Qonfig::UnknownSettingError # (key does not exist)
config.slice_value(:vendor_api, :port) # => Qonfig::UnknownSettingError # (key does not exist)

• with dot-notation:

config.slice_value('vendor_api.login') # => 'test_user'
config.slice_value('vendor_api.port') # => Qonfig::UnknownSettingError # (key does not exist)

.subset

• without dot-notation:

# - get a subset (a set of sets) of config settings represented as a hash;
# - each key (or key set) represents a requirement of a certain setting key;

config.subset(:vendor_api, :enable_graphql)
# => { 'vendor_api' => { 'login' => ..., 'domain' => ... }, 'enable_graphql' => false }

config.subset(:project_id, [:vendor_api, :domain], [:credentials, :user, :login])
# => { 'project_id' => nil, 'domain' => 'app.service.com', 'login' => 'D@iVeR' }

• with dot-notation:

config.subset('project_id', 'vendor_api.domain', 'credentials.user.login')
# => { 'project_id' => nil, 'domain' => 'app.service.com', 'login' => 'D@iVeR' }

Configuration

class Config < Qonfig::DataSet
  setting :testing do
    setting :engine, :rspec
    setting :parallel, true
  end

  setting :geo_api do
    setting :provider, :google_maps
  end

  setting :enable_middlewares, false
end

config = Config.new

configure via proc

config.configure do |conf|
  conf.enable_middlewares = true
  conf.geo_api.provider = :yandex_maps
  conf.testing.engine = :mini_test
end

configure via settings object (by option name)

config.settings.enable_middlewares = false
config.settings.geo_api.provider = :apple_maps
config.settings.testing.engine = :ultra_test

configure via settings object (by setting key)

config.settings[:enable_middlewares] = true
config.settings[:geo_api][:provider] = :rambler_maps
config.settings[:testing][:engine] = :mega_test

instant configuration via proc

config = Config.new do |conf|
  conf.enable_middlewares = false
  conf.geo_api.provider = :amazon_maps
  conf.testing.engine = :crypto_test
end

using a hash

config = Config.new(
  testing: { engine: :mini_test, parallel: false },
  geo_api: { provider: :rambler_maps },
  enable_middlewares: true
)
config.configure(enable_middlewares: false)

using both hash and proc (proc has higher priority)

config = Config.new(enable_middlewares: true) do |conf|
  conf.testing.parallel = true
end

config.configure(geo_api: { provider: nil }) do |conf|
  conf.testing.engine = :rspec
end

Inheritance

class CommonConfig < Qonfig::DataSet
  setting :uploader, :fog
end

class ProjectConfig < CommonConfig
  setting :auth_provider, :github
end

project_config = ProjectConfig.new

# inherited setting
project_config.settings.uploader # => :fog

# own setting
project_config.settings.auth_provider # => :github

Composition

class SharedConfig < Qonfig::DataSet
  setting :logger, Logger.new
end

class ServerConfig < Qonfig::DataSet
  setting :port, 12345
  setting :address, '0.0.0.0'
end

class DatabaseConfig < Qonfig::DataSet
  setting :user, 'test'
  setting :password, 'testpaswd'
end

class ProjectConfig < Qonfig::DataSet
  compose SharedConfig

  setting :server do
    compose ServerConfig
  end

  setting :db do
    compose DatabaseConfig
  end
end

project_config = ProjectConfig.new

# fields from SharedConfig
project_config.settings.logger # => #<Logger:0x66f57048>

# fields from ServerConfig
project_config.settings.server.port # => 12345
project_config.settings.server.address # => '0.0.0.0'

# fields from DatabaseConfig
project_config.settings.db.user # => 'test'
project_config.settings.db.password # => 'testpaswd'

Hash representation

• works via #to_h and #to_hash;
• supported options:
  • key_transformer: - an optional proc that accepts setting key and makes your custom transformations;
  • value_transformer: - an optional proc that accepts setting value and makes your custom transformations;
  • dot_style: - (false by default) represent setting keys in dot-notation (transformations are supported too);

class Config < Qonfig::DataSet
  setting :serializers do
    setting :json do
      setting :engine, :ok
    end

    setting :hash do
      setting :engine, :native
    end
  end

  setting :adapter do
    setting :default, :memory_sync
  end

  setting :logger, Logger.new(STDOUT)
end

Default behavior (without-options)

Config.new.to_h
# =>
{
  "serializers": {
    "json" => { "engine" => :ok },
    "hash" => { "engine" => :native },
  },
  "adapter" => { "default" => :memory_sync },
  "logger" => #<Logger:0x4b0d79fc>
}

With transformations

• with key_transformer and/or value_transformer;

key_transformer = -> (key) { "#{key}!!" }
value_transformer = -> (value) { "#{value}??" }

Config.new.to_h(key_transformer: key_transformer, value_transformer: value_transformer)
# =>
{
  "serializers!!": {
    "json!!" => { "engine!!" => "ok??" },
    "hash!!" => { "engine!!" => "native??" },
  },
  "adapter!!" => { "default!!" => "memory_sync??" },
  "logger!!" => "#<Logger:0x00007fcde799f158>??"
}

Dot-style format

• transformations are supported too (key_transformer and value_transformer);

Config.new.to_h(dot_style: true)
# =>
{
  "serializers.json.engine" => :ok,
  "serializers.hash.engine" => :native,
  "adapter.default" => :memory_sync,
  "logger" => #<Logger:0x4b0d79fc>,
}

transformer = -> (value) { "$$#{value}$$" }

Config.new.to_h(dot_style: true, key_transformer: transformer, value_transformer: transformer)

# => "#<Logger:0x00007fcde799f158>??"
{
  "$$serializers.json.engine$$" => "$$ok$$",
  "$$serializers.hash.engine$$" => "$$native$$",
  "$$adapter.default$$" => "$$memory_sync$$",
  "$$logger$$" => "$$#<Logger:0x00007fcde799f158>$$",
}

Smart Mixin

• class-level:
  • .configuration - settings definitions;
  • .configure - configuration;
  • .config - config object;
  • settings definitions are inheritable;
• instance-level:
  • #configure - configuration;
  • #config - config object;
  • #shared_config - class-level config object;

# --- usage ---

class Application
  # make configurable
  include Qonfig::Configurable

  configuration do
    setting :user
    setting :password
  end
end

app = Application.new

# class-level config
Application.config.settings.user # => nil
Application.config.settings.password # => nil

# instance-level config
app.config.settings.user # => nil
app.config.settings.password # => nil

# access to the class level config from an instance
app.shared_config.settings.user # => nil
app.shared_config.settings.password # => nil

# class-level configuration
Application.configure do |conf|
  conf.user = '0exp'
  conf.password = 'test123'
end

# instance-level configuration
app.configure do |conf|
  conf.user = 'admin'
  conf.password = '123test'
end

# class has own config object
Application.config.settings.user # => '0exp'
Application.config.settings.password # => 'test123'

# instance has own config object
app.config.settings.user # => 'admin'
app.config.settings.password # => '123test'

# access to the class level config from an instance
app.shared_config.settings.user # => '0exp'
app.shared_config.settings.password # => 'test123'

# and etc... (all Qonfig-related features)

# --- inheritance ---

class BasicApplication
  # make configurable
  include Qonfig::Configurable

  configuration do
    setting :user
    setting :pswd
  end

  configure do |conf|
    conf.user = 'admin'
    conf.pswd = 'admin'
  end
end

class GeneralApplication < BasicApplication
  # extend inherited definitions
  configuration do
    setting :db do
      setting :adapter
    end
  end

  configure do |conf|
    conf.user = '0exp' # .user inherited from BasicApplication
    conf.pswd = '123test' # .pswd inherited from BasicApplication
    conf.db.adapter = 'pg'
  end
end

BasicApplication.config.to_h
{ 'user' => 'admin', 'pswd' => 'admin' }

GeneralApplication.config.to_h
{ 'user' => '0exp', 'pswd' => '123test', 'db' => { 'adapter' => 'pg' } }

# and etc... (all Qonfig-related features)

Instantiation without class definition

• without inheritance:

config = Qonfig::DataSet.build do
  setting :user, 'D@iVeR'
  setting :password, 'test123'

  def custom_method
    'custom_result'
  end
end

config.is_a?(Qonfig::DataSet) # => true

config.settings.user # => 'D@iVeR'
config.settings.password # => 'test123'
config.custom_method # => 'custom_result'

• with inheritance:

class GeneralConfig < Qonfig::DataSet
  setting :db_adapter, :postgresql
end

config = Qonfig::DataSet.build(GeneralConfig) do
  setting :web_api, 'api.google.com'
end

config.is_a?(Qonfig::DataSet) # => true

config.settings.db_adapter # => :postgresql
config.settings.web_api # => "api.google.com"

Compacted config

• Definition and instantiation
  • by raw initialization
  • by existing Qonfig::DataSet class
  • by existing Qonfig::DataSet instance
  • instantiation without class definition
  • validation API
• Setting readers and writers
  • reading
  • writing
  • precitaes

• Qonfig::Compacted: represents the compacted config object with setting readers, setting writers and setting predicates only - and no any other useful instance-based functionality:
• setting keys are represented as direct instace methods (#settings invokation does not need);
• support for index-like access methods ([],[]=);
• full support of Qonfig::DataSet definition DSL commands:
  • setting, re_setting doc
  • validate, add_validator doc
  • load_from_self doc, load_from_yaml doc, load_from_json doc, load_from_toml doc;
  • expose_self doc, expose_yaml doc, expose_json doc, expose_toml doc
  • values_file doc
• support for validation of potential setting values .valid_with? documentation;
• can be instantiated by:
  • by existing config object: Qonfig::DataSet#compacted or Qonfig::Compacted.build_from(config, &configuration);
  • from existing Qonfig::DataSet class: Qonfig::DataSet.build_compacted;
  • by direct instantiation: Qonfig::Compacted.new(settings_values = {}, &configuration);
  • by implicit instance building without explicit class definition Qonfig::Compacted.build(&dsl_commands);
• you can define your own instance methods too;

Definition and instantiation

by raw initialization

class Config < Qonfig::Compacted
  setting :api, 'google.com'
  setting :enabled, true
  setting :queue do
    setting :engine, :sidekiq
  end
end

config = Config.new(api: 'yandex.ru') do |conf|
  conf.enabled = false
end

config.api # => 'yandex.ru'
config.enabled # => false
config.queue.engine # => :sidekiq

by existing Qonfig::DataSet class

class Config < Qonfig::DataSet
  setting :api, 'google.com'
  setting :enabled, true
end

config = Config.build_compacted # builds Qonfig::Compacted instance

config.api # => 'google.com'
config.enabled # => true

by existing Qonfig::DataSet instance

• Qonfig::DataSet#compacted
• (or) Qonfig::Compacted.build_from(config)

class Config < Qonfig::DataSet
  setting :api, 'google.com'
  setting :enabled, true
end

config = Config.new

compacted_config = config.compacted
# --- or ---
compacted_config = Qonfig::Compacted.build_from(config)

compacted_config.api # => 'google.com'
compacted_config.enabled # => true

instantiation without class definition

config = Qonfig::Compacted.build do
  setting :api, 'google.ru'
  setting :enabled, true
end

config.api # => 'google.ru'
config.enabled # => true

validation API (see full documentation):

# custom validators
Qonfig::Compacted.define_validator(:version_check) do |value|
  value.is_a?(Integer) && value < 100
end

class Config < Qonfig::Compacted
  setting :api, 'google.ru'
  setting :enabled, true
  setting :version, 2
  setting :queue { setting :engine, :sidekiq }

  # full support of original validation api
  validate :api, :string, strict: true
  validate :enabled, :boolean, strict: true
  validate :version, :version_check # custom validator
  validate 'queue.#', :symbol
end

# potential values validation
Config.valid_with?(api: :yandex) # => false
Config.valid_with?(enabled: nil) # => false
Config.valid_with?(version: nil) # => false
Config.valid_with?(api: 'yandex.ru', enabled: false, version: 3) # => true

config = Config.new

# instance validation
config.api = :yandex # => Qonfig::ValidationError (should be a type of string)
config.version = nil # => Qonfig::ValidationError (can not be nil)
config.queue.engine = 'sneakers' # => Qonfig::ValidationError (should be a type of symbol)

Setting readers and writers

class Config < Qonfig::Compcated
  setting :api, 'google.ru'
  setting :enabled, true
  setting :queue do
    setting :engine, :sidekiq
    setting :workers_count, 10
  end
end

config = Config.new

reading (by setting name and index method with dot-notation support and indifferent access)

# by setting name
config.api # => 'google.ru'
config.enabled # => true
config.queue.engine # => :sidekiq
config.queue.workers_count # => 10

# by index method with dot-notation support and indiffernt access
config[:api] # => 'google.ru'
config['enabled'] # => true
config[:queue][:engine] # => :sidekiq
config['queue.workers_count'] # => 10

writing (by setting name and index method with dot-notation support and indifferent access)

# by setting name
config.api = 'yandex.ru'
config.queue.engine = :sidekiq
# and etc

# by index method with dot-notaiton support and indifferent access
config['api'] = 'yandex.ru'
config['queue.engine'] = :sidekiq
config[:queue][:workers_count] = 5

predicates (see full documentation)

class Config < Qonfig::Compcated
  setting :enabled, true
  setting :api, 'yandex.ru'
  setting :queue do
    setting :engine, :sidekiq
  end
end

config = Config.new

config.enabled? # => true
config.enabled = nil
config.enabled? # => false

config.queue.engine? # => true
config.queue.engine =  nil
config.queue.engine? # => false

config.queue? # => true

Interaction

• Iteration over setting keys (#each_setting, #deep_each_setting)
• List of config keys (#keys, #root_keys)
• Config reloading (reload config definitions and option values)
• Clear options (set to nil)
• Frozen state (.freeze_state!, #freeze!, #frozen?)
• Settings as Predicates
• Setting key existence (#key?/#option?/#setting?)
• Run arbitrary code with temporary settings

Iteration over setting keys

• #each_setting { |key, value| }
  • iterates over the root setting keys;
• #deep_each_setting(yield_all: false) { |key, value| }
  • iterates over all setting keys (deep inside);
  • key object is represented as a string of .-joined setting key names;
  • yield_all: means "yield all config objects" (end values and root setting objects those have nested settings) (false by default);

class Config < Qonfig::DataSet
  setting :db do
    setting :creds do
      setting :user, 'D@iVeR'
      setting :password, 'test123',
      setting :data, test: false
    end
  end

  setting :telegraf_url, 'udp://localhost:8094'
  setting :telegraf_prefix, 'test'
end

config = Config.new

.each_setting

config.each_setting { |key, value| { key => value } }

# result of each step:
{ 'db' => <Qonfig::Settings:0x00007ff8> }
{ 'telegraf_url' => 'udp://localhost:8094' }
{ 'telegraf_prefix' => 'test' }

.deep_each_setting

config.deep_each_setting { |key, value| { key => value } }

# result of each step:
{ 'db.creds.user' => 'D@iveR' }
{ 'db.creds.password' => 'test123' }
{ 'db.creds.data' => { test: false } }
{ 'telegraf_url' => 'udp://localhost:8094' }
{ 'telegraf_prefix' => 'test' }

.deep_each_setting(yield_all: true)

config.deep_each_setting(yield_all: true) { |key, value| { key => value } }

# result of each step:
{ 'db' => <Qonfig::Settings:0x00007ff8> } # (yield_all: true)
{ 'db.creds' => <Qonfig::Settings:0x00002ff1> } # (yield_all: true)
{ 'db.creds.user' => 'D@iVeR' }
{ 'db.creds.password' => 'test123' }
{ 'db.crds.data' => { test: false } }
{ 'telegraf_url' => 'udp://localhost:8094' }
{ 'telegraf_prefix' => 'test' }

List of config keys

• #keys - returns a list of all config keys in dot-notation format;
  • all_variants: - get all possible variants of the config's keys sequences (false by default);
  • only_root: - get only the root config keys (false by default);
• #root_keys - returns a list of root config keys (an alias for #keys(only_root: true));

# NOTE: suppose we have the following config

class Config < Qonfig::DataSet
  setting :credentials do
    setting :social do
      setting :service, 'instagram'
      setting :login, '0exp'
    end

    setting :admin do
      setting :enabled, true
    end
  end

  setting :server do
    setting :type, 'cloud'
    setting :options do
      setting :os, 'CentOS'
    end
  end
end

config = Config.new

Default behavior

config.keys

# the result:
[
  "credentials.social.service",
  "credentials.social.login",
  "credentials.admin.enabled",
  "server.type",
  "server.options.os"
]

All key variants

config.keys(all_variants: true)

# the result:
[
  "credentials",
  "credentials.social",
  "credentials.social.service",
  "credentials.social.login",
  "credentials.admin",
  "credentials.admin.enabled",
  "server",
  "server.type",
  "server.options",
  "server.options.os"
]

Only root keys

config.keys(only_root: true)

# the result:
['credentials', 'server']

config.root_keys

# the result:
['credentials', 'server']

Config reloading

• method signature: #reload!(configurations = {}, &configuration);

# -- config example ---

class Config < Qonfig::DataSet
  setting :db do
    setting :adapter, 'postgresql'
  end

  setting :logger, Logger.new(STDOUT)
end

config = Config.new

config.settings.db.adapter # => 'postgresql'
config.settings.logger # => #<Logger:0x00007ff9>

# --- redefine some settings (or add a new one) --

config.configure { |conf| conf.logger = nil } # redefine some settings (will be reloaded)

# re-define and append settings
class Config
  setting :db do
    setting :adapter, 'mongoid' # re-define defaults
  end

  setting :enable_api, false # append new setting
end

# --- reload ---

# reload settings
config.reload!

config.settings.db.adapter # => 'mongoid'
config.settings.logger # => #<Logger:0x00007ff9> (reloaded from defaults)
config.settings.enable_api # => false (new setting)

# reload with instant configuration
config.reload!(db: { adapter: 'oracle' }) do |conf|
  conf.enable_api = true # changed instantly
end

config.settings.db.adapter # => 'oracle'
config.settings.logger = # => #<Logger:0x00007ff9>
config.settings.enable_api # => true # value from instant change

Clear options

• set all config's settings to nil;
• method signature: #clear!;

class Config
  setting :database do
    setting :user
    setting :password
  end

  setting :web_api do
    setting :endpoint
  end
end

config = Config.new do |conf|
  conf.database.user = '0exp'
  conf.database.password = 'test123'

  conf.web_api.endpoint = '/api/'
end

config.settings.database.user # => '0exp'
config.settings.database.password # => 'test123'
config.settings.web_api.endpoint # => '/api'

# clear all options
config.clear!

config.settings.database.user # => nil
config.settings.database.password # => nil
config.settings.web_api.endpoint # => nil

Frozen state

Instance-level

• method signature: #freeze!;

class Config < Qonfig::DataSet
  setting :logger, Logger.new(STDOUT)
  setting :worker, :sidekiq
  setting :db do
    setting :adapter, 'postgresql'
  end
end

config = Config.new
config.freeze!

config.settings.logger = Logger.new(StringIO.new) # => Qonfig::FrozenSettingsError
config.settings.worker = :que # => Qonfig::FrozenSettingsError
config.settings.db.adapter = 'mongoid' # => Qonfig::FrozenSettingsError

config.reload! # => Qonfig::FrozenSettingsError
config.clear! # => Qonfig::FrozenSettingsError

Definition-level

• DSL-method signature: freeze_state!
• indicaes that all your config instances should be frozen;
• freeze_state! DSL command is not inherited (your child and composed config classes will not have this declaration);

# --- base class ---
class Config < Qonfig::DataSet
  setting :test, true
  freeze_state!
end

config = Config.new
config.frozen? # => true
config.settings.test = false # => Qonfig::FrozenSettingsError

# --- child class ---
class InheritedConfig < Config
end

inherited_config = InheritedConfig.new
config.frozen? # => false
config.settings.test = false # ok :)

Settings as Predicates

• predicate form: ? at the end of setting name;
• nil and false setting values indicates false;
• other setting values indicates true;
• setting roots always returns true;

class Config < Qonfig::DataSet
  setting :database do
    setting :user
    setting :host, 'google.com'

    setting :engine do
      setting :driver, 'postgres'
    end
  end
end

config = Config.new

# predicates
config.settings.database.user? # => false (nil => false)
config.settings.database.host? # => true ('google.com' => true)
config.settings.database.engine.driver? # => true ('postgres' => true)

# setting roots always returns true
config.settings.database? # => true
config.settings.database.engine? # => ture

config.configure do |conf|
  conf.database.user = '0exp'
  conf.database.host = false
  conf.database.engine.driver = true
end

# predicates
config.settings.database.user? # => true ('0exp' => true)
config.settings.database.host? # => false (false => false)
config.settings.database.engine.driver? # => true (true => true)

Setting key existence

• supports dynamic array-like format and canonical dot-notation format;
• returns true if the concrete key is exist;
• returns false if the concrete key does not exist;
• dynamic array-like format:
  • #key?(*key_path) / #option?(*key_path) / #setting?(*key_path);
  • *key_path - an array of symbols and strings that represents a path to the concrete setting key;
  • (for example, config.key?(:credentials, :user) tries to check that config.settings.credentials.user is exist);
• dot-notation format:
  • #key?(key) / #option?(key) / #setting?(key);
  • key - string in dot-notated format
  • (for example: config.key?('credentials.user') tries to check that config.settings.crednetials.user is exist);

class Config < Qonfig::DataSet
  setting :credentials do
    setting :user, 'D@iVeR'
    setting :password, 'test123'
  end
end

config = Config.new

# --- array-like format ---
config.key?('credentials', 'user') # => true
config.key?('credentials', 'token') # => false (key does not exist)

# --- dot-notation format ---
config.key?('credentials.user') # => true
config.key?('credentials.token') # => false (key does not exist)

config.key?('credentials') # => true
config.key?('que_adapter') # => false (key does not exist)

# aliases
config.setting?('credentials') # => true
config.option?(:credentials, :password) # => true
config.option?('credentials.password') # => true

Run arbitrary code with temporary settings

• provides a way to run an arbitrary code with temporarily specified settings;
• your arbitrary code can temporary change any setting too - all settings will be returned to the original state;
• (it is convenient to run code samples by this way in tests (with substitued configs));
• it is fully thread-safe :);

class Config < Qonfig::DataSet
  setting :queue do
    setting :adapter, :sidekiq
    setting :options, {}
  end
end

config = Config.new

# run a block of code with temporary queue.adapter setting
config.with(queue: { adapter: 'que' }) do
  # your changed settings
  config.settings.queue.adapter # => 'que'

  # you can temporary change settings by your code too
  config.settings.queue.options = { concurrency: 10 }

  # ...your another code...
end

# original settings has not changed :)
config.settings.queue.adapter # => :sidekiq
config.settings.queue.options # => {}

Import settings / Export settings

• Import config settings (as instance methods)
• Export config settings (as singleton methods)

Sometimes the nesting of configs in your project is quite high, and it makes you write the rather "cumbersome" code (config.settings.web_api.credentials.account.auth_token for example). Frequent access to configs in this way is inconvinient - so developers wraps such code by methods or variables. In order to make developer's life easer Qonfig provides a special Import API simplifies the config importing (gives you .import_settings DSL) and gives an ability to instant config setting export from a config object (gives you #export_settings config's method).

You can use RabbitMQ-like pattern matching in setting key names:

• if the setting key name at the current nesting level does not matter - use *;
• if both the setting key name and nesting level does not matter - use #
• examples:
  • db.settings.user - matches to db.settings.user setting;
  • db.settings.* - matches to all setting keys inside db.settings group of settings;
  • db.*.user - matches to all user setting keys at the first level of db group of settings;
  • #.user - matches to all user setting keys;
  • service.#.password - matches to all password setting keys at all levels of service group of settings;
  • # - matches to ALL setting keys;
  • * - matches to all setting keys at the root level;
  • and etc;

Import config settings

• Qonfig::Imports - a special mixin that provides the convenient DSL to work with config import features (.import_settings method);
• .import_settings - DSL method for importing configuration settings (from a config instance) as instance methods of a class;
• (IMPORTANT) import_settings imports config settings as access methods to config's settings (creates attr_readers for your config);
• generated methods can be used as predicates (with trailing ? symbol);
• you can generate attr_accessors by specifying accessor: true option (be careful: you can get Qonfig::AmbiguousSettingValueError when you try to assign a value to config option which have nested settings);
• signature: .import_settings(config_object, *setting_keys, mappings: {}, prefix: '', raw: false)
  • config_object - an instance of Qonfig::DataSet whose config settings should be imported;
  • *setting_keys - an array of dot-notaed config's setting keys that should be imported (dot-notaed key is a key that describes each part of nested setting key as a string separated by dot-symbol);
    • last part of dot-notated key will become a name of the setting access instance method;
  • mappings: - a map of keys that describes custom method names for each imported setting;
  • prefix: - prexifies setting access method name with custom prefix;
  • raw: - use nested settings as objects or hashify them (false by default (means "hashify nested settings"));
  • accessor: - generate attr_accessor for imported config settigns (false by default (means "generate attr_readers only"));

Suppose we have a config with deeply nested keys:

# NOTE: (Qonfig::DataSet.build creates a class and instantly instantiates it)
AppConfig = Qonfig::DataSet.build do
  setting :web_api do
    setting :credentials do
      setting :account do
        setting :login, 'DaiveR'
        setting :auth_token, 'IAdkoa0@()1239uA'
      end
    end
  end

  setting :graphql_api, false
end

Let's see what we can to do :)

• Import a set of setting keys (simple dot-noated key list)
• Import with custom method names (mappings)
• Prexify method name
• Import nested settings as raw Qonfig::Settings objects
• Import with pattern-matching
• Support for predicate-like methods

Import a set of setting keys (simple dot-noated key list)

• last part of dot-notated key will become a name of the setting access instance method;

class ServiceObject
  include Qonfig::Imports

  import_settings(AppConfig,
    'web_api.credentials.account.login',
    'web_api.credentials.account'
  )
end

service = ServiceObject.new

service.login # => "D@iVeR"
service.account # => { "login" => "D@iVeR", "auth_token" => IAdkoa0@()1239uA" }

Import with custom method names (mappings)

• mappings: defines a map of keys that describes custom method names for each imported setting;

class ServiceObject
  include Qonfig::Imports

  import_settings(AppConfig, mappings: {
    account_data: 'web_api.credentials.account', # NOTE: name access method with "account_data"
    secret_token: 'web_api.credentials.account.auth_token' # NOTE: name access method with "secret_token"
  })
end

service = ServiceObject.new

service.account_data # => { "login" => "D@iVeR", "auth_token" => "IAdkoa0@()1239uA" }
service.auth_token # => "IAdkoa0@()1239uA"

Prexify method name

• prefix: - prexifies setting access method name with custom prefix;

class ServiceObject
  include Qonfig::Imports

  import_settings(AppConfig,
    'web_api.credentials.account',
    mappings: { secret_token: 'web_api.credentials.account.auth_token' },
    prefix: 'config_'
  )
end

service = ServiceObject.new

service.config_account # => { login" => "D@iVeR", "auth_token" => "IAdkoa0@()1239uA" }
service.config_secret_token # => "IAdkoa0@()1239uA"

Support for predicate-like methods

• generated methods can be used as predicates (with trailing ? symbol);

class ServiceObject
  include Qonfig::Imports

  import_settings(AppConfig,
    'web_api.credentials.account',
    mappings: { secret_token: 'web_api.credentials.account.auth_token' },
  )
end

service = ServiceObject.new

service.account? # => true
service.secret_token? # => true

Import nested settings as raw Qonfig::Settings objects

• raw: false is used by default (hashify nested settings)

# NOTE: import nested settings as raw objects (raw: true)
class ServiceObject
  include Qonfig::Imports

  import_settings(AppConfig, 'web_api.credentials', raw: true)
end

service = ServiceObject.new

service.credentials # => <Qonfig::Settings:0x00007ff8>
service.credentials.account.login # => "D@iVeR"
service.credentials.account.auth_token # => "IAdkoa0@()1239uA"

# NOTE: import nested settings as converted-to-hash objects (raw: false) (default behavior)
class ServiceObject
  include Qonfig::Imports

  import_settings(AppConfig, 'web_api.credentials', raw: false)
end

service = ServiceObject.new

service.credentials # => { "account" => { "login" => "D@iVeR", "auth_token" => "IAdkoa0@()1239uA"} }

Import with pattern-matching

• import root keys only: import_settings(config_object, '*');
• import all keys: import_settings(config_object, '#');
• import the subset of keys: import_settings(config_object, 'group.*.group.#') (pattern-mathcing usage);

class ServiceObject
  include Qonfig::Imports

  # import all settings from web_api.credentials subset
  import_settings(AppConfig, 'web_api.credentials.#')
  # generated instance methods:
  #   => service.account
  #   => service.login
  #   => service.auth_token

  # import only the root keys from web_api.credentials.account subset
  import_settings(AppConfig, 'web_api.credentials.account.*')
  # generated instance methods:
  #   => service.login
  #   => service.auth_token

  # import only the root keys
  import_settings(AppConfig, '*')
  # generated instance methods:
  #   => service.web_api
  #   => service.graphql_api

  # import ALL keys
  import_settings(AppConfig, '#')
  # generated instance methods:
  #   => service.web_api
  #   => service.credentials
  #   => service.account
  #   => service.login
  #   => service.auth_token
  #   => service.graphql_api
end

Export config settings

• works in .import_settings manner doc (see examples and documentation above :))
• all config objects can export their settings to an arbitrary object as singleton methods;
• (IMPORTANT) export_settings exports config settings as access methods to config's settings (creates attr_readers for your config);
• generated methods can be used as predicates (with trailing ? symbol);
• you can generate attr_accessors by specifying accessor: true option (be careful: you can get Qonfig::AmbiguousSettingValueError when you try to assign a value to config option which have nested settings);
• signature: #export_settings(exportable_object, *setting_keys, mappings: {}, prefix: '', raw: false):
  • exportable_object - an arbitrary object for exporting;
  • *setting_keys - an array of dot-notaed config's setting keys that should be exported (dot-notaed key is a key that describes each part of nested setting key as a string separated by dot-symbol);
    • last part of dot-notated key will become a name of the setting access instance method;
  • mappings: - a map of keys that describes custom method names for each exported setting;
  • prefix: - prexifies setting access method name with custom prefix;
  • raw: - use nested settings as objects or hashify them (false by default (means "hashify nested settings"));
• accessor: - generate attr_accessor for imported config settigns (false by default (means "generate attr_readers only"));

class Config < Qonfig::DataSet
  setting :web_api do
    setting :credentials do
      setting :account do
        setting :login, 'DaiveR'
        setting :auth_token, 'IAdkoa0@()1239uA'
      end
    end
  end

  setting :graphql_api, false
end

class ServiceObject; end

config = Config.new
service = ServiceObject.new

service.config_account # => NoMethodError

# NOTE: export settings as access methods to config's settings
config.export_settings(service, 'web_api.credentials.account', prefix: 'config_')

service.config_account # => { "login" => "D@iVeR", "auth_token" => "IAdkoa0@()1239uA" }

# NOTE: export settings with pattern matching
config.export_settings(service, '*') # export root settings

service.web_api # => { 'credentials' => { 'account' => { ... } }, 'graphql_api' => false }
service.graphql_api # => false

# NOTE: predicates
config.export_settings(service, '*')

config.web_api? # => true
config.graphql_api? # => false

Validation

• Introduction
• Key Search Pattern
• Proc-based validation
• Method-based validation
• Predefined validations
• Custom predefined validators
• Validation of potential setting values

Introduction

Qonfig provides a lightweight DSL for defining validations and works in all cases when setting values are initialized or mutated. Settings are validated as keys (matched with a specific string pattern). You can validate both a set of keys and each key separately. If you want to check the config object completely you can define a custom validation.

Features:

• validation is invoked on any mutation of any setting:
  • during dataset instantiation;
  • when assigning new values;
  • when calling #reload!;
  • when calling #clear!;
• provides strict and non-strict behavior (strict: true and strict: false respectively):
  • strict: false ignores validations for settings with nil (allows nil value);
  • strict: true does not ignores validations for settings with nil;
  • strict: false is used by default;
• provides a special key search pattern for matching setting key names;
• you can validate potential setting values without any assignment (documentation)
• uses the key search pattern for definging what the setting key should be validated;
• you can define your own custom validation logic and validate dataset instance completely;
• validation logic should return truthy or falsy value;
• supprots two validation techniques (proc-based (documentation) and dataset-method-based (documentation)):
  • proc-based (setting validation) (documentation)

      validate('db.user', strict: true) do |value|
        value.is_a?(String)
      end
    

  • proc-based (dataset validation) (doc)

      validate(strict: false) do
        settings.user == User[1]
      end
    

  • dataset-method-based (setting validation) (documentation)

      validate 'db.user', by: :check_user, strict: true
    
      def check_user(value)
        value.is_a?(String)
      end
    

  • dataset-method-based (dataset validation) (documentation)

      validate by: :check_config, strict: false
    
      def check_config
        settings.user == User[1]
      end
    

• provides a set of standard validations (documentation):
  • DSL: validate 'key.pattern', :predefned_validator;
  • supports strict behavior;
• you can define your own predefined validators (class-related and global-related) (documentation);

Key search pattern

Key search pattern works according to the following rules:

• works in RabbitMQ-like key pattern ruleses;
• has a string format;
• nested configs are defined by a set of keys separated by .-symbol;
• if the setting key name at the current nesting level does not matter - use *;
• if both the setting key name and nesting level does not matter - use #
• examples:
  • db.settings.user - matches to db.settings.user setting;
  • db.settings.* - matches to all setting keys inside db.settings group of settings;
  • db.*.user - matches to all user setting keys at the first level of db group of settings;
  • #.user - matches to all user setting keys;
  • service.#.password - matches to all password setting keys at all levels of service group of settings;
  • # - matches to ALL setting keys;
  • * - matches to all setting keys at the root level;
  • and etc;

Proc-based validation

• your proc should return truthy value or falsy value;
• nil values are ignored by default;
• set strict: true to disable nil ignorance (strict: false is used by default);
• how to validate setting keys:
  • define proc with attribute: validate 'your.setting.path' do |value|; end
  • proc will receive setting value;
• how to validate dataset instance:
  • define proc without setting key pattern: validate do; end;

class Config < Qonfig::DataSet
  setting :db do
    setting :user, 'D@iVeR'
    setting :password, 'test123'
  end

  setting :service do
    setting :address, 'google.ru'
    setting :protocol, 'https'

    setting :creds do
      seting :admin, 'D@iVeR'
    end
  end

  setting :enabled, false
  setting :token, '1a2a3a', strict: true

  # validates:
  #   - db.password
  validate 'db.password' do |value|
    value.is_a?(String)
  end

  # validates:
  #   - service.address
  #   - service.protocol
  #   - service.creds.user
  validate 'service.#' do |value|
    value.is_a?(String)
  end

  # validates:
  #   - dataset instance
  validate do # NOTE: no setting key pattern
    settings.enabled == false
  end

  # do not ignore `nil` (strict: true)
  validate(:token, strict: true) do
    value.is_a?(String)
  end
end

config = Config.new
config.settings.db.password = 123 # => Qonfig::ValidationError (should be a string)
config.settings.service.address = 123 # => Qonfig::ValidationError (should be a string)
config.settings.service.protocol = :http # => Qonfig::ValidationError (should be a string)
config.settings.service.creds.admin = :billikota # => Qonfig::ValidationError (should be a string)
config.settings.enabled = true # => Qonfig::ValidationError (isnt `true`)

config.settings.db.password = nil # ok, nil is ignored (non-strict behavior)
config.settings.token = nil # => Qonfig::ValidationError (nil is not ignored, strict behavior) (should be a type of string)

Method-based validation

• method should return truthy value or falsy value;
• nil values are ignored by default;
• set strict: true to disable nil ignorance (strict: false is used by default);
• how to validate setting keys:
  • define validation: validate 'db.*.user', by: :your_custom_method;
  • define your method with attribute: def your_custom_method(setting_value); end
• how to validate config instance
  • define validation: validate by: :your_custom_method
  • define your method without attributes: def your_custom_method; end

class Config < Qonfig::DataSet
  setting :services do
    setting :counts do
      setting :google, 2
      setting :rambler, 3
    end

    setting :minimals do
      setting :google, 1
      setting :rambler, 0
    end
  end

  setting :enabled, true
  setting :timeout, 12345, strict: true

  # validates:
  #   - services.counts.google
  #   - services.counts.rambler
  #   - services.minimals.google
  #   - services.minimals.rambler
  validate 'services.#', by: :check_presence

  # validates:
  #   - dataset instance
  validate by: :check_state # NOTE: no setting key pattern

  # do not ignore `nil` (strict: true)
  validate :timeout, strict: true, by: :check_timeout

  def check_presence(value)
    value.is_a?(Numeric) && value > 0
  end

  def check_state
    settings.enabled.is_a?(TrueClass) || settings.enabled.is_a?(FalseClass)
  end

  def check_timeout(value)
    value.is_a?(Numeric)
  end
end

config = Config.new

config.settings.counts.google = 0 # => Qonfig::ValidationError (< 0)
config.settings.minimals.google = -1 # => Qonfig::ValidationError (< 0)
config.settings.minimals.rambler = 'no' # => Qonfig::ValidationError (should be a numeric)

config.settings.counts.rambler = nil # ok, nil is ignored (default non-strict behavior)
config.settings.enabled = nil # ok, nil is ignored (default non-strict behavior)
config.settings.timeout = nil # => Qonfig::ValidationError (nil is not ignored, strict behavior) (should be a type of numeric)

Predefined validations

• DSL: validate 'key.pattern', :predefned_validator
• nil values are ignored by default;
• set strict: true to disable nil ignorance (strict: false is used by default);
• predefined validators:
  • :not_nil
  • :integer
  • :float
  • :numeric
  • :big_decimal
  • :array
  • :hash
  • :string
  • :symbol
  • :text (string or symbol)
  • :boolean
  • :class
  • :module
  • :proc

class Config < Qonfig::DataSet
  setting :user, 'empty'
  setting :password, 'empty'

  setting :service do
    setting :provider, :empty
    setting :protocol, :empty
    setting :on_fail, -> { puts 'atata!' }
  end

  setting :ignorance, false

  validate 'user', :string
  validate 'password', :string
  validate 'service.provider', :text
  validate 'service.protocol', :text
  validate 'service.on_fail', :proc
  validate 'ignorance', :not_nil
end

config = Config.new do |conf|
  conf.user = 'D@iVeR'
  conf.password = 'test123'
  conf.service.provider = :google
  conf.service.protocol = :https
end # NOTE: all right :)

config.settings.ignorance = nil # => Qonfig::ValidationError (cant be nil)

Custom predefined validators

• DSL: .define_validator(name, &validation) { |value| ... } - create your own predefined validator;
• class-level: define validators related only to the concrete config class;
• global-level: define validators related to all config classes (Qonfig::DataSet.define_validator);
• you can re-define any global and inherited validator (at class level);
• you can re-define any already registered global validator on Qonfig::DataSet (at global-level);

Define your own class-level validator

class Config < Qonfig::DataSet
  # NOTE: definition
  define_validator(:user_type) { |value| value.is_a?(User) }

  setting :admin # some key

  # NOTE: usage
  validate :admin, :user_type
end

Define new global validator

Qonfig::DataSet.define_validator(:secured_value) do |value|
  value == '***'
end

class Config < Qonfig::DataSet
  setting :password
  validate :password, :secured_value
end

Re-definition of existing validators in child classes

class Config < Qonfig::DataSet
  # NOTE: redefine existing :text validator only in Config class
  define_validator(:text) { |value| value.is_a?(String) }

  # NOTE: some custom validator that can be redefined in child classes
  define_validator(:user) { |value| value.is_a?(User) }
end

class SubConfig < Qonfig
  define_validator(:user) { |value| value.is_a?(AdminUser) } # NOTE: redefine inherited :user validator
end

Re-definition of existing global validators

# NOTE: redefine already existing :numeric validator
Qonfig::DataSet.define_validator(:numeric) do |value|
  value.is_a?(Numeric) || (value.is_a?(String) && value.match?(/\A\d+\.*\d+\z/))
end

Validation of potential setting values

• (instance-level) #valid_with?(setting_values = {}, &configuration) - check that current config instalce will be valid with passed configurations;
• (class-level) .valid_with?(setting_values = {}, &configuration) - check that potential config instancess will be valid with passed configurations;
• makes no assignments;

#valid_with? (instance-level)

class Config < Qonfig::DataSet
  setting :enabled, false
  setting :queue do
    setting :adapter, 'sidekiq'
  end

  validate :enabled, :boolean
  validate 'queue.adapter', :string
end

config = Config.new

config.valid_with?(enabled: true, queue: { adapter: 'que' }) # => true
config.valid_with?(enabled: 123) # => false (should be a type of boolean)
config.valid_with?(enabled: true, queue: { adapter: Sidekiq }) # => false (queue.adapter should be a type of string)

# do-config notation is supported too
config.valid_with?(enabled: true) do |conf|
  conf.queue.adapter = :sidekiq
end
# => false (queue.adapter should be a type of string)

.valid_with? (class-level)

class Config < Qonfig::DataSet
  setting :enabled, false
  setting :queue do
    setting :adapter, 'sidekiq'
  end

  validate :enabled, :boolean
  validate 'queue.adapter', :string
end

Config.valid_with?(enabled: true, queue: { adapter: 'que' }) # => true
Config.valid_with?(enabled: 123) # => false (should be a type of boolean)
Config.valid_with?(enabled: true, queue: { adapter: Sidekiq }) # => false (queue.adapter should be a type of string)

# do-config notation is supported too
Config.valid_with?(enabled: true) do |config|
  config.queue.adapter = :sidekiq
end
# => false (queue.adapter should be a type of string)

Work with files

• Setting keys definition
  • Load from YAML file
  • Expose YAML (Rails-like environment-based YAML configs)
  • Load from JSON file
  • Expose JSON (Rails-like environment-based JSON configs)
  • Load from ENV
  • Load from __END__ (aka load_from_self)
  • Expose __END__ (aka expose_self)
• Setting values
  • Default setting values file
  • Load setting values from YAML file
  • Load setting values from JSON file
  • Load setting values from __END__
  • Load setting values from file manually
• Daily work
  • Save to JSON file (save_to_json)
  • Save to YAML file (save_to_yaml)

Load from YAML file

• supports ERB;
• :strict mode (fail behaviour when the required yaml file doesnt exist):
  • true (by default) - causes Qonfig::FileNotFoundError;
  • false - do nothing, ignore current command;
• :replace_on_merge - whether the setting should be replaced on the key conflict, otherwise, it will be deep merged (default);

# travis.yml

sudo: false
language: ruby
rvm:
  - ruby-head
  - jruby-head

# project.yml

enable_api: false
Sidekiq/Scheduler:
  enable: true

# ruby_data.yml

version: <%= RUBY_VERSION %>
platform: <%= RUBY_PLATFORM %>

class Config < Qonfig::DataSet
  setting :ruby do
    load_from_yaml 'ruby_data.yml'
  end

  setting :travis do
    load_from_yaml 'travis.yml'
  end

  load_from_yaml 'project.yml'
end

config = Config.new

config.settings.travis.sudo # => false
config.settings.travis.language # => 'ruby'
config.settings.travis.rvm # => ['ruby-head', 'jruby-head']
config.settings.enable_api # => false
config.settings['Sidekiq/Scheduler']['enable'] #=> true
config.settings.ruby.version # => '2.5.1'
config.settings.ruby.platform # => 'x86_64-darwin17'

# --- strict mode ---
class Config < Qonfig::DataSet
  setting :nonexistent_yaml do
    load_from_yaml 'nonexistent_yaml.yml', strict: true # true by default
  end

  setting :another_key
end

Config.new # => Qonfig::FileNotFoundError

# --- non-strict mode ---
class Config < Qonfig::DataSet
  settings :nonexistent_yaml do
    load_from_yaml 'nonexistent_yaml.yml', strict: false
  end

  setting :another_key
end

Config.new.to_h # => { "nonexistent_yaml" => {}, "another_key" => nil }

Expose YAML

• load configurations from YAML file in Rails-like manner (with environments);
• works in load_from_yaml manner;
• via: - how an environment will be determined:
  • :file_name
    • load configuration from YAML file that have an :env part in it's name;
  • :env_key
    • load configuration from YAML file;
    • concrete configuration should be defined in the root key with :env name;
• env: - your environment name (must be a type of String, Symbol or Numeric);
• strict: - requires the existence of the file and/or key with the name of the used environment:
  • true:
    • file should exist;
    • root key with :env name should exist (if via: :env_key is used);
    • raises Qonfig::ExposeError if file does not contain the required env key (if via: :env key is used);
    • raises Qonfig::FileNotFoundError if the required file does not exist;
  • false:
    • file is not required;
    • root key with :env name is not required (if via: :env_key is used);
• :replace_on_merge - whether the setting should be replaced on the key conflict, otherwise, it will be deep merged (default);

Environment is defined as a root key of YAML file

# config/project.yml

default: &default
  enable_api_mode: true
  google_key: 12345
  window:
    width: 100
    height: 100

development:
  <<: *default

test:
  <<: *default
  sidekiq_instrumentation: false

staging:
  <<: *default
  google_key: 777
  enable_api_mode: false

production:
  google_key: asd1-39sd-55aI-O92x
  enable_api_mode: true
  window:
    width: 50
    height: 150

class Config < Qonfig::DataSet
  expose_yaml 'config/project.yml', via: :env_key, env: :production # load from production env

  # NOTE: in rails-like application you can use this:
  expose_yaml 'config/project.yml', via: :env_key, env: Rails.env
end

config = Config.new

config.settings.enable_api_mode # => true (from :production subset of keys)
config.settings.google_key # => asd1-39sd-55aI-O92x (from :production subset of keys)
config.settings.window.width # => 50 (from :production subset of keys)
config.settings.window.height # => 150 (from :production subset of keys)

Environment is defined as a part of YAML file name

# config/sidekiq.staging.yml

web:
  username: staging_admin
  password: staging_password

# config/sidekiq.production.yml

web:
  username: urj1o2
  password: u192jd0ixz0

class SidekiqConfig < Qonfig::DataSet
  # NOTE: file name should be described WITHOUT environment part (in file name attribute)
  expose_yaml 'config/sidekiq.yml', via: :file_name, env: :staging # load from staging env

  # NOTE: in rails-like application you can use this:
  expose_yaml 'config/sidekiq.yml', via: :file_name, env: Rails.env
end

config = SidekiqConfig.new

config.settings.web.username # => staging_admin (from sidekiq.staging.yml)
config.settings.web.password # => staging_password (from sidekiq.staging.yml)

Load from JSON file

• supports ERB;
• :strict mode (fail behaviour when the required yaml file doesnt exist):
  • true (by default) - causes Qonfig::FileNotFoundError;
  • false - do nothing, ignore current command;
• :replace_on_merge - whether the setting should be replaced on the key conflict, otherwise, it will be deep merged (default);

// options.json

{
  "user": "0exp",
  "password": 12345,
  "rubySettings": {
    "allowedVersions": ["2.3", "2.4.2", "1.9.8"],
    "gitLink": null,
    "withAdditionals": false
  }
}

class Config < Qonfig::DataSet
  load_from_json 'options.json'
end

config = Config.new

config.settings.user # => '0exp'
config.settings.password # => 12345
config.settings.rubySettings.allowedVersions # => ['2.3', '2.4.2', '1.9.8']
config.settings.rubySettings.gitLink # => nil
config.settings.rubySettings.withAdditionals # => false

# --- strict mode ---
class Config < Qonfig::DataSet
  setting :nonexistent_json do
    load_from_json 'nonexistent_json.json', strict: true # true by default
  end

  setting :another_key
end

Config.new # => Qonfig::FileNotFoundError

# --- non-strict mode ---
class Config < Qonfig::DataSet
  settings :nonexistent_json do
    load_from_json 'nonexistent_json.json', strict: false
  end

  setting :another_key
end

Config.new.to_h # => { "nonexistent_json" => {}, "another_key" => nil }

Expose JSON

• load configurations from JSON file in Rails-like manner (with environments);
• works in load_from_jsom/expose_yaml manner;
• via: - how an environment will be determined:
  • :file_name
    • load configuration from JSON file that have an :env part in it's name;
  • :env_key
    • load configuration from JSON file;
    • concrete configuration should be defined in the root key with :env name;
• env: - your environment name (must be a type of String, Symbol or Numeric);
• strict: - requires the existence of the file and/or key with the name of the used environment:
  • true:
    • file should exist;
    • root key with :env name should exist (if via: :env_key is used);
    • raises Qonfig::ExposeError if file does not contain the required env key (if via: :env key is used);
    • raises Qonfig::FileNotFoundError if the required file does not exist;
  • false:
    • file is not required;
    • root key with :env name is not required (if via: :env_key is used);
• :replace_on_merge - whether the setting should be replaced on the key conflict, otherwise, it will be deep merged (default);

Environment is defined as a root key of JSON file

// config/project.json

{
  "development": {
    "api_mode_enabled": true,
    "logging": false,
    "db_driver": "sequel",
    "throttle_requests": false,
    "credentials": {}
  },
  "test": {
    "api_mode_enabled": true,
    "logging": false,
    "db_driver": "in_memory",
    "throttle_requests": false,
    "credentials": {}
  },
  "staging": {
    "api_mode_enabled": true,
    "logging": true,
    "db_driver": "active_record",
    "throttle_requests": true,
    "credentials": {}
  },
  "production": {
    "api_mode_enabled": true,
    "logging": true,
    "db_driver": "rom",
    "throttle_requests": true,
    "credentials": {}
  }
}

class Config < Qonfig::DataSet
  expose_json 'config/project.json', via: :env_key, env: :production # load from production env

  # NOTE: in rails-like application you can use this:
  expose_json 'config/project.json', via: :env_key, env: Rails.env
end

config = Config.new

config.settings.api_mode_enabled # => true (from :production subset of keys)
config.settings.logging # => true (from :production subset of keys)
config.settings.db_driver # => "rom" (from :production subset of keys)
config.settings.throttle_requests # => true (from :production subset of keys)
config.settings.credentials # => {} (from :production subset of keys)

Environment is defined as a part of JSON file name

// config/sidekiq.staging.json
{
  "web": {
    "username": "staging_admin",
    "password": "staging_password"
  }
}

// config/sidekiq.production.json
{
  "web": {
    "username": "urj1o2",
    "password": "u192jd0ixz0"
  }
}

class SidekiqConfig < Qonfig::DataSet
  # NOTE: file name should be described WITHOUT environment part (in file name attribute)
  expose_json 'config/sidekiq.json', via: :file_name, env: :staging # load from staging env

  # NOTE: in rails-like application you can use this:
  expose_json 'config/sidekiq.json', via: :file_name, env: Rails.env
end

config = SidekiqConfig.new

config.settings.web.username # => "staging_admin" (from sidekiq.staging.json)
config.settings.web.password # => "staging_password" (from sidekiq.staging.json)

Load from ENV

• :convert_values (false by default):
  • 't', 'T', 'true', 'TRUE' - covnerts to true;
  • 'f', 'F', 'false', 'FALSE' - covnerts to false;
  • 1, 23 and etc - converts to Integer;
  • 1.25, 0.26 and etc - converts to Float;
  • 1, 2, test, FALSE,Qonfig (strings without quotes that contains at least one comma) - converts to Array with recursively converted values;
  • '"please, test"', "'test, please'" (quoted strings) - converts to String without quotes;
• :prefix - load ENV variables which names starts with a prefix:
  • nil (by default) - empty prefix;
  • Regexp - names that match the regexp pattern;
  • String - names which starts with a passed string;
• :trim_prefix (false by default);

# some env variables
ENV['QONFIG_BOOLEAN'] = 'true'
ENV['QONFIG_INTEGER'] = '0'
ENV['QONFIG_STRING'] = 'none'
ENV['QONFIG_ARRAY'] = '1, 2.5, t, f, TEST'
ENV['QONFIG_MESSAGE'] = '"Hello, Qonfig!"'
ENV['RUN_CI'] = '1'

class Config < Qonfig::DataSet
  # nested
  setting :qonfig do
    load_from_env convert_values: true, prefix: 'QONFIG' # or /\Aqonfig.*\z/i
  end

  setting :trimmed do
    load_from_env convert_values: true, prefix: 'QONFIG_', trim_prefix: true # trim prefix
  end

  # on the root
  load_from_env
end

config = Config.new

# customized
config.settings['qonfig']['QONFIG_BOOLEAN'] # => true ('true' => true)
config.settings['qonfig']['QONFIG_INTEGER'] # => 0 ('0' => 0)
config.settings['qonfig']['QONFIG_STRING'] # => 'none'
config.settings['qonfig']['QONFIG_ARRAY'] # => [1, 2.5, true, false, 'TEST']
config.settings['qonfig']['QONFIG_MESSAGE'] # => 'Hello, Qonfig!'
config.settings['qonfig']['RUN_CI'] # => Qonfig::UnknownSettingError

# trimmed (and customized)
config.settings['trimmed']['BOOLEAN'] # => true ('true' => true)
config.settings['trimmed']['INTEGER'] # => 0 ('0' => 0)
config.settings['trimmed']['STRING'] # => 'none'
config.settings['trimmed']['ARRAY'] # => [1, 2.5, true, false, 'TEST']
config.settings['trimmed']['MESSAGE'] # => 'Hello, Qonfig!'
config.settings['trimmed']['RUN_CI'] # => Qonfig::UnknownSettingError

# default
config.settings['QONFIG_BOOLEAN'] # => 'true'
config.settings['QONFIG_INTEGER'] # => '0'
config.settings['QONFIG_STRING'] # => 'none'
config.settings['QONFIG_ARRAY'] # => '1, 2.5, t, f, TEST'
config.settings['QONFIG_MESSAGE'] # => '"Hello, Qonfig!"'
config.settings['RUN_CI'] # => '1'

Load from __END__

• aka load_from_self
• :format - specify the format of data placed under the __END__ instruction:
  • format: :dynamic (default) - automatic format resolvation;
  • format: :yaml - YAML format;
  • format: :json - JSON format;
  • format: :toml - TOML format (via toml-plugin);
• :replace_on_merge - whether the setting should be replaced on the key conflict, otherwise, it will be deep merged (default);

class Config < Qonfig::DataSet
  load_from_self # on the root (:dynamic format is used by default)

  setting :nested do
    load_from_self, format: :yaml # with explicitly identified YAML format
  end
end

config = Config.new

# on the root
config.settings.ruby_version # => '2.5.1'
config.settings.secret_key # => 'top-mega-secret'
config.settings.api_host # => 'super.puper-google.com'
config.settings.connection_timeout.seconds # => 10
config.settings.connection_timeout.enabled # => false

# nested
config.settings.nested.ruby_version # => '2.5.1'
config.settings.nested.secret_key # => 'top-mega-secret'
config.settings.nested.api_host # => 'super.puper-google.com'
config.settings.nested.connection_timeout.seconds # => 10
config.settings.nested.connection_timeout.enabled # => false

__END__

ruby_version: <%= RUBY_VERSION %>
secret_key: top-mega-secret
api_host: super.puper-google.com
connection_timeout:
  seconds: 10
  enabled: false

Expose __END__

• aka expose_self;
• works in expose_json and expose_yaml manner, but with __END__ instruction of the current file;
• env: - your environment name (must be a type of String, Symbol or Numeric);
• :format - specify the format of data placed under the __END__ instruction:
  • format: :dynamic (default) - automatic format resolvation;
  • format: :yaml - YAML format;
  • format: :json - JSON format;
  • format: :toml - TOML format (via toml-plugin);
• :replace_on_merge - whether the setting should be replaced on the key conflict, otherwise, it will be deep merged (default);

class Config < Qonfig::DataSet
  expose_self env: :production, format: :yaml # with explicitly identified YAML format

  # NOTE: for Rails-like applications you can use this:
  expose_self env: Rails.env
end

config = Config.new

config.settings.log # => true (from :production environment)
config.settings.api_enabled # => true (from :production environment)
config.settings.creds.user # => "D@iVeR" (from :production environment)
config.settings.creds.password # => "test123" (from :production environment)

__END__

default: &default
  log: false
  api_enabled: true
  creds:
    user: admin
    password: 1234

development:
  <<: *default
  log: true

test:
  <<: *default
  log: false

staging:
  <<: *default

production:
  <<: *default
  log: true
  creds:
    user: D@iVeR
    password: test123

Default setting values file

• defines a file that should be used for setting values initialization for your config object;
• .values_file(file_path, format: :dynamic, strict: false, expose: nil)
  • file_path - full file path or :self (:self menas "load setting values from END data");
  • :format - defines the format of file (:dynamic means "try to automatically infer the file format") (:dynamic by default);
    • supports :yaml, :json, :toml (via Qonfig.plugin(:toml)), :dynamic (automatic format detection);
  • :strict - rerquires that file (or END-data) should exist (false by default);
  • :expose - what the environment-based subset of keys should be used (nil means "do not use any subset of keys") (nil by default);
• extra keys that does not exist in your config will cause an exception Qonfig::SettingNotFound respectively;
• initial values will be rewritten by values defined in your file;

Default behavior

# sidekiq.yml

adapter: sidekiq
options:
  processes: 10

class Config < Qonfig::DataSet
  values_file 'sidekiq.yml', format: :yaml

  setting :adapter, 'que'
  setting :options do
    setting :processes, 2
    setting :threads, 5
    setting :protected, false
  end
end

config = Config.new

config.settings.adapter # => "sidekiq" (from sidekiq.yml)
config.settings.options.processes # => 10 (from sidekiq.yml)
config.settings.options.threads # => 5 (original value)
config.settings.options.protected # => false (original value)

Load values from __END__-data

class Config < Qonfig::DataSet
  values_file :self, format: :yaml

  setting :user
  setting :password
  setting :enabled, true
end

config = Config.new

config.settings.user # => "D@iVeR" (from __END__ data)
config.settings.password # => "test123" (from __END__ data)
config.settings.enabled # => true (original value)

__END__

user: 'D@iVeR'
password: 'test123'

Setting values with environment separation

# sidekiq.yml

development:
  adapter: :in_memory
  options:
    threads: 10

production:
  adapter: :sidekiq
  options:
    threads: 150

class Config < Qonfig::DataSet
  values_file 'sidekiq.yml', format: :yaml, expose: :development

  setting :adapter
  setting :options do
    setting :threads
  end
end

config = Config.new

config.settings.adapter # => 'in_memory' (development keys subset)
config.settings.options.threads # => 10 (development keys subset)

File does not exist

# non-strict behavior (default)
class Config < Qonfig::DataSet
  values_file 'sidekiq.yml'
end

config = Config.new # no error

# strict behavior (strict: true)
class Config < Qonfig::DataSet
  values_file 'sidekiq.yml', strict: true
end

config = Config.new # => Qonfig::FileNotFoundError

Load setting values from YAML file (by instance)

• prvoides an ability to load predefined setting values from a yaml file;
• #load_from_yaml(file_path, strict: true, expose: nil, &configurations)
  • file_path - full file path or :self (:self means "load setting values from END data");
  • :strict - rerquires that file (or END-data) should exist (true by default);
  • :expose - what the environment-based subset of keys should be used (nil means "do not use any subset of keys") (nil by default);
  • &configurations - do |config| ability :)

Default behavior

# config.yml

domain: google.ru
creds:
  auth_token: test123

class Config < Qonfig::DataSet
  seting :domain, 'test.com'
  setting :creds do
    setting :auth_token, 'test'
  end
end

config = Config.new
config.settings.domain # => "test.com"
config.settings.creds.auth_token # => "test"

# load new values
config.load_from_yaml('config.yml')

config.settings.domain # => "google.ru" (from config.yml)
config.settings.creds.auth_token # => "test123" (from config.yml)

Load from __END__

class Config < Qonfig::DataSet
  seting :domain, 'test.com'
  setting :creds do
    setting :auth_token, 'test'
  end
end

config = Config.new
config.settings.domain # => "test.com"
config.settings.creds.auth_token # => "test"

# load new values
config.load_from_yaml(:self)
config.settings.domain # => "yandex.ru" (from __END__-data)
config.settings.creds.auth_token # => "CK0sIdA" (from __END__-data)

__END__

domain: yandex.ru
creds:
  auth_token: CK0sIdA

Setting values with environment separation

# config.yml

development:
  domain: dev.google.ru
  creds:
    auth_token: kekpek

production:
  domain: google.ru
  creds:
    auth_token: Asod1

class Config < Qonfig::DataSet
  setting :domain, 'test.com'
  setting :creds do
    setting :auth_token
  end
end

config = Config.new

# load new values (expose development settings)
config.load_from_yaml('config.yml', expose: :development)

config.settings.domain # => "dev.google.ru" (from config.yml)
config.settings.creds.auth_token # => "kek.pek" (from config.yml)

Load setting values from JSON file (by instance)

• prvoides an ability to load predefined setting values from a json file;
• #load_from_json(file_path, strict: true, expose: nil, &configurations)
  • file_path - full file path or :self (:self means "load setting values from END data");
  • :strict - rerquires that file (or END-data) should exist (true by default);
  • :expose - what the environment-based subset of keys should be used (nil means "do not use any subset of keys") (nil by default);
  • &configurations - do |config| ability :)

Default behavior

// config.json

{
  "domain": "google.ru",
  "creds": {
    "auth_token": "test123"
  }
}

class Config < Qonfig::DataSet
  seting :domain, 'test.com'
  setting :creds do
    setting :auth_token, 'test'
  end
end

config = Config.new
config.settings.domain # => "test.com"
config.settings.creds.auth_token # => "test"

# load new values
config.load_from_json('config.json')

config.settings.domain # => "google.ru" (from config.json)
config.settings.creds.auth_token # => "test123" (from config.json)

Load from __END__

class Config < Qonfig::DataSet
  seting :domain, 'test.com'
  setting :creds do
    setting :auth_token, 'test'
  end
end

config = Config.new
config.settings.domain # => "test.com"
config.settings.creds.auth_token # => "test"

# load new values
config.load_from_json(:self)
config.settings.domain # => "yandex.ru" (from __END__-data)
config.settings.creds.auth_token # => "CK0sIdA" (from __END__-data)

__END__

{
  "domain": "yandex.ru",
  "creds": {
    "auth_token": "CK0sIdA"
  }
}

Setting values with environment separation

// config.json

{
  "development": {
    "domain": "dev.google.ru",
    "creds": {
      "auth_token": "kekpek"
    }
  },
  "production": {
    "domain": "google.ru",
    "creds": {
      "auth_token": "Asod1"
    }
  }
}

class Config < Qonfig::DataSet
  setting :domain, 'test.com'
  setting :creds do
    setting :auth_token
  end
end

config = Config.new

# load new values (from development subset)
config.load_from_json('config.json', expose: :development)

config.settings.domain # => "dev.google.ru" (from config.json)
config.settings.creds.auth_token # => "kek.pek" (from config.json)

Load setting values from __END__ (by instance)

• prvoides an ability to load predefined setting values from __END__ file section;
• #load_from_self(strict: true, expose: nil, &configurations)
  • :format - defines the format of file (:dynamic means "try to automatically infer the file format") (:dynamic by default);
    • supports :yaml, :json, :toml (via Qonfig.plugin(:toml)), :dynamic (automatic format detection);
  • :strict - requires that END-data should exist (true by default);
  • :expose - what the environment-based subset of keys should be used (nil means "do not use any subset of keys") (nil by default);
  • &configurations - do |config| ability :)

Default behavior

class Config < Qonfig::DataSet
  setting :account, 'test'
  setting :options do
    setting :login, '0exp'
    setting :password, 'test123'
  end
end

config = Config.new
config.settings.account # => "test" (original value)
config.settings.options.login # => "0exp" (original value)
config.settings.options.password # => "test123" (original value)

# load new values
config.load_from_self(format: :yaml)
# or config.load_from_self

config.settings.account # => "real" (from __END__-data)
config.settings.options.login # => "D@iVeR" (from __END__-data)
config.settings.options.password # => "azaza123" (from __END__-data)

__END__

account: real
options:
  login: D@iVeR
  password: azaza123

Setting values with envvironment separation

class Config < Qonfig::DataSet
  setting :domain, 'test.google.ru'
  setting :options do
    setting :login, 'test'
    setting :password, 'test123'
  end
end

config = Config.new
config.settings.domain # => "test.google.ru" (original value)
config.settings.options.login # => "test" (original value)
config.settings.options.password # => "test123" (original value)

# load new values
config.load_from_self(format: :json, expose: :production)
# or config.load_from_self(expose: production)

config.settings.domain # => "prod.google.ru" (from __END__-data)
config.settings.options.login # => "prod" (from __END__-data)
config.settings.options.password # => "prod123" (from __END__-data)

__END__

{
  "development": {
    "domain": "dev.google.ru",
    "options": {
      "login": "dev",
      "password": "dev123"
    }
  },
  "production": {
    "domain": "prod.google.ru",
    "options": {
      "login": "prod",
      "password": "prod123"
    }
  }
}

Load setting values from file manually (by instance)

• prvoides an ability to load predefined setting values from a file;
• works in instance-based #load_from_yaml / #load_from_json / #load_from_self manner;
• signature: #load_from_file(file_path, format: :dynamic, strict: true, expose: nil, &configurations):
  • file_path - full file path or :self (:self means "load setting values from END data");
  • :format - defines the format of file (:dynamic means "try to automatically infer the file format") (:dynamic by default);
    • supports :yaml, :json, :toml (via Qonfig.plugin(:toml)), :dynamic (automatic format detection);
  • :strict - rerquires that file (or END-data) should exist (true by default);
  • :expose - what the environment-based subset of keys should be used (nil means "do not use any subset of keys") (nil by default);
  • &configurations - do |config| ability :)
• see examples for instance-based #load_from_yaml (doc) / #load_from_json (doc) / #load_from_self (doc);

Save to JSON file

• #save_to_json - represents config object as a json structure and saves it to a file:
  • uses native ::JSON.generate under the hood;
  • writes new file (or rewrites existing file);
  • attributes:
    • :path - (required) - file path;
    • :options - (optional) - native ::JSON.generate options (from stdlib):
      • :indent - " " by default;
      • :space - " " by default/
      • :object_nl - "\n" by default;
    • &value_preprocessor - (optional) - value pre-processor;

Without value preprocessing (standard usage)

class AppConfig < Qonfig::DataSet
  setting :server do
    setting :address, 'localhost'
    setting :port, 12_345
  end

  setting :enabled, true
end

config = AppConfig.new

# NOTE: save to json file
config.save_to_json(path: 'config.json')

{
 "sentry": {
  "address": "localhost",
  "port": 12345
 },
 "enabled": true
}

With value preprocessing and custom options

class AppConfig < Qonfig::DataSet
  setting :server do
    setting :address, 'localhost'
    setting :port, 12_345
  end

  setting :enabled, true
  setting :dynamic, -> { 1 + 2 }
end

config = AppConfig.new

# NOTE: save to json file with custom options (no spaces / no new line / no indent; call procs)
config.save_to_json(path: 'config.json', options: { indent: '', space: '', object_nl: '' }) do |value|
  value.is_a?(Proc) ? value.call : value
end

// no spaces / no new line / no indent / calculated "dynamic" setting key
{"sentry":{"address":"localhost","port":12345},"enabled":true,"dynamic":3}

Save to YAML file

• #save_to_yaml - represents config object as a yaml structure and saves it to a file:
  • uses native ::Psych.dump under the hood;
  • writes new file (or rewrites existing file);
  • attributes:
    • :path - (required) - file path;
    • :options - (optional) - native ::Psych.dump options (from stdlib):
      • :indentation - 2 by default;
      • :line_width - -1 by default;
      • :canonical - false by default;
      • :header - false by default;
      • :symbolize_keys - (non-native option) - false by default;
    • &value_preprocessor - (optional) - value pre-processor;

Without value preprocessing (standard usage)

class AppConfig < Qonfig::DataSet
  setting :server do
    setting :address, 'localhost'
    setting :port, 12_345
  end

  setting :enabled, true
end

config = AppConfig.new

# NOTE: save to yaml file
config.save_to_yaml(path: 'config.yml')

---
server:
  address: localhost
  port: 12345
enabled: true

With value preprocessing and custom options

class AppConfig < Qonfig::DataSet
  setting :server do
    setting :address, 'localhost'
    setting :port, 12_345
  end

  setting :enabled, true
  setting :dynamic, -> { 5 + 5 }
end

config = AppConfig.new

# NOTE: save to yaml file with custom options (add yaml version header; call procs)
config.save_to_yaml(path: 'config.yml', options: { header: true }) do |value|
  value.is_a?(Proc) ? value.call : value
end

# yaml version header / calculated "dynamic" setting key
%YAML 1.1
---
server:
  address: localhost
  port: 12345
enabled: true
dynamic: 10

Plugins

• toml (provides load_from_toml, save_to_toml, expose_toml);
• pretty_print (beautified/prettified console output);
• vault (provides load_from_vault, expose_vault)

Usage

• show available plugins:

Qonfig.plugins # => ["pretty_print", "toml", ..., ...]

• load specific plugin:

Qonfig.plugin(:pretty_print) # or Qonfig.plugin('pretty_print')
# -- or --
Qonfig.enable(:pretty_print) # or Qonfig.enable('pretty_print')
# -- or --
Qonfig.load(:pretty_print) # or Qonfig.load('pretty_print')

• show loaded plugins:

Qonfig.loaded_plugins # => ["pretty_print"]
# -- or --
Qonfig.enabled_plugins # => ["pretty_print"]

Plugins: toml

• Qonfig.plugin(:toml)
• adds support for toml format (specification);
• depends on toml-rb gem (link) (tested on >= 2.0);
• supports TOML 0.5.0 format (dependency lock) (toml-rb >= 2.0);
• provides .load_from_toml (works in .load_from_yaml manner (doc));
• provides .expose_toml (works in .expose_yaml manner (doc));
• provides #save_to_toml (works in #save_to_yaml manner (doc)) (toml-rb has no native options);
• provides format: :toml for .values_file (doc);
• provides #load_from_toml (work in #load_from_yaml manner (doc));

# 1) require external dependency
require 'toml-rb'

# 2) enable plugin
Qonfig.plugin(:toml)

# 3) use toml :)

Plugins: pretty_print

• Qonfig.plugin(:pretty_print)
• gives you really comfortable and beautiful console output;
• represents all setting keys in dot-notation format;

Example:

class Config < Qonfig::DataSet
  setting :api do
    setting :domain, 'google.ru'
    setting :creds do
      setting :account, 'D@iVeR'
      setting :password, 'test123'
    end
  end

  setting :log_requests, true
  setting :use_proxy, true
end

config = Config.new

• before:

=> #<Config:0x00007f9b6c01dab0
 @__lock__=
  #<Qonfig::DataSet::Lock:0x00007f9b6c01da60
   @access_lock=#<Thread::Mutex:0x00007f9b6c01da38>,
   @arbitary_lock=#<Thread::Mutex:0x00007f9b6c01d9e8>,
   @definition_lock=#<Thread::Mutex:0x00007f9b6c01da10>>,
 @settings=
  #<Qonfig::Settings:0x00007f9b6c01d858
   @__lock__=
    #<Qonfig::Settings::Lock:0x00007f9b6c01d808
     @access_lock=#<Thread::Mutex:0x00007f9b6c01d7b8>,
     @definition_lock=#<Thread::Mutex:0x00007f9b6c01d7e0>,
     @merge_lock=#<Thread::Mutex:0x00007f9b6c01d790>>,
   @__mutation_callbacks__=
    #<Qonfig::Settings::Callbacks:0x00007f9b6c01d8d0
     @callbacks=[#<Proc:0x00007f9b6c01d8f8@/Users/daiver/Projects/qonfig/lib/qonfig/settings/builder.rb:39>],
     @lock=#<Thread::Mutex:0x00007f9b6c01d880>>,
   @__options__=
    {"api"=>
      #<Qonfig::Settings:0x00007f9b6c01d498
# ... and etc

• after:

=> #<Config:0x00007f9b6c01dab0
 api.domain: "google.ru",
 api.creds.account: "D@iVeR",
 api.creds.password: "test123",
 log_requests: true,
 use_proxy: true>

# -- or --

=> #<Config:0x00007f9b6c01dab0 api.domain: "google.ru", api.creds.account: "D@iVeR", api.creds.password: "test123", log_requests: true, use_proxy: true>

Plugins: vault

• Qonfig.plugin(:vault)
• adds support for vault kv store, more info
• depends on vault gem (link) (tested on >= 0.1);
• provides .load_from_vault (works in .load_from_yaml manner (doc));
• provides .expose_vault (works in .expose_yaml manner (doc));

# 1) require external dependency
require 'vault'

# 2) Setup vault client

Vault.address = 'http://localhost:8200'
Vault.token = 'super-duper-token-here'

# 3) enable plugin
Qonfig.plugin(:vault)

# 3) use vault :)

Roadmap

• General:
  • documentation rework;
• Major:
  • support for Rails-like secrets;
  • support for persistent data storages (we want to store configs in multiple databases and files);
  • rails plugin;
  • support for pattern matching;
  • support for type checking (via rbs, typeprof, steep);
  • console utilities;
• Minor:
  • An ability to flag Qonfig::Configurable's config object as compacted (Qonfig::Compacted);
  • Instance-based behavior for Vault plugin, also use instance of Vault client instead of Singleton;
  • External validation class with an importing api for better custom validations;
  • Setting value changement trace (in anyway_config manner);
  • Instantiation and reloading callbacks;
  • File geneartors (.rb-files with a pre-filled code (and (maybe) with a pre-generated yaml/json/etc files));
  • Setting value changement subscriptions and callbacks;
  • CI rework (new configs, new steps, no strange dependencies);

Build

bin/rspec -w # test the core functionality and plugins
bin/rspec -n # test only the core functionality

Contributing

• Fork it ( https://github.com/0exp/qonfig/fork )
• Create your feature branch (git checkout -b feature/my-new-feature)
• Commit your changes (git commit -am '[my-new-featre] Add some feature')
• Push to the branch (git push origin feature/my-new-feature)
• Create new Pull Request

License

Released under MIT License.

Authors

Rustam Ibragimov