workpattern 0.3.0 → 0.3.1

data/CHANGELOG

@@ -1,3 +1,7 @@
+## Workpattern v0.3.1 (Oct 14, 2012)  ##
+
+* RDOC documentation not right on rubydoc.info (#5) * Barrie Callender *
+
 ## Workpattern v0.3.0 (Jul 19, 2012)  ##
 
 * incomplete tests for week (#2) * Barrie Callender *

data/README.md

@@ -4,6 +4,25 @@
 
 Simple addition and subtraction of minutes on dates taking account of real-life working and resting periods.
 
+## So What?
+
+The core Ruby classes that represent date and time allow calculations by adding a duration such as days or 
+minutes to a date and returning the new `Date` or `DateTime` as the result.  Although there 
+are 60 seconds in every minute and 60 minutes in every hour, there aren't always 24 hours in every day, and 
+if there was, we still wouldn't be working during all of them.  We would be doing other things like eating,
+sleeping, travelling and having a bit of leisure time.  Workpattern refers to this time as Resting time.
+It refers to the time when we're busy doing stuff as Working time.
+
+When it comes to scheduling work, whether part of a project, teachers in a classroom or even bed availability
+in a hospital, the working day can have anything from 0 hours to the full 24 hours.  Most office based work
+is something like 7.5 or 8 hours a day except weekends, public holidays and vacations when no work takes 
+place.
+
+The `Workpattern` library was born to allow date related calculations to take  into account real life 
+working and resting times.  It gets told about working and resting periods and can then perform calculations
+on a given date.  It can add and subtract a number of minutes, calculate the working minutes between two dates 
+and say whether a specific minute is working or resting.
+
 This gem has the potential to serve as the engine for scheduling algorithms that are the core of products such as Microsoft Project and Oracle Primavera P6 as well as other applications that need to know when they can perform work and when they can’t.
 
 ## Install
@@ -12,19 +31,19 @@ This gem has the potential to serve as the engine for scheduling algorithms that
 
 ## Getting Started
 
-The first step is to create a **Workpattern** to hold all the working and resting times.  I'll start in 2011 and let it run for 10 years.
+The first step is to create a `Workpattern` to hold all the working and resting times.  I'll start in 2011 and let it run for 10 years.
 
 ``` ruby
 mywp=Workpattern.new('My Workpattern',2011,10)
 ```
 
-My **Workpattern** will be created as a 24 hour a day full working time.  Now it has to be told about the resting periods.  First the weekends.
+My `Workpattern` will be created as a 24 hour a day full working time.  Now it has to be told about the resting periods.  First the weekends.
 
 ``` ruby
 mywp.resting(:days => :weekend)
 ```
 
-then the days in the week have specific working and resting times using the *Workpattern.clock* method, although anything that responds to **hour** and **min** methods will do ...
+then the days in the week have specific working and resting times using the *Workpattern.clock* method, although anything that responds to `#hour` and `#min` methods will do ...
 
 ``` ruby
 mywp.resting(:days =>:weekday, :from_time=>Workpattern.clock(0,0),:to_time=>Workpattern.clock(8,59))
@@ -47,6 +66,32 @@ result_date = mywp.calc(mydate,1920) # => 6/9/11@18:00
 * Pull requests are very welcome, however I have never participated in Open Source so will be a bit slow as I am learning. Please be patient with me.  Please include spec and/or feature coverage for every patch,  and create a topic branch for every separate change you make.
 * Advice, such as pointing out how I should really code in Ruby will be gratefully received.
 
+## Things To Do
+
+In its current form this library is being made available to see if there is any interest in using 
+it. At the moment it can perform the following:
+
+* define the working and resting minutes for any 24 hour day
+* given a date it can return the resulting date after adding or subtracting a number of minutes
+* calculate the number of working minutes between two dates
+* report whether a specific minute in time is working or resting
+
+This is what I consider to be the basics, but there are a number of functional and non-functial areas I 
+would like to address in a future version.
+
+## Functional
+
+* Merge two Workpatterns together to create a new one allowing either resting or working to take precedence
+* Given a date, find the next working or resting minute either before or after it.
+* Handle both 23 and 25 hour days that occur when the clocks change.
+* Extract patterns from the workpattern so they can be persisted in a database.
+* Decide how to handle different Timezones apart from UTC.
+
+## Non-Functional
+
+* Improve the documentation and introduce real world use as an example
+* Improve my ability to write Ruby code
+
 ## License
 
 (The MIT License)

data/lib/workpattern.rb

@@ -24,202 +24,126 @@ require 'workpattern/workpattern'
 #
 # Documentation: Barrie Callender <barrie@callenb.org>
 #
-# == Overview
-#
-# The core Ruby classes that represent date and time allow calculations by
-# adding a duration such as days or minutes to a date and returning the new
-# <tt>Date</tt> or <tt>DateTime</tt> as the result. 
-#
-# Although there are 60 seconds in every minute and 60 minutes in every hour, there
-# aren't always 24 hours in every day, and if there was, we still wouldn't
-# be working during all of them.  We would be doing other things like eating,
-# sleeping, travelling and having a bit of leisure time.  Workpattern refers to this 
-# time as Resting time.  It refers to the time when we're busy doing stuff as
-# Working time.
-#
-# When it comes to scheduling work, whether part of a project, teachers in a 
-# classroom or even bed availability in a hospital, the working day can have
-# anything from 0 hours to the full 24 hours.  Most office based work
-# is something like 7.5 or 8 hours a day except weekends, public holidays and
-# vacations when no work takes place.
-#
-# The <tt>Workpattern</tt> library was born to allow date related calculations to take 
-# into account real life working and resting times.  It gets told about working
-# and resting periods and can then perform calculations on a given date.  It can
-# add and subtract a number of minutes, calculate the working minutes between
-# two dates and say whether a specific minute is working or resting.
-#
-# == Illustration
-#
-# In real life we may be reasonably confident that it will take us 32 hours to
-# write a document.  If we started on a Thursday at 9:00am we wouldn't be
-# working 32 hours without interruption (let's pretend we're not software
-# developers for this one!).  We'd go home at the end of one working day and
-# not return until the next.  The weekend would not include working on the 
-# document either.  We would probably work 8 hours on Thursday, Friday, Monday 
-# and Tuesday to complete the work.
-#
-# The <tt>Workpattern</tt> library will be able to tell you that if you started at 
-# 9:00 am on Thursday, you should be finished at 6:00 pm on Tuesday - allowing an hour
-# for lunch each day!  For it to do that it has to know when you can work and
-# when you are resting.
-#
-# == An Example Session
-# 
-# Using the illustration as a basis, we want to find out when I will finish the document.
-# It is going to take me 32 hours to complete the document and I'm going to start on it 
-# as soon as I arrive at work on the morning of Thursday 1st September 2011.  My working
-# day starts at 9:00am,finishes at 6:00pm and I take an hour for lunch. I don't work 
-# on the weekend.
-#
-# The first step is to create a <tt>Workpattern</tt> to hold all the working and resting times.
-# I'll start in 2011 and let it run for 10 years.
-#
-#  mywp=Workpattern.new('My Workpattern',2011,10)
-#
-# My <tt>Workpattern</tt> will be created as a 24 hour a day full working time.  Now it has to 
-# be told about the resting periods.  First the weekends.
-#
-#  mywp.resting(:days => :weekend)
-# 
-# then the days in the week have specific working and resting times using the 
-# <tt>Time::hm</tt> method added by <tt>Workpattern</tt> ...
-#
-#  mywp.resting(:days =>:weekday, :from_time=>Workpattern.clock(0,0),:to_time=>Workpattern.clock(8,59))
-#  mywp.resting(:days =>:weekday, :from_time=>Workpattern.clock(12,0),:to_time=>Workpattern.clock(12,59))
-#  mywp.resting(:days =>:weekday, :from_time=>Workpattern.clock(18,0),:to_time=>Workpattern.clock(23,59))
-#
-# Now we have the working and resting periods setup we can just add 32 hours as 
-# minutes (1920) to our date.
-#
-#  mydate=DateTime.civil(2011,9,1,9,0)
-#  result_date = mywp.calc(mydate,1920) # => 6/9/11@18:00
-#
-# == Things To Do
-#
-# In its current form this library is being made available to see if there is any interest
-# in using it.  At the moment it can perform the following:
-# * define the working and resting minutes for any 24 hour day
-# * given a date it can return the resulting date after adding or subtracting a number of minutes
-# * calculate the number of working minutes between two dates
-# * report whether a specific minute in time is working or resting
-# This is what I consider to be the basics, but there are a number of functional and 
-# non-functial areas I would like to address in a future version.
-#
-# === Functional
-#
-# * Merge two Workpatterns together to create a new one allowing either resting or working to take precedence
-# * Given a date, find the next working or resting minute either before or after it.
-# * Handle both 23 and 25 hour days that occur when the clocks change.
-# * Extract patterns from the workpattern so they can be persisted in a database.
-# * Decide how to handle different Timezones apart from UTC.
-#
-# === Non-Functional
-#
-# * Improve the documentation and introduce real world use as an example
-# * Improve my ability to write Ruby code
-#
 module Workpattern
   
   # Represents a full working hour
+  # @since 0.2.0
   WORKING_HOUR = 2**60-1
+  
   # Represents a full resting hour
+  # @since 0.2.0  
   RESTING_HOUR = 0
+  
   # The default workpattern name
+  # @since 0.2.0  
   DEFAULT_WORKPATTERN_NAME = 'default'
+  
   # The default base year
+  # @since 0.2.0
   DEFAULT_BASE_YEAR = 2000
+  
   # The default span in years
+  # @since 0.2.0
   DEFAULT_SPAN = 100
+  
   # Hour in terms of days
+  # @since 0.2.0
   HOUR = Rational(1,24)
+  
   # Minute in terms of days
+  # @since 0.2.0
   MINUTE = Rational(1,1440)
-  # earliest or first time in the day
+  
+  # Earliest or first time in the day
+  # @since 0.0.1
   FIRST_TIME_IN_DAY=Clock.new(0,0)
-  # latest or last time in the day
+  
+  # Latest or last time in the day
+  # @since 0.0.1
   LAST_TIME_IN_DAY=Clock.new(23,59)
-  # specifies a working pattern
+  
+  # Specifies a working pattern
+  # @since 0.0.1
   WORK = 1
-  # specifies a resting pattern
+  
+  # Specifies a resting pattern
+  # @since 0.0.1
   REST = 0
+  
   # Represents the days of the week to be used in applying working and resting patterns.
+  # Values exist for each day of the week as well as for the weekend (Saturday and Sunday), 
+  # the week (Monday to Friday) and all days in the week.
   #
-  # ==== Valid Values
-  #
-  # <tt>:sun, :mon, :tue, :wed, :thu, :fri, :sat</tt> a day of the week.
-  # <tt>:all</tt> all days of the week.
-  # <tt>:weekend</tt> Saturday and Sunday.
-  # <tt>:weekday</tt> Monday to Friday inclusive.
-  #
+  # @since 0.0.1
   DAYNAMES={:sun => [0],:mon => [1], :tue => [2], :wed => [3], :thu => [4], :fri => [5], :sat => [6],
               :weekday => [1,2,3,4,5],
               :weekend => [0,6],
               :all => [0,1,2,3,4,5,6]}
               
-  # :call-seq: new(name, base, span) => workpattern 
+  # Covenience method to obtain a new <tt>Workpattern</tt> 
   #
-  # Covenience method to obtain a new <tt>Workpattern::Workpattern</tt> 
+  # A negative <tt>span</tt> counts back from the <tt>base</tt> year
   #
-  # ==== Parameters
+  # @param [String] name Every workpattern has a unique name.
+  # @param [Integer] base Workpattern starts on the 1st January of this year.
+  # @param [Integer] span Workpattern spans this number of years ending on 31st December.
+  # @return [Workpattern]
   #
-  # +name+:: 
-  #   Every workpattern has a unique name.
-  # +base+:: 
-  #   The starting year for the range of dates the Calendar
-  #   can use.  Always the 1st january.
-  # +span+:: 
-  #   Duration of the Calendar in years.  If <tt>span</tt> is negative
-  #   then the range counts backwards from the <tt>base</tt>.
+  # @since 0.2.0
   #
   def self.new(name=DEFAULT_WORKPATTERN_NAME, base=DEFAULT_BASE_YEAR, span=DEFAULT_SPAN)
     return Workpattern.new(name, base,span)
   end
   
-  # :call-seq: to_a => array 
+  # Covenience method to obtain an Array of all the known <tt>Workpattern</tt> objects
+  #
+  # @return [Array] all <tt>Workpattern</tt> objects
   #
-  # Covenience method to obtain an Array of all the known <tt>Workpattern::Workpattern</tt> objects
+  # @since 0.2.0
   #
   def self.to_a()
     return Workpattern.to_a
   end
 
-  # :call-seq: get(name) => workpattern 
+  # Covenience method to obtain an existing <tt>Workpattern</tt> 
   #
-  # Covenience method to obtain an existing <tt>Workpattern::Workpattern</tt> 
+  # @param [String] name The name of the Workpattern to retrieve.
+  # @return [Workpattern]
   #
-  # ==== Parameters
-  #
-  # +name+:: The name of the Workpattern.
+  # @since 0.2.0
   #
   def self.get(name)
     return Workpattern.get(name)
   end
   
-  # :call-seq: delete(name) => boolean 
-  #
-  # Convenience method to delete the named <tt>Workpattern::Workpattern</tt>
+  # Convenience method to delete the named <tt>Workpattern</tt>
   #
-  # === Parameters
+  # @param [String] name The name of the Workpattern to be deleted.
   #
-  # +name+:: The name of the Workpattern.
+  # @since 0.2.0
   #
   def self.delete(name)
     Workpattern.delete(name)
   end
    
-  # :call-seq: clear
-  #
   # Convenience method to delete all Workpatterns.
   # 
+  # @since 0.2.0
+  #
   def self.clear
     Workpattern.clear
   end
   
-  # :call-seq: clock(hour,min)
-  #
-  # Convenience method to create a Clock object.  This can be used for specifying times.
+  # Convenience method to create a Clock object.  This can be used for specifying times 
+  # if you don't want to create a <tt>DateTime</tt> object
   # 
+  # @param [Integer] hour the number of hours.
+  # @param [Integer] min the number of minutes
+  # @return [Clock]
+  # @see Clock
+  #
+  # @since 0.2.0
+  #
   def self.clock(hour,min)
     return Clock.new(hour,min)
   end

data/lib/workpattern/clock.rb

@@ -1,27 +1,33 @@
 module Workpattern
   # Represents time on a clock in hours and minutes.
   #
-  # myClock=Clock.new(3,32)
-  # myClock.minutes #=> 212
-  # myClock.hour #=> 3
-  # myClock.min  #=> 32
-  # myClock.time #=> Time.new(1963,6,10,3,32)
-  # 
+  # @example
+  #   myClock=Clock.new(3,32)
+  #   myClock.minutes #=> 212
+  #   myClock.hour #=> 3
+  #   myClock.min  #=> 32
+  #   myClock.time #=> Time.new(1963,6,10,3,32)
+  #   myClock.to_s #=> 3:32 212 
   #
-  # aClock=Clock.new(27,80)
-  # aClock.minutes #=> 1700
-  # aClock.hour #=> 4
-  # aClock.min #=> 20
-  # aClock.time #=> Time.new(1963,6,10,4,20)
+  #   aClock=Clock.new(27,80)
+  #   aClock.minutes #=> 1700
+  #   aClock.hour #=> 4
+  #   aClock.min #=> 20
+  #   aClock.time #=> Time.new(1963,6,10,4,20)
+  #   aClock.to_s #=> 4:20 1700
+  #
+  # @since 0.2.0
   #
   class Clock
-  
-    # :call-seq: new(hour,min) => Clock
-    # initialises <tt>Clock</tt> using the hours and minutes supplied
+    
+    # Initialises an instance of <tt>Clock</tt> using the hours and minutes supplied
     # or 0 if they are absent.  Although there are 24 hours in a day
     # (0-23) and 60 minutes in an hour (0-59), <tt>Clock</tt> calculates
     # the full hours and remaining minutes of whatever is supplied.
     #
+    # @param [Integer] hour number of hours
+    # @param [Integer] min number of minutes
+    #
     def initialize(hour=0,min=0)
       @hour=hour
       @min=min
@@ -30,34 +36,43 @@ module Workpattern
       @min=total_minutes % 60
     end
     
-    # :call-seq: minutes => Integer
-    # returns the total number of minutes
+    # Returns the total number of minutes
+    #
+    # @return [Integer] total minutes represented by the Clock object
     #
     def minutes
       return (@hour*60)+@min
     end
     
-    # :call-seq: hour => Integer
-    # returns the hour of the clock (0-23)
+    # Returns the hour of the clock (0-23)
+    #
+    # @return [Integer] hour of Clock from 0 to 23.
     #
     def hour
       return @hour % 24
     end
     
-    # :call-seq: min => Integer
-    # returns the minute of the clock (0-59)
+    # Returns the minute of the clock (0-59)
+    #
+    # @return [Integer] minute of Clock from 0 to 59
     #
     def min
       return @min % 60
     end
     
-    # :call-seq: time => DateTime
-    # returns a <tt>Time</tt> object with the correct
+    # Returns a <tt>Time</tt> object with the correct
     # <tt>hour</tt> and <tt>min</tt> values.  The date
-    # is 10th June 1963
-    # 
+    # is 10th June 1963.
+    #
+    # @return [DateTime] The time using the date of 10th June 1963 (My Birthday)
     def time
       return DateTime.new(1963,6,10,hour,min)
-    end      
+    end
+    
+
+    # @return [String] representation of <tt>Clock</tt> value as 'hh:mn minutes'
+    def to_s      
+      hour.to_s.concat(':').concat(min.to_s).concat(' ').concat(minutes.to_s)
+    end
   end
 end