date_parser 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 83fcce6dfc6821ee2701b10b33bb9cead5aa05e7
+  data.tar.gz: 47922dd354451a884c45e02f0fd818f359aef78c
+SHA512:
+  metadata.gz: 405f093a43e736aef635c60ca99655f891a42c9308d4da053e3a7aaa9cd9a8edabb93f2c1fa590141f87d289e80a348ab620468a35ef1433eeb16ef7819cd130
+  data.tar.gz: 4ce37b863c5901b1f4ddaa0bd68792f40f64cd3649e715d64dd7af49a6e6884088348487a3b76763b80f22380d2473a3eb1c2340105b553a77702e830604ef6d

data/NEWS.md

@@ -0,0 +1,13 @@
+# DateParser 0.1.1
+* Critical bug fix - Helper files now sent with the gem.
+
+# DateParser 0.1.0
+
+* Improved parsing algorithm.
+* No longer allow "sub-solutions" inside stricter solutions.
+* Parser can now correctly parse sentences like "meet me on the 10th"
+* Parser can now correctly parse XX/XX dates relative to a released date.
+* Now parses simple 'relative words' like "yesterday" and "today" correctly.
+* Many, many more functions are now released sensitive!
+* Option to parse single years (Such as "1302" alone.)
+* Various smaller bug fixes.

data/README.md

@@ -0,0 +1,126 @@
+# DateParser
+
+DateParser is a simple, fast, effective way of parsing dates from natural language
+text in a flexible way.
+
+# Installation
+```
+$ gem install date_parser
+```
+
+# Usage
+```ruby
+require 'date_parser'
+
+# DateParser::parse(txt, creation_date = nil, opts)
+
+text = "Newsflash: things happen on 02/12!"
+creation_date = Date.parse("January 1st, 1994")
+
+DateParser::parse(text, creation_date).to_s
+    #=> [#<Date: 1994-02-12 ((2449396j,0s,0n),+0s,2299161j)>]
+
+
+text = "We should go on the 4th if we can."
+creation_date = Date.parse("July 1st 2016")
+
+DateParser::parse(text, creation_date).to_s
+    #=> [#<Date: 2016-07-04 ((2457574j,0s,0n),+0s,2299161j)>]
+
+
+text = "Yesterday was certainly a day."
+creation_date = Date.parse("January 12, 1994")
+
+DateParser::parse(text, creation_date).to_s
+    #=> [#<Date: 1994-01-11 ((2449364j,0s,0n),+0s,2299161j)>]
+
+
+text = "The first time I asked someone on a date, I was in Iowa, it was a " +
+       "winterly mid-month January, we were to go to finding nemo, I was 9, and " +
+       "although she was interested, her parents said no."
+creation_date = Date.parse("July 6, 2016")
+
+DateParser::parse(text, creation_date).to_s
+    #=> [#<Date: 2016-01-01 ((2457389j,0s,0n),+0s,2299161j)>]
+
+
+text = "7-24-2015"
+DateParser::parse(text).to_s
+    #=> [#<Date: 2015-07-24 ((2457228j,0s,0n),+0s,2299161j)>]
+
+
+text = "2012-02-12"
+DateParser::parse(text).to_s
+    #=> [#<Date: 2012-02-12 ((2455970j,0s,0n),+0s,2299161j)>]
+
+
+text = "24-07-2015"
+DateParser::parse(text).to_s
+    #=> [#<Date: 2015-07-24 ((2457228j,0s,0n),+0s,2299161j)>]
+
+
+text = "In 1492 Columbus sailed the ocean blue."
+creation_date = nil
+
+DateParser::parse(text, creation_date, parse_single_years: true).to_s
+    #=> [#<Date: 1492-01-01 ((2266011j,0s,0n),+0s,2299161j)>]
+
+
+text = "Charlie Chaplin and Jason Earles (Hannah Montana's brother) were " +
+       "alive at the same time for eight months in 1977"
+creation_date = Date.parse("July 6, 2016")
+
+DateParser::parse(text, creation_date, parse_single_years: true).to_s
+    #=> [#<Date: 1977-01-01 ((2443145j,0s,0n),+0s,2299161j)>]
+
+
+text = "Sunday, Sunday, Sunday!"
+DateParser::parse(text, nil, unique: false).to_s
+    #=> [#<Date: 2016-07-24 ((2457594j,0s,0n),+0s,2299161j)>, 
+         #<Date: 2016-07-24 ((2457594j,0s,0n),+0s,2299161j)>, 
+         #<Date: 2016-07-24 ((2457594j,0s,0n),+0s,2299161j)>]
+
+
+text = "Sunday, Sunday, Sunday!"
+DateParser::parse(text, nil, unique: true).to_s
+    #=> [#<Date: 2016-07-24 ((2457594j,0s,0n),+0s,2299161j)>]
+
+
+DateParser::parse("No dates here", nil).to_s
+    #=> []
+
+
+DateParser::parse("No dates here", 
+                  nil, 
+                  nil_date: Date.parse("Jan 1, 2016")
+                  ).to_s
+    #=> [#<Date: 2016-01-01 ((2457389j,0s,0n),+0s,2299161j)>]
+```
+
+# Examples
+
+DateParser has just one function: `parse(txt, creation_date, opts)`, which
+always returns an array with Date elements parsed from the text.
+
+`parse` is case-insensitive, robust to crazy punctuation and spacing, and will 
+try to interpret dates in the strictest possible way before trying to find 
+looser interpretations. Additionally, no word can be used in more than one
+Date.
+
+For example: `DateParser::parse("Jan 12, 2013", nil, parse_single_years: true)` 
+will return `["Jan 12, 2013"]`, and not `["Jan 12, 2013", "Jan 1, 2013"]`
+
+## What is creation_date?
+It's meant to make the parser smarter! `creation_date` is the date the text was
+written. If provided, the parser will try to interpret dates like "Monday" relative
+to the `creation_date`.
+
+## Options!
+* `unique`: (boolean) Return only unique dates in the output array.
+* `nil_date`: (Date) If no dates are found, instead of returning an empty array,
+return an array containing only `nil_date`.
+* `parse_single_years`: (boolean) Should the parser interpret integers as years?
+
+# Requests or Bugs?
+Leave an issue on this Github page! I'll most likely get back to you within 24
+hours.

