tickle 0.1.3 → 0.1.5

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Joshua Lippiner
+Copyright (c) 2010 Joshua Lippiner
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -2,11 +2,11 @@
   http://github.com/noctivityinc/tickle
   by Joshua Lippiner, Noctivity
 
-** LEGACY WARNING
+== *LEGACY WARNING*
 
 If you starting using Tickle pre version 0.1.X, you will need to update your code to either include the :next_only => true option or read correctly from the options hash.  Sorry.
 
--- DESCRIPTION
+== DESCRIPTION
 
 Tickle is a natural language parser for recurring events.
  
@@ -14,17 +14,17 @@ Tickle is designed to be a compliment of Chronic and can interpret things such a
 
 Tickle has one main method, "Tickle.parse," which returns the next time the event should occur, at which point you simply call Tickle.parse again.   
 
--- INSTALLATION
+== INSTALLATION
 
 Tickle can be installed via RubyGems:
 
 $ gem install tickle
 
--- TINKERING
+== TINKERING
 
 Everything's at Github - http://github.com/noctivityinc/tickle
 
--- DEPENDENCIES
+== DEPENDENCIES
 
 chronic gem (gem install chronic)
 
@@ -37,31 +37,31 @@ You can parse strings containing a natural language interval using the Tickle.pa
 You can either pass a string prefixed with the word "every, each or 'on the'" or simply the time frame.   
 
 Tickle.parse returns a hash containing the following keys:
-* next = the next occurrence of the event.  This is NEVER today as its always the next date in the future.
-* starting = the date all calculations as based on.  If not passed as an option, the start date is right now.
-* until = the last date you want this event to run until.
-* expression = this is the natural language expression to store to run through tickle later to get the next occurrence.
+    * next = the next occurrence of the event.  This is NEVER today as its always the next date in the future.
+    * starting = the date all calculations as based on.  If not passed as an option, the start date is right now.
+    * until = the last date you want this event to run until.
+    * expression = this is the natural language expression to store to run through tickle later to get the next occurrence.
 
 Tickle returns nil if it cannot parse the string cannot be parsed.
 
 Tickle HEAVILY uses chronic for parsing both the event and the start date.
 
--- OPTIONS
+=== OPTIONS
 
 There are two ways to pass options: natural language or an options hash.
 
 NATURAL LANGUAGE:
-Pass a start date with the word "starting, start, stars" (e.g. Tickle.parse('every 3 days starting next friday'))
-Pass an end date with the word "until, end, ends, ending" (e.g. Tickle.parse('every 3 days until next friday'))
-Pass both at the same time (e.g. "starting May 5th repeat every other week until December 1")
+    * Pass a start date with the word "starting, start, stars" (e.g. Tickle.parse('every 3 days starting next friday'))
+    * Pass an end date with the word "until, end, ends, ending" (e.g. Tickle.parse('every 3 days until next friday'))
+    * Pass both at the same time (e.g. "starting May 5th repeat every other week until December 1")
 
 OPTIONS HASH
 Valid options are:
-* start - must be a valid date. (e.g. Tickle.parse('every other day', {:start => Date.new(2010,8,1) }))
-* until - must be a valid date. (e.g. Tickle.parse('every other day', {:until => Date.new(2010,10,1) }))
-* next_only - legacy switch to ONLY return the next occurrence as a date and not return a hash
+    * start - must be a valid date. (e.g. Tickle.parse('every other day', {:start => Date.new(2010,8,1) }))
+    * until - must be a valid date. (e.g. Tickle.parse('every other day', {:until => Date.new(2010,10,1) }))
+    * next_only - legacy switch to ONLY return the next occurrence as a date and not return a hash
 
--- SUPER IMPORTANT NOTE ABOUT NEXT OCCURRENCE & START DATE
+=== SUPER IMPORTANT NOTE ABOUT NEXT OCCURRENCE & START DATE
 
 You may notice when parsing an expression with a start date that the next occurrence IS the start date passed.  This is DESIGNED BEHAVIOR.  
 
