{"id":29016574,"url":"https://github.com/chef/mixlib-config","last_synced_at":"2025-06-25T22:30:41.476Z","repository":{"id":520577,"uuid":"148848","full_name":"chef/mixlib-config","owner":"chef","description":"A simple class based Config mechanism, similar to the one found in Chef","archived":false,"fork":false,"pushed_at":"2025-05-13T22:45:22.000Z","size":355,"stargazers_count":54,"open_issues_count":8,"forks_count":37,"subscribers_count":74,"default_branch":"main","last_synced_at":"2025-06-07T00:32:21.964Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.chef.io","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chef.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2009-03-12T01:12:18.000Z","updated_at":"2025-05-13T22:45:25.000Z","dependencies_parsed_at":"2024-06-18T13:41:50.559Z","dependency_job_id":"555a8edd-0132-4579-b18e-63db86b54379","html_url":"https://github.com/chef/mixlib-config","commit_stats":{"total_commits":264,"total_committers":38,"mean_commits":6.947368421052632,"dds":0.8636363636363636,"last_synced_commit":"39e44bcf2634bd6d7e42b436d3ffdb556f700ffc"},"previous_names":["opscode/mixlib-config"],"tags_count":75,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fmixlib-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fmixlib-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fmixlib-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fmixlib-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chef","download_url":"https://codeload.github.com/chef/mixlib-config/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fmixlib-config/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259186269,"owners_count":22818531,"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":"2025-06-25T22:30:39.424Z","updated_at":"2025-06-25T22:30:41.433Z","avatar_url":"https://github.com/chef.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mixlib::Config\n\n[![Gem Version](https://badge.fury.io/rb/mixlib-config.svg)](https://badge.fury.io/rb/mixlib-config)\n[![Build status](https://badge.buildkite.com/038bff14d03b1f91115dbb444ca81b387bd23855413f017fc0.svg?branch=master)](https://buildkite.com/chef-oss/chef-mixlib-config-master-verify)\n\n**Umbrella Project**: [Chef Foundation](https://github.com/chef/chef-oss-practices/blob/master/projects/chef-foundation.md)\n\n**Project State**: [Active](https://github.com/chef/chef-oss-practices/blob/master/repo-management/repo-states.md#active)\n\n**Issues [Response Time Maximum](https://github.com/chef/chef-oss-practices/blob/master/repo-management/repo-states.md)**: 14 days\n\n**Pull Request [Response Time Maximum](https://github.com/chef/chef-oss-practices/blob/master/repo-management/repo-states.md)**: 14 days\n\nMixlib::Config provides a class-based configuration object, as used in Chef. To use in your project:\n\n```ruby\n  require 'mixlib/config'\n\n  module MyConfig\n    extend Mixlib::Config\n    config_strict_mode true\n    default :first_value, 'something'\n    default :other_value, 'something_else'\n  end\n```\n\nYou can use this to provide a configuration file for a user. For example, if you do this:\n\n```ruby\n  MyConfig.from_file('~/.myconfig.rb')\n```\n\nA user could write a Ruby config file that looked like this:\n\n```ruby\n  first_value 'hi'\n  second_value \"#{first_value}!  10 times 10 is #{10*10}!\"\n```\n\nInside your app, you can check configuration values with this syntax:\n\n```ruby\n  MyConfig.first_value   # returns 'something'\n  MyConfig[:first_value] # returns 'something'\n```\n\nAnd you can modify configuration values with this syntax:\n\n```ruby\n  MyConfig.first_value('foobar')    # sets first_value to 'foobar'\n  MyConfig.first_value = 'foobar'   # sets first_value to 'foobar'\n  MyConfig[:first_value] = 'foobar' # sets first_value to 'foobar'\n```\n\nIf you prefer to allow your users to pass in configuration via YAML, JSON or TOML files, `mixlib-config` supports that too!\n\n```ruby\n  MyConfig.from_file('~/.myconfig.yml')\n  MyConfig.from_file('~/.myconfig.json')\n  MyConfig.from_file('~/.myconfig.toml')\n```\n\nThis way, a user could write a YAML config file that looked like this:\n\n```yaml\n---\nfirst_value: 'hi'\nsecond_value: 'goodbye'\n```\n\nor a JSON file that looks like this:\n\n```json\n{\n  \"first_value\": \"hi\",\n  \"second_value\": \"goodbye\"\n}\n```\n\nor a TOML file that looks like this:\n\n```toml\nfirst_value = \"hi\"\nsecond_value = \"goodbye\"\n```\n\nPlease note: There is an inherent limitation in the logic you can do with YAML and JSON file. At this time, `mixlib-config` does not support ERB or other logic in YAML or JSON config (read \"static content only\").\n\n## Nested Configuration\n\nOften you want to be able to group configuration options to provide a common context. Mixlib::Config supports this thus:\n\n```ruby\n  require 'mixlib/config'\n\n  module MyConfig\n    extend Mixlib::Config\n    config_context :logging do\n      default :base_filename, 'mylog'\n      default :max_log_files, 10\n    end\n  end\n```\n\nThe user can write their config file in one of three formats:\n\n### Method Style\n\n```ruby\nlogging.base_filename 'superlog'\nlogging.max_log_files 2\n```\n\n### Block Style\n\nUsing this format the block is executed in the context, so all configurables on that context is directly accessible\n\n```ruby\nlogging do\n  base_filename 'superlog'\n  max_log_files 2\nend\n```\n\n### Block with Argument Style\n\nUsing this format the context is given to the block as an argument\n\n```ruby\nlogging do |l|\n  l.base_filename = 'superlog'\n  l.max_log_files = 2\nend\n```\n\nYou can access these variables thus:\n\n```ruby\n  MyConfig.logging.base_filename\n  MyConfig[:logging][:max_log_files]\n```\n\n### Lists of Contexts\nFor use cases where you need to be able to specify a list of things with identical configuration\nyou can define a `context_config_list` like so:\n\n```ruby\n  require 'mixlib/config'\n\n  module MyConfig\n    extend Mixlib::Config\n\n    # The first argument is the plural word for your item, the second is the singular\n    config_context_list :apples, :apple do\n      default :species\n      default :color, 'red'\n      default :crispness, 10\n    end\n  end\n```\n\nWith this definition every time the `apple` is called within the config file it\nwill create a new item that can be configured with a block like so:\n\n```ruby\napple do\n  species 'Royal Gala'\nend\napple do\n  species 'Granny Smith'\n  color 'green'\nend\n```\n\nYou can then iterate over the defined values in code:\n\n```ruby\nMyConfig.apples.each do |apple|\n  puts \"#{apple.species} are #{apple.color}\"\nend\n\n# =\u003e Royal Gala are red\n# =\u003e Granny Smith are green\n```\n\n_**Note**: When using the config context lists they must use the [block style](#block-style) or [block with argument style](#block-with-argument-style)_\n\n### Hashes of Contexts\nFor use cases where you need to be able to specify a list of things with identical configuration\nthat are keyed to a specific value, you can define a `context_config_hash` like so:\n\n```ruby\n  require 'mixlib/config'\n\n  module MyConfig\n    extend Mixlib::Config\n\n    # The first argument is the plural word for your item, the second is the singular\n    config_context_hash :apples, :apple do\n      default :species\n      default :color, 'red'\n      default :crispness, 10\n    end\n  end\n```\n\nThis can then be used in the config file like so:\n\n```ruby\napple 'Royal Gala' do\n  species 'Royal Gala'\nend\napple 'Granny Smith' do\n  species 'Granny Smith'\n  color 'green'\nend\n\n# You can also reopen a context to edit a value\napple 'Royal Gala' do\n  crispness 3\nend\n```\n\nYou can then iterate over the defined values in code:\n\n```ruby\nMyConfig.apples.each do |key, apple|\n  puts \"#{key} =\u003e #{apple.species} are #{apple.color}\"\nend\n\n# =\u003e Royal Gala =\u003e Royal Gala are red\n# =\u003e Granny Smith =\u003e Granny Smith are green\n```\n\n_**Note**: When using the config context hashes they must use the [block style](#block-style) or [block with argument style](#block-with-argument-style)_\n\n## Default Values\n\nMixlib::Config has a powerful default value facility. In addition to being able to specify explicit default values, you can even specify Ruby code blocks that will run if the config value is not set. This can allow you to build options whose values are based on other options.\n\n```ruby\n  require 'mixlib/config'\n\n  module MyConfig\n    extend Mixlib::Config\n    config_strict_mode true\n    default :verbosity, 1\n    default(:print_network_requests) { verbosity \u003e= 2 }\n    default(:print_ridiculously_unimportant_stuff) { verbosity \u003e= 10 }\n  end\n```\n\nThis allows the user to quickly specify a number of values with one default, while still allowing them to override anything:\n\n```ruby\n  verbosity 5\n  print_network_requests false\n```\n\nYou can also inspect if the values are still their defaults or not:\n\n```ruby\nMyConfig.is_default?(:verbosity)  # == true\nMyConfig[:verbosity] = 5\nMyConfig.is_default?(:verbosity)  # == false\nMyConfig[:verbosity] = 1\nMyConfig.is_default?(:verbosity)  # == true\n```\n\nTrying to call `is_default?` on a config context or a config which does not have a declared default is an error and will raise.\n\n## Strict Mode\n\nMisspellings are a common configuration problem, and Mixlib::Config has an answer: `config_strict_mode`. Setting `config_strict_mode` to `true` will cause any misspelled or incorrect configuration option references to throw `Mixlib::Config::UnknownConfigOptionError`.\n\n```ruby\n  require 'mixlib/config'\n\n  module MyConfig\n    extend Mixlib::Config\n    config_strict_mode true\n    default :filename, '~/output.txt'\n    configurable :server_url # configurable declares an option with no default value\n    config_context :logging do\n      default :base_name, 'log'\n      default :max_files, 20\n    end\n  end\n```\n\nNow if a user types `fielname \"~/output-mine.txt\"` in their configuration file, it will toss an exception telling them that the option \"fielname\" is unknown. If you do not set config_strict_mode, the fielname option will be merrily set and the application just won't know about it.\n\nDifferent config_contexts can have different strict modes; but they inherit the strict mode of their parent if you don't explicitly set it. So setting it once at the top level is sufficient. In the above example, `logging.base_naem 'mylog'` will raise an error.\n\nIn conclusion: _always set config_strict_mode to true_. You know you want to.\n\n## Testing and Reset\n\nTesting your application with different sets of arguments can by simplified with `reset`. Call `MyConfig.reset` before each test and all configuration will be reset to its default value. There's no need to explicitly unset all your options between each run.\n\nNOTE: if you have arrays of arrays, or other deep nesting, we suggest you use code blocks to set up your default values (`default(:option) { [ [ 1, 2 ], [ 3, 4 ] ] }`). Deep children will not always be reset to their default values.\n\nEnjoy!\n\n## Contributing\n\nFor information on contributing to this project see \u003chttps://github.com/chef/chef/blob/master/CONTRIBUTING.md\u003e\n\n## License\n\n- Copyright:: Copyright (c) 2009-2019 Chef Software, Inc.\n- License:: Apache License, Version 2.0\n\n```text\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchef%2Fmixlib-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchef%2Fmixlib-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchef%2Fmixlib-config/lists"}