Configural

Version

0.0.1

Date

2011-08-22

Homepage

github.com/jacius/configural/

Author

John Croisant <[email protected]>

Copyright

2011 John Croisant

Description

Configural is a Ruby library for managing per-user configuration files and data storage. It aims to provide an easy to use API to allow applications to store and retrieve user configuration, cache, and persistant data files without any hassle.

Features

  • Stores config, cache, and data files in the conventional location for each operating system. Comes with support for Linux, Mac, and Windows out of the box.

  • Comes with support for YAML, JSON, Plist, and SDL config files out of the box (assuming you have the proper libraries; see the “Dependencies” section, below.)

  • Really easy to add support for more operating systems and more file formats.

  • Really, really easy to use!

Dependencies

Configural’s only dependencies are for the config file formats you want to use:

  • YAML: Requires ‘yaml’ (standard on most versions of Ruby).

  • JSON: Requires ‘json’ (standard on some versions of Ruby, otherwise install the gem or download from <json.rubyforge.org>).

  • Plist: Requires ‘plist’ (install the gem or download from <plist.rubyforge.org>).

  • SDL: Requires ‘sdl4r’ (install the gem or download from <sdl4r.rubyforge.org>).

Usage

Here is some basic usage information. For more details, see the documentation for Configural::App, Configural::Config, Configural::Data, and Configural::Cache.

To add support for another operating system or file format, see the “Extending Configural” guide (docs/extending_configural.rdoc).

Setting up

Before you can use any part of Configural, you must create an App instance, like so:

require 'configural'
app = Configural::App.new("My App")

Replace “My App” with the name of your application. This string is used to name the directories where your config, data, and cache files are saved.

Config files

See the “Using Config Files” guide (docs/using_config_files.rdoc).

Data and cache files

Data and cache files are just files where you can read and write anything you want. They have no special magic, except Configural helps you store them in the conventional location for each OS.

You can use the read and write methods for convenience, or use the open method to get a File instance. open accepts an optional mode and an optional block, just like File.open.

app.data['mydata.txt'].write("My data.")
app.data['mydata.txt'].read         # => "My data."
app.data['mydata.txt'].open{ |file|
  # Do whatever you want with the File instance.
}

In this case, ‘mydata.txt’ refers to a file inside the data storage directory, which is different for each operating system. Unlike configs, you should use a file extension when referring to a data or cache file. (Configural can’t automatically guess a file extension, because data and cache files can be any file format you want.)

Caches work the same as data, except you use app.cache instead of app.data, and cache files are stored in a different directory.

Where files are stored

Configural supports three kinds of files:

  • Config: User preferences and other configuration settings.

  • Data: Persistant data files. This could be used for things like saved playlists, installed add-ons, downloaded music files, or any other user data that should be preserved indefinitely.

  • Cache: Temporary files created (for example) to save bandwidth or time. These are files that can safely be deleted by the user; deleting them won’t break the application or cause data loss.

Each kind of file is stored in a different directory, as appropriate to the conventions of the user’s operating system.

(The following examples assume your app is named “My App”.)

Linux

Config: ~/.config/My App/
Data: ~/.local/share/My App/
Cache: ~/.cache/My App/

Mac

Config: ~/Library/Preferences/My App/
Data: ~/Library/Application Support/My App/
Cache: ~/Library/Caches/My App/

Windows

Config: %APPDATA%\My App\Config\
Data: %APPDATA%\My App\Data\
Cache: %APPDATA%\My App\Cache\

%APPDATA% is an environment variable with different values depending on your version of Windows. The usual values are:

XP: C:\Documents and Settings\%USERNAME%\Application Data
Vista and later: C:\Users\%USERNAME%\AppData\Roaming

License

Configural is licensed under the following terms (the “MIT License”):

Copyright © 2011 John Croisant

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.