{"id":13483599,"url":"https://github.com/markbates/configatron","last_synced_at":"2025-05-14T20:10:39.313Z","repository":{"id":405392,"uuid":"24053","full_name":"markbates/configatron","owner":"markbates","description":"A super cool, simple, and feature rich configuration system for Ruby apps.","archived":false,"fork":false,"pushed_at":"2024-05-12T20:40:42.000Z","size":302,"stargazers_count":598,"open_issues_count":13,"forks_count":71,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-13T16:01:47.108Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.metabates.com","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markbates.png","metadata":{"files":{"readme":"README.md","changelog":"History.txt","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2008-06-10T18:28:42.000Z","updated_at":"2025-03-26T07:52:14.000Z","dependencies_parsed_at":"2022-07-07T17:51:16.612Z","dependency_job_id":"f93029e2-d470-4998-9672-fe0ae176a03e","html_url":"https://github.com/markbates/configatron","commit_stats":{"total_commits":273,"total_committers":30,"mean_commits":9.1,"dds":0.6263736263736264,"last_synced_commit":"30071ef081d431e1ca92e54ab973c73fcca34224"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markbates%2Fconfigatron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markbates%2Fconfigatron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markbates%2Fconfigatron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markbates%2Fconfigatron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markbates","download_url":"https://codeload.github.com/markbates/configatron/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254219374,"owners_count":22034397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T17:01:13.203Z","updated_at":"2025-05-14T20:10:39.292Z","avatar_url":"https://github.com/markbates.png","language":"Ruby","readme":"# Configatron\n[![Build Status](https://travis-ci.org/markbates/configatron.png)](https://travis-ci.org/markbates/configatron) [![Code Climate](https://codeclimate.com/github/markbates/configatron.png)](https://codeclimate.com/github/markbates/configatron)\n\nConfigatron makes configuring your applications and scripts incredibly easy. No longer is a there a need to use constants or global variables. Now you can use a simple and painless system to configure your life. And, because it's all Ruby, you can do any crazy thing you would like to!\n\nOne of the more important changes to V3 is that it now resembles more a `Hash` style interface. You can use `[]`, `fetch`, `each`, etc... Actually the hash notation is a bit more robust since the dot notation won't work for a few property names (a few public methods from `Configatron::Store` itself).\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'configatron'\n```\n\nAnd then execute:\n\n```bash\n$ bundle\n```\n\nOr install it yourself as:\n\n```bash\n$ gem install configatron --pre\n```\n\n## Usage\n\nOnce installed you just need to require it:\n\n```ruby\nrequire 'configatron'\n```\n\n### Simple\n\n```ruby\nconfigatron.email = 'me@example.com'\nconfigatron.database.url = \"postgres://localhost/foo\"\n```\n\nNow, anywhere in your code you can do the following:\n\n```ruby\nconfigatron.email # =\u003e \"me@example.com\"\nconfigatron.database.url # =\u003e \"postgres://localhost/foo\"\n```\n\nVoila! Simple as can be.\n\nNow you're saying, what if I want to have a 'default' set of options, but then override them later, based on other information? Simple again. Let's use our above example. We've configured our `database.url` option to be `postgres://localhost/foo`. The problem with that is that is our production database url, not our development url. Fair enough, all you have to do is redeclare it:\n\n```ruby\nconfigatron.database.url = \"postgres://localhost/foo_development\"\n```\n\nbecomes:\n\n```ruby\nconfigatron.email # =\u003e \"me@example.com\"\nconfigatron.database.url # =\u003e \"postgres://localhost/foo_development\"\n```\n\nNotice how our other configuration parameters haven't changed? Cool, eh?\n\n### Hash/YAML\n\nYou can configure Configatron from a hash as well (this is particularly useful if you'd like to have configuration files):\n\n```ruby\nconfigatron.configure_from_hash(email: {pop: {address: 'pop.example.com', port: 110}}, smtp: {address: 'smtp.example.com'})\n\nconfigatron.email.pop.address # =\u003e 'pop.example.com'\nconfigatron.email.pop.port # =\u003e 110\n# and so on...\n```\n\n### Method vs hash access\n\nAs a note, method (`configatron.foo`) access will be shadowed by public methods defined on the configatron object. (The configatron object descends from [`BasicObject`](http://apidock.com/ruby/BasicObject) and adds a few methods to resemble the `Hash` API and to play nice with `puts`, so it should have a pretty bare set of methods.)\n\nIf you need to use keys that are themselves method names, you can just use hash access (`configatron['foo']`).\n\n### Namespaces\n\nThe question that should be on your lips is what I need to have namespaced configuration parameters. It's easy! Configatron allows you to create namespaces.\n\n```ruby\nconfigatron.website_url = \"http://www.example.com\"\nconfigatron.email.pop.address = \"pop.example.com\"\nconfigatron.email.pop.port = 110\nconfigatron.email.smtp.address = \"smtp.example.com\"\nconfigatron.email.smtp.port = 25\n\nconfigatron.to_h # =\u003e {:website_url=\u003e\"http://www.example.com\", :email=\u003e{:pop=\u003e{:address=\u003e\"pop.example.com\", :port=\u003e110}, :smtp=\u003e{:address=\u003e\"smtp.example.com\", :port=\u003e25}}}\n```\n\nConfigatron allows you to nest namespaces to your hearts content! Just keep going, it's that easy.\n\nOf course you can update a single parameter n levels deep as well:\n\n```ruby\nconfigatron.email.pop.address = \"pop2.example.com\"\n\nconfigatron.email.pop.address # =\u003e \"pop2.example.com\"\nconfigatron.email.smtp.address # =\u003e \"smtp.example.com\"\n```\n\nConfigatron will also let you use a block to clean up your configuration. For example the following two ways of setting values are equivalent:\n\n```ruby\nconfigatron.email.pop.address = \"pop.example.com\"\nconfigatron.email.pop.port = 110\n\nconfigatron.email.pop do |pop|\n  pop.address = \"pop.example.com\"\n  pop.port = 110\nend\n```\n\n### Temp Configurations\n\nSometimes in testing, or other situations, you want to temporarily change some settings. You can do this with the `temp` method (only available on the top-level configatron `RootStore`):\n\n```ruby\nconfigatron.one = 1\nconfigatron.letters.a = 'A'\nconfigatron.letters.b = 'B'\nconfigatron.temp do\n  configatron.letters.b = 'bb'\n  configatron.letters.c = 'c'\n  configatron.one # =\u003e 1\n  configatron.letters.a # =\u003e 'A'\n  configatron.letters.b # =\u003e 'bb'\n  configatron.letters.c # =\u003e 'c'\nend\nconfigatron.one # =\u003e 1\nconfigatron.letters.a # =\u003e 'A'\nconfigatron.letters.b # =\u003e 'B'\nconfigatron.letters.c # =\u003e {}\n```\n\n### Delayed and Dynamic Configurations\n\nThere are times when you want to refer to one configuration setting in another configuration setting. Let's look at a fairly contrived example:\n\n```ruby\nconfigatron.memcached.servers = ['127.0.0.1:11211']\nconfigatron.page_caching.servers = configatron.memcached.servers\nconfigatron.object_caching.servers = configatron.memcached.servers\n\nif Rails.env == 'production'\n  configatron.memcached.servers = ['192.168.0.1:11211']\n  configatron.page_caching.servers = configatron.memcached.servers\n  configatron.object_caching.servers = configatron.memcached.servers\nelsif Rails.env == 'staging'\n  configatron.memcached.servers = ['192.168.0.2:11211']\n  configatron.page_caching.servers = configatron.memcached.servers\n  configatron.object_caching.servers = configatron.memcached.servers\nend\n```\n\nNow, we could've written that slightly differently, but it helps to illustrate the point. With Configatron you can create `Delayed` and `Dynamic` settings.\n\n#### Delayed\n\nWith `Delayed` settings execution of the setting doesn't happen until the first time it is executed.\n\n```ruby\nconfigatron.memcached.servers = ['127.0.0.1:11211']\nconfigatron.page_caching.servers = Configatron::Delayed.new {configatron.memcached.servers}\nconfigatron.object_caching.servers = Configatron::Delayed.new {configatron.memcached.servers}\n\nif Rails.env == 'production'\n  configatron.memcached.servers = ['192.168.0.1:11211']\nelsif Rails.env == 'staging'\n  configatron.memcached.servers = ['192.168.0.2:11211']\nend\n```\n\nExecution occurs once and after that the result of that execution is returned. So in our case the first time someone calls the setting `configatron.page_caching.servers` it will find the `configatron.memcached.servers` setting and return that. After that point if the `configatron.memcached.servers` setting is changed, the original settings are returned by `configatron.page_caching.servers`.\n\n#### Dynamic\n\n`Dynamic` settings are very similar to `Delayed` settings, but with one big difference. Every time you call a `Dynamic` setting is executed. Take this example:\n\n```ruby\nconfigatron.current.time = Configatron::Dynamic.new {Time.now}\n```\n\nEach time you call `configatron.current.time` it will return a new value to you. While this seems a bit useless, it is pretty useful if you have ever changing configurations.\n\n### Reseting Configurations\n\nIn some testing scenarios, it can be helpful to restore Configatron to its default state. This can be done with:\n\n```ruby\nconfigatron.reset!\n``` \n\n### Checking keys\n\nEven if parameters haven't been set, you can still call them, but you'll get a `Configatron::Store` object back. You can use `.has_key?` to determine if a key already exists.\n\n```ruby\nconfigatron.i.dont.has_key?(:exist) # =\u003e false\n```\n\n#### (key)!\n\nYou can also append a `!` to the end of any key. If the key exists it will return it, otherwise it will raise a `Configatron::UndefinedKeyError`.\n\n``` ruby\nconfigatron.a.b = 'B'\nconfigatron.a.b # =\u003e 'B'\nconfigatron.a.b! # =\u003e 'B'\nconfigatron.a.b.c! # =\u003e raise Configratron::UndefinedKeyError\n```\n\n### Kernel\n\nThe `configatron` \"helper\" method is stored in the `Kernel` module. You can opt-out of this global monkey-patching by requiring `configatron/core` rather than `configatron`. You'll have to set up your own `Configatron::RootStore` object.\n\nExample:\n\n```ruby\nrequire 'configatron/core'\n\nstore = Configatron::RootStore.new\nstore.foo = 'FOO'\n\nstore.to_h #= {foo: 'FOO'}\n```\n\n### Locking\n\nOnce you have setup all of your configurations you can call the `lock!` method to lock your settings and raise an error should anyone try to change settings or access an unset setting later.\n\nExample:\n\n```ruby\nconfigatron.foo = 'FOO'\nconfigatron.lock!\n\nconfigatron.foo # =\u003e 'FOO'\n\nconfigatron.bar # =\u003e raises Configatron::UndefinedKeyError\nconfigatron.bar = 'BAR' # =\u003e raises Configatron::LockedError\n```\n\n## Rails\n\nConfigatron works great with Rails. Use the built-in generate to generate an initializer file and a series of environment files for you to use to configure your applications.\n\n``` bash\n$ rails generate configatron:install\n```\n\nConfigatron will read in the `config/configatron/defaults.rb` file first and then the environment specific file, such as `config/configatron/development.rb`. Settings in the environment file will merge into and replace the settings in the `defaults.rb` file.\n\n### Example\n\n```ruby\n# config/configatron/defaults.rb\nconfigatron.letters.a = 'A'\nconfigatron.letters.b = 'B'\n```\n\n```ruby\n# config/configatron/development.rb\nconfigatron.letters.b = 'BB'\nconfigatron.letters.c = 'C'\n```\n\n```ruby\nconfigatron.to_h # =\u003e {:letters=\u003e{:a=\u003e\"A\", :b=\u003e\"BB\", :c=\u003e\"C\"}}\n```\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Write Tests!\n4. Commit your changes (`git commit -am 'Add some feature'`)\n5. Push to the branch (`git push origin my-new-feature`)\n6. Create new Pull Request\n\n## Contributors\n\n* Mark Bates\n* Greg Brockman\n* Kurtis Rainbolt-Greene\n* Rob Sanheim\n* Jérémy Lecour\n* Cody Maggard\n* Jean-Denis Vauguet\n* chatgris\n* Simon Menke\n* Mat Brown\n* Torsten Schönebaum\n* Gleb Pomykalov\n* Casper Gripenberg\n* Artiom Diomin\n* mattelacchiato\n* Dan Pickett\n* Tim Riley\n* Rick Fletcher\n* Jose Antonio Pio\n* Brandon Dimcheff\n* joe miller\n* Josh Nichols\n","funding_links":[],"categories":["Configuration","Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkbates%2Fconfigatron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkbates%2Fconfigatron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkbates%2Fconfigatron/lists"}