fwissr 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 --- 
 SHA1: 
-  data.tar.gz: 933e4bc006d16954c87cc4f7b1290ec7fde652a4
-  metadata.gz: 2213070acd5d61baf5ebb2e5ae1188547aafb402
+  metadata.gz: 7b60e1c93fd5fdd4b3d8b81f044bf954eebe4983
+  data.tar.gz: 540b15881e2030ec311ea5872e77e8704a98f4d4
 SHA512: 
-  data.tar.gz: 42223b4c419f6c65e4ff88f35abfd14d787448bc79fb3aebdd1ab40746764e7542a42d10a4730f70aa86212192af708220dd4c6344cbc860afb79e088bd12fae
-  metadata.gz: 7f223d8a1d5f91a943b0fb0ac51fcc862a448f4279fa5479db8319a7441d20c36bb558f6eb8b2bd841bb1c6a37d4d3d4c29bdfc603a0cc5cdeea73e94ce052dc
+  metadata.gz: f66e1dc7a1ceca8a2ca76b45ea97a02d2eaaf28d25f6e12b20e1789c83ea039fa13192502fd3bb2bbc70e1c07c2d2c5e90efa084bd82ca5b9a4d3db5f9be1ea1
+  data.tar.gz: 147b2802a910e2aba9ae169c6bd8769ec6c584699ad337e005039d339f9a0a6e155745bc206be8acac5e37bbd1299ec0d92d2a6e22b34eeeda5a3a3e2976b3fe

data/README.md

@@ -1,7 +1,14 @@
 Fwissr
 ======
 
