Class: ValidatesTimeliness::Formats

Inherits:
Object
  • Object
show all
Defined in:
lib/validates_timeliness/formats.rb

Overview

A date and time format regular expression generator. Allows you to construct a date, time or datetime format using predefined tokens in a string. This makes it much easier to catalogue and customize the formats rather than dealing directly with regular expressions. The formats are then compiled into regular expressions for use validating date or time strings.

Formats can be added or removed to customize the set of valid date or time string values.

Constant Summary collapse

@@time_formats =

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)

All other characters are considered literal. You can embed regexp 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 clsses for safety.

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')

Special Cases:

   yy = 2 or 4 digit year
yyyyy = 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 6 digits

Any other invalid combination of repeating tokens will be swallowed up 
by the next lowest length valid repeating token (e.g. yyy will be
replaced with yy)

[
  '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'
]
@@date_formats = 
[
  'yyyy-mm-dd',
  'yyyy/mm/dd',
  'yyyy.mm.dd',
  'm/d/yy',
  'd/m/yy',
  'm\d\yy',
  'd\m\yy',
  'd-m-yy',
  'd.m.yy',
  'd mmm yy'
]
@@datetime_formats = 
[
  'yyyy-mm-dd hh:nn:ss',
  'yyyy-mm-dd h:nn',
  'yyyy-mm-dd hh:nn:ss.u',
  'm/d/yy h:nn:ss',
  'm/d/yy h:nn_ampm',
  'm/d/yy h:nn',
  'd/m/yy hh:nn:ss',
  'd/m/yy h:nn_ampm',
  'd/m/yy h:nn',
  'ddd, dd mmm yyyy hh:nn:ss (zo|tz)', # RFC 822
  'ddd mmm d hh:nn:ss zo yyyy', # Ruby time string
  'yyyy-mm-ddThh:nn:ss(?:Z|zo)' # iso 8601
]
@@format_tokens =

All tokens available for format construction. The token array is made of token regexp, validation regexp and key for format proc mapping if any. If the token needs no format proc arg then the validation regexp should not have a capturing group, as all captured groups are passed to the format proc.

The token regexp should only use a capture group if ‘look-behind’ anchor is required. The first capture group will be considered a literal and put into the validation regexp string as-is. This is a hack.

[
  { 'd'    => [ /(\A|[^d])d{1}(?=[^d])/, '(\d{1,2})', :day ] }, #/
  { 'ddd'  => [ /d{3,}/, '(\w{3,9})' ] },
  { 'dd'   => [ /d{2,}/, '(\d{2})',   :day ] },
  { 'mmm'  => [ /m{3,}/, '(\w{3,9})', :month ] },
  { 'mm'   => [ /m{2}/,  '(\d{2})',   :month ] },
  { 'm'    => [ /(\A|[^ap])m{1}/, '(\d{1,2})', :month ] },
  { 'yyyy' => [ /y{4,}/, '(\d{4})',   :year ] },
  { 'yy'   => [ /y{2,}/, '(\d{2}|\d{4})', :year ] },
  { 'hh'   => [ /h{2,}/, '(\d{2})',   :hour ] },
  { 'h'    => [ /h{1}/,  '(\d{1,2})', :hour ] },
  { 'nn'   => [ /n{2,}/, '(\d{2})',   :min ]  },
  { 'n'    => [ /n{1}/,  '(\d{1,2})', :min ] },
  { 'ss'   => [ /s{2,}/, '(\d{2})',   :sec ] },
  { 's'    => [ /s{1}/,  '(\d{1,2})', :sec ] },
  { 'u'    => [ /u{1,}/, '(\d{1,6})', :usec ] },
  { 'ampm' => [ /ampm/,  '((?:[aApP])\.?[mM]\.?)', :meridian ] },
  { 'zo'   => [ /zo/,    '(?:[+-]\d{2}:?\d{2})'] },
  { 'tz'   => [ /tz/,    '(?:[A-Z]{1,4})' ] }, 
  { '_'    => [ /_/,     '\s?' ] }
]
@@format_proc_args =

Arguments whichs will be passed to the format proc if matched in the time string. The key must should the key from the format tokens. The array consists of the arry position of the arg, the arg name, and the code to place in the time array slot. The position can be nil which means the arg won’t be placed in the array.

The code can be used to manipulate the arg value if required, otherwise should just be the arg name.

{
  :year     => [0, 'y', 'unambiguous_year(y)'],
  :month    => [1, 'm', 'month_index(m)'],
  :day      => [2, 'd', 'd'],
  :hour     => [3, 'h', 'full_hour(h,md)'],
  :min      => [4, 'n', 'n'],
  :sec      => [5, 's', 's'],
  :usec     => [6, 'u', 'microseconds(u)'],
  :meridian => [nil, 'md', nil]
}

Class Method Summary collapse

Class Method Details

.add_formats(type, *add_formats) ⇒ Object

Adds new formats. Must specify format type and can specify a :before option to nominate which format the new formats should be inserted in front on to take higher precedence. Error is raised if format already exists or if :before format is not found.



193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/validates_timeliness/formats.rb', line 193

def add_formats(type, *add_formats)
  formats = self.send("#{type}_formats")
  options = {}
  options = add_formats.pop if add_formats.last.is_a?(Hash)
  before = options[:before]
  raise "Format for :before option #{format} was not found." if before && !formats.include?(before)
  
  add_formats.each do |format|
    raise "Format #{format} is already included in #{type} formats" if formats.include?(format)

    index = before ? formats.index(before) : -1
    formats.insert(index, format)
  end
  compile_format_expressions
end

.compile_format_expressions ⇒ Object 



154
155
156
157
158
 
# File 'lib/validates_timeliness/formats.rb', line 154

def compile_format_expressions
  @@time_expressions     = compile_formats(@@time_formats)
  @@date_expressions     = compile_formats(@@date_formats)
  @@datetime_expressions = compile_formats(@@datetime_formats)
end

.parse(string, type, strict = true) ⇒ Object

Loop through format expressions for type and call proc on matches. Allow pre or post match strings to exist if strict is false. Otherwise wrap regexp in start and end anchors. Returns 7 part time array.



164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/validates_timeliness/formats.rb', line 164

def parse(string, type, strict=true)
  return string unless string.is_a?(String)
  
  expressions = expression_set(type, string)
  time_array = nil
  expressions.each do |(regexp, processor)|
    regexp = strict || type == :datetime ? /\A#{regexp}\Z/ : (type == :date ? /\A#{regexp}/ : /#{regexp}\Z/)
    if matches = regexp.match(string.strip)
      time_array = processor.call(*matches[1..7])
      break
    end
  end
  return time_array
end

.remove_formats(type, *remove_formats) ⇒ Object

Delete formats of specified type. Error raised if format not found.



180
181
182
183
184
185
186
187
 
# File 'lib/validates_timeliness/formats.rb', line 180

def remove_formats(type, *remove_formats)
  remove_formats.each do |format|
    unless self.send("#{type}_formats").delete(format)
      raise "Format #{format} not found in #{type} formats"
    end
  end
  compile_format_expressions
end

.remove_us_formats ⇒ Object

Removes formats where the 1 or 2 digit month comes first, to eliminate formats which are ambiguous with the European style of day then month. The mmm token is ignored as its not ambigous.



213
214
215
216
217
218
 
# File 'lib/validates_timeliness/formats.rb', line 213

def remove_us_formats
  us_format_regexp = /\Am{1,2}[^m]/
  date_formats.reject! { |format| us_format_regexp =~ format }
  datetime_formats.reject! { |format| us_format_regexp =~ format }
  compile_format_expressions
end