midnight 0.0.1.pre

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 bluefuton
+
+MIT License
+
+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

@@ -0,0 +1,30 @@
+# Midnight
+
+A library to parse natural language date/time into a cron expression.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'midnight'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install midnight
+
+## Usage
+
+<pre>Midnight.parse('every 5 minutes').to_s
+ => "*/5 * * * *"</pre>
+
+## Contributing
+
+1. Fork it ( http://github.com/bluefuton/midnight/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/README.textile

@@ -0,0 +1,20 @@
+h1. midnight
+
+<img src="https://api.travis-ci.org/bluefuton/midnight.png" alt="Travis build status" />
+
+A library to parse natural language date/time into a cron expression.
+
+<pre>Midnight.parse('every 5 minutes').to_s
+ => "*/5 * * * *"</pre>
+
+h2. Supported phrases
+
+A full list of supported natural language phrases can be found in <a href="https://github.com/bluefuton/midnight/blob/develop/test/test_parsing.rb">test_parsing.rb</a>.
+
+In the future there'll be support for more complex repetitions - a wishlist can be found in <a href="https://github.com/bluefuton/midnight/blob/develop/todo.txt">todo.txt</a>.
+
+h2. Credits
+
+My tokeniser code is based on the excellent <a href="https://github.com/yb66/tickle">Tickle</a> gem, which in turn relies on <a href="https://github.com/mojombo/chronic">Chronic</a> for date parsing.
+
+Author: Chris Rosser <chris@bluefuton.com>

data/Rakefile

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+task :default => 'test'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  #test.verbose = true
+end

data/lib/midnight.rb

@@ -0,0 +1,42 @@
+#=============================================================================
+#
+#  Name:       Midnight
+#  Author:     Chris Rosser
+#  Purpose:    Parse natural language date/time into a cron expression
+#
+#=============================================================================
+
+$:.unshift File.dirname(__FILE__)     # For use/testing when no gem is installed
+
+require 'date'
+require 'time'
+require 'chronic'
+
+require 'midnight/midnight'
+require 'midnight/handler'
+require 'midnight/repeater'
+require 'midnight/cron_expression'
+require 'midnight/converter'
+require 'midnight/version'
+
+module Midnight
+  def self.debug; false; end
+
+  def self.dwrite(msg)
+    puts msg if Midnight.debug
+  end
+end
+
+class Date
+   def days_in_month
+     d,m,y = mday,month,year
+     d += 1 while Date.valid_civil?(y,m,d)
+     d - 1
+   end
+end
+
+class Array
+  def same?(y)
+    self.sort == y.sort
+  end
+end

data/lib/midnight/converter.rb

@@ -0,0 +1,152 @@
+class Midnight::Converter
+  attr_accessor :expr, :tokens
+
+  def convert_tokens_to_cron_expression(tokens)
+    @expr = Midnight::CronExpression.new
+    @tokens = tokens
+
+    return @expr if @tokens.empty? || tokens.detect { |t| t.type == :special }
+
+    detect_minute_repetition
+    detect_hour_repetition
+    detect_day_repetition
+    detect_weekday_repetition
+    detect_week_repetition
+    detect_month_repetition
+    detect_year_repetition
+
+    #puts tokens.inspect
+    @expr
+  end
+
+  protected
+  def detect_minute_repetition
+    @tokens.each do |token|
+      if (token.type == :minute_word)
+        num_token = tokens.detect { |t| t.type == :number }
+        hour_token = tokens.detect { |t| t.type == :hour }
+        if num_token.is_a?(Midnight::Token)
+          @expr.minute = '*/' + num_token.interval.to_s
+        elsif !hour_token.nil?
+          @expr.hour = adjust_hour_for_meridiem(hour_token.word)
+          @expr.minute = token.word
+        elsif @tokens.length == 1  
+          @expr.force_run_every_minute = true
+        end 
+      end
+
+      if (token.type == :minute)
+        @expr.minute = token.word
+      end
+    end
+  end
+
+  def detect_hour_repetition
+    num_token = tokens.detect { |t| t.type == :number }
+
+    @tokens.each do |token|
+      if (token.type == :hour)
+        @expr.minute = 0 if @expr.minute.nil?
+        num_token = tokens.detect { |t| t.type == :number }
+        if num_token.is_a?(Midnight::Token)
+          @expr.hour = '*/' + num_token.interval.to_s
+        elsif @tokens.length == 1
+          @expr.hour = nil
+        else
+          @expr.hour = adjust_hour_for_meridiem(token.word)
+        end 
+      end
+
+      if (token.type == :meridiem && !num_token.nil?)
+        @expr.hour = adjust_hour_for_meridiem(num_token.word)
+      end
+    end      
+  end
+
+  def detect_week_repetition
+    token = @tokens.first
+
+    if (token.type == :week && token.interval == 7)
+      @expr.day_of_week = 0
+      @expr.hour = 0
+      @expr.minute = 0
+    end
+  end
+
+  def detect_weekday_repetition
+    token = @tokens.detect { |t| t.type == :weekday }
+    if (!token.nil?)
+      @expr.day_of_week = token.position_in_sequence
+      if !@tokens.detect { |t| t.type == :minute_word }
+        @expr.hour = 0 if @expr.hour.nil?
+      end
+      @expr.minute = 0 if @expr.minute.nil?
+    end
+  end    
+
+  def detect_day_repetition
+    @tokens.each do |token|
+      if (token.type == :day && token.interval == 1)
+        @expr.minute = '0'
+
+        # Do we need to run it at a specific time?
+        hour_token = tokens.detect { |t| t.type == :number || t.type == :hour }
+        if hour_token.is_a?(Midnight::Token)
+
+          hour = hour_token.interval if hour_token.type == :number
+          hour = hour_token.word if hour_token.type == :hour
+
+          # Is there a meridiem token (am/pm) too?
+          hour = adjust_hour_for_meridiem(hour)
+
+          # Is a minute specified?
+          minute_token = tokens.detect { |t| t.type == :minute }
+          if minute_token.is_a?(Midnight::Token)          
+            @expr.minute = minute_token.word
+          end
+
+          @expr.hour = hour
+        else
+          @expr.hour = 0
+        end 
+      end
+    end
+  end
+
+  def detect_month_repetition
+    token = @tokens.first
+    if (token.type == :month)
+      @expr.day_of_month = 1
+      @expr.hour = 0
+      @expr.minute = 0
+    end
+  end     
+
+  def detect_year_repetition
+    token = @tokens.first
+    if (token.type == :year || token.type == :month_name)
+      @expr.day_of_month = 1
+      @expr.hour = 0
+      @expr.minute = 0
+      @expr.month = 1
+      @expr.month = token.position_in_sequence if token.type == :month_name
+    end
+  end 
+
+  def adjust_hour_for_meridiem(hour)
+    hour = hour.to_i
+
+    # Is there a meridiem token (am/pm)?
+    meridiem_token = @tokens.detect { |t| t.type == :meridiem } 
+
+    if (!meridiem_token.nil? && meridiem_token.word == 'pm' && hour < 12)
+      hour = hour + 12
+    end
+
+    if hour == 24
+      hour = 0
+    end
+
+    hour
+  end
+end

data/lib/midnight/cron_expression.rb

@@ -0,0 +1,38 @@
+# * * * * *  command to execute
+# ┬ ┬ ┬ ┬ ┬
+# │ │ │ │ │
+# │ │ │ │ │
+# │ │ │ │ └───── day of week (0 - 7) (0 to 6 are Sunday to Saturday, or use names; 7 is Sunday, the same as 0)
+# │ │ │ └────────── month (1 - 12)
+# │ │ └─────────────── day of month (1 - 31)
+# │ └──────────────────── hour (0 - 23)
+# └───────────────────────── min (0 - 59)
+class Midnight::CronExpression #:nodoc:
+  attr_accessor :minute, :hour, :day_of_month, :month, :day_of_week, :force_run_every_minute
+
+  def to_s
+    return '* * * * *' if (@force_run_every_minute === true)
+
+    expression_parts = [
+      get_attribute(:minute),
+      get_attribute(:hour),
+      get_attribute(:day_of_month),
+      get_attribute(:month),
+      get_attribute(:day_of_week)
+    ]
+
+    # Better to return nil than accidentally recommend that people run a job every minute
+    # Set force_run_every_minute to true to return * * * * * 
+    if (expression_parts.select { |x| x != '*'}.empty?)
+      return nil
+    end 
+
+    expression_parts.join(' ')
+  end
+
+  protected
+  def get_attribute(symbol)
+    attribute = instance_variable_get('@' + symbol.to_s)
+    attribute.nil? ? '*' : attribute.to_s
+  end
+end

data/lib/midnight/handler.rb

@@ -0,0 +1,104 @@
+module Midnight
+  class << self
+
+    def guess()
+      # Not sure we'll need interval for cron output
+      interval = guess_unit_types
+      interval ||= guess_weekday
+      interval ||= guess_weekday
+      interval ||= guess_month_names
+      interval ||= guess_number_and_unit
+      interval ||= guess_special
+
+      # defines the next occurrence of this midnight if not set in a guess routine
+      @next ||= @start + (interval * 60 * 60 * 24) if interval
+      
+      # # check to see if the start date is > NOW and, if so, set the next occurrence = start
+      @next = @start if @start.to_time > Time.now
+      
+      # # return the next occurrence
+      return @next.to_time if interval
+    end
+
+    def guess_unit_types
+      interval = 1 if token_types.same?([:day])
+      interval = 7 if token_types.same?([:week])
+      interval = 30 if token_types.same?([:month])
+      interval = 365 if token_types.same?([:year])
+      interval
+    end
+
+    def guess_weekday
+      if token_types.same?([:weekday]) then
+        @start = Chronic.parse(token_of_type(:weekday).start.to_s)
+        interval = 7
+      end
+      interval
+    end
+
+    def guess_month_names
+      if token_types.same?([:month_name]) then
+        @start = Chronic.parse("#{token_of_type(:month_name).start.to_s} 1")
+        interval = 30
+      end
+      interval
+    end
+
+    def guess_number_and_unit
+      interval = token_of_type(:number).interval if token_types.same?([:number, :day])
+      interval = (token_of_type(:number).interval * 7) if token_types.same?([:number, :week])
+      interval = (token_of_type(:number).interval * 30) if token_types.same?([:number, :month])
+      interval = (token_of_type(:number).interval * 365) if token_types.same?([:number, :year])
+      interval
+    end
+
+    def guess_special
+      interval = guess_special_other
+      interval ||= guess_special_beginning
+      interval ||= guess_special_middle
+      interval ||= guess_special_end
+    end
+
+    private
+
+    def guess_special_other
+      interval = 2 if token_types.same?([:special, :day]) && token_of_type(:special).start == :other
+      interval = 14 if token_types.same?([:special, :week]) && token_of_type(:special).start == :other
+      if token_types.same?([:special, :month]) && token_of_type(:special).start == :other then interval = 60;  @next = Chronic.parse('2 months from now'); end
+      if token_types.same?([:special, :year]) && token_of_type(:special).start == :other then interval = 730;  @next = Chronic.parse('2 years from now'); end
+      interval
+    end
+
+    def guess_special_beginning
+      if token_types.same?([:special, :week]) && token_of_type(:special).start == :beginning then interval = 7;  @start = Chronic.parse('Sunday'); end
+      if token_types.same?([:special, :month]) && token_of_type(:special).start == :beginning then interval = 30;  @start = Chronic.parse('1st day next month'); end
+      if token_types.same?([:special, :year]) && token_of_type(:special).start == :beginning then interval = 365;  @start = Chronic.parse('1st day next year'); end
+      interval
+    end
+
+    def guess_special_end
+      if token_types.same?([:special, :week]) && token_of_type(:special).start == :end then interval = 7;  @start = Chronic.parse('Saturday'); end
+      if token_types.same?([:special, :month]) && token_of_type(:special).start == :end then interval = 30;  @start = Date.new(Date.today.year, Date.today.month, Date.today.days_in_month); end
+      if token_types.same?([:special, :year]) && token_of_type(:special).start == :end then interval = 365;  @start = Date.new(Date.today.year, 12, 31); end
+      interval
+    end
+    
+    def guess_special_middle
+      if token_types.same?([:special, :week]) && token_of_type(:special).start == :middle then interval = 7;  @start = Chronic.parse('Wednesday'); end
+      if token_types.same?([:special, :month]) && token_of_type(:special).start == :middle then
+        interval = 30;
+        @start = (Date.today.day >= 15 ? Chronic.parse('15th day of next month') : Date.new(Date.today.year, Date.today.month, 15))
+      end
+      if token_types.same?([:special, :year]) && token_of_type(:special).start == :middle then
+        interval = 365;
+        @start = (Date.today.day >= 15 && Date.today.month >= 6 ? Date.new(Date.today.year+1, 6, 15) : Date.new(Date.today.year, 6, 15))
+      end
+      interval
+    end
+
+    def token_of_type(type)
+      @tokens.detect {|token| token.type == type}
+    end
+
+  end
+end

data/lib/midnight/midnight.rb

@@ -0,0 +1,91 @@
+require_relative "../numerizer/numerizer.rb"
+
+module Midnight
+  class << self
+
+    def parse(text, specified_options = {})
+      # get options and set defaults if necessary
+      default_options = {:start => Time.now}
+      options = default_options.merge specified_options
+
+      # ensure the specified options are valid
+      specified_options.keys.each do |key|
+        default_options.keys.include?(key) || raise(InvalidArgumentException, "#{key} is not a valid option key.")
+      end
+      Chronic.parse(specified_options[:start]) || raise(InvalidArgumentException, ':start specified is not a valid datetime.') if specified_options[:start]
+
+      # remove every is specified
+      text = text.gsub(/^every\s\b/, '')
+
+      # put the text into a normal format to ease scanning using Chronic
+      text = pre_normalize(text)
+      text = Chronic::Parser.new.pre_normalize(text)
+      text = numericize_ordinals(text)
+
+      # check to see if this event starts some other time and reset now
+      event, starting = text.split('starting')
+      @start = (Chronic.parse(starting) || options[:start])
+      @next = nil
+
+      # split into tokens
+      @tokens = base_tokenize(event)
+
+      # scan the tokens with each token scanner
+      @tokens = Repeater.scan(@tokens)
+
+      # remove all tokens without a type
+      @tokens.reject! {|token| token.type.nil? }
+
+      converter = Converter.new
+      cron_expression = converter.convert_tokens_to_cron_expression(@tokens)
+
+      return cron_expression
+    end
+
+    # Normalize natural string removing prefix language
+    def pre_normalize(text)
+      normalized_text = text.gsub(/^every\s\b/, '')
+      normalized_text = text.gsub(/^each\s\b/, '')
+      normalized_text = text.gsub(/^on the\s\b/, '')
+      normalized_text
+    end
+
+    # Split the text on spaces and convert each word into
+    # a Token
+    def base_tokenize(text) #:nodoc:
+      text.split(' ').map { |word| Token.new(word) }
+    end
+
+    # Convert ordinal words to numeric ordinals (third => 3rd)
+    def numericize_ordinals(text) #:nodoc:
+      text = text.gsub(/\b(\d*)(st|nd|rd|th)\b/, '\1')
+    end
+
+    # Returns an array of types for all tokens
+    def token_types
+      @tokens.map(&:type)
+    end
+  end
+
+  class Token #:nodoc:
+    attr_accessor :word, :type, :interval, :start, :position_in_sequence
+
+    def initialize(word)
+      @word = word
+      @type = @interval = @start = nil
+    end
+
+    def update(type, start=nil, interval=nil, position_in_sequence=nil)
+      @start = start
+      @type = type
+      @interval = interval
+      @position_in_sequence = position_in_sequence
+    end
+  end
+
+  # This exception is raised if an invalid argument is provided to
+  # any of Midnight's methods
+  class InvalidArgumentException < Exception
+
+  end
+end