data/lib/date_parser.rb

@@ -0,0 +1,82 @@
+require 'date'
+
+require_relative 'date_parser/natural_date_parsing'
+
+# DateParser is the main interface between the user and the parser
+#
+# == Methods
+#
+# <b>parse(txt, options)</b>: Parse a block of text and return an array of the parsed
+# dates as Date objects.
+#
+
+module DateParser
+  
+  # Parses a text object and returns an array of parsed dates.
+  #
+  # ==== Attributes
+  #
+  # * +txt+ - The text to parse.
+  # * +creation_date+ - A Date object of when the text was created or released. 
+  # Defaults to nil, but if provided can make returned dates more accurate.
+  #
+  # ==== Options
+  #
+  # * +:unique+ - Return only unique Date objects. Defaults to false
+  # * +:nil_date+ - A date to return if no dates are parsed. Defaults to nil.
+  # * +:parse_single_years+ - Should we parse single ints as years? Defaults to false.
+  #
+  # ==== Examples
+  #
+  #    text = "Henry and Hanke created a calendar that causes each day to fall " +
+  #           "on the same day of the week every year. They recommend its " +
+  #           "implementation on January 1, 2018, a Monday."
+  #    creation_date = Date.parse("July 6, 2016")
+  #
+  #    DateParser::parse(text, creation_date)
+  #        #=> [#<Date: 2018-01-01 ((2458120j,0s,0n),+0s,2299161j)>, 
+  #             #<Date: 2016-07-11 ((2457581j,0s,0n),+0s,2299161j)>]
+  #
+  #    ######################################
+  #    ##
+  #    ## Option Examples:
+  #    ##
+  #
+  #    text = "Sunday, Sunday, Sunday!"
+  #    DateParser::parse(text, nil, unique: false)
+  #        #=> [#<Date: 2016-07-24 ((2457594j,0s,0n),+0s,2299161j)>, 
+  #             #<Date: 2016-07-24 ((2457594j,0s,0n),+0s,2299161j)>, 
+  #             #<Date: 2016-07-24 ((2457594j,0s,0n),+0s,2299161j)>]
+  #
+  #    DateParser::parse(text, nil unique: true)
+  #        #=> [#<Date: 2016-07-24 ((2457594j,0s,0n),+0s,2299161j)>]
+  #
+  #    DateParser::parse("No dates here", nil)
+  #        #=> []
+  #
+  #    DateParser::parse("No dates here", nil, nil_date: Date.parse("Jan 1 2012"))
+  #        #=> [#<Date: 2012-01-01 ((2455928j,0s,0n),+0s,2299161j)>]
+  #
+  def DateParser.parse(txt, creation_date = nil, opts = {})
+    unique = opts[:unique] || false
+    nil_date = opts[:nil_date] || nil
+    parse_single_years = opts[:parse_single_years] || false
+    
+    interpreted_dates = NaturalDateParsing::interpret_date(txt, 
+                                                           creation_date, 
+                                                           parse_single_years)
+    
+    if unique
+      interpreted_dates.uniq!
+    end
+    
+    if interpreted_dates.empty?
+      interpreted_dates = [nil_date].flatten
+    end
+    
+    # Possibility of getting [nil]
+    interpreted_dates.delete(nil)
+    
+    return interpreted_dates
+  end
+end