-A simple configuration registry tool by Fotonauts.
+A simple configuration registry tool by [Fotonauts](http://www.fotopedia.com).
+
+[![Build Status](https://travis-ci.org/fotonauts/fwissr.png)](https://travis-ci.org/fotonauts/fwissr)
+[![Code Climate](https://codeclimate.com/github/fotonauts/fwissr.png)](https://codeclimate.com/github/fotonauts/fwissr)
+
+- More information [on our tumblr](http://fotopedia-code.tumblr.com)
+- Source code [on github](http://github.com/fotonauts/fwissr)
+- Code documentation [on rubydoc](http://rubydoc.info/github/fotonauts/fwissr/frames)
 
 
 Install
@@ -152,7 +159,7 @@ If the `filepath` setting is a directory then all the configuration files in tha
 {
   "fwissr_sources": [
     { "filepath": "/mnt/my_app/conf/" },
-  ],
+  ]
 }
 ```
 
@@ -379,6 +386,9 @@ registry['/foo']
 Credits
 =======
 
-The Fotonauts team: http://www.fotopedia.com
+From Fotonauts:
+
+- Aymerick Jéhanne [@aymerick](https://twitter.com/aymerick)
+- Pierre Baillet [@octplane](https://twitter.com/octplane)
 
 Copyright (c) 2013 Fotonauts released under the MIT license.

data/lib/fwissr/registry.rb

@@ -25,6 +25,9 @@ module Fwissr
       @refresh_thread = nil
     end
 
+    # Add a source to registry
+    #
+    # @param source [Fwissr::Source] Concrete source instance
     def add_source(source)
       @semaphore.synchronize do
         @sources << source
@@ -42,11 +45,15 @@ module Fwissr
       self.ensure_refresh_thread
     end
 
+    # Reload the registry
     def reload!
       self.reset!
       self.load!
     end
 
+    # Get a registry key value
+    #
+    # @param key [String] Key
     def get(key)
       # split key
       key_ary = key.split('/')
@@ -65,12 +72,18 @@ module Fwissr
 
     alias :[] :get
 
+    # Get all keys in registry
+    #
+    # @return [Array] Keys list
     def keys
       result = [ ]
       _keys(result, [ ], self.registry)
       result.sort
     end
 
+    # Dump the registry
+    #
+    # @return [Hash] The entire registry
     def dump
       self.registry
     end
@@ -80,16 +93,19 @@ module Fwissr
     # PRIVATE
     #
 
+    # @api private
     def refresh_thread
       @refresh_thread
     end
 
+    # @api private
     def have_refreshable_source?
       @semaphore.synchronize do
         !@sources.find { |source| source.can_refresh? }.nil?
       end
     end
 
+    # @api private
     def ensure_refresh_thread
       # check refresh thread state
       if ((@refresh_period > 0) && self.have_refreshable_source?) && (!@refresh_thread || !@refresh_thread.alive?)
@@ -103,6 +119,7 @@ module Fwissr
       end
     end
 
+    # @api private
     def ensure_frozen
       if !@registry.frozen?
         @semaphore.synchronize do
@@ -111,6 +128,7 @@ module Fwissr
       end
     end
 
+    # @api private
     def reset!
       @semaphore.synchronize do
         @registry = { }
@@ -121,6 +139,7 @@ module Fwissr
       end
     end
 
+    # @api private
     def load!
       @semaphore.synchronize do
         @registry = { }
@@ -132,6 +151,7 @@ module Fwissr
       end
     end
 
+    # @api private
     def registry
       self.ensure_refresh_thread
       self.ensure_frozen
@@ -139,7 +159,8 @@ module Fwissr
       @registry
     end
 
-    # helper for #keys
+    # Helper for #keys
+    # @api private
     def _keys(result, key_ary, hash)
       hash.each do |key, value|
         key_ary << key

data/lib/fwissr/source/file.rb

@@ -1,7 +1,13 @@
+# File based source
 class Fwissr::Source::File < Fwissr::Source
 
   class << self
 
+    # Instanciate source from path
+    #
+    # @param path [path] File path
+    # @param options [Hash] Source options
+    # @return [Fwissr::Source::File] Instance
     def from_path(path, options = { })
       if path.nil? || (path == '')
         raise "Unexpected file source path: #{path.inspect}"
@@ -10,6 +16,10 @@ class Fwissr::Source::File < Fwissr::Source
       self.new(path, options)
     end
 
+    # Instanciate source from settings
+    #
+    # @param settings [Hash] Source settings
+    # @return [Fwissr::Source::File] Instance
     def from_settings(settings)
       options = settings.dup
       options.delete('filepath')
@@ -28,6 +38,7 @@ class Fwissr::Source::File < Fwissr::Source
   # API
   #
 
+  # Subclass {Fwissr::Source#initialize}
   def initialize(path, options = { })
     super(options)
 
@@ -36,6 +47,7 @@ class Fwissr::Source::File < Fwissr::Source
     @path = path
   end
 
+  # Implements {Fwissr::Source#fetch_conf}
   def fetch_conf
     result = { }
 
@@ -59,6 +71,7 @@ class Fwissr::Source::File < Fwissr::Source
   # PRIVATE
   #
 
+  # @api private
   def merge_conf_file!(result, conf_file_path)
     # parse conf file
     conf = Fwissr.parse_conf_file(conf_file_path)

data/lib/fwissr/source/mongodb.rb

@@ -10,13 +10,15 @@ rescue LoadError
   end
 end
 
+# Mongodb based source
 class Fwissr::Source::Mongodb < Fwissr::Source
 
+  # A mongodb connection
+  # @api private
   class Connection
 
     attr_reader :db_name
 
-    # init
     def initialize(uri)
       raise "URI is missing: #{uri}" if (uri.nil? || uri == '')
 
@@ -44,6 +46,7 @@ class Fwissr::Source::Mongodb < Fwissr::Source
       end
     end
 
+    # Database connection
     def conn
       @conn ||= begin
         case @kind
@@ -55,6 +58,7 @@ class Fwissr::Source::Mongodb < Fwissr::Source
       end
     end
 
+    # Database collection
     def collection(col_name)
       @collections[col_name] ||= begin
         case @kind
@@ -66,7 +70,7 @@ class Fwissr::Source::Mongodb < Fwissr::Source
       end
     end
 
-    # returns an Enumerator for all documents from given collection
+    # Returns an Enumerator for all documents from given collection
     def fetch(col_name)
       case @kind
       when :moped, :mongo
@@ -74,7 +78,7 @@ class Fwissr::Source::Mongodb < Fwissr::Source
       end
     end
 
-    # insert document in collection
+    # Insert document in collection
     def insert(col_name, doc)
       case @kind
       when :moped, :mongo
@@ -82,7 +86,7 @@ class Fwissr::Source::Mongodb < Fwissr::Source
       end
     end
 
-    # create a collection
+    # Create a collection
     def create_collection(col_name)
       case @kind
       when :moped
@@ -92,7 +96,7 @@ class Fwissr::Source::Mongodb < Fwissr::Source
       end
     end
 
-    # drop database
+    # Drop database
     def drop_database(db_name)
       case @kind
       when :moped
@@ -105,6 +109,10 @@ class Fwissr::Source::Mongodb < Fwissr::Source
 
   class << self
 
+    # Instanciate source
+    #
+    # @param settings [Hash] Mongodb settings
+    # @return [Fwissr::Source::Mongodb] Instance
     def from_settings(settings)
       if settings['mongodb'].nil? || (settings['mongodb'] == '') || settings['collection'].nil? || (settings['collection'] == '')
         raise "Erroneous mongodb settings: #{settings.inspect}"
@@ -119,6 +127,7 @@ class Fwissr::Source::Mongodb < Fwissr::Source
       self.new(conn, settings['collection'], options)
     end
 
+    # @api private
     def connection_for_uri(uri)
       @connections ||= { }
       @connections[uri] ||= Fwissr::Source::Mongodb::Connection.new(uri)
@@ -135,6 +144,7 @@ class Fwissr::Source::Mongodb < Fwissr::Source
   # API
   #
 
+  # Subclass {Fwissr::Source#initialize}
   def initialize(conn, collection_name, options = { })
     super(options)
 
@@ -142,6 +152,7 @@ class Fwissr::Source::Mongodb < Fwissr::Source
     @collection_name = collection_name
   end
 
+  # Implements {Fwissr::Source#fetch_conf}
   def fetch_conf
     result = { }
     result_part = result
@@ -158,7 +169,7 @@ class Fwissr::Source::Mongodb < Fwissr::Source
       end
     end
 
-    # build conf hash from collection's documents
+    # Build conf hash from collection's documents
     conf = { }
     self.conn.fetch(@collection_name).each do |doc|
       key = doc['_id']

data/lib/fwissr/source.rb

@@ -1,3 +1,4 @@
+# @abstract Subclass and override {#fetch_conf} to implement a configuration source.
 class Fwissr::Source
 
   autoload :File,    'fwissr/source/file'
@@ -30,17 +31,21 @@ class Fwissr::Source
     @conf = nil
   end
 
-  # reset source
+  # Reset source
   def reset!
     @conf = nil
   end
 
-  # source can be refreshed ?
+  # Source can be refreshed ?
+  #
+  # @return [Boolean] Is it a refreshable source ?
   def can_refresh?
     @options && (@options['refresh'] == true)
   end
 
-  # get conf
+  # Get source conf
+  #
+  # @return [Hash] The source's configuration
   def get_conf
     if (@conf && !self.can_refresh?)
       # return already fetched conf if refresh is not allowed
@@ -51,9 +56,11 @@ class Fwissr::Source
     end
   end
 
-  # fetch conf from source
+  # Fetch conf from source
+  #
+  # @abstract MUST be implemented by child class
+  # @return [Hash] The source's configuration
   def fetch_conf
-    # MUST be implemented by child class
     raise "not implemented"
   end
 

data/lib/fwissr/version.rb

@@ -1,3 +1,3 @@
 module Fwissr
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 end

data/lib/fwissr.rb

@@ -16,6 +16,30 @@ require 'fwissr/version'
 require 'fwissr/source'
 require 'fwissr/registry'
 
+#
+# Global Registry
+# ===============
+#
+# Fwissr loads all conf files in main directories: +/etc/fwissr/+ and +~/.fwissr/+
+#
+# Two conf files are treated differently: +/etc/fwissr/fwissr.json+ and +~/.fwissr/fwissr.json+
+#
+# These two main conf files are 'top_level' ones and so their settings are added to global registry root. They can
+# too contain a +fwissr_sources+ setting that is then used to setup additional sources.
+#
+# Global registry is accessed with Fwissr#[] method
+#
+# @example +/etc/fwissr/fwissr.json+ file:
+#
+#  {
+#    'fwissr_sources': [
+#      { 'filepath': '/mnt/my_app/conf/' },
+#      { 'filepath': '/etc/my_app.json' },
+#      { 'mongodb': 'mongodb://db1.example.net/my_app', 'collection': 'config', 'refresh': true },
+#    ],
+#    'fwissr_refresh_period': 30
+# }
+#
 module Fwissr
 
   # default path where main conf file is located
@@ -30,19 +54,22 @@ module Fwissr
   class << self
     attr_writer :main_conf_path, :main_user_conf_path
 
-    # Get config files directory
+    # Main config files directory
+    # @api private
     def main_conf_path
       @main_conf_path ||= DEFAULT_MAIN_CONF_PATH
     end
 
-    # Get user's specific config files directory
+    # User's specific config files directory
+    # @api private
     def main_user_conf_path
       @main_user_conf_path ||= File.join(Fwissr.find_home, DEFAULT_MAIN_USER_CONF_DIR)
     end
 
-    # finds the user's home directory
+    # Finds the user's home directory
     #
-    # Borrowed from rubygems
+    # @note Borrowed from rubygems
+    # @api private
     def find_home
       ['HOME', 'USERPROFILE'].each do |homekey|
         return ENV[homekey] if ENV[homekey]
@@ -64,6 +91,7 @@ module Fwissr
     end
 
     # Parse command line arguments
+    # @api private
     def parse_args!(argv)
       args = {
         :inspect  => false,
@@ -121,26 +149,8 @@ module Fwissr
       args
     end
 
-
-    #
-    # Global Registry
-    #
-    #
-    # NOTE: Parses main conf files (/etc/fwissr/fwissr.json and ~/.fwissr/fwissr.json) then uses 'fwissr_sources' setting to setup additional sources
-    #
-    # Example of /etc/fwissr/fwissr.json file:
-    #
-    #  {
-    #    'fwissr_sources': [
-    #      { 'filepath': '/mnt/my_app/conf/' },
-    #      { 'filepath': '/etc/my_app.json' },
-    #      { 'mongodb': 'mongodb://db1.example.net/my_app', 'collection': 'config', 'refresh': true },
-    #    ],
-    #    'fwissr_refresh_period': 30,
-    # }
-    #
-
-    # access global registry with Fwissr['/foo/bar']
+    # Load global registry
+    # @api private
     def global_registry
       @global_registry ||= begin
         result = Fwissr::Registry.new('refresh_period' => self.main_conf['fwissr_refresh_period'])
@@ -168,7 +178,8 @@ module Fwissr
       end
     end
 
-    # fetch main fwissr conf
+    # Main config
+    # @api private
     def main_conf
       @main_conf ||= begin
         result = { }
@@ -185,29 +196,38 @@ module Fwissr
       end
     end
 
+    # Main config file
+    # @api private
     def main_conf_file
       @main_conf_file ||= File.join(self.main_conf_path, MAIN_CONF_FILE)
     end
 
+    # Main user's config file
+    # @api private
     def main_user_conf_file
       @main_user_conf_file ||= File.join(self.main_user_conf_path, MAIN_CONF_FILE)
     end
 
-    # delegate to global registry
-    [ :[], :get ].each do |meth_name|
-      class_eval <<-EOS, __FILE__, __LINE__
-        def #{meth_name}(key)
-          self.global_registry[key]
-        end
-      EOS
+    # Global registry accessor
+    #
+    # @param key [String] setting key
+    # @return [Object] setting value
+    def [](key)
+      self.global_registry[key]
     end
 
-    [ :keys, :dump ].each do |meth_name|
-      class_eval <<-EOS, __FILE__, __LINE__
-        def #{meth_name}
-          self.global_registry.__send__('#{meth_name}')
-        end
-      EOS
+    alias :get :[]
+
+    # Dumps global registry keys
+    #
+    # @return [Array] Keys list
+    def keys
+      self.global_registry.keys
+    end
+
+    # @return [Hash] The entire registry
+    def dump
+      self.global_registry.dump
     end
 
 
@@ -215,6 +235,11 @@ module Fwissr
     # Utils
     #
 
+    # Parse a configuration file
+    #
+    # @param conf_file_path [String] Configuration file path
+    # @return [Hash] Parse configuration
+    # @api private
     def parse_conf_file(conf_file_path)
       conf_file_ext = File.extname(conf_file_path)
 
@@ -234,12 +259,14 @@ module Fwissr
       end
     end
 
-    # borrowed from rails
+    # @note Borrowed from rails
+    # @api private
     def merge_conf(to_hash, other_hash)
       self.merge_conf!(to_hash.dup, other_hash)
     end
 
-    # borrowed from rails
+    # @note Borrowed from rails
+    # @api private
     def merge_conf!(to_hash, other_hash)
       other_hash.each_pair do |k,v|
         tv = to_hash[k]
@@ -248,7 +275,8 @@ module Fwissr
       to_hash
     end
 
-    # simple deep freezer
+    # Simple deep freezer
+    # @api private
     def deep_freeze(obj)
       if obj.is_a?(Hash)
         obj.each do |k, v|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: fwissr
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors: 
 - Fotonauts Team