Project

ace-config

0.0
The project is in a healthy, maintained state
ace-configyurigitsu/ace-configHomepageDocumentationSource CodeBug TrackerWiki
Managing, configurations with type validation, configirations load and export support.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Popularity
Downloads
179
Stars
1
Forks
0
Watchers
1
 Releases
Current version
0.1.0.beta.rc1b
Total releases
1
First release
2024-09-29
Latest release
2024-09-29
 Pull Requests
Open Pull Requests
0
Closed Pull Requests
0
Merged Pull Requests
7
Pull Request Acceptance Rate
100%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2024-09-13
Reverse Dependencies
0

 Dependencies

Runtime

bigdecimal
~> 3.0
 Project Readme

ace-config

ace-config is a 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.

Table of Contents

  • Installation
  • Basic Usage
  • Namespacing
  • Configuration Container Usage
  • Typing
    • Set Configuration Validation
    • Declaring Validation
    • Type Schema
    • Built-in Types
  • Loading Configuration Data
    • Loading from a JSON String
    • Loading from a YAML File
  • Exporting Configuration Data
    • 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
  extend AceConfig::Configuration
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

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
  extend AceConfig::Configuration
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 <symbol arg>
  configure :nested do
    config :option
  end
end

Set configurations

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

Get configurations

MyGem.settings.option        # => 1
MyGem.settings.typed_opt_one # => 1
MyGem.settings.typed_opt_two # => 1

Set Configuration Type Validation

MyGem.settings do 
  config.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.

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.

Error Handling

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

Example

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

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.

Error Handling

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

Example

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

Exporting Configuration Data

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

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}

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"

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.