Project

dotcfg

0.0
No release in over 3 years
Low commit activity in last 3 years
JSON and YAML config serialization and persistence
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

~> 2.5
~> 0.1
 Project Readme

CI Status Gem Version Code Climate

dotcfg

dotcfg is a simple, intuitive way for your app to store configuration data on the filesystem -- ideally within the user's home directory, presumably in a dotfile. If your config data can be represented by a Hash, then dotcfg can easily serialize and persist that data between runs.

Serialization Formats

dotcfg currently understands JSON and YAML, defaulting to YAML.

Usage

Install

3 options:

  • git clone
  • gem install
  • Bundler Gemfile

git clone

Clone the repo, then cd dotcfg

Optional, if you use direnv and want to use Nix flakes to load a dev env: direnv allow

From here, use -I lib with calls to e.g. ruby or irb to make dotcfg available without having the gem installed. e.g.

$ irb -Ilib -rdotcfg

irb(main):001:0> CFG = DotCfg.new 'example.cfg'
=>
#<DotCfg:0x00007f75d06b83a0
...
irb(main):002:0> CFG[:does_not_exist]
=> nil
irb(main):003:0> CFG['hello'] = 'world'
=> "world"
irb(main):004:0> CFG['hello']
=> "world"
irb(main):005:0>

gem install

gem install dotcfg

Bundler Gemfile

Add to your Gemfile:

gem 'dotcfg', '~> 1.0'

Usage

require 'dotcfg'

# if file exists, read and load it; otherwise initialize the file
CFG = DotCfg.new '~/.example'

CFG[:does_not_exist]
# => nil

CFG['hello'] = 'world'
CFG['hello']
# => "world"

puts CFG.pretty
# ---
# hello: world

CFG.serialize
# => "---\nhello: world\n"

CFG.save
# write to ~/.example

Use JSON

require 'dotcfg'

# if file exists, read and load it; otherwise initialize the file
CFG = DotCfg.new '~/.example', :json

# ...

puts CFG.pretty
# {
#   "hello": "world"
# }

CFG.serialize
# => "{\"hello\":\"world\"}"

# ...

Details

Symbols and Strings

When JSON consumes symbols, it emits strings. So if you want to use JSON, use strings rather than symbols for your config items. YAML cycles strings and symbols independently, so stick to one or the other.

The Simplest Thing That Could Possibly Work

PROCS = {
  json: {
    to: proc { |data| data.to_json },
    from: proc { |json| JSON.parse json },
    pretty: proc { |data| JSON.pretty_generate data },
  },
  yaml: {
    to: proc { |data| data.to_yaml },
    from: proc { |yaml| YAML.load yaml },
    pretty: proc { |data| data.to_yaml },
  },
}