secretary 0.0.1 → 0.1.0

data/History.txt

@@ -1,3 +1,25 @@
+
+=== 0.2.0 / 2008-08-29
+
+* 1 minor enhancements
+
+  * Added more complete RDocs for the Secretary class. RDocs for gophers
+    are planned in the future.
+ 
+* 1 major change
+
+  * Fundamentally changed how gophers validate data. Now there is a general 
+    Gopher#validate(data) method, which checks if the data's type matches
+    the gopher's data-type, and also checks if the data fulfills the
+    new Gopher#validation_proc attribute, which can be passed through the
+    initializer's block.
+
+=== 0.1.0 / 2008-08-12
+
+* 1 minor enhancement
+
+  * An RSpec file that runs all specs, all_spec.rb, has been added
+
 === 0.0.1 / 2008-08-11
 
 * 1 major enhancement

data/Manifest.txt

@@ -7,9 +7,11 @@ lib/secretary/error.rb
 lib/secretary/gopher.rb
 lib/secretary/gopher/yaml.rb
 spec/spec_helper.rb
-spec/secretary_spec.rb
+spec/secretary.rb
 spec/error_spec.rb
-spec/gopher_spec.rb
+spec/gopher/yaml_spec.rb
 spec/hash.yaml
 spec/array.yaml
-spec/broken-yaml.txt
+spec/broken-yaml.yaml
+spec/one-row.csv
+spec/two-rows.csv

data/README.txt

@@ -4,35 +4,25 @@
 
 == DESCRIPTION:
 
-Secretary is a gem who makes managing simple preference files in Ruby easy
-and painless. If you tire of being bound to PStore or YAML and want a
-consistent, pluggable way to read and write preferences, your Secretary would
-be happy to help!
+Secretary is a gem who makes managing simple preference files in Ruby easier
+and more painless.
 
 == FEATURES:
 
-* She's smooth and simple: just import and initialize!
-* She flexible: though she uses the simple YAML markup language by default, she
-  can easily switch to any other format!
-* She supports custom defaults, a big essential!
+* She encapsulates preference files in a single, easily manageable object
+* She's smooth and simple: just import and initialize
 * She's easily extensible--subclass Secretary::Gopher to be able to load any
-  kind of file you wish!
-* All in all, she's a small, no-frills object who gives you one less thing to
-  worry about. It can't be any easier!
+  kind of file you wish
 
 == SYNOPSIS:
 
-  import 'secretary/simple'
+  import 'secretary'
   
-  preferences = {'name': 'Samantha', 'port': 151}
-  defaults = {'name': '', 'port': 80}
-  
-  secretary = Secretary.new 'preferences.yaml', defaults
+  secretary = Secretary.new 'preferences.yaml', :defaults => {'name': '', 'port': 80}
   
   # The first argument is the path to the file that she will sync to.
-  # The second argument indicates the object that contains her defaults.
-  # There's also an optional third argument that determines how she will sync
-  # with her file--by default, it'll be YAML.
+  # The second argument is a option hash.
+  # Passing in a :defaults option gives the Hash that contains her defaults.
   
   secretary['url'] = 'http://samantha.name'
   
@@ -47,8 +37,7 @@ be happy to help!
 * At least Ruby 1.8.0
 * The standard forwarable.rb
 * The standard yaml.rb
-* At least RSpec 1.1 (but only if you want to unit test using Secretary's
-  included specs)
+* At least RSpec 1.1 (but only if you want to use the included specs)
 
 == INSTALL:
 
@@ -59,34 +48,9 @@ install it automatically:
 
 == NOTES:
 
-I'm planning to add support for managing arbitrary objects, not just Hashes,
-as well as support for more formats like CSV (easy), JSON (easier), and XML
-(hard).
-
-In addition, this is my first programming project ever, and I'm sort of not
-used to this. I'd be very happy to hear your comments and bugs on Rubyforge.
-
-== LICENSE:
-
-(The MIT License)
-
-Copyright (c) 2008
-
-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:
+Throughout this library's documentation, Secretaries will be referred to as
+"she"s, and Gophers will be referred to as "he"s.
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+I'm planning to add support for for more formats such as JSON and (gulp) XML.
 
-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.
+I'd be very happy to hear your comments and bugs on Rubyforge.

data/lib/secretary.rb

@@ -1,48 +1,101 @@
 $: << File.expand_path(File.dirname(__FILE__) + '/../lib')
+
+class Secretary
+end
+
 require 'secretary/error'
 require 'secretary/gopher/yaml'
 require 'forwardable'
 
