date_parity 0.0.2 → 0.0.3

data/README.md

@@ -1,10 +1,53 @@
-# DateParity
+# Date Parity
 
-Consistent date formatting and parsing for Rails applications. Creates parity between date.to\_s and
- string.to\_date in Rails applications.
+Date formatting and parsing per request in Rails with parity between date.to\_s.and string.to\_date.
 
-This is implemented with a "Date.format" syntax and usage, similar to "Time.zone" in rails. This can be 
-set per request (i.e. per user) in a controller before or around filter.
+Rails already has some great Date formatting and parsing options available. For example, Date.DATE\_FORMATS makes it easy to configure and reuse common formats for your application. But, other then the :default it require an explicit field.to\_s(:format) to be applied. Additionally, nothing happens automatically when parsing those dates back from user edits. This generally require some explicit steps per field in your model or controller. 
+
+Rails also provides the ability to localize your Date formats. But, that requires decisions made for all users in a particular locale.
+
+Often, we need to allow users, companies, organizations, etc. the ability to choose preferred date formats. Both of the Rails standard approaches using Date.DATE\_FORMATS or localization fall short at making that easy. You end up writing a lot helpers around date fields, and code to normalize posted date values. 
+ 
+This is where date\_parity helps. It is implemented by setting a `Date.format` string, similar to a per user `Time.zone` in Rails. This can be set per request (i.e. per user) in a controller's before\_filter or around\_filter.
+
+For example:
+```ruby
+Date.format = "%m/%d/%Y"
+date = "12/31/2012".to_date
+=> Mon, 31 Dec 2012
+date.to_s
+=> "12/31/2012"
+
+Date.format = "%d/%m/%Y"
+date = "31/12/2012".to_date
+=> Mon, 31 Dec 2012
+date.to_s
+=> "31/12/2012"
+
+Date.format = '%Y-%m-%d'
+date = "2012-12-31".to_date
+=> Mon, 31 Dec 2012
+date.to_s
+=> "2012-12-31"
+
+Date.format = '%d.%m.%Y'
+date = "31.12.2012".to_date
+=> Mon, 31 Dec 2012
+date.to_s
+=> "31.12.2012"
+
+Date.format = '%Y.%m.%d'
+date = "2012.12.31".to_date
+=> Mon, 31 Dec 2012
+date.to_s
+=> "2012.12.31"
+
+Date.format = '%Y/%m/%d'
+date = "2012/12/31".to_date
+=> Mon, 31 Dec 2012
+date.to_s
+=> "2012/12/31"
+```
 
 ## Installation
 
@@ -22,41 +65,37 @@ Or install it yourself as:
 
 ## Usage
 
