register 0.5.3 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e369eac31276624d538745280cb280fcbbe61b41
-  data.tar.gz: f2927260fab0adef3486b976d0b8c25bb599abbe
+  metadata.gz: 9747f4557a3c6de92a37efff1e8a283a8715133a
+  data.tar.gz: 19eba97e52016589e2bc6ca9a7492f042d182940
 SHA512:
-  metadata.gz: 37dd3f2dc9d2a523f7c8e153b8698268567d7bff81b1737e78caa06513e4e2ca81bb31343761130b906601077c10230066e118dc3d316b86f43b4c5037351712
-  data.tar.gz: c78fb667da5066c918df19928326e03e2779fd7d36921aef1216ba77351e1dfce6ecf66c3da1b99bb22bc525228da89977966c4f588312414ff12fd4d8fdf6f4
+  metadata.gz: b47edbd458b251f7fa1532cfad381d9e8552ed01cf7709883a40003e9831c63e5f785a256bc2b0c9cfdaa3c79ddc790ffffae3f9f594ec2c8d026bc2c9546e5c
+  data.tar.gz: 0f7139bb74ba86e14e6d360c93c30f921b5b76a03dd326fa5246168a992aeeb5fe327f953b62cd57029bc57388f82af2f0b6ef07837e3ff732d1754a498752f4

data/.yardopts

@@ -0,0 +1 @@
+--no-private --protected lib/**/*.rb - README.md LICENSE.txt 

data/README.md

@@ -12,9 +12,11 @@ A good example is a register of several connections to either *Redis* or *MemCac
 
 ## Usage
 
+You need to create a module for each individual "store" — behind the scenes `Register` uses ruby `Hash`, but protects any write access to it using a local mutex to ensure thread-safety.
+
 ### Creating a Register
 
-To create a register module, just include `Register` in any ruby module: 
+To create a register module, just include `Register` in any of your custom ruby modules: 
 
 ```ruby
 require 'register'
@@ -24,9 +26,13 @@ module Cache
 end
 ```
 