@@ -69,7 +69,7 @@ Here's why - assume your user says "remind me every 3 weeks starting Dec 1" and
 
 If you don't like that, fork and have fun but don't say I didn't warn ya.
 
--- EXAMPLES
+=== EXAMPLES
 
   require 'rubygems'
   require 'tickle'
@@ -153,7 +153,7 @@ WITH OPTIONS HASH
   Tickle.parse('3 months, {:until=>Thu, 07 Oct 2010}')  #=> {:next=>2010-08-08 14:01:19 -0400, :recurrence_expression=>"3 months", :starting=>2010-05-07 14:01:19 -0400, :until=>2010-10-07 00:00:00 -0400}
   .
 
--- USING IN APP
+== USING IN APP
 
 To use in your app, we recommend adding two attributes to your database model:
 * next_occurrence
@@ -165,14 +165,14 @@ code, each day, simply check to see if today is >= next_occurrence and, if so, r
 After it completes, call Tickle.parse(tickle_expression) again to update the next occurrence of the event.
 
 
--- TESTING
+== TESTING
 
 Tickle comes with a full testing suite that tests and shows sample output for simple, complex, options hash and invalid arguments.
 
 Please note, the tests were designed to output the parsed expression and not return true.  This allows (and sorry, forces you) to have to skim through the 
 results and queries to ensure they are working correctly.  You can also add your own for fun.
 
--- LIMITATIONS
+== LIMITATIONS
 
 Currently, Tickle only works for day intervals but feel free to fork and add time-based interval support or send me a note if you really want me to add it.
 
