validates_timeliness 2.3.2 → 3.0.0.beta

data/CHANGELOG

@@ -1,7 +1,15 @@
-= 2.3.2 [2010-11-07]
-- Fixed parser for string with timezone offset (thanks sigi)
-- Support for latest I18n interpolation tokens in locale file
-- Fixed parser allowing an hour over 12 for AM meridian
+= 3.0.0.beta
+- Rails 3 and ActiveModel compatibility
+- Uses ActiveModel::EachValidator as validator base class.
+- Configuration settings stored in ValidatesTimeliness module only. ValidatesTimeliness.setup block to configure.
+- Plugin parser is off by default.
+- Method override for parsing and before type cast values is on validated attributes only. Old version handled all date/datetime columns, validates or not. Too intrusive.
+- Add validation helpers to classes using extend_orms config setting. e.g. conf.extend_orms = [ :active_record ]
+- Changed :between option so it is split into :on_or_after and :on_or_before option values. The error message for either failing check will be used instead of a between error message.  
+- Provides :timeliness option key for validates class method. Be sure to pass :type option as well e.g. :type => :date.
+- Allows validation methods to be called on record instances as per ActiveModel API
+- Performs parsing (optional) and raw value caching (before_type_cast) on validated attributes only. It used to be all date, time and datetime attributes.
+- Fix meridian bug where time parsed with hour of 0 or greater than 12 was accepted.
 
 = 2.3.1 [2010-03-19]
 - Fixed bug where custom attribute writer method for date/times were being overriden

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2008 Adam Meehan
+Copyright (c) 2008-2010 Adam Meehan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,62 +1,84 @@
-= validates_timeliness
+= ValidatesTimeliness
 
 * Source:  http://github.com/adzap/validates_timeliness
 * Bugs:    http://github.com/adzap/validates_timeliness/issues
 
-== DESCRIPTION:
+== Description
 
-Validate dates, times and datetimes for Rails 2.x. Plays nicely with Rails
-automatic timezone handling. Allows you to add custom formats or remove defaults
-easily. This allows you to control what you think should be a valid date or
-time string.
+Validate dates, times and datetimes for Rails 3.x and ActiveModel.
 