-### Storing Items in the Register
+### Adding Items to the Register
+
+To add items to the register, call the `#register` method on the module (or it's alias `.<<`, passing an array of identifiers first, followed by the actual item to store. 
 
-To add items to the register, call the `<<` method, passing an array of identifiers, followed by the actual item to store. In other words, the last items of the argument array is the actual item stored against each of the identifiers passed before it.
+In other words, the very last item of the argument array is the actual item stored against each of the keys passed in an array before it.
+
+The `#register` method returns the item successfully stored, or raises one of several exceptions.
 
 ```ruby
 
@@ -34,66 +40,131 @@ To add items to the register, call the `<<` method, passing an array of identifi
 CacheStore = Struct.new(:name)
 
 # Register items associated with any one of the identifiers
-Cache.register :planetary, :cosmic, CacheStore.new(:saturn)
+Cache.register :planetary, 
+               :cosmic, 
+               CacheStore.new(:saturn)
+#=> #<struct CacheStore name=:saturn>
+
+# Use the block syntax to define the value:
+Cache.register(*%i[primary main rails deploy]) do
+  CacheStore.new(:primary)
+end
+#=> #<struct CacheStore name=:primary>
 
-# You can use << syntax which is an alias to #register, but 
-# then use << to append the actual item
-Cache.<< %i[primary main rails deploy] << CacheStore.new(:primary)
+# Use the << method alias instead (just ensure the proper 
+# grouping of the arguments)
+Cache << %i[number].push(Math::PI)
+#=> 3.141592653589793
 
-Cache.<< %i[durable secondary] << CacheStore.new(:secondary)
+# Using double << with () 
+Cache << (%i[durable secondary] << CacheStore.new(:secondary))
+#=> #<struct CacheStore name=:secondary>
 ```
 
-### Looking up (Fetching) Items from the Register
+#### Exceptions while Adding Items
+
+ * `AlreadyRegisteredError` is thrown when the key is already in the store, and the option `:ignore_if_exists` is not passed to the `register()` method;
+
+ * `ReservedIdentifierError` is thrown upon an attempt to register a keyword that is reserved (i.e. clashes with one of the methods on the blank `Module`).
+
+
+### Fetching an Item from the Register
 
 There are two ways to fetch the previously-stored item:
 
   1. Using the `#for(:name)` method
+
   2. Using the auto-generated module-level accessor
   
 In the first example, we would call `Cache.for(:planetary)` to fetch the cache store, while in the second case we would call `Cache.planetary` method, which provides additional guarantees: if the method is not there, something is definitely wrong.  
 
 ```ruby
-Cache.planetary.name should eq(:saturn)
-Cache.primary === Cache.main === Cache.rails === Cache.deploy
+Cache.cosmic
+# => #<struct CacheStore name=:saturn>
+Cache.planetary.name 
+# => :saturn
+Cache.primary == Cache.main == Cache.rails == Cache.deploy
+# => true
 Cache.durable.name = 'DURABLE'
-Cache.secondary.name # => 'DURABLE'
+# => 'DURABLE'
+Cache.secondary.name 
+# => 'DURABLE'
 ```
 
-Here is a more complete RSPec example:
+#### Exceptions while Fetching Items
+
+ * `NoSuchIdentifierError` is thrown upon lookup with method `#for` when no requested key was found in the store;
+
+## Contributing
+ 
+ * Fork the project.
+ * Make your feature addition or bug fix.
+ * Add specs for it, as without tests the PR will be rejected.
+ * Do not change the version.
+ * Send a pull request, with a well worded description.
+
+
+There are some additional methods that will help you debug should things go weird:
+
+### Additional Methods: `#keys` and `#values`
+
+These two methods proxy into the underlying `Hash`. The `#values` method returns the uniq'd array of the values.
 
 ```ruby
-require 'rspec'
-require 'rspec/its'
-RSpec.describe Cache do
-  subject(:cache) { Cache }
-  its(:planetary) { should eq CachStore.new(:saturn) }    
-  its(:deploy) { should eq CachStore.new(:primary) }    
-  its(:durable) { should eq CachStore.new(:secondary) }
-  it 'should also respond to #for' do
-    expect(cache.for(:secondary)).to eq(CacheStore(:secondary))      
-  end
-end
+# ap Cache.keys
+[
+    [0] :planetary,
+    [1] :cosmic,
+    [2] :primary,
+    [3] :main,
+    [4] :rails,
+    [5] :deploy,
+    [6] :durable,
+    [7] :secondary,
+    [8] :number
+]
+# ap Cache.store.values.uniq
+[
+    [0] #<Struct:CacheStore:0x7facd107c800
+        name = :saturn
+    >,
+    [1] #<Struct:CacheStore:0x7facd2836c98
+        name = :primary
+    >,
+    [2] #<Struct:CacheStore:0x7facd281fa98
+        name = :secondary
+    >,
+    [3] 3.141592653589793
+]
 ```
-    
+
+### Internal Storage
+
+This gem uses a plain ruby `Hash` to store the values, but protects write access with a `Mutex`. 
+
+While it is not advisable to manipulate the underlying storage, you can access it via `Cache.send(:store)`, i.e:
+
+```ruby
+Cache.send(:store).class
+# => Hash
+```
+
 ## Installation
 
     gem install register 
+    
+Or if you are using Bundler, add the following to your `Gemfile`:
 
-## Note on Patches and Pull Requests
- 
- * Fork the project.
- * Make your feature addition or bug fix.
- * Add tests for it. This is important so I don't break it in a future version unintentionally.
- * Commit, do not mess with rakefile, version, or history. If you want to have your own version, that is fine but bump  version in a commit by itself I can ignore when I pull.
- * Send a pull request. Bonus points for topic branches.
+    gem 'register'        
 
 ## Copyright
 
-Copyright &copy; 2017 Konstantin Gredeskoul. See LICENSE for details.
+Copyright &copy; 2017 Konstantin Gredeskoul. See [LICENSE](LICENSE.txt) for details.
 
 ## Contributors
 
  * [Konstantin Gredeskoul](https://github.com/kigster)
+ * You?
  
  
 

data/Rakefile

@@ -1,23 +1,35 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'yard'
+require 'colored2'
 
 def shell(*args)
-  puts "running: #{args.join(' ')}"
+  puts "running: #{args.join(' ').blue.bold}".yellow
   system(args.join(' '))
 end
 
+module Register
+  DIST_DIRS=%w(lib)
+  BIN_DIRS=%w()
+end
+
 task :permissions do
   shell('rm -rf pkg/')
-  shell('chmod -v o+r,g+r * */* */*/* */*/*/* */*/*/*/* */*/*/*/*/*')
-  shell('chmod -v o+x,g+x exe/* bin/*')
-  shell("find . -type d -exec chmod o+x,g+x {} \\;")
+  Register::BIN_DIRS.each do |dir|
+    shell("chmod -v o+rx,g+rx #{dir}/*")
+  end
+
+  Register::DIST_DIRS.each do |dir|
+    shell("chmod -v o+rx,g+rx #{dir}")
+    shell("find #{dir} -name '[a-z]*' -type d -exec chmod o+rx,g+rx {} \\; -print")
+    shell("find #{dir} -type f -exec chmod o+r,g+r {} \\; -print")
+  end
 end
 
 task :build => :permissions
 
 YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files = %w(lib/**/*.rb exe/*.rb - README.md LICENSE)
+  t.files = %w(lib/**/*.rb exe/*.rb  - README.md LICENSE.txt )
   t.options.unshift('--title','Register - An easy way to create Mudule-level accessors to global resources')
   t.after = ->() { exec('open doc/index.html') }
 end

data/lib/register.rb

@@ -1,31 +1,73 @@
 require 'register/version'
 require 'colored2'
+require 'forwardable'
+
+# **Register** is a tiny library that can be included in a module
+# that is to become a Façade to several application globals via
+# auto-generated module-level methods.
+#
+# A good example is a register of several connections to either
+# *Redis* or  *MemCached*, for example you might have a short-term
+# memcached connection with a short default expiration TTL, and a
+# longer-living one that requires sweeping to clean. You could
+# use `Register` to wrap access to these singletons in
+# `MyModule.cache_type` accessors.
+#
+# Usage
+# =====
+#
+# To create a register module, just include `Register` in any
+# of your custom ruby modules:
+#
+#         require 'register'
+#
+#         module Cache
+#           include Register
+#         end
+#
+#         Cache.register :rails, Rails.cache
+#         Cache.register :durable, ActiveSupport::Cache::DalliStore.new(
+#           ENV['MEMCACHED_HOSTS'] ? ENV['MEMCACHED_HOSTS'].split(',') : %w[localhost:11211],
+#           namespace:      'v1',
+#           socket_timeout: 0.2,
+#           expires_in:     0, # never expire
+#           keepalive:      true,
+#           compress:       true,
+#           failover:       true
+#         )
+#
+#         Cache.rails # => Rails.cache
+#         Cache.durable # => DalliStore, etc.
+#
 module Register
   class RegisterError < StandardError; end
   class AlreadyRegisteredError < RegisterError; end
   class NoSuchIdentifierError < RegisterError; end
   class ReservedIdentifierError < RegisterError; end
 
-  module DummyModule
-  end
-
-  RESERVED = (DummyModule.methods << %i[for register << add_method]).flatten!.freeze
+  RESERVED = (Register.methods + %i[for register keys values << add_method]).flatten.uniq.freeze
 
   def self.included(klass)
     klass.instance_eval do
       @store = Hash.new
       @mutex = Mutex.new
       class << self
-        attr_accessor :store, :mutex
-        def <<(*names, &block)
+        extend Forwardable
+        def_delegators :@store, :keys
+        attr_accessor :mutex
+
+        def << *names, **opts, &block
           names.flatten!
           item = block ? yield(self) : names.pop
-          validate_existing_keys!(names)
           validate_reserved_keys!(names)
-          names.each do |n|
-            store[n] = item
-            add_method(n)
+          @mutex.synchronize do
+            validate_existing_keys!(names, opts)
+            names.each do |n|
+              store[n] = item
+              add_method(n)
+            end
           end
+          item
         end
 
         alias register <<
@@ -38,19 +80,25 @@ module Register
           store[id]
         end
 
+        def values
+          store.values.uniq
+        end
+
         private
 
+        def store
+          @store
+        end
+
         def add_method(id)
           return unless id.is_a?(Symbol)
-          @mutex.synchronize do
-            unless self.respond_to?(id)
-              line_no     = __LINE__
-              method_defs = %Q!
+          unless self.respond_to?(id)
+            line_no     = __LINE__
+            method_defs = %Q!
               def self.#{id}
                 store[:#{id}]
               end\n!
-              module_eval method_defs, __FILE__, line_no
-            end
+            module_eval method_defs, __FILE__, line_no
           end
         end
 
@@ -61,14 +109,12 @@ module Register
           end
         end
 
-        def validate_existing_keys!(names)
+        def validate_existing_keys!(names, opts = {})
           already = names.select { |n| store.key?(n) }
-          unless already.empty?
+          if !already.empty? && opts[:ignore_if_exists].nil?
             raise AlreadyRegisteredError, "The following keys are already in the registry: #{already}"
           end
         end
-
-
       end
     end
   end

data/lib/register/version.rb

@@ -1,3 +1,3 @@
 module Register
-  VERSION = '0.5.3'.freeze
+  VERSION = '0.5.4'.freeze
 end

data/register.gemspec

@@ -21,7 +21,9 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'codeclimate-test-reporter'
   spec.add_development_dependency 'colored2'
+  spec.add_development_dependency 'irbtools'
   spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'yard-rspec'
   spec.add_development_dependency 'awesome_print'
   spec.add_development_dependency 'bundler', '~> 1.15'
   spec.add_development_dependency 'rake', '~> 10.0'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: register
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.4
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: irbtools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: awesome_print
   requirement: !ruby/object:Gem::Requirement
@@ -152,6 +180,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE.txt
 - README.md