+# A Secretary easily manages a data structure (by default a Hash only) and a
+# corresponding data file (by default a YAML file). To this end it utilizes a
+# gopher (by default a Secretary::Gopher::YAML object). The Secretary tells
+# the gopher to fetch or save certain files whenever it's needed, but the
+# Secretary herself manages the file path, any default options, and the data
+# itself.
+
+# If you subclass the Secretary class to be able to store a different kind of
+# data, like, say, an Array instead of a Hash, then you'll need to override the
+# contents and to_hash methods. (In addition, you may want to use a different
+# kind of gopher too. See the documentation on Secretary::Gopher for info about
+# that.)
+
 class Secretary
-  VERSION = '0.0.1'
+	VERSION = '0.1.0'
   extend Forwardable
   include Enumerable
-  attr_reader :file_path, :defaults, :gopher
+  attr_accessor :file_path, :defaults
+  attr_reader :gopher
   
-  def initialize(file_path, defaults={}, gopher_class=Gopher::YAML)
+  # Creates a brand-spanking new Secretary who takes charge of the file at the
+  # given file_path.
+	# You can give an options hash. Two options are eaten by the Secretary
+	# intializer (the rest are passed into the gopher initializer). They are
+	# :defaults, which is a Hash containing the default data, and :gopher, which
+	# is a Gopher class from which the Secretary's gopher will be created.
+	# She will raise an ArgumentError if you give a gopher class object that does
+	# not respond to :new, or if the newly initialized gopher object cannot act
+	# like a Gopher (i.e. if it cannot respond to :load and :save).
+	# If she finds a file at the file_path you give her, then she'll combine the
+	# data that her new gopher loads from the file with the defaults that you
+	# gave her to get her contents.
+	# If no file is found at the given file_path, then just the defaults are
+	# put into the contents.
+  def initialize(file_path, options={})
+		defaults = options.delete(:defaults) || {}
+		gopher_class = options.delete(:gopher) || Gopher::YAML
     unless gopher_class.respond_to? :new
       raise ArgumentError, "given gopher class is not a class (#{gopher_class})"
     end
     @file_path = file_path
     @defaults = defaults
-    @gopher = gopher_class.new Hash
-    unless @gopher.respond_to? :load_from_path
-      raise ArgumentError, "given gopher class\'s members do not respond to :load_from_path (#{gopher})"
+    @gopher = gopher_class.new options
+    unless @gopher.respond_to? :load
+      raise ArgumentError, "given gopher class\'s members do not respond to " +
+				":load (#{gopher})"
+    end
+    unless @gopher.respond_to? :save
+      raise ArgumentError, "given gopher class\'s members do not respond to " +
+				":save (#{gopher})"
     end
     @contents = {}
-    reload
+    reload!
   end
   
-  def_delegators :to_hash, :[], :include?, :each, :each_pair, :each_key, :each_value
-  def_delegators :@contents, :[]=, :delete
+  def_delegators :to_hash, :[], :include?, :each, :each_pair,
+    :each_key, :each_value
+  def_delegators :@contents, :[]=, :delete, :update
   
+  # A Secretary is equal to another object if the other object responds to
+  # :file_path, :defaults, :gopher, and :contents, and if the objects' values of
+  # those corresponding methods are equal to each other.
   def ==(other)
     other.respond_to? :file_path and other.respond_to? :defaults \
-      and other.respond_to? :gopher and other.respond_to? :to_hash \
+      and other.respond_to? :gopher and other.respond_to? :contents \
       and file_path == other.file_path and defaults == other.defaults \
-      and gopher == other.gopher and to_hash == other.to_hash
+      and gopher == other.gopher and contents == other.contents
   end
   
-  def to_hash
+	# Returns a new object containing the Secretary's data that she originally got
+	# from her file. It consists of the her defaults overridden by her file's
+	# data. Note that this method returns a new object, which means that it is
+	# only meant for inspection; modifying the object it returns will not affect
+	# her data. If you want to modify her data, directly tell her to use the []=
+	# or delete methods.
+  def contents
     defaults.merge @contents
   end
   
-  def reload
+	def to_hash
+		contents
+	end
+	
+	# Reloads data from the Secretary's file. If she succeeds, then this method
+	# returns true. If she can't find a file at her file_path, then this method
+	# returns false.
+  def reload!
     begin
-      loaded_data = gopher.load_from_path(file_path)
-      unless loaded_data.respond_to? :to_hash
-        raise IOError, "gopher's loaded data is unconvertable to a Hash and thus invalid (#{loaded_data})"
-      end
+      loaded_data = gopher.load(file_path)
       @contents.merge! loaded_data
       return true
     rescue Error::MissingFile
