README.md

fig_tree

Create nested, easy-to-use configuration for your gem or application, which also allows defining lists of configuration objects that can be fetched later on. Loosely similar to the dry-configurable gem but with several advantages.

Installation

Add this line to your application's Gemfile:

gem 'fig_tree'

And then execute:

$ bundle

Or install it yourself as:

$ gem install fig_tree

Versioning

We use a version of semver for this gem. Any change in previous behavior (something works differently or something old no longer works) is denoted with a bump in the minor version (0.4 -> 0.5). Patch versions are for bugfixes or new functionality which does not affect existing code. You should be locking your Gemfile to the minor version:

gem 'fig_tree', '0.0.1'

Usage

FigTree allows you to define the shape of your configuration and then configure it in a number of elegant ways.

Defining configurations

FigTree is designed to be included in a class that has a configuration. Here's an example:

class FileCreator
  include FigTree
  
  define_settings do
    setting :enabled, true # default is true
    setting :file_owner # default is nil
    setting :logger, default_proc: proc { Rails.logger } # execute the proc to figure out the default value
    setting :allowed_directories, ['app/lib', 'app/'] # set default to any object
    setting(:after_create, proc { }) # default is a proc that does nothing
  end  
end

You can then configure your class in a nice DSL:

FileCreator.configure do
  enabled false
  file_owner "john.smith"
  after_create do
    puts "Done!"
  end
end

If you like, you can pass the config object as an argument (the = are optional):

FileCreator.configure do |config|
  config.enabled = false 
  config.file_owner = "john.smith"
  config.after_create do
    puts "Done!"
  end
end

Or you can just modify it directly:

FileCreator.config.enabled = false

You can reference the settings quite easily:

FileCreator.config.file_owner # john.smith
FileCreator.config.logger # Rails.logger, even if it didn't exist at the time the configuration
                          # was defined
FileCreator.config.after_create.call # puts "Done!"

You can call configure multiple times without issue. Each configure call will add onto the previous one.

Nested configurations

You can create configuration namespaces by simply passing a block to the setting method:

class FileCreator
  include FigTree
  
  define_settings do
    setting :file_options do
      setting :permissions do
        setting :user_read
        setting :user_write
      end
      setting :group_name
    end
  end  
end

# configuring

FileCreator.configure do
  # you can nest your configuration like so:
  file_options do
    group_name "wheel"
  end
  # or you can namespace them:
  file_options.permissions.user_read = true
end

# reading works the same way
FileCreator.config.file_options.group_name # wheel

Defining "setting lists"

FigTree allows you to define the structure of a configurable object which you can create multiples of. An example might be a number of message consumers, or a number of file processors.

class Consumers
  include FigTree
  
  define_settings do
    setting_object :consumer do
      setting :name
      setting :topic
      setting :broker do
        setting :timeout, 60.seconds
      end
    end
  end  
end

# configuring

Consumers.configure do
  consumer do
    name "users"
    setting "Users.User"
    broker.timeout 5.seconds
  end
end

# reading uses the special `consumer_objects` method to retrieve the setting objects with the name
# "consumer"
timeouts = FileCreator.config.consumer_objects.map { |c| c.broker.timeout }

Deprecations

You can set up a deprecation of an old config path to a new one thusly:

FileCreator.define_settings do
  deprecate 'user_read', 'file_options.user_read'
end

Users can then still use the old config, which will be automatically mapped to the new one:

FileCreator.user_read = true
# will set `file_options.user_read` instead, and print out a deprecation warning:
# config.user_read is deprecated - use config.file_options.user_read

Testing

You can use the with_config method to test your code with specific config values that get reset after the block is done executing:

FileCreator.with_config('file_options.group_name' => 'root') do
  # test this code
end
# file_options.group_name will be set back to the original value afterwards

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/flipp-oss/fig_tree .

Linting

FigTree uses Rubocop to lint the code. Please run Rubocop on your code before submitting a PR.

---

Sponsored by