quando 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67727f8c24dd9cfcafee9cc9fa7ccb50880c3a2056f7f55f917adf5c2e70510e
-  data.tar.gz: 91abb35930e411985e321787af73c2a1b00d057fc9d596c40b7de6ca1d4173ae
+  metadata.gz: a6c1973b3643f2518981fb2adee83308115f6e11f60f8b558c840bca6f7fd32e
+  data.tar.gz: 4ffe51a57833e4f4c1be7376c9a8cd7a613b407ce9ae753f60ae2060b6dc6137
 SHA512:
-  metadata.gz: 3fa3f35f2e28dd16cf7e984faa8c77617b2c553d6fa3de9b30dfc820f258217285298c91a6969fbe1bf02ef9dbc3331f7afca52e2fa125e930ba80a252684c04
-  data.tar.gz: e0c125d630b353fbe4c97705d4e2867c1776073d2ea176f87d8c7ee2c7045e40a5c628848a403f47ebd4db8166799dcac062613082d070ceaeb4e8fd96766e30
+  metadata.gz: 6ffe9976de04d37d34310d00650c5b1394b485e8c7ae39ec2ee50534f5fadc5a9fcc7871ddb6d02cdd1417976deb5783424555ccf410edb710342e474c49cdd8
+  data.tar.gz: e0254d48250868d689dabc06d43e00f078b0fa0f6fe14d768c9cafa97bdff66fc44df2361af5577def1e16fbd6341bd56223bee455f5b0a098f5d18668e10c01

data/.gitignore

@@ -1,5 +1,6 @@
 .DS_Store
-pkg
 .idea/
