configural 0.0.1

data/ChangeLog.txt

@@ -0,0 +1,318 @@
+commit 3aedf30e220481cb015c162eacf41a56c4b9d12a
+Author: John Croisant <john@croisant.net>
+Date:   Sun Sep 11 22:24:51 2011 -0500
+
+    Added methods: Config#[]= and Data#[]=
+
+M	lib/configural/config.rb
+M	lib/configural/data.rb
+
+commit 025610e4d06cc8e5d50abaa00c8e4776a72d8ee5
+Author: John Croisant <john@croisant.net>
+Date:   Sat Sep 10 02:11:41 2011 -0500
+
+    App can now also have non-per-user #cache/#config/#data.
+    
+    These are for files that are stored within the app's directory,
+    such as config files and data that ship with the app.
+    
+    Before you can use App#cache, #config, or #data, you must must set
+    #cache_path, #config_path, and/or #data_path to the directories where
+    each kind of file is located.
+    
+    Or, you can set App#path to the app's main directory; then files
+    default to the 'cache', 'config', and 'data' directories within that
+    main directory. If a specific path (e.g. #cache_path) is set, that
+    path takes precedence over the default path.
+
+M	lib/configural/app.rb
+
+commit bbe7a87968b146aa25b532adbb66caf3a01c5418
+Author: John Croisant <john@croisant.net>
+Date:   Fri Sep 9 16:07:41 2011 -0500
+
+    FileBase now takes a file path, instead of a Config instance.
+    
+    This makes FileBase more flexible and useful. Config class now handles
+    the logic for deciding the path and extension for config files.
+
+M	lib/configural/config.rb
+M	lib/configural/config/file_base.rb
+
+commit 4b8a788e4fe69c3aa1ae1d7a17d3d5ca05d711a5
+Author: John Croisant <john@croisant.net>
+Date:   Fri Sep 9 14:37:17 2011 -0500
+
+    Added Configural::User class, which will manage per-user stuff.
+
+M	lib/configural.rb
+M	lib/configural/app.rb
+M	lib/configural/config.rb
+M	lib/configural/data.rb
+A	lib/configural/user.rb
+
+commit 4c3855be515030407a4960efcf917dc00df8639f
+Author: John Croisant <john@croisant.net>
+Date:   Tue Aug 30 00:54:50 2011 -0500
+
+    Config and Data ask App for paths instead of Platform directly.
+
+M	lib/configural/app.rb
+M	lib/configural/config.rb
+M	lib/configural/data.rb
+
+commit 5c3f3a1018866582a1aacd2e4d506a70b7a8050d
+Author: John Croisant <john@croisant.net>
+Date:   Mon Aug 29 02:11:34 2011 -0500
+
+    Updated README.rdoc to mention SDL support.
+
+M	README.rdoc
+
+commit 7604f3b88bb071821c6dc13a398ab024ce9cddf5
+Author: John Croisant <john@croisant.net>
+Date:   Mon Aug 29 01:59:11 2011 -0500
+
+    Added Config::SDLFile (Simple Declarative Language). [#1]
+
+M	lib/configural/config.rb
+A	lib/configural/config/sdl_file.rb
+
+commit ff1eddc54ee9e16d7e31e1eaaf25cca7efe3a0f4
+Author: John Croisant <john@croisant.net>
+Date:   Mon Aug 29 01:30:00 2011 -0500
+
+    Fixed silly mistakes in yaml_file.rb and plist_file.rb.
+
+M	lib/configural/config/plist_file.rb
+M	lib/configural/config/yaml_file.rb
+
+commit 3e46378b51366128dfc70583e24f87d0cc491b10
+Author: John Croisant <john@croisant.net>
+Date:   Sun Aug 28 22:07:17 2011 -0500
+
+    More error checking for JSON, Plist, and YAML saving/loading.
+
+M	lib/configural/config/json_file.rb
+M	lib/configural/config/plist_file.rb
+M	lib/configural/config/yaml_file.rb
+
+commit 42b752e236764c94f768881979aa6041f67d8060
+Author: John Croisant <john@croisant.net>
+Date:   Sun Aug 28 21:59:21 2011 -0500
+
+    Wrote config file format section of docs/extending_configural.rdoc.
+
+M	docs/extending_configural.rdoc
+
+commit 625e6924a86759079bbba4d4bedc47d29e8ccc26
+Author: John Croisant <john@croisant.net>
+Date:   Sun Aug 28 13:50:35 2011 -0500
+
+    Added "Extending Configural" guide. Still more to be written.
+
+M	README.rdoc
+A	docs/extending_configural.rdoc
+
+commit 07b8345e03957008df0211154734931cd9ffa26f
+Author: John Croisant <john@croisant.net>
+Date:   Sun Aug 28 01:32:25 2011 -0500
+
+    Split the README section about config files to its own guide.
+    
+    The guide content has also been updated since the README.
+    See docs/using_config_files.rdoc.
+
+M	README.rdoc
+A	docs/using_config_files.rdoc
+
+commit 27cf614487dc49da4e12c1f60bb374763e572280
+Author: John Croisant <john@croisant.net>
+Date:   Sun Aug 28 00:58:34 2011 -0500
+
+    Added Config::FileBase#close, for "unloading" all data.
+
+M	lib/configural/config/file_base.rb
+
+commit 89cb2d3e3b0d42d0c4f3aede84afe2410568658c
+Author: John Croisant <john@croisant.net>
+Date:   Sun Aug 28 00:58:32 2011 -0500
+
+    Changed how Config::FileBase is loaded and saved.
+    
+    * #load only loads if the file has not been loaded yet.
+    * #load! loads no matter what.
+    * #save only saves if the file has been loaded.
+    * #save! saves no matter what.
+    * #_load and #_save implement the format-specific logic. These are the
+      methods subclasses should override now, instead of #load and #save.
+
+M	lib/configural/config/file_base.rb
+M	lib/configural/config/json_file.rb
+M	lib/configural/config/plist_file.rb
+M	lib/configural/config/yaml_file.rb
+
+commit 49695b3c90d6dcdbde78e2cb75aeee327b8b2afa
+Author: John Croisant <john@croisant.net>
+Date:   Sun Aug 28 00:58:31 2011 -0500
+
+    You can now use a file extension in config names.
+    
+    If it has no file extension, use the default format. If it has a file
+    extension, check for a format that provides that extension. If no
+    format provides that extension, raise an error.
+
+M	lib/configural/config.rb
+M	lib/configural/config/file_base.rb
+
+commit 5dd1672b57f5b4f5a8a178694a6173ecb68882e1
+Author: John Croisant <john@croisant.net>
+Date:   Sun Aug 28 00:58:30 2011 -0500
+
+    FileBase#extnames should be class method. FileBase.format was missing.
+
+M	lib/configural/config/file_base.rb
+
+commit 73df309c3a5611a38f2ac3581f4dd4727a8680ad
+Author: John Croisant <john@croisant.net>
+Date:   Sun Aug 28 00:58:28 2011 -0500
+
+    Replaced Config#format with the :default_format option.
+
+M	lib/configural/config.rb
+
+commit 6692d912b73a0d9402dd337e89563d500d37e8a0
+Author: John Croisant <john@croisant.net>
+Date:   Sun Aug 28 00:58:26 2011 -0500
+
+    Split config.rb into separate files for each class.
+
+M	lib/configural/config.rb
+A	lib/configural/config/file_base.rb
+A	lib/configural/config/json_file.rb
+A	lib/configural/config/plist_file.rb
+A	lib/configural/config/yaml_file.rb
+
+commit a8944eab2d1451e2b42369c4841aea8c0cf73ed8
+Author: John Croisant <john@croisant.net>
+Date:   Sun Aug 28 00:58:22 2011 -0500
+
+    Config files load when initialized unless Config has :lazy_loading enabled.
+    
+    This should hopefully be the "least surprising" behavior.
+
+M	lib/configural/config.rb
+
+commit f8d7196eacd0966d661b0ba31f8bbaa6f56b5c87
+Author: John Croisant <john@croisant.net>
+Date:   Sun Aug 28 00:57:58 2011 -0500
+
+    Added Config @options and accessors.
+
+M	lib/configural/config.rb
+
+commit 9e82862fc6435dcd8a5e63f56f17eaef295dee15
+Author: John Croisant <john@croisant.net>
+Date:   Wed Aug 24 03:34:36 2011 -0500
+
+    Updated README.rdoc with a lot of info.
+
+M	README.rdoc
+
+commit 8ae0e51e397d4bb821574612dc55aa0e64c0ce27
+Author: John Croisant <john@croisant.net>
+Date:   Wed Aug 24 01:10:50 2011 -0500
+
+    Store config and data in different directories on Windows.
+
+M	lib/configural/platform.rb
+
+commit 0ea1e419d476b02adf1b0a68e2d4208cc2304dd3
+Author: John Croisant <john@croisant.net>
+Date:   Wed Aug 24 00:30:17 2011 -0500
+
+    Added JSONFile class, for serializing configs as JSON.
+
+M	lib/configural/config.rb
+
+commit 56f6fd565ffc34e62043261147fffd0b88f69574
+Author: John Croisant <john@croisant.net>
+Date:   Wed Aug 24 00:17:01 2011 -0500
+
+    Added method: Config::FileBase#to_hash
+
+M	lib/configural/config.rb
+
+commit b910dd7145c9bd67de13b2d43c316ff0de33863c
+Author: John Croisant <john@croisant.net>
+Date:   Wed Aug 24 00:16:25 2011 -0500
+
+    Fixed bogus logic in Config::FileBase#load_if_uninitialized
+
+M	lib/configural/config.rb
+
+commit 8707356c520d64bc349c2f390b52ea0d2800d578
+Author: John Croisant <john@croisant.net>
+Date:   Tue Aug 23 23:28:59 2011 -0500
+
+    Added PlistFile class, for storing configs as property lists.
+
+M	lib/configural/config.rb
+
+commit a89964791d56d792103e8ee224ca7e27fab9449d
+Author: John Croisant <john@croisant.net>
+Date:   Tue Aug 23 21:38:44 2011 -0500
+
+    Added proper support for multiple possible config file extensions.
+
+M	lib/configural/config.rb
+
+commit 118e78f92006729947a0e0e3a2727983808011a0
+Author: John Croisant <john@croisant.net>
+Date:   Tue Aug 23 21:11:56 2011 -0500
+
+    Revamped Config format selection system.
+
+M	lib/configural/config.rb
+
+commit d3af955376b9c3ecfbbe852db9f15bf8fdd74b48
+Author: John Croisant <john@croisant.net>
+Date:   Tue Aug 23 18:30:31 2011 -0500
+
+    Revamped platform detection.
+
+M	lib/configural.rb
+M	lib/configural/app.rb
+M	lib/configural/config.rb
+M	lib/configural/data.rb
+A	lib/configural/platform.rb
+
+commit 372a63c1b754ab798613e5b651597d9b346617c9
+Author: John Croisant <john@croisant.net>
+Date:   Mon Aug 22 23:50:52 2011 -0500
+
+    First attempt at implementation.
+
+A	lib/configural.rb
+A	lib/configural/app.rb
+A	lib/configural/config.rb
+A	lib/configural/data.rb
+
+commit 539982d794c319051fb2a1ab9ff25775c5fb1412
+Author: John Croisant <john@croisant.net>
+Date:   Mon Aug 22 15:25:31 2011 -0500
+
+    Checked in project infrastructure.
+
+A	.gitignore
+A	NEWS.rdoc
+A	README.rdoc
+A	Rakefile
+A	configural.gemspec
+A	scripts/mkchangelog.rb
+
+commit b77e356d4fb023dde8c16f03ff63edc108b8efc8
+Author: John Croisant <john@croisant.net>
+Date:   Mon Aug 22 15:14:41 2011 -0500
+
+    Initial commit.

data/NEWS.rdoc

@@ -0,0 +1,4 @@
+= NEWS
+
+== Configural 0.1
+

data/README.rdoc

@@ -0,0 +1,158 @@
+
+= Configural
+
+Version::    0.0.1
+Date::       2011-08-22
+
+Homepage::   http://github.com/jacius/configural/
+Author::     John Croisant <john@croisant.net>
+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 <http://json.rubyforge.org>).
+- Plist: Requires 'plist' (install the gem or download from
+  <http://plist.rubyforge.org>).
+- SDL: Requires 'sdl4r' (install the gem or download from
+  <http://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 (c) 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.