-In Rails controller before\_filter:
-Date.format = '%m/%d/%Y'
-
-or from a persisted field that stores the desired format:
-Date.format = current\_user.date\_format 
-
-In any view assuming @model\_created\_on is a date, and Date.format
-was set as above:
-<%=@modele.created\_on  %>
-=> 12/31/2012 
-
-And then you get parity when a form with this field is posted. 
-Rails will attempt to convert the posted string value of "12/31/2012"
-using Date.\_parse, which DateParity overrides and respects your Date.format. 
-Without DateParity gem, @model.start\_on would have ended up nil because 
-"12/31/2012" is invalid argument Ruby Date.\_parse. However, when date\_parity is 
-included, Date will use the format string stored on Date.format
-(if it exist) to correctly parse "12/31/2012", as December 31, 2012, when 
-Date.format = "%m/%d/%Y" 
-
-Note: Rails text\_field form helper uses @model.attribute\before\_type\_cast by default.
-When using date\_parity on plain text fields, you will probably want to set your value
-to explicitly use @model.attribute if it exists. Otherwise, you won't see the formatted
-date field:
-For example:
-<%= f.text_field :created_on, :value => @user.created\_on ||  @user.created\_on\_before\_type\_cast %>
-
-Date.format can be set to any date format that is parsable by strptime. 
-For example, the following are all valid:<br>
-    Date.format = "%m/%d/%Y"<br>
-    Date.format = "%d/%m/%Y"<br>
-    Date.format = '%Y-%m-%d'<br>
-    Date.format = '%d.%m.%Y'<br>
-    Date.format = '%Y.%m.%d'<br>
-    Date.format = '%Y/%m/%d'<br>
+In a Rails controller before\_filter:
+```Date.format = '%m/%d/%Y'```
+
+Generally, you will want to set that string based on user preference, as in:
+```Date.format = current_user.date_format```
+
+Then in any view assuming @model\_started\_on is a date field, and Date.format was set as above to '%m/%d/%Y':
+```ruby
+<%=@modele.started_on  %>
+#=> '12/31/2012' 
+```
+
+And then you get parity when a form with this field is posted. Rails will attempt to convert the posted string value of "12/31/2012" using Date.\_parse, which DateParity overrides and respects your Date.format.  
+
+Without the date\_parity gem, @model.start\_on would have ended up nil because "12/31/2012" is an invalid argument for ruby Date.\_parse. However, when date\_parity is included, Date will use the format string set on Date.format to correctly parse "12/31/2012", as December 31, 2012, when Date.format = "%m/%d/%Y". 
+
+Note: Rails text\_field form helper uses ```@model.attribute_before_type_cast``` by default.  When using date\_parity on plain text fields, you will probably want to set your value to explicitly use @model.attribute if it exists. Otherwise, you won't see the formatted date field: For example:
+```ruby 
+<%= f.text_field :start_on, :value => @user.started_on ||  @user.started_on_before_type_cast %>
+```
+
+Date.format can be set to any date format that can be parsed by strptime. 
+For example, the following are all valid:
+```ruby
+Date.format = "%m/%d/%Y"
+Date.format = "%d/%m/%Y"
+Date.format = '%Y-%m-%d'
+Date.format = '%d.%m.%Y'
+Date.format = '%Y.%m.%d'
+Date.format = '%Y/%m/%d'
+```
 
 ## Contributing
 

data/date_parity.gemspec

@@ -7,8 +7,8 @@ Gem::Specification.new do |gem|
 
   gem.author       = 'Scott Stewart'
   gem.email         = 'scottpstewart@gamil.com'
-  gem.description   = 'Consistent date formatting done simple'
-  gem.summary       = 'Consistent date formatting done simple'
+  gem.description   = 'Rails Date formatting and parsing with full parity between date.to_s.and string.to_date per request.'
+  gem.summary       = 'Rails Date formatting and parsing with full parity between date.to_s.and string.to_date per request.'
   gem.homepage      = ""
 
   gem.add_dependency 'activesupport', '>= 3.2'

data/lib/date_parity/version.rb

@@ -1,3 +1,3 @@
 module DateParity
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: date_parity
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-13 00:00:00.000000000 Z
+date: 2012-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70261701192120 !ruby/object:Gem::Requirement
+  requirement: &70323438102960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '3.2'
   type: :runtime
   prerelease: false
-  version_requirements: *70261701192120
+  version_requirements: *70323438102960
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70261701191700 !ruby/object:Gem::Requirement
+  requirement: &70323438102540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70261701191700
+  version_requirements: *70323438102540
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &70261701191240 !ruby/object:Gem::Requirement
+  requirement: &70323438102080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,8 +43,9 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70261701191240
-description: Consistent date formatting done simple
+  version_requirements: *70323438102080
+description: Rails Date formatting and parsing with full parity between date.to_s.and
+  string.to_date per request.
 email: scottpstewart@gamil.com
 executables: []
 extensions: []
@@ -75,7 +76,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2984063008747520348
+      hash: -101513963914939075
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -84,13 +85,14 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2984063008747520348
+      hash: -101513963914939075
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
-summary: Consistent date formatting done simple
+summary: Rails Date formatting and parsing with full parity between date.to_s.and
+  string.to_date per request.
 test_files:
 - test/date_parity_test.rb
 - test/lib/date_parity/test_helper.rb