bottled_observers 0.1.0.alpha.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1a32f5a4c6ac1a64683f4b80e60a69a7536d3584
-  data.tar.gz: 338109d77dd2f7eeffbfc3295e6d271c16f68524
+  metadata.gz: 0de7b24c1c7374eb622b321c0a15bfe54abda7f4
+  data.tar.gz: 5514640d30cb75a05fbb9fac0d898dcc27a182b7
 SHA512:
-  metadata.gz: b75f44850891b606243876455843af74217cd09662fd8157f72f6af1d3ef5e3f18a824138f924b6ecc1551076494b4fcef13231a00372019b96df5ea1a4547ea
-  data.tar.gz: ffa4db46b39e685ae4e579b08594f86e227b67f67c17d615daeec33061917ea3fecd24d1a9468ee070058a7e77080a9a834f846d94289110549b570acae6429a
+  metadata.gz: a5cfb97d46b6ce73546dedd6dc03f963e297944f53aee7bfb4402e601fb61ef2bb8d7e36b3b48703437ea11ed8ae8ac7d67d7fbc12349d2ce33fc2f4498dde62
+  data.tar.gz: 839972e93ad95495ec94ec40a647627d0099e76f5662b9476d5667fede9284786bd752d3b3205ce8affdba3b4c7628978155f9cb2a25510c5172c3517075d4dd

data/README.md

@@ -1,8 +1,12 @@
 # BottledObservers
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/bottled_observers`. To experiment with that code, run `bin/console` for an interactive prompt.
+## The best thing to happen since bottled water
 
-TODO: Delete this and the text above, and describe your gem
+Wait, wasn't that [bottled_decorators?](https://github.com/John-Hayes-Reed/bottled_decorators),
+or was it [bottled_services?](https://github.com/John-Hayes-Reed/bottled_services), 
+I am starting to lose track. Anyway! bottled_observers are an easy-to-use solution, 
+for the Observer / Subscribe-Publish pattern in ruby. all you need to worry about 
+is adding your business logic, let bottled_observers handle the rest!
 
 ## Installation
 
@@ -22,17 +26,143 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+bottled_observers has two main modules you need to be aware of; BottledObserver and BottledObservable.  
+
+#### BottledObserver
+
+This module should be included in your observer class, and that observer class 
+should only contain a single public method: `#call`.  
+eg:
+
+```ruby
+class SendPushNotification
+  include BottledObserver # <-- just like this!
+  
+  def call
+    # Some intense and awesome logic to notify the hell out of them users.
+  end
+end
+```
+
+That is all there is to it, your observer is now ready to rock'n'roll.
+
+#### BottledObservable
+
+This module is included in any class that should allow observers to subscribe to it.  
+eg:
+
+```ruby
+class Product
+  include BottledObservable # <-- and just like this!
+  
+  # The rest of the class....
+end
+```
+
+And that is it, your whole bottled_observers subscribe/publish cycle is ready to go.
+
+#### The Subscribe / Publish Cycle  
+
+There are three main methods available in your arsenal that you need to be aware of:
+* `#add_subscription`
+* `#modified`
+* `#publish`
+
+These are available to your observable class instances, so if we wanted to subscribe
+our `SendPushNotification` observer to an instance of our `Product` class, we could
+do the following:
+
+```ruby
+@product = Product.find(1)                     # <-- instantiate Product from a record in the database. 
+@product.add_subscription SendPushNotification # <-- add a subscription for the SendPushNotification class
+```
+
+We now have a `SendPushNotification` observer lying in wait for any publications from the `@product` instance.  
+Then, when we want to notify the observer(s) of any changes to the instance, just 
+set the state of the instance as *modified* using the `#modified` method, and publish
+this change of state to its subscribers:
+
+*Example case: sending push notifications after a successful save of the @product instance.*
+```ruby
+# The product is only in a modified state if the save is successful
+@product.modified if @product.save
+ 
+# If the @product's state is 'modified' the observers call method will be excecuted. 
+# If the state is not modified, nothing will happen.
+@product.publish
+```
+
+**Super simple!**
+
+Another thing that needs to be noted is, after publishing, the instances *modified* 
+state is reset, so to publish anything again, it must be set again.
+
+```ruby
+@product.modified
+@product.publish # <-- push notifications sent.
+@product.publish # <-- push notifications not sent.
+```
+
+```ruby
+@product.modified
+@product.publish # <-- push notifications sent.
+@product.modified
+@product.publish # <-- push notifications sent.
+```
+
+#### Extras
+
+You can have as many observers subscribed to a single instance as you like:
+```ruby
+@product.add_subscription SendPushNotification
+@product.add_subscription MailToMailingList
+@product.add_subscription CreateRecentActivityRecord
+
+@product.modified if @product.save
+@product.publish
+```
+
+`#subscriptions` will return an array of current observer instances subscribed to the observable instance:
+```ruby
+@product.add_subscription SendPushNotification
+@product.subscriptions #=> [#<SendPushNotification:0x00...>]
+```
+
+To remove observers of a particular class, use `#remove_subscription`:
+```ruby
+@product.add_subscription SendPushNotification
+@product.subscriptions #=> [#<SendPushNotification:0x00...>]
+@product.remove_subscription SendPushNotification
+@product.subscriptions #=> []
+```
+
+Or use `#remove_subscriptions` *(notice the plural)* to, you guessed it, remove **all** observers:
+```ruby
+@product.add_subscription SendPushNotification
+@product.add_subscription MailToMailingList
+@product.add_subscription CreateRecentActivityRecord
+@product.subscriptions #=> [#<SendPushNotification:0x00...>, ...]
+
+@product.remove_subscriptions
+@product.subscriptions #=> []
+```
+
+You can also check if your product is in a modified state by checking if it is `#publishable?`:
+```ruby
+@product.publishable? #=> false
+@product.modified
+@product.publishable? #=> true
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/bottled_observers. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/John-Hayes-Reed/bottled_observers. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 
@@ -40,4 +170,4 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 ## Code of Conduct
 
-Everyone interacting in the BottledObservers project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/bottled_observers/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the BottledObservers project’s codebases, issue trackers, chat rooms and mailing lists is expected to have a beer or two before and enjoy life. Oh yeah and apparently this too: [code of conduct](https://github.com/[USERNAME]/bottled_observers/blob/master/CODE_OF_CONDUCT.md).

data/lib/bottled_observers/bottled_observable.rb

@@ -46,7 +46,6 @@ module BottledObservable
   #   @model.remove_subscriptions
   # @return [void]
   def remove_subscriptions
-    puts 'entered'
     subscriptions.map(&:class).each(&method(:remove_subscription))
   end
 

data/lib/bottled_observers/version.rb

@@ -1,3 +1,3 @@
 module BottledObservers
-  VERSION = :'0.1.0.alpha.1'
+  VERSION = :'0.1.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bottled_observers
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.1
+  version: 0.1.0
 platform: ruby
 authors:
 - John Hayes-Reed
@@ -91,9 +91,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.6.10