English
资源说明：Configuration object and YAML-based storage for Rails apps
Configoro
=========
**Environment-specific configuration data for Rails apps**
| **Author** | Tim Morgan |
| **License** | Released under the MIT license. |
About
-----
Pretty much every Rails app out there needs to store environment-specific
configuration data: API URLs, Memcache settings, AWS keys, etc. The "quick fix"
approach is usually to dump this information in, e.g., `development.rb` as
constants, like `MAILCHIMP_API_URL`. This creates cluttered and unorganized
environment files.
Configoro creates a configuration object that can be accessed as both a hash and
struct. It stores common configuration data merged with environment-specific
data.
The data is read from YAML files stored alongside the environment files.
Installation
------------
To use this gem, simply add
```` ruby
gem 'configoro'
````
to your Gemfile, then run
```` ruby
rails generate configoro
````
to install some default configuration files. Edit these new files with your
configuration data.
Usage
-----
Assume your application namespace is `MyApp` (which is what it
would be if you had created your Rails project using `rails new my_app`). You
can find your namespace in your `config/application.rb` file.
In this case, you would access your configuration using the
`MyApp::Configuration` object. You can access it as an indifferent hash
```` ruby
MyApp::Configuration[:mailchimp_api_url]
MyApp::Configuration['mailchimp_api_url']
````
or as a struct.
```` ruby
MyApp::Configuration.mailchimp_api_url
````
If you include any hashes in your configuration YAML files, they will also be
accessible as indifferent hashes or structs:
```` ruby
MyApp::Configuration.memcache.timeout
MyApp::Configuration[:memcache]['timeout']
MyApp::Configuration['memcache'].timeout
````
Configuration Files
-------------------
Configuration is stored within the `config/environments` directory of your Rails
app. Files ending in ".yml" are loaded from the `common/` subdirectory and a
subdirectory named after the current environment.
Configuration files are preprocessed as ERB, in the same way that Rails
preprocesses `config/database.yml`. This allows dynamic configuration,
e.g. `host: <%= ENV["DB_HOST"] || "localhost" %>`.
Each file goes into its own hash in the configuration. For example, if you
placed a file called `memcache.yml` within `config/environments/development`,
you would be able to access your Memcache timeout using
`MyApp::Configuration.memcache.timeout`.
h3. Custom Configuration Locations
If you need to do your own configuration loading, you can do so using the
{Configoro::Hash#<<} method. For example, you could place the following in a
Ruby file under `config/initializers`:
```` ruby
MyApp::Configuration << "path/to/additional/yaml_file.yml"
MyApp::Configuration << { 'additional' => 'configuration' }
MyApp::Configuration.additional #=> 'configuration'
````
Note that if you pass a path to a YAML file, a key will be created to store the
contents of the file, named after the file name. If the key already exists, the
new values will be deep-merged into the existing values.
In the example above, the data in the `yaml_file.yml` file can be accessed using
`MyApp::Configuration.yaml_file`.
Other Notes
-----------
If you want to use Configoro outside of Rails or your gemset, you can require
the `configoro/simple` file. This file defines a subset of the `Configoro`
object you can use to access your configuration. You will need to set
{Configoro.paths} manually, and the `Configoro::Hash` object will have the same
functionality as a normal Hash, without all the bells and whistles described
above.
If you then "upgrade" your environment to a full-fledged Rails or gem-ified
environment (perhaps by running your app's `environment.rb` file, be sure to
run {Configoro.reset_paths} before requiring the `configoro` gem file.
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
