ace-config

ace-config

Ruby gem created to simplify managing application configurations and enhance the development of other gems that require configuration management. It offers a simple interface for defining, setting, and retrieving configuration options with type validation, helping ensure configurations are correct and reliable.

• ace-config provides built-in support for importing and exporting configurations in JSON, YAML, and Hash formats, enhancing versatility.

• ace-config offers various built-in types like basic types, data structures, numeric types, and time types.

• ace-config supports infinite nested configurations and 'classy' access providing a flexible and powerful configuration management solution.

Features

• Simple Configuration Management: Easily define, set, and retrieve configuration options.
• Type Validation: Ensure configurations are correct with built-in type validation.
• Multiple Formats: Import and export configurations in JSON, YAML, and Hash formats.
• Nested Configurations: Support for infinite nested configurations for complex applications.
• Classy Access: Access configurations in a 'classy' manner for better organization and readability.
• Built-in Types: Utilize various built-in types including basic types, data structures, numeric types, and time types.
• Extensible: Easily extendable to accommodate custom configuration needs.

Table of Contents

• Installation
• Basic Usage
• Configuration Container Usage
• DSL Syntax
• Typing
  • Define Configuration Validation
  • Declaring Validation
  • Type Schema
  • Built-in Types
• Import:
  • Loading Configurations
  • Loading from a JSON String
  • Loading from a YAML File
• Export:
  • Exporting Configurations
  • to_h
  • to_json
  • to_yaml
• OSS
  • Development
  • Contributing
  • License
  • Code of Conduct

Installation

Install the gem and add to the application's Gemfile by executing:

bundle add ace-config

If bundler is not being used to manage dependencies, install the gem by executing:

gem install ace-config

Basic Usage

require 'ace_config'

module MyApp
  include AceConfig
end 

MyApp.configure :settings do
  config option: 42
  config.int typed_opt_one: 42
  config typed_opt_two: 4.2, type: :float  
end

MyApp.settings.option                 # => 42
MyApp.settings.typed_opt_one          # => 42
MyApp.settings.typed_opt_two          # => 4.2

Basic Syntax

MyApp.configure :settings do
  config option: 42
end

Namespacing

MyApp.configure :app do
  configure :lvl_one do
    config opt: 100
    configure :lvl_two do
      config opt: 200
      configure :lvl_three do
        config opt: 300
        configure :lvl_four do
          config opt: 400
          configure :lvl_five do
            config opt: 500
            # NOTE: as deep as you want
          end
        end
      end
    end
  end
end

MyApp.app.lvl_one.opt                                     # => 100
MyApp.app.lvl_one.lvl_two.opt                             # => 200
MyApp.app.lvl_one.lvl_two.lvl_three.opt                   # => 300
MyApp.app.lvl_one.lvl_two.lvl_three.lvl_four.opt          # => 400
MyApp.app.lvl_one.lvl_two.lvl_three.lvl_four.lvl_five.opt # => 500

Configure Type Validation

MyApp.configure :settings do
  config custom_typed_opt_one: '42', type: :float
end
# => AceConfig::SettingTypeError

Configuration Container Usage

require 'ace_config'

module MyGem
  include AceConfig
end 

Declare configurations

MyGem.configure :settings do
  config :option
  config.int :typed_opt_one
  config :typed_opt_two, type: Integer
  # NOTE: declare nested namespace with configure <symbol arg>
  configure :nested do
    config :option
  end
end

Define configurations

MyGem.settings do 
  config option: 1
  config typed_opt_one: 2
  config typed_opt_two: 3 
  # NOTE: access namespace via <.dot_access> 
  config.nested do 
    config option: 4
  end
end

Define with DSL Syntax

MyGem.settings do 
  option 1
  typed_opt_one 2
  typed_opt_two 3 
  # NOTE: access namespace via <block> 
  nested do 
    option 1
  end
end

Get configurations

MyGem.settings.option        # => 1
MyGem.settings.typed_opt_one # => 2
MyGem.settings.typed_opt_two # => 3
MyGem.settings.nested.option # => 4

Define Configuration Type Validation

MyGem.settings do 
  config.typed_opt_two: '1'
end 
# => AceConfig::SettingTypeError

