user_config 0.0.3 → 0.0.4

data/README.md

@@ -4,18 +4,38 @@ user_config is a library to manage configuration files in user's home directory
 for ruby libraries or applications.
 The format of a configuration file is yaml.
 
+## Behavior
+
+The class UserConfig manages values of configuration,
+which is handled as a set of hashes and is saved to yaml files
+in specified directory under user's home directory.
+
 ## Examples
 
-### Create configuration files
+### Simple usage
+
+    uconf = UserConfig.new(".some_config")
+
+The directory ~/.some\_config is created in the directory ENV['HOME'].
+To set the value "world" for the key "hello" of ~/.some\_config/file.yaml,
+
+    uconf["file.yaml"]["hello"] = "world"
+
+The value is not saved to the file. To do that,
+
+    uconf["file.yaml"].save
 
-The directory '.some_config' is created in the directory ENV['HOME'].
-And then we save values to the file 'conf.yaml' in the directory.
+### Create initial configuration files
+
+If we want to create initial files with default values,
+we use the method UserConfig#default.
 
     UserConfig.default('conf.yaml', { 'key1' => 'val1', 'key2' => 'val2' })
     uconf = UserConfig.new('.some_config')
     uconf.create('conf.yaml')
 
-Similarly, we can create a file 'conf2.yaml'.
+The file ~/.some_config'/confi.yaml is created.
+To create another file 'conf2.yaml',
 
     UserConfig.default('conf2.yaml', { 'hello' => 'world'})
     uconf.create('conf2.yaml')
@@ -45,6 +65,17 @@ If we modify some files, we can save all files by UserConfig#save_all.
     yaml2['new_key'] = 'ABCDE'
     uconf.save_all
 
+### Behavior like a hash
+
+In internal of UserConfig::YAMLFile, the methods of Hash is called except for some methods.
+
+    uconf = UserConfig.new('.some_config')
+    yaml = uconf['conf.yaml']
+    yaml.each do |key, val|
+      ...
+    end
+    yaml.empty?
+
 ## Contributing to user_config
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet

data/lib/user_config.rb

@@ -7,6 +7,8 @@ class UserConfig
   class DirectoryExistenceError < StandardError
   end
 
+  # Get default value of current class.
+  # The value is a hash, of which keys are paths of yaml files.
   def self.default_value
     unless @default_value
       @default_value = {}
@@ -14,18 +16,21 @@ class UserConfig
     @default_value
   end
 
+  # Set default values of the specified file of current class.
+  # @param [String] path Relative path of the specified yaml file
+  # @param [Hash] default_hash Default values
   def self.default(path, default_hash)
     self.default_value[path] = default_hash
   end
 
   attr_reader :directory
 
-  # +directory_name+ is a name of a configuration directory.
-  # opts[:home] is root directory, of which default value is ENV['HOME'].
-  # opts[:permission] is a file permission of the configuration directory,
-  # of which default value is 0700.
-  # If opts[:new_directory] is true and the directory exists
-  # then an error raises.
+  # @param [String] directory_name :name of a configuration directory.
+  # @option opts [String] :home Root directory, of which default value is ENV['HOME'].
+  # @option opts [Integer] :permission A file permission of the configuration directory,
+  #   of which default value is 0700.
+  # @option opts [boolean] :new_directory
+  #   If opts[:new_directory] is true and the directory exists then an error raises.
   def initialize(directory_name, opts = {})
     @directory = File.expand_path(File.join(opts[:home] || ENV['HOME'], directory_name))
     @file = {}
@@ -39,6 +44,9 @@ class UserConfig
     end
   end
 
+  # @param [String] path Relative path of a specified file
+  # @param [boolean] create_directory If the value is true then we create parent directories recursively.
+  # @return [String] An absolute path of a specified file
   def file_path(path, create_directory = nil)
     if Pathname(path).absolute?
       raise ArgumentError, "Path '#{path}' is absolute."
@@ -60,14 +68,18 @@ class UserConfig
   end
   private :load_file
 
-  # Save the configuration file of +path+.
-  # If we set a hash to +value+ then its value is saved to the new configuration file.
+  # Save the configuration file under the directory.
+  # @param [String] path Relative path of target file
+  # @param [Hash] value Values to be saved to the file
   def create(path, value = nil)
     yaml_file = load_file(path, true, value)
     yaml_file.save
   end
 
   # Make directory under the configuration directory.
+  # @param [String] path Relative path of a directory
+  # @param [Hash] opts Options
+  # @option opts [Integer] :mode Permission for a directory to be created
   def make_directory(path, opts = {})
     fpath = file_path(path)
     unless File.exist?(fpath)
@@ -79,7 +91,9 @@ class UserConfig
     fpath
   end
 
