birthday 0.1.0 → 0.1.1

data/README.md

@@ -4,19 +4,78 @@ This is a small gem that hooks into ActiveRecord and allows to tag a database fi
 
 ## How To Install
 
-After the gem has been properly tested, it will be released on RubyGems, and will be available to be installed with:
+To install this gem, fire this command from your terminal:
 
     gem install birthday
 
-or in your Gemfile:
+or add this line to your Gemfile:
 
     gem 'birthday', '~> 0.1.0'
 
 ## Synopsis
 
-Read [a blog post about the gem](http://blog.railslove.com/2011/10/17/birthday-gem-easy-anniversaries-handling-ruby/) at Railslove blog to get a comprehensive guide to usage of this gem.
+After installing this gem, you are able to work with anniversaries, such as birthdays in such a manner:
 
-You can create your own adapters for the ORM adapters we're not supporting yet by writing a class with a class method `scope_hash`, which will return a hash normally used in `active_record` scopes.
+    class User < ActiveRecord::Base
+    
+      acts_as_birthday :birthday
+    
+    end
+
+Add `acts_as_birthday :field_name` to your ActiveRecord model (or symbols for multiple fields, if you need to), and right away you can access methods:
+
+* `birthday_age` - which will calculate current anniversary/age from the point in time,
+* `birthday_today?` - which will return true or false, depending on whether the anniversary happens today.
+
+### Created instance methods
+
+If you add more fields to `acts_as_birthday` method, like:
+
+    acts_as_birthday :birthday, :anniversary, :something_else
+
+it will automatically create methods: `birthday_age`, `birthday_today?`, `anniversary_age`, `anniversary_today?`, `something_else_age`, `something_else_today?`.
+
+### Created scopes
+
+On top of that you get useful scopes: `find_birthdays_for`, `find_anniversaries_for` and `find_something_elses_for`.
+
+These scopes accept maximum of two parameters, which have to respond to method `to_date` (by default objects of class Date, Time and DateTime). Thanks to these now you can search for birthdays...
+
+* on a specific date:
+
+        > User.find_birthdays_for(Date.parse('04-04-2000'))
+         => [#<User id: 23, birthday: "1961-04-04">, #<User id: 34, birthday: "1985-04-04">]
+
+* between a specific range:
+
+        > User.find_birthdays_for(Date.parse('04-04-2000'), Date.parse('05-04-2000'))
+         => [#<User id: 23, birthday: "1961-04-04">, #<User id: 34, birthday: "1985-04-04">, #<User id: 56, birthday: "1976-04-24">, #<User id: 57, birthday: "1958-04-30">, #<User id: 60, birthday: "1986-05-04">]
+
+* and even at the turn of the years:
+
+        # This will search for birthdays between 12.12 and 3.01
+        > User.find_birthdays_for(Date.parse('12-12-2000'), Date.parse('03-01-2001'))
+         => [#<User id: 1, birthday: "1961-12-14">, #<User id: 12, birthday: "1985-12-15">, #<User id: 25, birthday: "1961-12-24">, #<User id: 27, birthday: "1985-01-01">, #<User id: 40, birthday: "1961-01-02">]
+
+Since all these are essentially scopes, there's nothing stopping you from chaining them with other scopes:
+
+    class User < ActiveRecord::Base
+    
+      acts_as_birthday :birthday
+    
+      scope :admins, {:is_admin => true}
+      scope :named_like, lambda { |name| { :conditions => [ "first_name LIKE :q OR email LIKE :q OR last_name LIKE :q", { :q => "%#{name}%" } ] } }
+    
+    end
+    
+    
+    > User.admins.named_like("Mike").find_birthdays_for(Date.parse('12-12-2000'), Date.parse('03-01-2001'))
+
+### Your own adapters
+
+At this moment, this gem supports only MySQL and PostgreSQL databases. If you want to support another type of database (perhaps SQLite), you can write your own adapter.
+
+You can create your own birthday adapters for the ORM adapters we're not supporting yet by writing a class with a class method `scope_hash`, which will return a hash normally used in `active_record` scopes.
 
     module Railslove
       module Acts
@@ -36,6 +95,8 @@ You can create your own adapters for the ORM adapters we're not supporting yet b
 
 With this namespacing (`Railslove::Acts::Birthday::Adapter`) and naming the class after `active_record`'s ORM adapter (like `SqliteAdapter` in the example above) you can automatically use your own adapters with this gem.
 
+If you happen to write one of the adapters, don't hesitate to [make a pull request](https://github.com/railslove/birthday/pull/new/master)! You will help the whole Ruby community with it!
+
 ### To do
 
 * kick class_eval?
@@ -58,6 +119,11 @@ Copyright (c) 2011 Railslove
 * [@Holek (Mike Połtyn)](http://github.com/Holek)
 * [@Bumi (Michael Bumann)](http://github.com/bumi)
 
+## External links
+
+* [Railslove blog post about the usage of this gem](http://blog.railslove.com/2011/10/17/birthday-gem-easy-anniversaries-handling-ruby/)
+* [Rubygems.org site for `birthday` gem](http://rubygems.org/gems/birthday)
+
 ## License
 
 The MIT License

data/lib/railslove/acts/birthday/birthday.rb

@@ -2,6 +2,7 @@
 module Railslove
   module Acts #:nodoc:
     module Birthday #:nodoc:
+      autoload :Adapter, 'railslove/acts/birthday/adapter'
 
       def self.included(base)
         base.extend ClassMethods

data/lib/railslove/acts/birthday/version.rb

@@ -1,7 +1,7 @@
 module Railslove
   module Acts
     module Birthday
-      VERSION = "0.1.0"
+      VERSION = "0.1.1"
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: birthday
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: 
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - "Mike Po\xC5\x82tyn"
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-11-18 00:00:00 Z
+date: 2011-11-23 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rake