-docker/*
+bundle
+docker
 docker-compose.yml
+pkg

data/.rspec

@@ -1,2 +1,3 @@
 --format documentation
 --color
+--require spec_helper

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    quando (0.0.4)
+    quando (0.0.5)
 
 GEM
   remote: https://rubygems.org/
@@ -38,4 +38,4 @@ DEPENDENCIES
   rspec (~> 3.0)
 
 BUNDLED WITH
-   1.16.6
+   1.17.2

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018-2019 Sergey Konotopov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,50 +1,208 @@
-# Quando
+![Quando](quando.png "Quando")
 
 [![Gem Version](https://badge.fury.io/rb/quando.svg)](https://badge.fury.io/rb/quando)
 [![Build Status](https://semaphoreci.com/api/v1/kinkou/quando/branches/master/shields_badge.svg)](https://semaphoreci.com/kinkou/quando)
 [![Maintainability](https://api.codeclimate.com/v1/badges/b0653fc45ec54c23e05c/maintainability)](https://codeclimate.com/github/kinkou/quando/maintainability)
 
-Quando is a configurable date parser. Show it what's what and parse any (Gregorian calendar) date. Quando can be configured on:
+Quando is a configurable date parser which picks up where ```Date.strptime``` stops. It was made to work with non-standard, multi-language dates (that is, dates recorded by humans in languages other than English) but can be used for almost any date format.
+
+A typical use case for Quando is dealing with input like:
+
+```text
+"01 января 2019 г."
+"1-ЯНВ-19"
+"01.01.19"
+"1/Jan/2019"
+"yanvar'19"
+"ЯНВ"
+```
+
+This is a real-life example of how people would routinely write January 1, 2019 in Russia, but since many countries have their own words for month names, it might be a common problem.
+
+## How it works
+
+```bash
+gem install quando
+```
+
+and then
+
+```ruby
+require 'quando'
+
+Quando.configure do |c|
+  # Define regular expressions to identify possible month names:
+  c.jan = /january|jan|yanvar|январь|января|янв/i # simplified for readability
+  # c.feb = …
+ 
+  # …more configuration…
+
+  # Then combine them into regexps that will match the date formats you accept:
+  c.formats = [
+    /#{c.day} #{c.month_txt} #{c.year} г\./i, # matches "01 января 2019 г."
+    /#{c.day}\.#{c.month_num}\.#{c.year2}/i, # matches "01.01.19"
+    /#{c.month_txt}'#{c.year2}/i, # matches "январь'19"
+    /#{c.month_txt}/i, # matches "ЯНВ"
+  ]
+end
+
+Quando.parse("01 января 2019 г.") #=> #<Date: 2019-01-01>
+Quando.parse("01.01.19") #=> #<Date: 2019-01-01>
+Quando.parse("январь'19") #=> #<Date: 2019-01-01>
+Quando.parse("ЯНВ") #=> #<Date: 2019-01-01> (given that current year is 2019)
+```
+
+## Quando in detail
+
+### Configuration object
+
+Configuration properties can be set by submitting a block to the ```Quando.configure``` method, as seen in the example above, or by calling the setter methods on the configuration object directly:
+
+```ruby
+Quando.config.jun = /qershor|mehefin/   # Albanian and Welsh month names
+Quando.config.jul = /korrik|gorffennaf/ # will make you cry
+```
+
+### Regular expressions
+
+If you need to use grouping, remember that non-capturing groups ```(?:abc)``` provide better performance.
+
+If, for some reason, you need to use named groups ```(?<name>abc)```, avoid names ```day```, ```month``` and ```year```. Quando uses them internally, so conflicts are possible.
+
+### Textual month matchers
+
+To let Quando recognize months in your language you need to define corresponding regular expressions for all months:
 
-#### Application-level:
 ```ruby
 Quando.configure do |c|
-  c.dlm = /[ ,-]/
+  # In Finland, your matchers might look like this:
+  c.jan = /jan(?:uary)?   | tammikuu(?:ta)? /xi
+  c.feb = /feb(?:ruary)?  | helmikuu(?:ta)? /xi
+  c.mar = /mar(?:ch)?     | maaliskuu(?:ta)?/xi
+  c.apr = /apr(?:il)?     | huhtikuu(?:ta)? /xi
+  c.may = /may            | toukokuu(?:ta)? /xi
+  c.jun = /june?          | kesäkuu(?:ta)?  /xi
+  c.jul = /july?          | heinäkuu(?:ta)? /xi
+  c.aug = /aug(?:ust)?    | elokuu(?:ta)?   /xi
+  c.sep = /sep(?:tember)? | syyskuu(?:ta)?  /xi
+  c.oct = /oct(?:ober)?   | lokakuu(?:ta)?  /xi
+  c.nov = /nov(?:ember)?  | marraskuu(?:ta)?/xi
+  c.dec = /dec(?:ember)?  | joulukuu(?:ta)? /xi
+  
+  # …more configuration…
+end
+```
+
+### Numerical matchers
+
+Quando comes with defaults that will probably work in most situations:
+
+```Quando.config.day``` matches numbers from 1 to 31, both zero-padded and unpadded;
 
-  c.jan = /janeiro/i
-  c.feb = /fevereiro/i
-  c.mar = /março/i
-  c.apr = /abril/i
-  # …
-  c.unimonth!
+```Quando.config.month_num``` matches numbers from 1 to 12, both zero-padded and unpadded;
 
+```Quando.config.year``` matches any 4-digit sequence;
+```Quando.config.year2``` matches any 2-digit sequence.
+
+If you need to adjust these matchers make sure that they produce named captures ```day```, ```month``` and ```year```, respectively:
+
+```ruby
+Quando.config.day = /(?<day> …)/
+Quando.config.month_num = /(?<month> …)/
+Quando.config.year = /(?<year> …)/
+```
+
+### Delimiter matcher
+
+By default, ```Quando.config.dlm``` will greedily match spaces, dashes, dots and slashes.
+
+### Format matchers
+
+With format matchers you describe the concrete date formats that Quando will recognize. Within them you can include the date part matchers you defined previously.
+
+```Quando.config.day```, ```Quando.config.month_num```, ```Quando.config.month_txt```, ```Quando.config.year```, ```Quando.config.year2``` can be used.
+
+```Quando.config.month_txt``` is a regexp that automatically combines all textual month matchers, and will thus match any month.
+
+```ruby
+Quando.configure do |c|
+  # …some initial configuration…
+ 
   c.formats = [
-    /#{c.day} #{c.dlm} #{c.month_txt} #{c.dlm} #{c.year}/xi,
-    /#{c.year} #{c.dlm} #{c.month_txt} #{c.dlm} #{c.day}/xi,
+    /^ #{c.day} #{c.dlm} #{c.month_txt} #{c.dlm} #{c.year} $/xi,
+    # compiles into something like
+    # /^ (?<day>…) [ .]+ (?<month>jan|feb|…) [ .]+ (?<year>…) $/xi
+    # and returns ~ #<MatchData "14 Apr 1965" day:"14" month:"Apr" year:"1965">
+    # on successful match 
   ]
 end
+```
+
+### How dates are parsed
+
+Quando matches regular expressions from ```Quando.config.formats```, *in the specified order*, against the input. If there is a match, the resulting ```MatchData``` object is analyzed.
+
+If there is a named capture ```:day``` or ```:month```, either is used in the result, given that they are within correct range. If the format matcher did not define such named group, ```1``` is used:
 
-Quando.parse('14-abril-1965') #=> #<Date: 1965-04-14>
-Quando.parse('1965, abril 14') #=> #<Date: 1965-04-14>
+```ruby
+Quando.config.formats = [
+  /#{Quando.config.month_num}\.#{Quando.config.year}/
+]
+
+Quando.parse('04.2019') #=> #<Date: 2019-04-01>
 ```
 
-#### Instance-level:
-It will not affect your application-level configuration.
+If there is a named capture ```:year```, it is used in the result. If the format matcher did not define such named group, current year is used. If the captured value is less than ```100``` (which is the case for years written as 2-digit numbers), Quando will add a value from ```Quando.config.century``` (defaults to ```2000```), effectively converting, for example, ```18``` to ```2018``` (ok, it's not really a century, but rather a *nittonhundratalet*, but let's keep things simple). Be mindful of this behaviour, adjusting ```Quando.config.century``` accordingly:
+
+```ruby
+Quando.config.formats = [Quando.config.year]
+Quando.parse('2019') #=> #<Date: 2019-01-01>
+
+Quando.config.formats = [Quando.config.year2]
+Quando.parse('65') #=> #<Date: 2065-01-01>
+
+Quando.parse('65', century: 1900) #=> #<Date: 1965-01-01>
+# or
+Quando.config.century = 1900
+Quando.parse('65') #=> #<Date: 1965-01-01>
+```
+
+### Defaults
+
+Out of the box, Quando will parse a reasonable variety of day-month-year ordered numerical and English textual dates. Some examples:
+
+```text
+14.4.1965, 14/04/1965, …
+14-apr-1965, 14 Apr 1965, …
+April 1965, apr 1965, …
+13.12.05, 13-12-05, …
+April, APR, …
+```
+
+See ```Quando.config.formats``` for details.
+
+### Multiple ways to configure
+
+You can configure Quando instances independently of each other and of the class:
+
 ```ruby
 Quando.parse('14-abril-1965') #=> nil
 
 date_parser = Quando::Parser.new.configure do |c|
-  # here be the options from the previous example
+  # …some configuration…
 end
 date_parser.parse('14-abril-1965') #=> #<Date: 1965-04-14>
 
 Quando.parse('14-abril-1965') #=> nil
 ```
 
-#### Or just one-time usage:
+or just pass a format matcher as a parameter:
+
 ```ruby
 m = /(?<year>#{Quando.config.year}) (?<day>\d\d) (?<month>[A-Z]+)/i
 Quando.parse('1965 14 Apr', matcher: m) #=> #<Date: 1965-04-14>
 ```
 
-Enjoy.
+### Requirements
+
+Ruby >= 1.9.3. Enjoy!

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'quando'
+require 'pry'
+
+Pry.start

data/lib/quando/config.rb

@@ -4,77 +4,106 @@
 module Quando
   class Config
 
-    AVAILABLE_OPTIONS = [
-      :dlm, :year, :day,
-      :jan, :feb, :mar, :apr, :may, :jun, :jul, :aug, :sep, :oct, :nov, :dec,
-      :month_num, :month_txt,
-      :formats
-    ]
+    MONTHS = [:jan, :feb, :mar, :apr, :may, :jun, :jul, :aug, :sep, :oct, :nov, :dec]
+    AUTOUPDATE = [:dlm, :year, :year2, :day, *MONTHS, :month_num]
+    COMPOUND = [:month_txt, :formats]
+    OPTIONS = [*AUTOUPDATE, *COMPOUND, :century]
 
-    attr_accessor *AVAILABLE_OPTIONS
+    private_constant :AUTOUPDATE, :COMPOUND, :OPTIONS
 
-    MONTHS = [:jan, :feb, :mar, :apr, :may, :jun, :jul, :aug, :sep, :oct, :nov, :dec]
+    attr_accessor *OPTIONS
 
     def initialize
-      @dlm = /[ -.\/\\]/
-      @year = /(?<year>(?:\d{2})|(?:\d{4}))/i
-      @month_num = /(?<month>(?:1[0-2])|(?:0?[1-9]))/
-      @day = /(?<day>(?:[3][0-1])|(?:[1-2][0-9])|(?:0?[1-9]))/
-
-      @jan = /(?:JANUARY)|(?:JAN\.?)/i
-      @feb = /(?:FEBRUARY)|(?:FEB\.?)/i
-      @mar = /(?:MARCH)|(?:MAR\.?)/i
-      @apr = /(?:APRIL)|(?:APR\.?)/i
-      @may = /(?:MAY\.?)/i
-      @jun = /(?:JUNE)|(?:JUN\.?)/i
-      @jul = /(?:JULY)|(?:JUL\.?)/i
-      @aug = /(?:AUGUST)|(?:AUG\.?)/i
-      @sep = /(?:SEPTEMBER)|(?:SEPT?\.?)/i
-      @oct = /(?:OCTOBER)|(?:OCT\.?)/i
-      @nov = /(?:NOVEMBER)|(?:NOV\.?)/i
-      @dec = /(?:DECEMBER)|(?:DEC\.?)/i
+      @century = 2000
+
+      @dlm = /[ -.\/]+/
+      @year = /(?<year> \d{4})/x
+      @year2 = /(?<year> \d{2})/x
+      @month_num = /(?<month> 1[0-2] | 0?[1-9])/x
+      @day = /(?<day> 3[0-1] | [12][0-9] | 0?[1-9])/x
+
+      @jan = /JAN(?:UARY)?/xi
+      @feb = /FEB(?:RUARY)? /xi
+      @mar = /MAR(?:CH)?/xi
+      @apr = /APR(?:IL)?/xi
+      @may = /MAY/xi
+      @jun = /JUNE?/xi
+      @jul = /JULY?/xi
+      @aug = /AUG(?:UST)?/xi
+      @sep = /SEP(?:TEMBER)?/xi
+      @oct = /OCT(?:OBER)?/xi
+      @nov = /NOV(?:EMBER)? /xi
+      @dec = /DEC(?:EMBER)? /xi
 
       uniupdate!
     end
 
+    # Sets @month_txt which is a compound of all month regexps and matches any month name
+    def unimonth!
+      all_months_txt_rxs = MONTHS.map { |m| instance_variable_get("@#{m}".to_sym) }.join('|')
+      @month_txt = Regexp.new("(?<month>#{all_months_txt_rxs})", true)
+    end
+
+    # Sets @formats which is an array of regexps used in succession to match and identify parts of the dates
     def uniformats!
       @formats = [
-        # 14.4.1965, 14/04/1965, 13-12-05
+        # Formats with a 4-digits year
+        # 14.4.1965, 14/04/1965, 14-4-1965, 14 04 1965, …
         /\A\s* #{@day} #{@dlm} #{@month_num} #{@dlm} #{@year} \s*\z/xi,
 
-        # 14-APRIL-1965, 14-apr-65, 13/Dec/05, …
+        # 14-APRIL-1965, 14-apr-1965, 14/Apr/1965, …
         /\A\s* #{@day} #{@dlm} #{@month_txt} #{@dlm} #{@year} \s*\z/xi,
 
-        # April 1965, apr.1965, DEC-05, …
+        # April 1965, apr.1965, …
         /\A\s* #{@month_txt} #{@dlm} #{@year} \s*\z/xi,
 
-        # April, DECEMBER, apr., …
+        # Same formats with a 2-digits year
+        # 13.12.05, 13/12/05, 13-12-05, …
+        /\A\s* #{@day} #{@dlm} #{@month_num} #{@dlm} #{@year2} \s*\z/xi,
+
+        # April, DECEMBER, sep., …
         /\A\s* #{@month_txt} \s*\z/xi,
       ]
     end
 
-    def unimonth!
-      all_months_txt_rxs = MONTHS.map { |m| instance_variable_get("@#{m}".to_sym) }.join('|')
-      @month_txt = Regexp.new("(?<month>#{all_months_txt_rxs})", true)
-    end
-
+    # A single method to update all compound matchers when a part matcher was changed
     def uniupdate!
       unimonth!
       uniformats!
     end
 
+    # Batch-define setters for date part matchers (listed in AUTOUPDATE) that, when set,
+    # automatically update the compound matchers (listed in COMPOUND)
+    AUTOUPDATE.each do |var|
+      # def jan=(regexp)
+      #   return regexp if @jan == regexp
+      #   @jan = regexp
+      #   uniupdate!
+      # end
+      define_method("#{var}=".to_sym) do |regexp|
+        var_name = "@#{var}".to_sym
+        return regexp if instance_variable_get(var_name) == regexp
+        instance_variable_set(var_name, regexp)
+        uniupdate!
+      end
+    end
   end
 
+  # Quando's class-level configuration
   # @return [Quando::Config]
   def self.config
     @config ||= Config.new
   end
 
+  # @return [Quando::Config]
   def self.configure
     config unless @config
     yield(config) if block_given?
+    @config
   end
 
+  # Reset Quando's class-level configuration to defaults
+  # @return [Quando::Config]
   def self.reset!
     @config = Config.new
   end

data/lib/quando/parser.rb

@@ -48,7 +48,7 @@ module Quando
       return unless found?(:year)
 
       year = @date_parts[:year].to_i
-      year < 100 ? year + 2000 : year
+      year < 100 ? year + config.century : year
     end
 
     # @return [Integer, nil]
@@ -58,7 +58,7 @@ module Quando
 
       month = @date_parts[:month]
 
-      if config.month_num.match(month)
+      month_num = if config.month_num.match(month)
         month.to_i
       else
         month_index = Quando::Config::MONTHS.find_index do |month_name|
@@ -68,6 +68,8 @@ module Quando
 
         month_index + 1 if month_index
       end
+
+      month_num if (1..12).include?(month_num)
     end
 
     # @return [Integer, nil]
@@ -76,6 +78,7 @@ module Quando
       return unless found?(:day)
 
       day = @date_parts[:day].to_i
+
       day if (1..31).include?(day)
     end
 

data/lib/quando/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quando
-  VERSION = '0.0.4'
+  VERSION = '0.0.5'
 end

data/lib/quando.rb

@@ -7,8 +7,10 @@ require 'quando/parser'
 
 module Quando
 
-  # @param opts [Hash]
   # @param date [String]
+  # @param opts [Hash]
+  # @option opts [Regexp, Array<Regexp>] :matcher (nil)
+  # @option opts [Integer] :century (nil)
   # @return [Date, nil]
   def self.parse(date, opts = {})
     return if (date = date.to_s.strip).empty?
@@ -21,6 +23,12 @@ module Quando
       end
     end
 
+    if opts[:century]
+      p.configure do |c|
+        c.century = opts[:century]
+      end
+    end
+
     p.parse(date)
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quando
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Sergey Konotopov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-10-14 00:00:00.000000000 Z
+date: 2019-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -79,13 +79,16 @@ files:
 - ".rspec"
 - Gemfile
 - Gemfile.lock
+- LICENSE.md
 - README.md
 - Rakefile
+- bin/console
 - lib/quando.rb
 - lib/quando/config.rb
 - lib/quando/parser.rb
 - lib/quando/version.rb
 - quando.gemspec
+- quando.png
 homepage: https://github.com/kinkou/quando
 licenses: []
 metadata: {}
@@ -104,8 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Configurable date parser