ruby_multiton 0.0.5.pre → 0.0.6.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c6a90d144a4241aca403b545de014afd972daa0a
-  data.tar.gz: 28eecb183e08c0889efa20de9ffbc6834a3ffa06
+  metadata.gz: 51a3a796c0ca21cd5533ca4c3e5932945261dc3d
+  data.tar.gz: 5866f116e8d626414cc135386cef3eb4598fd92c
 SHA512:
-  metadata.gz: 5da5a167965238d46b484e60b11797d12d7bae9309cb23b75d17898dac762dbfa5f9260036bffd36edc0f6739330f731389b18917a32cb7220e2e6c779b32efc
-  data.tar.gz: 6a6044c436bced6addf20fbdca748aeae6cac5baf0b2a0817068aea31ad3271db355ef379ea55eae236ca59edec0a22456a9bfc040604cebfd8c70d6469601c7
+  metadata.gz: a48dbcaefbc2e1cc2d17269b7b21eba9a41f39e45328ce5655cb70dafc0609ce367ffd9aaccdd3bbb4f2626e88ab8802cb28c91f2a83d83a4fb962e7d9d86061
+  data.tar.gz: 63ea49d20f752e16f397bd03b7d01621084b9a2ee48742c6733195ff48a42d6416e6398eb51e078afa931a5299b6e3d9e47b91bdd1e2a7f238d0c81e9ce07ada

data/README.md

@@ -6,7 +6,184 @@
 [![Test Coverage](http://img.shields.io/codeclimate/coverage/github/gdeoliveira/ruby_multiton.svg)][codeclimate]
 [![Inline docs](http://inch-ci.org/github/gdeoliveira/ruby_multiton.svg?branch=master)][inch-ci]
 
-[gem]: https://rubygems.org/gems/ruby_multiton
-[travis]: http://travis-ci.org/gdeoliveira/ruby_multiton/branches
+Multiton is an implementation of the [multiton pattern][multiton] in pure Ruby. Some its features include:
+
+- Can be used to implement the [singleton pattern][singleton] in a very straightforwad way
+- Transparent interface that makes designing multiton classes as easy as designing regular ones
+- Support for [serializing][marshal_dump] and [deserializing][marshal_load] multiton instances
+- Clonning, duplicating and inheriting from a multiton class will create a *new* multiton class
+- Thread safety, implemented via [shared/exclusive locks][sync]
+- [Compatible with MRI, JRuby and other Ruby implementations][travis].
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "ruby_multiton"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ruby_multiton
+
+## Usage
+
+#### Implementing a singleton class
+
+The easiest use case for Multiton is to implement a singleton class. To achieve this Multiton mimics the approach used
+by the [Singleton module][singleton_module] from Ruby's standard library:
+
+```ruby
+require "multiton"
+
+class C
+  extend Multiton
+end
+
+C.instance.object_id  #=> 47143710911900
+C.instance.object_id  #=> 47143710911900
+```
+
+As an example lets create a singleton object that returns the amount of seconds elapsed since it was first initialized:
+
+```ruby
+class Timestamp
+  extend Multiton
+
+  def initialize
+    self.initialized_at = Time.now
+  end
+
+  def elapsed_seconds
+    Time.now - initialized_at
+  end
+
+  private
+
+  attr_accessor :initialized_at
+end
+
+Timestamp.instance  #=> #<Timestamp:0x00562e486384c8 @initialized_at=2017-04-17 20:00:15 +0000>
+
+# Some time later...
+Timestamp.instance.elapsed_seconds  #=> 542.955918039
+```
+
+#### Implementing a multiton class
+
+To implement a multiton class we will need a `key` to be able to access the different instances afterwards. Multiton
+achieves this by using the parameters passed to the `initialize` method as the `key`:
+
+```ruby
+require "multiton"
+
+class C
+  extend Multiton
+
+  def initialize(key)
+  end
+end
+
+C.instance(:one).object_id  #=> 47387777147320
+C.instance(:one).object_id  #=> 47387777147320
+
+C.instance(:two).object_id  #=> 47387776632880
+C.instance(:two).object_id  #=> 47387776632880
+```
+
+As an example lets create multiton objects representing playing cards that we can check if they were drawn or not:
+
+```ruby
+class Card
+  extend Multiton
+
+  def initialize(number, suit)
+    self.has_been_drawn = false
+  end
+
+  def draw
+    self.has_been_drawn = true
+  end
+
+  def drawn?
+    has_been_drawn
+  end
+
+  private
+
+  attr_accessor :has_been_drawn
+end
+
+Card.instance(10, :spades).drawn?  #=> false
+
+Card.instance(5, :hearts).draw
+Card.instance(10, :spades).draw
+
+Card.instance(5, :hearts).drawn?    #=> true
+Card.instance(10, :spades).drawn?   #=> true
+Card.instance(2, :diamonds).drawn?  #=> false
+```
+
+#### Serializing and deserializing multiton instances
+
+Multiton instances can be serialized and deserialized like regular objects. Continuing with the previous `Card` example:
+
+```ruby
+Card.instance(2, :diamonds).drawn?  #=> false
+
+serialized_card = Marshal.dump(Card.instance(2, :diamonds))
+
+Marshal.load(serialized_card).drawn?  #=> false
+
+Card.instance(2, :diamonds).draw
+
+Marshal.load(serialized_card).drawn?  #=> true
+```
+
+#### Clonning, duplicating and inheriting from multiton classes
+
+Multiton supports cloning, duplicating and inheriting from a multiton class:
+
+```ruby
+require "multiton"
+
+class C
+  extend Multiton
+end
+
+D = C.clone
+
+E = D.dup
+
+class F < E
+end
+
+F.instance.object_id  #=> 47418482076880
+F.instance.object_id  #=> 47418482076880
+```
+
+Note that `C`, `D`, `E` and `F` are all considered different classes and will consequently not share any instances.
+
+## Contributing
+
+1. Fork it ( https://github.com/gdeoliveira/ruby_multiton/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am "Add some feature"`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
 [codeclimate]: https://codeclimate.com/github/gdeoliveira/ruby_multiton
+[gem]: https://rubygems.org/gems/ruby_multiton
 [inch-ci]: http://inch-ci.org/github/gdeoliveira/ruby_multiton
+[marshal_dump]: https://ruby-doc.org/core-2.4.1/Marshal.html#method-c-dump
+[marshal_load]: https://ruby-doc.org/core-2.4.1/Marshal.html#method-c-load
+[multiton]: https://en.wikipedia.org/wiki/Multiton_pattern
+[singleton]: https://en.wikipedia.org/wiki/Singleton_pattern
+[singleton_module]: https://ruby-doc.org/stdlib-2.4.1/libdoc/singleton/rdoc/Singleton.html
+[sync]: https://ruby-doc.org/stdlib-2.4.1/libdoc/sync/rdoc/Sync.html
+[travis]: http://travis-ci.org/gdeoliveira/ruby_multiton/branches

data/lib/multiton/version.rb

@@ -1,5 +1,5 @@
 module Multiton
   ##
   # Current version of Multiton.
-  VERSION = "0.0.5.pre".freeze
+  VERSION = "0.0.6.pre".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_multiton
 version: !ruby/object:Gem::Version
-  version: 0.0.5.pre
+  version: 0.0.6.pre
 platform: ruby
 authors:
 - Gabriel de Oliveira