data/lib/date_parser/natural_date_parsing.rb

@@ -0,0 +1,455 @@
+require_relative 'date_utils'
+require_relative "utils"
+
+# Handles the mechanics of natural language processing.
+#
+# == Methods
+#
+# <b>interpret_date(txt, creation_date, parse_single_years)</b>: 
+# Return an array of dates from the set of parameters.
+#
+# We parse in order of decreasing
+# strictness. I.e., a very specific phrase like "January 1st, 2013" will be parsed
+# before "January 1st," which will be parsed before just "2013". Whenever we
+# determine a phrase is part of a date, we remove the phrase after parsing.
+# So in the example "January 1st, 2013" we'll return only one date.
+#
+# If no dates are found, returns an empty array.
+#
+# <b>parse_one_word(word, creation_date, parse_single_years)</b>: Given a single word,
+# a string, tries to return a Date object.
+#
+
+module NaturalDateParsing
+  
+  ###############################################
+  ##
+  ## Constants
+  ##
+  
+  # Names of days as well as common shortened versions.
+  SINGLE_DAYS = [
+                 'mon', 'tue', 'wed', 'thur', 'fri', 'sat', 'sun',
+                 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 
+                 'saturday', 'sunday', 'tues'
+                ]
+                
+  # Phrases that denote a date relative to today (here often
+  # called the creation_date)
+  RELATIVE_DAYS = ['today', 'tomorrow', 'tonight', 'yesterday']
+  
+  # Names of months as well as common shortened versions
+  MONTH = [
+           'jan', 'feb', 'mar', 'may', 'june', 'july', 'aug', 'sept', 'oct',
+           'nov', 'dec',
+           'january', 'february', 'march', 'april', 'august', 'september',
+           'october', 'november', 'december'
+          ]
+          
+  # A list of numbers from [1, 31]
+  NUMERIC_DAY = ('1'..'31').to_a
+                
+  # Numbers from [1, 31] as well as the common suffixes (such as 1st, 2nd, e.t.c.)
+  SUFFIXED_NUMERIC_DAY = [
+                           '1st', '2nd', '3rd', '4th', '5th', '6th', '7th', 
+                           '8th', '9th', '10th', '11th', '12th', '13th', '14th', 
+                           '15th', '16th', '17th', '18th', '19th', '20th', 
+                           '21st', '22nd', '23rd','24th', '25th', 
+                           '26th', '27th', '28th', '29th', '30th', '31st'
+                         ]
+  
+  ###############################################
+  ##
+  ## Main Parsing/Processing Function
+  ##
+  
+  # Processes a given text and returns an array of probable dates contained within.
+  #
+  # ==== Description
+  # 
+  # Tries to interpret dates from the given text, in order from strictest
+  # interpretation to looser interpretations. No word can be part of two
+  # different dates.
+  #
+  # Works by calling parse_three_words, parse_two_words, and parse_one_word
+  # on the text. 
+  #
+  # ==== Attributes
+  #
+  # * +txt+ - The text to parse.
+  # * +creation_date+ - A Date object of when the text was created or released. 
+  # Defaults to nil, but if provided can make returned dates more accurate.
+  # * +parse_single_years+ - A boolean. If true, we interpret single numbers as
+  # years. This is a very broad assumption, and so defaults to false.
+  #
+  # ==== Examples
+  #
+  #    text = "Henry and Hanke created a calendar that causes each day to fall " +
+  #           "on the same day of the week every year. They recommend its " +
+  #           "implementation on January 1, 2018, a Monday."
+  #    creation_date = Date.parse("July 6, 2016")
+  #
+  #    NaturalDateParsing.interpret_date(text, creation_date)
+  #        #=> [#<Date: 2018-01-01 ((2458120j,0s,0n),+0s,2299161j)>, 
+  #             #<Date: 2016-07-11 ((2457581j,0s,0n),+0s,2299161j)>]
+  #
+  #    NaturalDateParsing.interpret_date("No dates here!")
+  #        #=> []
+  #
+  #    NaturalDateParsing.interpret_date("2012", nil, true)
+  #        #=> [#<Date: 2012-01-01 ((2455928j,0s,0n),+0s,2299161j)>]
+  #
+  def NaturalDateParsing.interpret_date(
+                                        txt, 
+                                        creation_date = nil, 
+                                        parse_single_years = false
+                                        )
+    possible_dates = []
+    txt = Utils::clean_str(txt)
+    words = txt.split(" ").map{|x| x.strip}
+    
+    # We use the while loop, as apparently there are cases where we try to subset
+    # words despite the value of i being >= words.length - 3
+    # TODO: Figure out why the above happens. Preferably return to for loop.
+    # TODO: Cleaner way of structuring the below? I could break up the loops
+    # into single functions. Consider.
+    i = 0
+    
+    while (i <= words.length - 3) do
+      subset_words = words[i..(i+2)]
+      
+      proposed_date = parse_three_words(subset_words, creation_date)
+      
+      if(! proposed_date.nil?)
+        possible_dates << proposed_date
+        words = Utils::delete_at_indices(words, i..(i+2))
+        i -= 1
+      end
+      
+      i += 1
+    end
+    
+    i = 0
+    
+    while (i <= words.length - 2) do
+      subset_words = words[i..(i+1)]
+      proposed_date = parse_two_words(subset_words, creation_date)
+      
+      if(! proposed_date.nil?)
+        possible_dates << proposed_date
+        words = Utils::delete_at_indices(words, i..(i+1))
+        i -= 1
+      end
+      
+      i += 1
+    end
+    
+    i = 0
+    
+    while (i <= words.length - 1) do
+      subset_words = words[i]
+      
+      proposed_date = parse_one_word(subset_words, creation_date, parse_single_years)
+      
+      if(! proposed_date.nil?)
+        possible_dates << proposed_date
+        words.delete_at(i)
+        i -= 1
+      end
+      
+      i += 1
+    end
+    
+    return possible_dates
+  end
+  
+  
+  ###############################################
+  ##
+  ## Parse Cases (1 word, 2 words, 3 words)
+  ##
+  
+  # Takes a single word and tries to return a date.
+  #
+  # If no date can be interpreted from the word, returns nil. We consider these
+  # cases:
+  # * DAY (mon, tuesday, e.t.c.)
+  # * A relative day (today, tomorrow, tonight, yesterday)
+  # * Dates of the form MM/DD
+  # * Numbers such as [1st, 31st]
+  # * MONTH (jan, february, e.t.c.)
+  # * YYYY (2012, 102. Must be enabled.)
+  # * YYYY-MM-DD, DD-MM-YYYY, MM-DD-YYYY
+  #
+  # ==== Attributes
+  #
+  # * +word+ - A String, preferably consisting of a single word.
+  # * +creation_date+ - A Date object of when the text was created or released. 
+  # Defaults to nil, but if provided can make returned dates more accurate.
+  # * +parse_single_years+ - A boolean. If true, we interpret single numbers as
+  # years. This is a very broad assumption, and so defaults to false.
+  #
+  def NaturalDateParsing.parse_one_word(
+                                        word, 
+                                        creation_date = nil, 
+                                        parse_single_years = false
+                                        )
+    
+    if SINGLE_DAYS.include? word
+      proposed_date = Date.parse(word)
+      
+      # If we have the creation_date date, we can try to be a little smarter
+      if(! creation_date.nil?)
+        weeks_to_shift = difference_in_weeks(Date.today, creation_date)
+                                                         
+        proposed_date = proposed_date - (weeks_to_shift * 7)
+        
+        # Right now though, it should be within 1 week of accuracy, and either one
+        # week ahead or one week behind.
+        # The solution is pretty simple. If the proposed date 
+        # is more than a week ahead of the creation date, then go back one week.
+        if proposed_date - creation_date > 7
+          proposed_date = proposed_date - 7
+        elsif proposed_date - creation_date < 0
+          proposed_date = proposed_date + 7
+        end
+      end
+      
+      return proposed_date
+    end
+    
+    # Parsing phrases like "yesterday", "today", "tonight"
+    if RELATIVE_DAYS.include? word
+      if word == 'today' || word == 'tonight'
+        if creation_date.nil?
+          return Date.today
+        else
+          return creation_date
+        end
+      elsif word == 'yesterday'
+        if creation_date.nil?
+          return Date.today - 1
+        else
+          return creation_date - 1
+        end
+      elsif word == "tomorrow"
+        return creation_date + 1
+      end
+    end
+    
+    # Parsing strings of the form XX/XX
+    if word.include? '/'
+      return slash_date(word, creation_date)
+    end
+    
+    # Parsing strings like "23rd"
+    if SUFFIXED_NUMERIC_DAY.include? word
+      return numeric_single_day(word, creation_date)
+    end
+    
+    # Parsing month names 
+    if MONTH.include? word
+      return default_month(word, creation_date)
+    end
+    
+    # In this case, we assume it's a year!
+    if parse_single_years && (Utils::is_int? word)
+      return default_year(word)
+    end
+    
+    # Parsing XX-XX-XXXX or XXXX-XX-XX
+    if full_numeric_date?(word)
+      return full_numeric_date(word)
+    end
+    
+  end
+  
+  
+  # Takes two words and tries to return a date.
+  #
+  # If no date can be interpreted from the word, returns nil. In this case,
+  # we look for dates of this form:
+  # * MONTH DAY
+  #
+  # ==== Attributes
+  #
+  # * +words+ - An array of two words, downcased and stripped.
+  # * +creation_date+ - A Date object of when the text was created or released. 
+  # Defaults to nil, but if provided can make returned dates more accurate.
+  #
+  def NaturalDateParsing.parse_two_words(words, creation_date = nil)
+    
+    if MONTH.include?(words[0]) && _weak_day?(words[1])
+      return month_day(words, creation_date)
+    end
+    
+  end
+  
+  
+  # Takes three words and tries to return a date.
+  #
+  # If no date can be interpreted from the word, returns nil. In this case,
+  # assumes the word can take these forms:
+  # * MONTH DAY YEAR
+  #
+  # ==== Attributes
+  #
+  # * +words+ - An array of three words, downcased and stripped.
+  # * +creation_date+ - A Date object of when the text was created or released. 
+  # Defaults to nil, but if provided can make returned dates more accurate.
+  #
+  def NaturalDateParsing.parse_three_words(words, creation_date = nil)
+
+    if MONTH.include?(words[0]) && _weak_day?(words[1]) && Utils::is_int?(words[2])
+      return Date.parse(words.join(" "))
+    end
+    
+  end
+  
+  ###############################################
+  ##
+  ## Parse Functions
+  ##
+  
+  # Given a single word, assumes the word is of the form XX/XX and returns
+  # the appropriate Date object. If not possible, returns nil.
+  def NaturalDateParsing.slash_date(word, creation_date = nil)
+    samp = word.split('/')
+    month = samp[0].to_i
+    day = samp[1].to_i
+    
+    if month > 0 && month <= 12 && day > 0 && day <= 31
+      # TODO: IMPROVE EXCEPTION HANDLING.
+      begin
+        proposed_date = Date.parse(word)
+        if(! creation_date.nil?) ## We're sensitive to only years here.
+          years_diff = Date.today.year - creation_date.year
+          proposed_date = proposed_date << (12 * years_diff)
+        end
+        return proposed_date
+      rescue ArgumentError
+        return nil
+      end
+    end
+  end
+  
+  # Parses an array containing two elements (single words) on the assumption
+  # that the array is of the form ["MONTH", "DAY"]
+  def NaturalDateParsing.month_day(words, creation_date = nil)
+    begin
+      proposed_date = Date.parse(words.join(" "))
+      
+      diff_in_years = creation_date.nil? ? 0 : (creation_date.year - Date.today.year)
+      
+      return proposed_date >> diff_in_years * 12
+    rescue ArgumentError
+      return nil
+    end
+  end
+  
+  # Parses a single numeric date (1st, 2nd, 3rd, e.t.c.).
+  def NaturalDateParsing.numeric_single_day(word, creation_date = nil)
+    diff_in_months = creation_date.nil? ? 0 : (creation_date.year * 12 + creation_date.month) - 
+                                              (Date.today.year * 12 + Date.today.month)
+    
+    begin
+      return Date.parse(word) >> diff_in_months
+    rescue ArgumentError
+      ## If an ArgumentError arises, Date is not convinced it's a date.
+      return nil
+    end
+  end
+  
+  # Parses a single word of the form XXXX-XX-XX, DD-MM-YYYY or MM-DD-YYYY
+  def NaturalDateParsing.full_numeric_date(word)
+    subparts = word.split("-")
+    
+    # This is a weak check to see where the year is
+    year_index = (subparts[0].to_i).abs > 31 ? 0 : 2
+    
+    # Then we assume it's of the form YYYY-MM-DD
+    if year_index == 0
+      return Date.parse(word)
+    else
+      # We check the subparts to try to see which part is DD.
+      # If we can't determine it, we assume it's International Standard Format,
+      # or DD-MM-YY
+      
+      if subparts[1].to_i > 12
+        # American Standard (MM-DD-YYYY)
+        subparts[0] = numeric_month_to_string(subparts[0].to_i)
+        return Date.parse(subparts.join(" "))
+        
+      else
+        # International Standard (DD-MM-YYYY)
+        return Date.parse(word)
+      end
+    end
+    
+    return Date.parse(word)
+  end
+  
+  
+  private
+  
+  ##############################################
+  ##
+  ## Private Functions
+  ##
+  
+  def NaturalDateParsing._weak_day?(word)
+    return (NUMERIC_DAY.include? word) || (SUFFIXED_NUMERIC_DAY.include? word)
+  end
+  
+  def NaturalDateParsing.default_year(year)
+    return Date.parse("Jan 1 " + year)
+  end
+  
+  ## TODO. NOT SENSITIVE TO YEAR.
+  def NaturalDateParsing.default_month(month, released = nil)
+    this_year = released.nil? ? Date.today.year : released.year
+    return Date.parse(month + " " + this_year.to_s)
+  end
+  
+  def NaturalDateParsing.suffix(number)
+    int = number.to_i
+    
+    ## Check to see if the least significant digit is 1.
+    if int & 1 == 1
+      return int.to_s + "st"
+    else
+      return int.to_s + "th"
+    end
+  end
+  
+  ## Be careful with this.
+  ## date1 is the later date.
+  def NaturalDateParsing.difference_in_weeks(date1, date2)
+    return ((date1 - date2) / 7).to_i
+  end
+  
+  # Is it of the form XXXX-XX-XX?
+  def NaturalDateParsing.full_numeric_date?(word)
+    output = true
+    
+    if word.include? "-"
+      substrings = word.split("-")
+      for substring in substrings do
+        output = output && Utils.is_int?(substring)
+      end
+    else
+      output = false
+    end
+    
+    return output
+  end
+  
+  def NaturalDateParsing.numeric_month_to_string(numeric)
+    months = ["january", "february", "march", "april", "may", "june",
+              "july", "august", "september", "october", "november",
+              "december"]
+    
+    return months[numeric - 1]
+  end
+  
+end