@@ -50,6 +103,7 @@ class Secretary
     end
   end
   
+	# Saves its contents to its file path.
   def save
     gopher.save self.to_hash, file_path
   end

data/lib/secretary/error.rb

@@ -1,31 +1,31 @@
+
 class Secretary
-  
-  module Error
-    
-    class MissingFile < IOError
+end
 
-      def initialize(missing_file_path)
-        super "no such file or directory (#{missing_file_path})"
-      end
+module Secretary::Error
+  
+  class MissingFile < IOError
 
+    def initialize(missing_file_path)
+      super "no such file or directory (#{missing_file_path})"
     end
 
-    class Parsing < IOError
+  end
 
-      def initialize(parsing_error, file_type)
-        super "attempted to parse an invalid #{file_type} file (#{parsing_error})"
-      end
+  class Parsing < IOError
 
+    def initialize(parsing_error, file_type)
+      super "attempted to parse an invalid #{file_type} file (#{parsing_error})"
     end
 
-    class InvalidData < IOError
+  end
 
-      def initialize(data, valid_data_type)
-        super "preference file of invalid data type (should be #{valid_data_type} instead of #{data.class})"
-      end
+  class InvalidData < IOError
 
+    def initialize(data)
+      super "preference file contains invalid data (#{data.inspect})"
     end
 
   end
-  
-end
+
+end

data/lib/secretary/gopher.rb

@@ -1,59 +1,95 @@
 require 'secretary/error'
 
 class Secretary
-  
-  class Gopher
-    # Abstract base class that requires methods #parse_file(input_file),
-    # #valid_file_type(), and #emit(data) to survive.
-    VERSION = '0.0.1'
-    attr_reader :valid_data_type
-    class << self
-      attr_reader :valid_file_type
-    end
-    
-    def initialize(valid_data_type)
-      @valid_data_type = valid_data_type
-    end
+end
 
-    def load_from_path(file_path)
-      if File.exist? file_path
-        open file_path do |file|
-          return load_from_file(file)
-        end
-      else
-        raise Secretary::Error::MissingFile.new(file_path)
-      end
-    end
+# Requires one of the following:
+# - parse_file
+# - load_from_file
+# 
+# As well as one of the following:
+# - emit
+# - save_into_file_path
+#
+# You may override the following:
+# - validate
+# - raw
+# - cook
+# - parse_file
+# - load_from_file
+# - emit
+# - save_into_file_path
 
-    def load_from_file(file)
-      begin
-        file_data = parse_file file
-      rescue Secretary::Error::Parsing => parsing_error
-        raise parsing_error
-      end
-      unless file_data.kind_of? valid_data_type
-        raise Secretary::Error::InvalidData.new(file_data, valid_data_type)
-      end
-      return file_data
-    end
-    
-    def save(data, file_path)
-      unless data.kind_of? valid_data_type
-        raise ArgumentError, "invalid data #{data} is not a kind of #{valid_data_type}"
-      end
-      open file_path, 'w' do |file|
-        file.puts emit(data)
-      end
+class Secretary::Gopher
+	attr_reader :options
+  class << self
+    attr_reader :file_type
+		@file_type = 'data'
+  end
+  
+	def initialize options={}
+		@options = options
+	end
+	
+  def file_type
+    self.class.file_type
+  end
+  
+  def == other
+    self.class == other.class
+  end
+  
+  def load file_path
+    if File.exist? file_path
+			file_data = load_from_file_path file_path
+    else
+      raise Secretary::Error::MissingFile.new(file_path)
     end
-    
-    def valid_file_type
-      self.class.valid_file_type
+    unless validate file_data
+      raise Secretary::Error::InvalidData.new(file_data)
     end
-    
-    def ==(other)
-      self.class == other.class
+		return cook(file_data)
+  end
+	
+  def save(data, file_path)
+    unless validate data then raise ArgumentError,
+			"invalid data #{data} is not a kind of #{data_type}"
+		end
+		save_into_file_path raw(data), file_path
+  end
+	
+	def validate data
+		true
+	end
+	
+	def raw data
+		data
+	end
+	
+	def cook data
+		data
+	end
+	
+	protected
+	
+	def load_from_file_path(file_path)
+		open file_path do |file|
+			return load_from_file(file)
+		end
+	end
+	
+  def load_from_file(file)
+    begin
+			parse_file file
+    rescue Secretary::Error::Parsing
+      raise
     end
-    
   end
   
+	def save_into_file_path(data, file_path)
+    open file_path, 'w' do |file|
+      file.puts emit(data)
+    end
+	end
+	
 end