Module Chronic
In: lib/chronic.rb
lib/chronic/chronic.rb
lib/chronic/grabber.rb
lib/chronic/handler.rb
lib/chronic/handlers.rb
lib/chronic/mini_date.rb
lib/chronic/numerizer.rb
lib/chronic/ordinal.rb
lib/chronic/pointer.rb
lib/chronic/repeater.rb
lib/chronic/repeaters/repeater_day.rb
lib/chronic/repeaters/repeater_day_name.rb
lib/chronic/repeaters/repeater_day_portion.rb
lib/chronic/repeaters/repeater_fortnight.rb
lib/chronic/repeaters/repeater_hour.rb
lib/chronic/repeaters/repeater_minute.rb
lib/chronic/repeaters/repeater_month.rb
lib/chronic/repeaters/repeater_month_name.rb
lib/chronic/repeaters/repeater_season.rb
lib/chronic/repeaters/repeater_season_name.rb
lib/chronic/repeaters/repeater_second.rb
lib/chronic/repeaters/repeater_time.rb
lib/chronic/repeaters/repeater_week.rb
lib/chronic/repeaters/repeater_weekday.rb
lib/chronic/repeaters/repeater_weekend.rb
lib/chronic/repeaters/repeater_year.rb
lib/chronic/scalar.rb
lib/chronic/season.rb
lib/chronic/separator.rb
lib/chronic/span.rb
lib/chronic/tag.rb
lib/chronic/time_zone.rb
lib/chronic/token.rb

Parse natural language dates and times into Time or {Chronic::Span} objects

@example

  require 'chronic'

  Time.now   #=> Sun Aug 27 23:18:25 PDT 2006

  Chronic.parse('tomorrow')
    #=> Mon Aug 28 12:00:00 PDT 2006

  Chronic.parse('monday', :context => :past)
    #=> Mon Aug 21 12:00:00 PDT 2006

  Chronic.parse('this tuesday 5:00')
    #=> Tue Aug 29 17:00:00 PDT 2006

  Chronic.parse('this tuesday 5:00', :ambiguous_time_range => :none)
    #=> Tue Aug 29 05:00:00 PDT 2006

  Chronic.parse('may 27th', :now => Time.local(2000, 1, 1))
    #=> Sat May 27 12:00:00 PDT 2000

  Chronic.parse('may 27th', :guess => false)
    #=> Sun May 27 00:00:00 PDT 2007..Mon May 28 00:00:00 PDT 2007

@author Tom Preston-Werner, Lee Jarvis

Methods

Classes and Modules

Module Chronic::Handlers
Class Chronic::ChronicPain
Class Chronic::Grabber
Class Chronic::Handler
Class Chronic::MiniDate
Class Chronic::Numerizer
Class Chronic::Ordinal
Class Chronic::Pointer
Class Chronic::Repeater
Class Chronic::Scalar
Class Chronic::Season
Class Chronic::Separator
Class Chronic::Span
Class Chronic::Tag
Class Chronic::TimeZone
Class Chronic::Token

Constants

VERSION = "0.6.6"
DEFAULT_OPTIONS = { :context => :future, :now => nil, :guess => true, :ambiguous_time_range => 6, :endian_precedence => [:middle, :little], :ambiguous_year_future_bias => 50

Attributes

debug  [RW]  @return [Boolean] true when debug mode is enabled
now  [RW]  The current Time Chronic is using to base from

@example

  Time.now #=> 2011-06-06 14:13:43 +0100
  Chronic.parse('yesterday') #=> 2011-06-05 12:00:00 +0100

  now = Time.local(2025, 12, 24)
  Chronic.parse('tomorrow', :now => now) #=> 2025-12-25 12:00:00 +0000

@return [Time, nil]

time_class  [RW]  @example
  require 'chronic'
  require 'active_support/time'

  Time.zone = 'UTC'
  Chronic.time_class = Time.zone
  Chronic.parse('June 15 2006 at 5:54 AM')
    # => Thu, 15 Jun 2006 05:45:00 UTC +00:00

@return [Time] The time class Chronic uses internally

Public Class methods

List of {Handler} definitions. See {parse} for a list of options this method accepts

@see parse @return [Hash] A Hash of Handler definitions

Guess a specific time within the given span

@param [Span] span @return [Time]

Convert number words to numbers (three => 3, fourth => 4th)

@see Numerizer.numerize @param [String] text The string to convert @return [String] A new string with words converted to numbers

Parses a string containing a natural language date or time

If the parser can find a date or time, either a Time or Chronic::Span will be returned (depending on the value of `:guess`). If no date or time can be found, `nil` will be returned

@param [String] text The text to parse

@option opts [Symbol] :context (:future)

  * If your string represents a birthday, you can set `:context` to
    `:past` and if an ambiguous string is given, it will assume it is
    in the past. Specify `:future` or omit to set a future context.

@option opts [Object] :now (Time.now)

  * By setting `:now` to a Time, all computations will be based off of
    that time instead of `Time.now`. If set to nil, Chronic will use
    `Time.now`

@option opts [Boolean] :guess (true)

  * By default, the parser will guess a single point in time for the
    given date or time. If you'd rather have the entire time span
    returned, set `:guess` to `false` and a {Chronic::Span} will
    be returned

@option opts [Integer] :ambiguous_time_range (6)

  * If an Integer is given, ambiguous times (like 5:00) will be
    assumed to be within the range of that time in the AM to that time
    in the PM. For example, if you set it to `7`, then the parser
    will look for the time between 7am and 7pm. In the case of 5:00, it
    would assume that means 5:00pm. If `:none` is given, no
    assumption will be made, and the first matching instance of that
    time will be used

@option opts [Array] :endian_precedence ([:middle, :little])

  * By default, Chronic will parse "03/04/2011" as the fourth day
    of the third month. Alternatively you can tell Chronic to parse
    this as the third day of the fourth month by altering the
    `:endian_precedence` to `[:little, :middle]`

@option opts [Integer] :ambiguous_year_future_bias (50)

  * When parsing two digit years (ie 79) unlike Rubys Time class,
    Chronic will attempt to assume the full year using this figure.
    Chronic will look x amount of years into the future and past. If
    the two digit year is `now + x years` it's assumed to be the
    future, `now - x years` is assumed to be the past

@return [Time, Chronic::Span, nil]

Clean up the specified text ready for parsing

Clean up the string by stripping unwanted characters, converting idioms to their canonical form, converting number words to numbers (three => 3), and converting ordinal words to numeric ordinals (third => 3rd)

@example

  Chronic.pre_normalize('first day in May')
    #=> "1st day in may"

  Chronic.pre_normalize('tomorrow after noon')
    #=> "next day future 12:00"

  Chronic.pre_normalize('one hundred and thirty six days from now')
    #=> "136 days future this second"

@param [String] text The string to normalize @return [String] A new string ready for Chronic to parse

[Validate]