+If you a looking for the old version for Rails 2.x go here[http://github.com/adzap/validates_timeliness/tree/v2.3].
 
-== FEATURES:
 
-* Adds ActiveRecord validation for dates, times and datetimes
+== Features
 
-* Add or remove date/time formats to customize validation
+* Adds ActiveModel validation for dates, times and datetimes
 
-* Create new formats using very simple date/time format tokens
+* Should work with any ORM using ActiveModel
 
-* Restores ability to see raw value entered for date/time attributes with
-  _before_type_cast modifier, which was lost in Rails 2.1.
+* Supports timezone handling
 
-* Supports Rails timezone handling
+* Supports I18n for the error messages
 
-* Supports Rails I18n for the error messages
+* Adds before_type_cast method on validated attributes, if ORM supports it.
 
-* Rspec matcher for testing model validation of dates and times
 
+== Installation
 
-== INSTALLATION:
+As plugin (from master)
 
-As gem
+  rails plugin install git://github.com/adzap/validates_timeliness.git
 
-  gem install validates_timeliness -v '~> 2.3'
+As gem (not working as yet)
 
-  # in environment.rb
+  # in Gemfile
+  gem 'validates_timeliness'
 
-  config.gem 'validates_timeliness', :version => '~> 2.3'
+  # Run bundler
+  $ bundle install
 
-As plugin (from master)
+Then run
+  
+  $ rails generate validates_timeliness:install
+
+This creates configuration initializer and locale files. In the initializer, you there are a number of config options to customize the plugin.
+
+  ValidatesTimeliness.setup do |config|
+
+    # Add plugin to supported ORMs (only :active_record for now)
+    # config.extend_orms = [ :active_record ]
+
+  end
+
+By default the plugin extends ActiveRecord if present. Currently ActiveRecord is the only ORM included for extension. If you wish to extend
+another ORM then look at the {wiki page}[http://github.com/adzap/validates_timeliness/wiki/ORM-Support] for more information.
+
+To extend other ORMs is pretty straight forward. It's matter of hooking into a couple of methods, being the attribute method generation and 
+timezone handling of validated attributes. However, the plugin must support the ActiveModel validations system. If you extend an ORM 
+successfully, please send me a pull request to add the shim to the plugin or let me know where to find it.
 
-  ./script/plugin install git://github.com/adzap/validates_timeliness.git -r v2.3
 
-== USAGE:
+== Usage:
 
 To validate a model with a date, time or datetime attribute you just use the
 validation method
 
   class Person < ActiveRecord::Base
-    validates_date :date_of_birth
-
+    validates_date :date_of_birth, :on_or_before => lambda { Date.today }
+    # or
+    validates :date_of_birth, :timeliness => {:on_or_before => lambda { Date.today }, :type => date}
   end
 
+  # or even on a specific record, per ActiveModel API.
+
+  @person.validates_date :date_of_birth, :on_or_before => lambda { Date.today }
+
+
 The list of validation methods available are as follows:
   validates_date     - validate value as date
   validates_time     - validate value as time only i.e. '12:20pm'
   validates_datetime - validate value as a full date and time
+  validates          - use the :timeliness key and set the type in the hash.
 
 The validation methods take the usual options plus some specific ones to restrict
 the valid range of dates or times allowed
@@ -67,7 +89,8 @@ Temporal options (or restrictions):
   :on_or_before - Attribute must be equal to or before this value to be valid
   :after        - Attribute must be after this value to be valid
   :on_or_after  - Attribute must be equal to or after this value to be valid
-  :between      - Attribute must be between the values to be valid. Takes an array of two values or a range
+  :between      - Attribute must be between the values to be valid. Range or Array of 2 values. 
+                  Uses :on_or_after and :on_of_before for error messages on lower and upper bounds respectively.
 
 Regular validation options:
   :allow_nil    - Allow a nil value to be valid
@@ -76,327 +99,162 @@ Regular validation options:
   :unless       - Execute validation when :unless evaluates false
 
 Special options:
-  :with_time    - Validate a date attribute value combined with a time value against any temporal restrictions
-  :with_date    - Validate a time attribute value combined with a date value against any temporal restrictions
   :ignore_usec  - Ignores microsecond value on datetime restrictions
-  :format       - Limit validation to a single format for special cases. Takes plugin format value.
-
-Message options: - Use these to override the default error messages
-  :invalid_date_message
-  :invalid_time_message
-  :invalid_datetime_message
-  :is_at_message
-  :before_message
-  :on_or_before_message
-  :after_message
-  :on_or_after_message
-  :between_message
-
-The temporal restrictions, with_date and with_time can take 4 different value types:
-* String value
+  :format       - Limit validation to a single format for special cases. Requires plugin parser.
+
+The temporal restrictions can take 4 different value types:
+
 * Date, Time, or DateTime object value
-* Proc or lambda object which may take an optional parameter being the record object
-* A symbol matching the method name in the model
+* Proc or lambda object which may take an optional parameter, being the record object
+* A symbol matching a method name in the model
+* String value
 
 When an attribute value is compared to temporal restrictions, they are compared as
 the same type as the validation method type. So using validates_date means all
-values are compared as dates. This is except in the case of with_time and with_date
-options which effectively force the value to validated as a datetime against the
-temporal options.
-
-== EXAMPLES:
-
-  validates_date :date_of_birth :before => lambda { 18.years.ago },
-                                :before_message => "must be at least 18 years old"
-
-  validates_time :breakfast_time, :on_or_after => '6:00am',
-                                  :on_or_after_message => 'must be after opening time',
-                                  :before => :second_breakfast_time,
-                                  :allow_nil => true
-
-  validates_datetime :appointment_date, :before => lambda { 1.week.from_now }
-
-  validates_date :entry_date, :with_time => '17:00', :on_or_before => :competition_closing
-
-
-=== DATE/TIME FORMATS:
-
-So what formats does the plugin allow. Well there are default formats which can
-be added to easily using the plugins format rules. Also formats can be easily
-removed without hacking the plugin at all.
-
-Below are the default formats. If you think they are easy to read then you will
-be happy to know that is exactly the format you can use to define your own if
-you want. No complex regular expressions or duck punching (monkey patching) the
-plugin is needed.
-
-==== Time formats:
-  hh:nn:ss
-  hh-nn-ss
-  h:nn
-  h.nn
-  h nn
-  h-nn
-  h:nn_ampm
-  h.nn_ampm
-  h nn_ampm
-  h-nn_ampm
-  h_ampm
-
-NOTE: Any time format without a meridian token (the 'ampm' token) is considered in 24 hour time.
-
-==== Date formats:
-  yyyy/mm/dd
-  yyyy-mm-dd
-  yyyy.mm.dd
-  m/d/yy  OR  d/m/yy
-  m\d\yy  OR  d\m\yy
-  d-m-yy
-  d.m.yy
-  d mmm yy
-
-NOTE: To use non-US date formats see US/EURO FORMATS section
-
-==== Datetime formats:
-  m/d/yy h:nn:ss   OR  d/m/yy hh:nn:ss
-  m/d/yy h:nn      OR  d/m/yy h:nn
-  m/d/yy h:nn_ampm OR  d/m/yy h:nn_ampm
-  yyyy-mm-dd hh:nn:ss
-  yyyy-mm-dd h:nn
-  ddd mmm d hh:nn:ss zo yyyy # Ruby time string
-  yyyy-mm-ddThh:nn:ssZ  # ISO 8601 without zone offset
-  yyyy-mm-ddThh:nn:sszo # ISO 8601 with zone offset
-
-NOTE: To use non-US date formats see US/EURO FORMATS section
+values are compared as dates.
 
-Here is what each format token means:
 
-  Format tokens:
-       y = year
-       m = month
-       d = day
-       h = hour
-       n = minute
-       s = second
-       u = micro-seconds
-    ampm = meridian (am or pm) with or without dots (e.g. am, a.m, or a.m.)
-       _ = optional space
-      tz = Timezone abbreviation (e.g. UTC, GMT, PST, EST)
-      zo = Timezone offset (e.g. +10:00, -08:00, +1000)
+== Configuration
 
-  Repeating tokens:
-       x = 1 or 2 digits for unit (e.g. 'h' means an hour can be '9' or '09')
-      xx = 2 digits exactly for unit (e.g. 'hh' means an hour can only be '09')
+=== Error Messages
 
-  Special Cases:
-      yy = 2 or 4 digit year
-    yyyy = exactly 4 digit year
-     mmm = month long name (e.g. 'Jul' or 'July')
-     ddd = Day name of 3 to 9 letters (e.g. Wed or Wednesday)
-       u = microseconds matches 1 to 3 digits
+Using the I18n system to define new defaults:
 
-All other characters are considered literal. For the technically minded
-(well you are developers), these formats are compiled into regular expressions
-at runtime so don't add any extra overhead than using regular expressions
-directly. So, no, it won't make your app slow!
+  en:
+    errors:
+      messages:
+        invalid_date: "is not a valid date"
+        invalid_time: "is not a valid time"
+        invalid_datetime: "is not a valid datetime"
+        is_at: "must be at %{restriction}"
+        before: "must be before %{restriction}"
+        on_or_before: "must be on or before %{restriction}"
+        after: "must be after %{restriction}"
+        on_or_after: "must be on or after %{restriction}"
 
-To see all defined formats look in lib/validates_timeliness/formats.rb.
+The %{restriction} signifies where the interpolation value for the restriction will be inserted.
 
-=== US/EURO FORMATS
+You can also use validation options for custom error messages. The following option keys are available:
 
-The perenial problem for non-US developers or applications not primarily for the
-US, is the US date format of m/d/yy. This is ambiguous with the European format
-of d/m/yy. By default the plugin uses the US formats as this is the Ruby default
-when it does date interpretation, and is in keeping PoLS (principle of least
-surprise).
+    :invalid_date_message
+    :invalid_time_message
+    :invalid_datetime_message
+    :is_at_message
+    :before_message
+    :on_or_before_message
+    :after_message
+    :on_or_after_message
 
-To switch to using the European (or Rest of The World) formats put this in an
-initializer or environment.rb
+Note: There is no :between_message option. The between error message should be defined using the :on_or_before and :on_or_after messages.
 
-  ValidatesTimeliness::Formats.remove_us_formats
+It is highly recommended you use the I18n system for error messages.
 
-Now '01/02/2000' will be parsed as 1st February 2000, instead of 2nd January 2000.
 
-=== CUSTOMISING FORMATS:
+=== Plugin Parser
 
-I hear you say "Thats greats but I don't want X format to be valid". Well to
-remove a format stick this in an initializer file
+The plugin comes with a customisable date and time parser. You can add or remove valid formats
+for dates, times, and datetimes. It is also more strict than the Ruby parser, which means it 
+won't accept day of the month if it's not a valid number for that month.
 
-  ValidatesTimeliness::Formats.remove_formats(:date, 'm\d\yy')
+By default the parser is switched off. To switch it on:
 
-Done! That format is no longer considered valid. Easy!
+  # in the setup block
+  config.use_plugin_parser = true
 
-Ok, now I hear you say "Well I have format that I want to use but you don't have it".
-Ahh, then add it yourself. Again stick this in an initializer file
+See the wiki[http://github.com/adzap/validates_timeliness/wiki/Plugin-Parser] for all the details about the parser.
 
-  ValidatesTimeliness::Formats.add_formats(:time, "d o'clock")
 
-Now "10 o'clock" will be a valid value. So easy, no more whingeing!
+=== Restriction Option Shorthand
 
-You can embed regular expressions in the format but no gurantees that it will
-remain intact. If you avoid the use of any token characters and regexp dots or
-backslashes as special characters in the regexp, it may well work as expected.
-For special characters use POSIX character classes for safety. See the ISO 8601
-datetime for an example of an embedded regular expression.
+It is common to restrict an attribute to being on or before the current time or current day. 
+To specify this you need to use a lambda as an option value e.g. <tt>lambda { Time.now }</tt>.
+This can be tedious noise amongst your validations for something so common. To combat this the
+plugin allows you to use shorthand symbols for often used relative times or dates.
 
-Because formats are evaluated in order, adding a format which may be ambiguous
-with an existing format, will mean your format is ignored. If you need to make
-your new format higher precedence than an existing format, you can include the
-before option like so
+Just provide the symbol as the option value like so:
 
-  ValidatesTimeliness::Formats.add_formats(:time, 'ss:nn:hh', :before => 'hh:nn:ss')
+  validates_date :birth_date, :on_or_before => :today
 
-Now a time of '59:30:23' will be interpreted as 11:30:59 pm. This option saves
-you adding a new one and deleting an old one to get it to work.
+The :today symbol is evaluated as <tt>lambda { Date.today }</tt>. The :now and :today
+symbols are pre-configured. Configure your own like so:
 
+  # in the setup block
+  config.restriction_shorthand_symbols.update(
+    :yesterday => lambda { 1.day.ago }
+  )
 
-=== AMBIGUOUS YEAR THRESHOLD
 
-When dealing with 2 digit year values, by default a year is interpreted as being
-in the last century at or above 30. You can customize this however
+=== Default Timezone
 
-  ValidatesTimeliness::Formats.ambiguous_year_threshold = 20
+The plugin needs to know the default timezone you are using when parsing or type casting values. If you are using
+ActiveRecord then the default is automatically set to the same default zone as ActiveRecord. If you are using 
+another ORM you may need to change this setting.
 
-Now you get:
+  # in the setup block
+  config.default_timezone = :utc
 
-  year of 19 is considered 2019
-  year of 20 is considered 1920
+By default it will be UTC if ActiveRecord is not loaded.
 
 
-=== DUMMY DATE FOR TIME TYPES
+=== Dummy Date For Time Types
 
 Given that Ruby has no support for a time-only type, all time type columns are evaluated
 as a regular Time class objects with a dummy date value set. Rails defines the dummy date as
 2000-01-01. So a time of '12:30' is evaluated as a Time value of '2000-01-01 12:30'. If you
 need to customize this for some reason you can do so as follows
 
-  ValidatesTimeliness::Formats.dummy_date_for_time_type = [2009, 1, 1]
+  # in the setup block
+  config.dummy_date_for_time_type = [2009, 1, 1]
 
 The value should be an array of 3 values being year, month and day in that order.
 
 
-=== TEMPORAL RESTRICTION ERRORS:
+=== Temporal Restriction Errors
 
 When using the validation temporal restrictions there are times when the restriction
-value itself may be invalid. Normally this will add an error to the model such as
-'restriction :before value was invalid'. These can be annoying if you are using
-procs or methods as restrictions and don't care if they don't evaluate properly
-and you want the validation to complete. In these situations you turn them off.
-
-To turn them off:
+option value itself may be invalid. This will add an error to the model such as
+'Error occurred validating birth_date for :before restriction'. These can be annoying
+in development or production as you most likely just want to skip the option if no
+valid value was returned. By default these errors are displayed in Rails test mode.
 
-  ValidatesTimeliness::Validator.ignore_restriction_errors = true
+To turn them on/off:
 
-A word of warning though, as this may hide issues with the model and make those
-corner cases a little harder to test. In general if you are using procs or
-model methods and you only care when they return  a value, then they should
-return nil in all other situations. Restrictions are skipped if they are nil.
+  # in the setup block
+  config.ignore_restriction_errors = true
 
 
-=== DISPLAY INVALID VALUES IN DATE HELPERS:
+=== Display Invalid Values in Select Helpers
 
-The plugin has some extensions to ActionView and ActiveRecord by allowing invalid
+The plugin offers an extension for ActionView to allowing invalid
 date and time values to be redisplayed to the user as feedback, instead of
 a blank field which happens by default in Rails. Though the date helpers make this a
-pretty rare occurence, given the select dropdowns for each date/time component, but
+pretty rare occurrence, given the select dropdowns for each date/time component, but
 it may be something of interest.
 
 To activate it, put this in an initializer:
 
-  ValidatesTimeliness.enable_datetime_select_extension!
-
-This will be removed from v3 as it adds too little to maintain.
-
-=== OTHER CUSTOMISATION:
-
-The error messages for each temporal restrictions can also be globally overridden by
-updating the default AR error messages like so
-
-For Rails 2.0/2.1:
-
-  ActiveRecord::Errors.default_error_messages.update(
-    :invalid_date     => "is not a valid date",
-    :invalid_time     => "is not a valid time",
-    :invalid_datetime => "is not a valid datetime",
-    :is_at            => "must be at %s",
-    :before           => "must be before %s",
-    :on_or_before     => "must be on or before %s",
-    :after            => "must be after %s",
-    :on_or_after      => "must be on or after %s",
-    :between          => "must be between %s and %s"
-  )
-
-Where %s is the interpolation value for the restriction.
-
-Rails 2.2+ using the I18n system to define new defaults:
-
-  en:
-    activerecord:
-      errors:
-        messages:
-          invalid_date: "is not a valid date"
-          invalid_time: "is not a valid time"
-          invalid_datetime: "is not a valid datetime"
-          is_at: "must be at {{restriction}}"
-          before: "must be before {{restriction}}"
-          on_or_before: "must be on or before {{restriction}}"
-          after: "must be after {{restriction}}"
-          on_or_after: "must be on or after {{restriction}}"
-          between: "must be between {{earliest}} and {{latest}}"
-
-The {{restriction}} signifies where the interpolation value for the restriction
-will be inserted.
-
-And for something a little more specific you can override the format of the interpolation
-values inserted in the error messages for temporal restrictions like so
-
-For Rails 2.0/2.1:
-
-  ValidatesTimeliness::Validator.error_value_formats.update(
-    :time     => '%H:%M:%S',
-    :date     => '%Y-%m-%d',
-    :datetime => '%Y-%m-%d %H:%M:%S'
-  )
-
-Rails 2.2+ using the I18n system to define new defaults:
-
-  validates_timeliness:
-    error_value_formats:
-      date: '%Y-%m-%d'
-      time: '%H:%M:%S'
-      datetime: '%Y-%m-%d %H:%M:%S'
-
-Those are Ruby strftime formats not the plugin formats.
+  # in the setup block
+  config.enable_date_time_select_extension!
 
 
-=== RSPEC MATCHER:
+=== Strict Parsing for Select Helpers
 
-To sweeten the deal that little bit more, you have an Rspec matcher available for
-you model specs. Now you can easily test the validations you have just written
-with the plugin or better yet *before* you write them! You just use the
-validation options you want as you would with the validation method. Those
-options are then verified and reported if they fail.
-
-First require it in your spec_helper.rb
-
-  require 'validates_timeliness/matcher'
-
-Use it like so:
-
-  @person.should validate_date(:birth_date, :before => Time.now, :before_message => 'should be before today')
+When using date/time select helpers, the component values are handled by ActiveRecord using
+the Time class to instantiate them into a time value. But this mean that some invalid dates,
+such as 31st June, are shifted forward and treated as valid. To handle these cases in a strict
+way you can enable the plugin handler to treat them as invalid dates.
 
+To activate it, put this in an initializer:
 
-The matcher names are just the singular of the validation methods.
+  # in the setup block
+  config.enable_multiparameter_extension!
 
-== CREDITS:
 
-* Adam Meehan (adam.meehan@gmail.com, http://duckpunching.com/)
+== Credits
 
-* Jonathan Viney (http://workingwithrails.com/person/4985-jonathan-viney)
-  For his validates_date_time plugin which I have used up until this plugin and
-  which influenced some of the design and I borrowed a little of code from it.
+* Adam Meehan (adam.meehan@gmail.com, http://github.com/adzap)
 
 
-== LICENSE:
+== License
 
 Copyright (c) 2008-2010 Adam Meehan, released under the MIT license