Class: Chalk::Config

Inherits:
Object
  • Object
show all
Includes:
Singleton
Defined in:
lib/chalk-config.rb,
lib/chalk-config/version.rb,
lib/chalk-config/errors.rb

Overview

The main class powering Chalk's configuration.

This is written using a wrapped Singleton, which makes testing possible (just stub Chalk::Config.instance to return a fresh instance) and helps hide implementation.

Defined Under Namespace

Classes: DisallowedEnvironment, Error, MissingEnvironment

Constant Summary collapse

VERSION = 
"0.2.1"

Class Method Summary collapse

Class Method Details

.assert_environment(environments) ⇒ Object

Raises if the current environment is not one of the whitelisted environments provided.

Generally useful if you have a dev-only codepath you want to be sure never activates in production.

Raises:



133
134
135
136
137
138
 
# File 'lib/chalk-config.rb', line 133

def self.assert_environment(environments)
  environments = [environments] if environments.kind_of?(String)
  return if environments.include?(environment)

  raise DisallowedEnvironment.new("Current environment #{environment.inspect} is not one of the allowed environments #{environments.inspect}")
end

.assert_not_environment(environments) ⇒ Object

Raises if the current environment is one of the blacklisted environments provided.

Generally useful if you have a dev-only codepath you want to be sure never activates in production.

Raises:



145
146
147
148
149
150
 
# File 'lib/chalk-config.rb', line 145

def self.assert_not_environment(environments)
  environments = [environments] if environments.kind_of?(String)
  return unless environments.include?(environment)

  raise DisallowedEnvironment.new("Current environment #{environment.inspect} is one of the disallowed environments #{environments.inspect}")
end

.environment ⇒ String

You should generally not take any action directly off this value. All codepath switches should be triggered off configuration keys, possibly with environment assertions to ensure safety.

Returns:

  • (String) —

    The current environment (default: 'default')



38
39
40
 
# File 'lib/chalk-config.rb', line 38

def self.environment
  instance.send(:environment)
end

.environment=(name) ⇒ String

Sets the current environment. All configuration is then reapplied in the order it was registered. This means you don't have to worry about setting your environment prior to registering config files.

Returns:

  • (String) —

    The current environment.



29
30
31
 
# File 'lib/chalk-config.rb', line 29

def self.environment=(name)
  instance.send(:environment=, name)
end

.register(filepath, options = {}) ⇒ Object

Register a given YAML file to be included in the global configuration.

The config will be loaded once (cached in memory) and be immediately deep-merged onto configatron. If you later run environment=, then all registered configs will be reapplied in the order they were loaded.

So for example, running Chalk::Config.register('/path/to/config.yaml') for a file with contents:

env1:
  key1: value1
  key2: value2

would yield configatron.env1.key1 == value1, configatron.env1.key2 == value2. Later registering a file with contents:

env1:
  key1: value3

would yield configatron.env1.key1 == value3, configatron.env1.key2 == value2.

Parameters:

  • filepath (String) —

    Absolute path to the config file

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :optional (Boolean) —

    If true, it's fine for the file to be missing, in which case this registration is discarded.

  • :raw (Boolean) —

    If true, the file doesn't have environment keys and should be splatted onto configatron directly. Otherwise, grab just the config under the appropriate environment key.

  • :nested (String) —

    What key to namespace all of this configuration under. (So nested: 'foo' would result in configuration available under configatron.foo.*.)



103
104
105
106
107
108
 
# File 'lib/chalk-config.rb', line 103

def self.register(filepath, options={})
  unless filepath.start_with?('/')
    raise ArgumentError.new("Register only accepts absolute paths, not #{filepath.inspect}. (This ensures that config is always correctly loaded rather than depending on your current directory. To avoid this error in the future, you may want to use a wrapper that expands paths based on a base directory.)")
  end
  instance.send(:register, filepath, options)
end

.register_raw(config) ⇒ Object

Register a given raw hash to be included in the global configuration.

This allows you to specify arbitrary configuration at runtime. It's generally not recommended that you use this method unless your configuration really can't be encoded in config files. A common example is configuration from environment variables (which might be something like the name of your service).

Like register, if you later run environment=, this configuration will be reapplied in the order it was registered.

Parameters:

  • config (Hash) —

    The raw configuration to be deep-merged into configatron.



124
125
126
 
# File 'lib/chalk-config.rb', line 124

def self.register_raw(config)
  instance.send(:register_raw, config)
end

.required_environments ⇒ Enumerable

Access the environments registered by required_environments=.

Returns:

  • (Enumerable) —

    The registered environments list (by default, nil)



58
59
60
 
# File 'lib/chalk-config.rb', line 58

def self.required_environments
  instance.send(:required_environments)
end

.required_environments=(environments) ⇒ Object

Specify the list of environments every configuration file must include.

It's generally recommended to set this in a wrapper library, and use that wrapper library in all your projects. This way you can be defensive, and have certainty no config file slips through without the requisite environment keys.

Parameters:

  • environments (Enumerable<String>) —

    The list of required environments.



51
52
53
 
# File 'lib/chalk-config.rb', line 51

def self.required_environments=(environments)
  instance.send(:required_environments=, environments)
end