-  # Load the configuration file of +path+.
+  # Load the configuration file.
+  # @param [String] path Relative path of a file to be loaded
+  # @return [hash]
   def load(path)
     @file[path] || load_file(path)
   end
@@ -116,8 +130,10 @@ class UserConfig
     end
   end
 
-  # List files in directory +dir+.
-  # If opts[:absolute] is true, return an array of absolute paths.
+  # List files in the specified directory.
+  # @param [String] dir A directory in which you want to list files.
+  # @param [Hash] opts Options
+  # @option opts [boolean] :absolute If the value is true then we get an array of absolute paths.
   def list_in_directory(dir, opts = {})
     fpath = file_path(dir)
     if File.directory?(fpath)
@@ -135,7 +151,9 @@ class UserConfig
     end
   end
 
-  # Open file of +path+ with +mode+.
+  # Open a file.
+  # @param [String] path A path of the file
+  # @param [String] mode A mode
   def open(path, mode, &block)
     full_path = file_path(path, true)
     f = Kernel.open(full_path, mode)
@@ -151,7 +169,9 @@ class UserConfig
     end
   end
 
-  # Read file of +path+ and return a string.
+  # Read a file
+  # @param [String] path A relative path of a file
+  # @return [String] Strings of the file
   def read(path)
     fpath = file_path(path)
     if File.exist?(fpath)
@@ -164,33 +184,40 @@ class UserConfig
   class YAMLFile
     attr_reader :path
 
-    # +path+ is path of yaml file, which saves pairs of key and value.
-    # +default+ is a hash saving default value.
-    # if +opts[:merge]+ is true then values of an instance are merged with default values.
+    # @param [String] path A path of yaml file, which saves pairs of key and value.
+    # @param [Hash] default A hash saving default value.
+    # @param [Hash] opts Options
+    # @option opts [booean] If the value is true then values of an instance are merged with default values.
     def initialize(path, default, opts = {})
       @path = path
       @default = default
-      @cache = load
+      @cache = load_yaml_file
       if opts[:merge]
         @cache.merge!(@default)
       end
     end
 
-    def load
+    def load_yaml_file
       if File.exist?(path)
         YAML.load_file(path)
       else
         {}
       end
     end
-    private :load
+    private :load_yaml_file
 
     def to_yaml
       YAML.dump(@cache)
     end
 
-    def to_hash
-      @cache
+    # @param [boolean] merge If the value is true then we merges default values and cached values.
+    # @return [Hash] A hash created by merging default values and cached values.
+    def to_hash(merge = false)
+      if merge
+        @default.merge(@cache)
+      else
+        @cache
+      end
     end
 
     # Save cached values to the path of file.
@@ -218,5 +245,13 @@ class UserConfig
     def set?(key)
       @cache.has_key?(key)
     end
+
+    def method_missing(method_name, *args, &block)
+      if Hash.method_defined?(method_name)
+        to_hash(true).__send__(method_name, *args, &block)
+      else
+        super
+      end
+    end
   end
 end

data/lib/user_config/version.rb

@@ -1,3 +1,3 @@
 class UserConfig
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/spec/user_config_spec.rb

@@ -202,6 +202,21 @@ describe UserConfig do
     UserConfig.default_value.object_id.should_not == UserConfigCustom.default_value.object_id
   end
 
+  context "when calling methods of Hash" do
+    before(:all) do
+      UserConfig.default("to_test_hash", { :a => "A", :b => "B" })
+    end
+
+    it "should be empty." do
+      subject["empty_conf"].empty?.should be_true
+    end
+
+    it "should return merged hash" do
+      subject["to_test_hash"][:b] = "BBB"
+      subject["to_test_hash"].to_hash(true).should == { :a => "A", :b => "BBB" }
+    end
+  end
+
   after(:all) do
     FileUtils.rm_r(@home)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: user_config
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-29 00:00:00.000000000 Z
+date: 2012-01-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &19641620 !ruby/object:Gem::Requirement
+  requirement: &11654660 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *19641620
+  version_requirements: *11654660
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &19641160 !ruby/object:Gem::Requirement
+  requirement: &11654240 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *19641160
+  version_requirements: *11654240
 description: The library creates, saves, and loads configuration files, which are
   in a user's home directory or a specified directory.
 email:
@@ -48,7 +48,6 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- VERSION
 - lib/user_config.rb
 - lib/user_config/version.rb
 - spec/spec_helper.rb
@@ -76,8 +75,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: user_config
-rubygems_version: 1.8.5
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Management of configuration files in a user's home directory
 test_files: []
+has_rdoc: 

data/VERSION

@@ -1 +0,0 @@
-0.0.2