Adds some documentation

[rbdr/lyricli.rb] / lib / lyricli / configuration.rb

diff --git a/lib/lyricli/configuration.rb b/lib/lyricli/configuration.rb
index 8d26b7f179c8bd48b7539a1b0fae3131aabb81e7..720070ced8181acaa438851a009429e927dbc6a3 100644 (file)
--- a/lib/lyricli/configuration.rb
+++ b/lib/lyricli/configuration.rb
@@ -1,6 +1,9 @@
 module Lyricli
 module Lyricli

+
+  # This class handles the configuration of Lyricli

   class Configuration
 
   class Configuration
 

+    # Defines the paths to the default and user configuration files

     def initialize
       @config_path = "~/.lyricli.conf"
       @defaults_path = "defaults.json"
     def initialize
       @config_path = "~/.lyricli.conf"
       @defaults_path = "defaults.json"


@@ -9,45 +12,80 @@ module Lyricli
 
     @@instance = Configuration.new
 
 
     @@instance = Configuration.new
 

+    # Ensure this is only called once. Only use the instance class variable
+    # to access this method, as its constructor is private.

     def self.instance
       @@instance
     end
 
     def self.instance
       @@instance
     end
 

+    # Access configuration properties, loads config if needed beforehand.
+    #
+    # @param [String] key the configuration key to access
+    # @return [String, Hash, Array] the value of the configuration key.

     def [](key)
       load_config unless @config
       @config[key]
     end
 
     def [](key)
       load_config unless @config
       @config[key]
     end
 

+    # Assigns a new value to a configuration key, loads config if needed and
+    # saves it after updating.
+    #
+    # @param [String] key the configuration key to set
+    # @param [Object] value the value for the configuration key, can be any
+    #                 object as long as it can be converted to JSON

     def []=(key, value)
       load_config unless @config
       @config[key] = value
       save_config
     end
 
     def []=(key, value)
       load_config unless @config
       @config[key] = value
       save_config
     end
 

-    private_class_method :new
+    # Deletes a key from the configuration, loads config if needed and saves
+    # it after deleting.
+    #
+    # @param [String] key the key to delete
+    def delete(key)
+      load_config unless @config
+      @config.delete(key)
+      save_config
+    end

 
 

-    private
+    private_class_method :new

 
 

-    # TODO: Apart from this, load a default yml that will be used for this.
-    # And just extend everything from the user's config.
+    # Loads the configuration from the user file, attempts to create it from
+    # defaults if it's not present. sets the `@config` instance variable.

     def load_config
     def load_config

-      # path = File.expand_path(@config_path)
-      path_root = File.expand_path(File.dirname(__FILE__))
-      path = File.join(path_root, @defaults_path)
+      path = File.expand_path(@config_path)

 
       if File.exists?(path)
         file = File.new(path, "r")
         @config = MultiJson.decode(file.read)
       else
 
       if File.exists?(path)
         file = File.new(path, "r")
         @config = MultiJson.decode(file.read)
       else

-        @config = {}
+        load_default_config

       end
     end
 
       end
     end
 

+    # Serializes the `@config` Hash to JSON and saves it to a file.

     def save_config
       path = File.expand_path(@config_path)
       file = File.new(path, "w")
       file.print(MultiJson.encode(@config))
       file.close
     end
     def save_config
       path = File.expand_path(@config_path)
       file = File.new(path, "w")
       file.print(MultiJson.encode(@config))
       file.close
     end

+
+    private
+
+    # Loads the default configuration from a JSON file
+    def load_default_config
+      # Load the default
+      path_root = File.expand_path(File.dirname(__FILE__))
+      path = File.join(path_root, @defaults_path)
+
+      if File.exists?(path)
+        file = File.new(path, "r")
+        @config = MultiJson.decode(file.read)
+      else
+        @config = {}
+      end
+    end

   end
 end
   end
 end