data/lib/date_parser/utils.rb

@@ -0,0 +1,42 @@
+# Extra utility functions for broader use in the gem.
+
+module Utils
+  
+  # Determine whether or not a String is a base 10 integer.
+  def Utils.is_int?(str)
+    str.to_i.to_s == str || strong_is_int?(str)
+  end
+  
+  # A more rigorous check to see if the String is an int.
+  def Utils.strong_is_int?(str)
+    nums = ("0".."9").to_a
+    
+    for char in str.each_char do
+      if ! nums.include? char
+        return false
+      end
+    end
+    
+    return true
+  end
+  
+  # Removes punctuation.
+  def Utils.clean_out_punctuation(str)
+    str.gsub(/[^a-z0-9\s\/-]/i, '')
+  end
+  
+  # Removes punctuation and downcases the str.
+  def Utils.clean_str(str)
+    clean_out_punctuation(str).downcase
+  end
+  
+  # Performs delete_at for a range of integers
+  def Utils.delete_at_indices(array, range)
+    first_val = range.first
+    for _ in range do
+      array.delete_at(first_val)
+    end
+    
+    return array
+  end
+end

data/lib/spec/date_parser_spec.rb

@@ -0,0 +1,301 @@
+require_relative "../date_parser"
+
+## Run this file with this command:
+## rspec lib/spec/date_parser_spec.rb
+
+describe NaturalDateParsing do
+  
+  #########################################################
+  ##
+  ## Basic Mechanics Testing
+  ##
+  
+  before do
+    
+    @date = "April 6th, 2014"
+    @text = "Remember to meet me on April 6th, 2014, alright?"
+    @paragraph = "April 6th, 2014 isn't good for me. We should meet instead on\n" +
+                 "February 4th, 2013. Or even March 31st, 2017. No rush."
+    
+    @parsed_date = [Date.parse("April 6th, 2014")]
+    @parsed_date_paragraph = [
+                              Date.parse("April 6th, 2014"),
+                              Date.parse("February 4th, 2013"),
+                              Date.parse("March 31st, 2017")
+                              ]
+  end
+  
+  describe ".interpret_date" do
+    context "given 'April 6th, 2014'" do
+      it "returns Sun, 06 Apr 2014 as a date object" do
+        expect(NaturalDateParsing::interpret_date(@date)).to eql(@parsed_date)
+      end
+    end
+    
+    context "given a sentence containing April 6th, 2014" do
+      it "returns Sun, 06 Apr 2014 as a date object" do 
+        expect(NaturalDateParsing::interpret_date(@text)).to eql(@parsed_date)
+      end
+    end
+    
+    context "given a paragraph containing several dates" do
+      it "returns a list of all dates mentioned in the paragraph" do
+        expect(NaturalDateParsing::interpret_date(@paragraph)).to eql(@parsed_date_paragraph)
+      end
+    end
+  end
+end
+
+
+describe NaturalDateParsing do
+  
+  #########################################################
+  ##
+  ## Edge Cases. More Colloquial Language. More complicated phrases.
+  ##
+  
+  describe ".interpret_date" do
+    
+    context "Given a longer sentence containing a date" do
+      text = "La Puerta del Conde (The Count's Gate) is the site in Santo" + 
+        "Domingo, Dominican Republic where Francisco del Rosario Sánchez, one of the" + 
+        "Dominican Founding Fathers, proclaimed Dominican independence and raised the" + 
+        "first Dominican Flag, on February 27, 1844."
+      creation_date = nil
+      answer = [Date.parse("February 27, 1844")]
+      
+      it "captures the single date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+    context "Colloquial use of date 1" do
+      text = "We should go on the 4th if we can."
+      creation_date = Date.parse("July 1st 2016")
+      answer = [Date.parse("July 4th, 2016")]
+      
+      it "correctly uses the creation_date parameter" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+    context "Correct use of XX/XX format 1" do
+      text = "Newsflash: things happen on 02/12!"
+      creation_date = Date.parse("January 1st, 1994")
+      answer = [Date.parse("February 12, 1994")]
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+    context "Given yesterday" do
+      text = "Yesterday was certainly a day."
+      creation_date = nil
+      answer = [Date.today - 1]
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+    context "Given yesterday with a creation_date date" do
+      text = "Yesterday was certainly a day."
+      creation_date = Date.parse("January 12, 1994")
+      answer = [Date.parse("January 11, 1994")]
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+    context "Single year is correctly parsed" do
+      text = "In 1492 Columbus sailed the ocean blue."
+      creation_date = nil
+      answer = [Date.parse("January 1, 1492")]
+      parse_single_years = true
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date, parse_single_years)).to eql(answer)
+      end
+    end
+    
+    context "Correctly parses month and day in middle of sentence" do
+      text = "Something something something march 4 something something"
+      creation_date = Date.parse("Jan 1, 2004")
+      answer = [Date.parse("March 4, 2004")]
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+  end
+end
+
+
+describe NaturalDateParsing do
+  
+  #########################################################
+  ##
+  ## Colloquial Language samples from volunteers
+  ##
+  
+  describe ".interpret_date" do
+    
+    context "Colloquial example 1" do
+      text = "Charlie Chaplin and Jason Earles (Hannah Montana's brother) were " +
+      "alive at the same time for eight months in 1977"
+      creation_date = Date.parse("July 6, 2016")
+      answer = [Date.parse("January 1, 1977")]
+      parse_single_years = true
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date, parse_single_years)).to eql(answer)
+      end
+    end
+    
+    ## Stopping this test for right now. Hard to tell which April.
+    ## Ambiguous in the general case.
+    #context "Colloquial example 2" do
+    #  text = "For a job I started this April, I had to parse dates of various " +
+    #  "formats, such as MM-DD-YY, MM/YYYY, and YY-MM-DD. It was infuriating, " +
+    #  "and what I assume you to be doing reminds me of this."
+    #  creation_date = Date.parse("July 6, 2016")
+    #  answer = [Date.parse("April 1, 2016")] ## Reconsider
+    #  
+    #  it "correctly grabs the date" do
+    #    expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+    #  end
+    #end
+    
+    context "Colloquial example 3" do
+      text = "August 25, 2013, I met So-and-So"
+      creation_date = Date.parse("July 6, 2016")
+      answer = [Date.parse("August 25, 2013")]
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+    context "Colloquial example 4" do
+      text = "Quincy Jones (producer of Thriller) and Michael Caine (veteran " +
+      "British actor) were both born on the same day and the same hour on March " +
+      "14, 1933. They are still friends to this day."
+      creation_date = Date.parse("July 6, 2016")
+      answer = [Date.parse("March 14, 1933")]
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+    context "Colloquial example 5" do
+      text = "Two days ago (July 4, 2016) was the 190th death anniversary of " +
+      "the second and third US Presidents: John Adams and Thomas Jefferson, who died 5 hours apart."
+      creation_date = Date.parse("July 6, 2016")
+      answer = [Date.parse("July 4, 2016")]
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+    context "Colloquial example 6" do
+      text = "On October 3rd So-and-So asked me what day it was"
+      creation_date = Date.parse("July 6, 2016")
+      answer = [Date.parse("October 3, 2016")]
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+    context "Colloquial example 7" do
+      text = "Henry and Hanke created a calendar that causes each day to fall " +
+      "on the same day of the week every year. They recommend its " +
+      "implementation on January 1, 2018, a Monday."
+      creation_date = Date.parse("July 6, 2016")
+      answer = [Date.parse("January 1, 2018"),
+                Date.parse("July 11, 2016")] # Reconsider
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+    context "Colloquial example 8" do
+      text = "Beyoncé Giselle Knowles-Carter was born on September 4, 1981."
+      creation_date = Date.parse("July 6, 2016")
+      answer = [Date.parse("September 4, 1981")]
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+    context "Colloquial example 9" do
+      text = "The first time I asked someone on a date, I was in Iowa, it was a " +
+      "winterly mid-month January, we were to go to finding nemo, I was 9, and " +
+      "although she was interested, her parents said no."
+      creation_date = Date.parse("July 6, 2016")
+      answer = [Date.parse("January 1st, 2016")]
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+    context "Colloquial example 10" do
+      text = "You ate 10 dates from a crate of dates that were picked on June " +
+      "8th from a date tree that was cultivated one score and three years ago. " +
+      "Good luck parsing through the antics of my semantics."
+      creation_date = Date.parse("July 6, 2016")
+      answer = [Date.parse("June 8, 2016")]
+      
+      it "correctly grabs the date" do
+        expect(NaturalDateParsing::interpret_date(text, creation_date)).to eql(answer)
+      end
+    end
+    
+  end
+end
+
+
+describe DateParser do
+  
+  #########################################################
+  ##
+  ## More Edge Cases looking at specific features.
+  ##
+  
+  describe ".parse" do
+    context "Parse fully numeric date" do
+      text = "2012-02-12"
+      answer = [Date.parse("2012-02-12")]
+      
+      it "correctly grabs the date" do
+        expect(DateParser::parse(text)).to eql(answer)
+      end
+    end
+    
+    context "Parse American fully numeric date" do
+      text = "7-24-2015"
+      answer = [Date.parse("July 24, 2015")]
+      
+      it "correctly grabs the date" do
+        expect(DateParser::parse(text)).to eql(answer)
+      end
+    end
+    
+    context "Parse International Standard fully numeric date" do
+      text = "24-07-2015"
+      answer = [Date.parse("24-07-2015")]
+      
+      it "correctly grabs the date" do
+        expect(DateParser::parse(text)).to eql(answer)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: date_parser
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Ryan Kwon
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-07-26 00:00:00.000000000 Z
+dependencies: []
+description: DateParser is a simple, fast, and effective way to parse dates from natural
+  language text in a robust way.
+email: rynkwn@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- NEWS.md
+files:
+- NEWS.md
+- README.md
+- lib/date_parser.rb
+- lib/date_parser/date_utils.rb
+- lib/date_parser/natural_date_parsing.rb
+- lib/date_parser/utils.rb
+- lib/spec/date_parser_spec.rb
+homepage: https://github.com/rynkwn/DateParser
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Quickly parse natural language into dates robustly.
+test_files:
+- lib/spec/date_parser_spec.rb