Class: ValidatesTimeliness::Formats

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

Overview

A date and time parsing library which allows you to add custom formats using simple predefined tokens. This makes it much easier to catalogue and customize the formats rather than dealing directly with regular expressions.

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
 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 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 h:nn_ampm',
  '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:ssZ', # iso 8601 without zone offset
  'yyyy-mm-ddThh:nn:sszo' # iso 8601 with zone offset
]
@@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{4}|\d{2})', :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})', :offset ] },
  { 'tz'   => [ /tz/,    '(?:[A-Z]{1,4})' ] },
  { '_'    => [ /_/,     '\s?' ] }
]
@@format_proc_args =

Arguments which will be passed to the format proc if matched in the time string. The key must be 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)'],
  :offset   => [7,   'z', 'offset_in_seconds(z)'],
  :meridian => [nil, 'md', nil]
}

Class Method Summary collapse

Class Method Details

.abbr_month_names ⇒ Object 



282
283
284
 
# File 'lib/validates_timeliness/formats.rb', line 282

def abbr_month_names
  defined?(I18n) ? I18n.t('date.abbr_month_names') : Date::ABBR_MONTHNAMES
end

.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.



228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/validates_timeliness/formats.rb', line 228

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 



175
176
177
178
179
 
# File 'lib/validates_timeliness/formats.rb', line 175

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

.full_hour(hour, meridian) ⇒ Object 



254
255
256
257
258
259
260
261
262
 
# File 'lib/validates_timeliness/formats.rb', line 254

def full_hour(hour, meridian)
  hour = hour.to_i
  return hour if meridian.nil?
  if meridian.delete('.').downcase == 'am'
    hour == 12 ? 0 : hour
  else
    hour == 12 ? hour : hour + 12
  end
end

.microseconds(usec) ⇒ Object 



286
287
288
 
# File 'lib/validates_timeliness/formats.rb', line 286

def microseconds(usec)
  (".#{usec}".to_f * 1_000_000).to_i
end

.month_index(month) ⇒ Object 



273
274
275
276
 
# File 'lib/validates_timeliness/formats.rb', line 273

def month_index(month)
  return month.to_i if month.to_i.nonzero?
  abbr_month_names.index(month.capitalize) || month_names.index(month.capitalize)
end

.month_names ⇒ Object 



278
279
280
 
# File 'lib/validates_timeliness/formats.rb', line 278

def month_names
  defined?(I18n) ? I18n.t('date.month_names') : Date::MONTHNAMES
end

.offset_in_seconds(offset) ⇒ Object 



290
291
292
293
294
295
 
# File 'lib/validates_timeliness/formats.rb', line 290

def offset_in_seconds(offset)
  sign = offset =~ /^-/ ? -1 : 1
  parts = offset.scan(/\d\d/).map {|p| p.to_f }
  parts[1] = parts[1].to_f / 60
  (parts[0] + parts[1]) * sign * 3600
end

.parse(string, type, options = {}) ⇒ 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 time array if matches a format, nil otherwise.



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/validates_timeliness/formats.rb', line 185

def parse(string, type, options={})
  return string unless string.is_a?(String)
  options.reverse_merge!(:strict => true)

  sets = if options[:format]
    options[:strict] = true
    [ send("#{type}_expressions").assoc(options[:format]) ]
  else
    expression_set(type, string)
  end

  matches = nil
  processor = sets.each do |format, regexp, proc|
    full = /\A#{regexp}\Z/ if options[:strict]
    full ||= case type
    when :date     then /\A#{regexp}/
    when :time     then /#{regexp}\Z/
    when :datetime then /\A#{regexp}\Z/
    end
    break(proc) if matches = full.match(string.strip)
  end
  last = options[:include_offset] ? 8 : 7
  if matches
    values = processor.call(*matches[1..last])
    values[0..2] = dummy_date_for_time_type if type == :time
    return values
  end
end

.remove_formats(type, *remove_formats) ⇒ Object

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



215
216
217
218
219
220
221
222
 
# File 'lib/validates_timeliness/formats.rb', line 215

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.



247
248
249
250
251
252
 
# File 'lib/validates_timeliness/formats.rb', line 247

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

.unambiguous_year(year) ⇒ Object 



264
265
266
267
268
269
270
271
 
# File 'lib/validates_timeliness/formats.rb', line 264

def unambiguous_year(year)
  if year.length <= 2
    century = Time.now.year.to_s[0..1].to_i
    century -= 1 if year.to_i >= ambiguous_year_threshold
    year = "#{century}#{year.rjust(2,'0')}"
  end
  year.to_i
end