MyGem.settings do 
  typed_opt_two '1'
end 
# => AceConfig::SettingTypeError

Loading Configuration Data

The AceConfig module allows you to load configuration data from various sources, including YAML and JSON. Below are the details for each option.

• json (String)
• yaml (String)
• hash (Hash)
• schema (Hash) (Optional) See: Type Schema and Built-in Types

Loading from a JSON String

You can load configuration data from a JSON string by passing the json option to the configure method.

Parameters

• json (String): A JSON string containing the configuration data.
• schema (Hash) (Optional): A hash representing the type schema for the configuration data.

Error Handling

• If the JSON format is invalid, a LoadDataError will be raised with the message "Invalid JSON format".

Example 1

MyGem.configure(:settings, json: '{"opt_one":1,"opt_two":2}').settings
# => #<MyGem::Setting:0x00007f8c1c0b2a80 @options={:opt_one=>1, :opt_two=>2}>

Example 2

MyGem.configure(:settings, json: '{"opt_one":1,"opt_two":2}', schema: { opt_one: :int, opt_two: :str })
# => AceConfig::SettingTypeError: Expected: <str>. Given: 2 which is <Integer> class.

Example 3

MyGem.configure(:settings, json: '{"opt_one":1,"opt_two":2}', schema: { opt_one: :int, opt_two: :int })

MyGem.settings do 
  opt_one 1
  opt_two "2"
end
# => AceConfig::SettingTypeError: Expected: <intstr>. Given: \"2\" which is <String> class.

Loading from a YAML File

You can also load configuration data from a YAML file by passing the yaml option to the configure method.

Parameters

• yaml (String): A file path to a YAML file containing the configuration data.
• schema (Hash) (Optional): A hash representing the type schema for the configuration data.

Error Handling

• If the specified YAML file is not found, a LoadDataError will be raised with the message "YAML file not found".

YAML File

# settings.yml

opt_one: 1
opt_two: 2

Example 1

MyGem.configure :settings, yaml: 'settings.yml' 
# => #<MyGem::Setting:0x00006f8c1c0b2a80 @options={:opt_one=>1, :opt_two=>2}>

Example 2

MyGem.configure :settings, yaml: 'settings.yml', schema: { opt_one: :int, opt_two: :str }
# => AceConfig::SettingTypeError: Expected: <str>. Given: 2 which is <Integer> class.

Example 3

MyGem.configure :settings, yaml: 'settings.yml', schema: { opt_one: :int, opt_two: :int }

MyGem.settings do 
  opt_one 1
  opt_two "2"
end
# => AceConfig::SettingTypeError: Expected: <intstr>. Given: \"2\" which is <String> class.

Exporting Configuration Data

You can dump the configuration data in various formats using the following methods:

to_h

MyGem.configure :settings do
  config opt_one: 1
  config opt_two: 2
end

MyGem.settings.to_json # => '{"opt_one":1,"opt_two":2}'

to_json

MyGem.configure :settings do
  config opt_one: 1
  config opt_two: 2
end

MyGem.settings.to_json # => '{"opt_one":1,"opt_two":2}'

to_yaml

MyGem.configure :settings do
  config opt_one: 1
  config opt_two: 2
end

MyGem.settings.to_yaml # => "---\nopt_one: 1\nopt_two: 2\n"

type_schema

MyGem.configure :settings do
  config.int opt_one: 1
  config.str opt_two: "2"
end

MyGem.settings.type_schema # => {:opt_one=>:int, :opt_two=>:str}

Built-in Types

Base Types

:int  => Integer
:str  => String
:sym  => Symbol
:null => NilClass
:any  => Object
:true_class  => TrueClass
:false_class => FalseClass

Data Structures

:hash  => Hash
:array => Array

Numeric

:big_decimal => BigDecimal,
:float       => Float,
:complex     => Complex,
:rational    => Rational,

Time

:date      => Date,
:date_time => DateTime,
:time      => Time,

Composite

:bool       => [TrueClass, FalseClass],
:numeric    => [Integer, Float, BigDecimal],
:kernel_num => [Integer, Float, BigDecimal, Complex, Rational],
:chrono     => [Date, DateTime, Time]

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/yurigitsu/ace-config. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the AceConfig project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.