@@ -187,13 +187,13 @@ As always, BIG shout-out to the RVM Master himself, Wayne Seguin, for putting up
 
 == Note on Patches/Pull Requests
  
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for time-based branches.
+    * Fork the project.
+    * Make your feature addition or bug fix.
+    * Add tests for it. This is important so I don't break it in a
+      future version unintentionally.
+    * Commit, do not mess with rakefile, version, or history.
+      (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+    * Send me a pull request. Bonus points for time-based branches.
 
 == Copyright
 

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.1.5

data/git-flow-version

@@ -1 +1 @@
-GITFLOW_VERSION=0.1.3
+GITFLOW_VERSION=0.1.5

data/lib/tickle.rb

@@ -17,8 +17,8 @@ require 'tickle/tickle'
 require 'tickle/handler'
 require 'tickle/repeater'
 
-module Tickle
-  VERSION = "0.1.3"
+module Tickle #:nodoc:
+  VERSION = "0.1.5"
 
   def self.debug; false; end
 
@@ -36,7 +36,8 @@ module Tickle
   end
 end
 
-class Date
+class Date #:nodoc:
+  # returns the days in the sending month
   def days_in_month
     d,m,y = mday,month,year
     d += 1 while Date.valid_civil?(y,m,d)
@@ -44,7 +45,8 @@ class Date
   end
 end
 
-class String
+class String #:nodoc:
+  # returns true if the sending string is a text or numeric ordinal (e.g. first or 1st)
   def is_ordinal?
     scanner = %w{first second third fourth fifth sixth seventh eighth ninth tenth eleventh twelfth thirteenth fourteenth fifteenth sixteenth seventeenth eighteenth nineteenth twenty thirty thirtieth}
     regex = /\b(\d*)(st|nd|rd|th)\b/
@@ -52,7 +54,8 @@ class String
   end
 end
 
-class Array
+class Array #:nodoc:
+  # compares two arrays to determine if they both contain the same elements
   def same?(y)
     self.sort == y.sort
   end

data/lib/tickle/handler.rb

@@ -1,6 +1,10 @@
-module Tickle
-  class << self
+module Tickle #:nodoc:
+  class << self #:nodoc:
 
+    # The heavy lifting.  Goes through each token groupings to determine what natural language should either by 
+    # parsed by Chronic or returned.  This methodology makes extension fairly simple, as new token types can be 
+    # easily added in repeater and then processed by the guess method
+    #
     def guess()
       guess_unit_types
       guess_weekday unless @next

data/lib/tickle/tickle.rb

@@ -1,6 +1,38 @@
-module Tickle
-  class << self
-
+# Copyright (c) 2010 Joshua Lippiner
+#
+# 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.
+
+module Tickle  #:nodoc:
+  class << self #:nodoc:
+    # == Configuration options
+    #
+    # * +start+ - start date for future occurrences.  Must be in valid date format.
+    # * +until+ - last date to run occurrences until.  Must be in valid date format.
+    # 
+    #  Use by calling Tickle.parse and passing natural language with or without options.
+    #      
+    #  def get_next_occurrence
+    #      results = Tickle.parse('every Wednesday starting June 1st until Dec 15th')
+    #      return results[:next] if results
+    #  end
+    #
     def parse(text, specified_options = {})
       # get options and set defaults if necessary
       default_options = {:start => Time.now, :next_only => false, :until  => nil}
@@ -59,10 +91,7 @@ module Tickle
       if !best_guess
         return nil
       elsif options[:next_only] != true
-        h = {:next => best_guess.to_time, :recurrence_expression => event.strip}
-        h.merge!({:starting => @start.to_time}) if @start
-        h.merge!({:until => @until.to_time}) if @until
-        return h
+        return {:next => best_guess.to_time, :expression => event.strip, :starting => @start, :until => @until}
       else
         return best_guess
       end
@@ -86,16 +115,13 @@ module Tickle
         event, ending = process_for_ending(text)
       end
 
-      @start = (starting && Tickle.parse(pre_filter(starting), {:next_only => true}) || options[:start])
+      @start = (starting && Tickle.parse(pre_filter(starting), {:next_only => true}) || options[:start]).to_time
       @until = (ending && Tickle.parse(pre_filter(ending), {:next_only => true})  || options[:until])
+      @until = @until.to_time if @until
       @next = nil
       return event
     end
 
-    def inspect_matches
-
-    end
-
     # process the remaining expression to see if an until, end, ending is specified
     def process_for_ending(text)
       regex = /^(.*)(\s(?:end|until)(?:s|ing)?)(.*)/i
@@ -179,10 +205,15 @@ module Tickle
 
     protected
 
+    # Returns the next available month based on the current day of the month.
+    # For example, if get_next_month(15) is called and today is the 10th, then it will return the 15th of this month.
+    # However, if get_next_month(15) is called and today is the 18th, it will return the 15th of next month.
     def get_next_month(number)
       month = number.to_i < Date.today.day ? (Date.today.month == 12 ? 1 : Date.today.month + 1) : Date.today.month
     end
 
+    # Return the number of days in a specified month.
+    # If no month is specified, current month is used.
     def days_in_month(month=nil)
       month ||= Date.today.month
       days_in_mon = Date.civil(Date.today.year, month, -1).day
@@ -200,6 +231,7 @@ module Tickle
       @start = start
     end
 
+    # Updates an existing token.  Mostly used by the repeater class.
     def update(type, start=nil, interval=nil)
       @start = start
       @type = type
@@ -210,12 +242,10 @@ module Tickle
   # This exception is raised if an invalid argument is provided to
   # any of Tickle's methods
   class InvalidArgumentException < Exception
-
   end
 
   # This exception is raised if there is an issue with the parsing
   # output from the date expression provided
   class InvalidDateExpression < Exception
-
   end
 end

data/tickle.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{tickle}
-  s.version = "0.1.3"
+  s.version = "0.1.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Joshua Lippiner"]

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 3
-  version: 0.1.3
+  - 5
+  version: 0.1.5
 platform: ruby
 authors: 
 - Joshua Lippiner