timesheet 0.2.0

data/History.txt

@@ -0,0 +1,4 @@
+=== 0.0.1 2009-11-29
+
+* 1 major enhancement:
+  * Initial release

data/Manifest.txt

@@ -0,0 +1,24 @@
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+bin/timesheet
+lib/timesheet.rb
+lib/timesheet/range_extensions.rb
+lib/timesheet/time_entry.rb
+lib/timesheet/time_log.rb
+lib/timesheet/time_report.rb
+lib/timesheet/timesheet_parser.rb
+lib/timesheet/trollop.rb
+script/console
+script/destroy
+script/generate
+spec/range_extensions_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+spec/time_entry_spec.rb
+spec/time_log_spec.rb
+spec/time_report_spec.rb
+spec/timesheet_parser_spec.rb
+spec/timesheet_spec.rb
+tasks/rspec.rake

data/README.rdoc

@@ -0,0 +1,104 @@
+= timesheet
+
+* http://github.com/jschank/timesheet
+
+== DESCRIPTION:
+
+<i>Timesheet</i> is simple ruby application for tracking time spent on projects.
+It is a console application that uses a simple text file storage back-end (YAML::Store)
+
+The main idea is to be able to produce reports of hours spent, such that I can use geektool to display the reports.
+
+== FEATURES/PROBLEMS:
+
+with <i>timesheet</i> you can:
+
+* <b>add</b> new entries to the database
+* <b>edit</b> existing entries
+* <b>delete</b> existing entries
+* <b>list</b> existing entries, and specify a time range
+* <b>produce</b> simple reports
+
+== SYNOPSIS:
+
+<i>Timesheet</i> is a script for keeping track of time spent on various projects.
+
+=== Usage:
+
+	timesheet [OPTIONS] COMMAND [ARGS]
+
+COMMAND is any of the following:
+	add
+	edit
+	delete
+	list
+	report
+
+OPTIONS are:
+<tt>--debug, -d</tt>:: Show debugging information while processing
+<tt>--version, -v</tt>:: Print version and exit
+<tt>--help, -h</tt>:: Show this message
+
+=== For help run:
+
+ 	timesheet COMMAND --help
+
+for more information on a specific command.
+
+=== Your Data
+
+your <i>timesheet</i> data will be stored in a hidden directory under your user account. <i>Timesheet</i> figures out
+where this is by referencing the "HOME" environment variable. The default location is therefore:
+<tt>/Users/someuser/.timesheet/store.yaml</tt>
+
+You may override this location to any specific location you want by setting the "TIMESHEET_DATA_FILE" environment variable.
+This should be the full path to where you want the data stored. Including filename and extension.
+You only need to set this if you are unsatisfied with the default location.
+
+=== the .idea folder
+
+This project was created using RubyMine 2.0, and that IDE stores its state in the .idea folder.
+If you aren't using RubyMine, you can delete it.
+
+== REQUIREMENTS:
+
+* FIX (list of requirements)
+
+== INSTALL:
+
+  sudo gem install timesheet
+
+== To Do
+
+- Add indicator in reports for start or end times which had to be trimmed
+- Add indicator in reports that exclude comments, that comments are available, when they are, i.e. after a summary,
+you might want to know that you should do a detail, or byday report
+- Add option to produce pdf file, for this to work, I need to ensure that all the reports are using <b>ruport</b>.
+- If comments get too long, we may want to exclude them from the detail report
+- Add a new command to inspect a single entry. Just dump all the fields for a given record number
+- Might want to track comments separately and/or make an entries comments an array rather than a single comment.
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 John F. Schank III
+
+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/Rakefile

@@ -0,0 +1,29 @@
+require 'rubygems'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+require './lib/timesheet'
+
+Hoe::plugin :newgem
+Hoe::plugin :gemcutter
+# Hoe.plugin :website
+# Hoe.plugin :cucumberfeatures
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.spec 'timesheet' do
+  self.developer 'John F. Schank III', 'jschank@mac.com'
+  self.rubyforge_name       = self.name # TODO this is default value
+  self.extra_deps           = [['activesupport', '>= 0'], ['archive-tar-minitar', '>= 0'], ['chronic', '>= 0'], ['color', '>= 0'], ['fastercsv', '>= 0'], ['hoe', '>= 0'], ['json_pure', '>= 0'], ['newgem', '>= 0'], ['pdf-writer', '>= 0'], ['rake', '>= 0'], ['RedCloth', '>= 0'], ['rich_units', '>= 0'], ['rspec', '>= 0'], ['rubigen', '>= 0'], ['rubyforge', '>= 0'], ['ruport', '>= 0'], ['syntax', '>= 0'], ['transaction-simple', '>= 0']]
+  # self.extra_deps         = [['activesupport','>= 2.0.2']]
+
+end
+
+require 'newgem/tasks'
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# remove_task :default
+# task :default => [:spec, :features]
+
+

data/bin/timesheet

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+
+require 'timesheet'
+
+Timesheet.run(ARGV)

data/lib/timesheet.rb

@@ -0,0 +1,82 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'rubygems'
+require 'fileutils'
+require 'rich_units'
+require 'pathname'
+require 'yaml'
+require 'yaml/store'
+require 'timesheet/range_extensions'
+require 'timesheet/time_entry'
+require 'timesheet/time_log'
+require 'timesheet/time_report'
+require 'timesheet/trollop'
+require 'timesheet/timesheet_parser'
+
+class Timesheet
+
+  VERSION = '0.2.0'
+
+  def self.run(params)
+    command_hash = {}
+    command_hash = TimesheetParser.parse(params)
+
+    raise "Cannot determine location for data. Try timesheet --help for details." unless (ENV["TIMESHEET_DATA_FILE"] || ENV["HOME"])
+
+    data_file ||= ENV["TIMESHEET_DATA_FILE"]
+    data_file ||= (ENV["HOME"] + "/.timesheet/store.yaml")
+
+    FileUtils.makedirs(File.dirname(data_file))
+
+    store = YAML::Store.new(data_file)
+    tl = TimeLog.new(store)
+    ts = Timesheet.new(tl)
+    ts.process(command_hash)
+
+  rescue Exception => e
+    raise if command_hash[:debug]
+    puts e.message
+
+  end
+
+  def initialize(timelog)
+    @timelog = timelog
+  end
+
+  def process(command_opts)
+    command = command_opts[:command]
+    case command
+      when :add    : process_add_command(command_opts)
+      when :edit   : process_edit_command(command_opts)
+      when :delete : process_delete_command(command_opts)
+      when :report : process_report_command(command_opts)
+      else raise "Unknown command #{command}"
+    end
+  end
+
+  def process_add_command(command_opts)
+    te = TimeEntry.new(command_opts[:project], command_opts[:start], command_opts[:end], command_opts[:comment])
+    @timelog.add(te)
+  end
+
+  def process_edit_command(command_opts)
+    record_number = command_opts.delete(:record_number)
+    @timelog.update(record_number, command_opts)
+  end
+
+  def process_delete_command(command_opts)
+    record_number = command_opts.delete(:record_number)
+    @timelog.delete(record_number)
+  end
+
+  def process_report_command(command_opts)
+    start_time = command_opts[:start]
+    end_time = command_opts[:end]
+    entries = @timelog.extract_entries(start_time, end_time)
+    time_report = TimeReport.new(entries)
+    time_report.report(command_opts)
+  end
+
+end
+

data/lib/timesheet/range_extensions.rb

@@ -0,0 +1,24 @@
+# Thanks to: http://opensoul.org/2007/2/13/ranges-include-or-overlap-with-ranges
+class Range
+
+
+  def overlap?(range)
+    self.include?(range.first) || range.include?(self.first)
+  end
+
+  alias_method :include_without_range?, :include?
+
+  def include_with_range?(value)
+    if value.is_a?(Range)
+      last = value.exclude_end? ? value.last - 1 : value.last
+      self.include?(value.first) && self.include?(last)
+    else
+      include_without_range?(value)
+    end
+  end
+
+  alias_method :include?, :include_with_range?
+
+#  alias_method_chain :include?, :range
+
+end

data/lib/timesheet/time_entry.rb

@@ -0,0 +1,50 @@
+class TimeEntry 
+
+  include Comparable
+
+  def initialize(project, start_time, end_time, comment = nil)
+
+    raise ArgumentError.new("Start time must come before end time") if start_time > end_time
+
+    @project = project
+    @start_time = start_time
+    @end_time = end_time
+    @comment = comment
+    @record_number = nil
+
+  end
+
+  attr_accessor :project
+  attr_reader :start_time
+  attr_reader :end_time
+  attr_accessor :comment
+  attr_accessor :record_number
+
+  def conflict?(other_entry)
+    to_range.overlap? other_entry.to_range
+  end
+
+  def start_time=(new_start_time)
+    raise ArgumentError.new("Start time must come before end time") if new_start_time > @end_time
+    @start_time = new_start_time
+  end
+
+  def end_time=(new_end_time)
+    raise ArgumentError.new("End time must come after start time") if @start_time > new_end_time
+    @end_time = new_end_time
+  end
+
+  def duration
+    return 0 if @start_time == nil || @end_time == nil
+    RichUnits::Duration.new(@end_time - @start_time)
+  end
+
+  def <=>(other_time_entry)
+    self.start_time <=> other_time_entry.start_time
+  end
+
+  def to_range
+    Range.new(@start_time, @end_time, true)
+  end
+
+end

data/lib/timesheet/time_log.rb

@@ -0,0 +1,71 @@
+class TimeLog
+
+  def initialize(store)
+    @store = store
+    @store.transaction do
+      @store[:entries] ||= []
+      @store[:entry_record_number] ||= 0
+    end
+  end
+
+  def count
+    @store.transaction do
+      @store[:entries].count
+    end
+  end
+
+  def add(entry)
+    @store.transaction do
+      raise ArgumentError.new("Cannot add an entry which conflicts with existing entries.") if @store[:entries].any? { |e| e.conflict? entry }
+      @store[:entry_record_number] += 1
+      entry.record_number = @store[:entry_record_number]
+      @store[:entries] << entry
+    end
+  end
+
+  def find(record_number)
+    @store.transaction do
+      found_entries = @store[:entries].select{|e| e.record_number == record_number}
+      raise "Record number #{record_number} is not unique in the database." if found_entries.count > 1
+      raise ArgumentError.new("Cannot find an entry with record number #{record_number} to edit") if found_entries.count == 0
+
+      found_entries.first
+    end
+  end
+
+  def extract_entries(start_time, end_time)
+    covered_entries = []
+    @store.transaction do
+      span_to_cover = Range.new(start_time, end_time, true)
+      covered_entries = @store[:entries].select{|e| span_to_cover.overlap? e.to_range }
+    end
+    covered_entries
+  end
+
+  def update(record_number, properties)
+    @store.transaction do
+      found_entries = @store[:entries].select{|e| e.record_number == record_number}
+      raise "Record number #{record_number} is not unique in the database." if found_entries.count > 1
+      raise ArgumentError.new("Cannot find an entry with record number #{record_number} to edit") if found_entries.count == 0
+
+      entry = found_entries.first
+      entry.project = properties[:project] if properties[:project]
+      entry.start_time = properties[:start] if properties[:start]
+      entry.end_time = properties[:end] if properties[:end]
+      entry.comment = properties[:comment] if properties[:comment]
+      raise ArgumentError.new("The new times for this entry conflict with existing entries.") if @store[:entries].any? { |e| e != entry && e.conflict?(entry) }
+    end
+  end
+
+  def delete(record_number)
+    @store.transaction do
+      found_entries = @store[:entries].select{|e| e.record_number == record_number}
+      raise "Record number #{record_number} is not unique in the database." if found_entries.count > 1
+      raise ArgumentError.new("Cannot find an entry with record number #{record_number} to delete.") if found_entries.count == 0
+
+      @store[:entries].delete(found_entries.first)
+    end
+  end
+
+  
+end

data/lib/timesheet/time_report.rb

@@ -0,0 +1,113 @@
+require 'ruport'
+require 'time'
+
+class TimeReport
+
+  def initialize(entries)
+    @entries = entries
+  end
+
+  attr_accessor :entries
+
+  def trim(start_time, end_time)
+    @entries.map! do |e|
+      e.start_time = start_time if e.to_range.include?(start_time)
+      e.end_time = end_time if e.to_range.include?(end_time)
+      e
+    end
+  end
+
+  def report(command_options, outstream = STDOUT)
+    trim(command_options[:start], command_options[:end])
+
+    detail_report(outstream) if command_options[:detail]
+    summary_report(outstream) if command_options[:summary]
+    byday_report(outstream) if command_options[:byday]
+  end
+
+  private
+
+  def detail_report(outstream)
+   table = Ruport::Data::Table({ :column_names => ["Id", "Project", "Start - Stop", "Hours", "Comment"]}) do |table|
+      @entries.sort.each do |entry|
+        row = []
+
+        # format record number
+        row << sprintf("%5d", entry.record_number)
+
+        # format project
+        row << entry.project
+
+        # format start - stop
+        str = ""
+        str << entry.start_time.strftime("%m/%d/%Y at %I:%M %p")
+        str << " to "
+        str << entry.end_time.strftime("%m/%d/%Y at ") if ( (entry.start_time.year != entry.end_time.year) && (entry.start_time.yday != entry.end_time.yday))
+        str << entry.end_time.strftime("%I:%M %p")
+        row << str
+
+        # format duration
+        str = ""
+        str << entry.duration.strftime("%d Days ") if entry.duration.days > 0
+        str << entry.duration.strftime("%hh %mm")
+        row << str
+
+        # format comment
+        row << entry.comment
+
+        table << row
+      end
+    end
+
+    outstream.puts table.as(:text, {:ignore_table_width => true})
+
+  end
+
+  def summary_report(outstream)
+    summary = Hash.new(0)
+
+    total = @entries.inject(0) do |sum, entry|
+      summary[entry.project] += entry.duration.to_i
+      sum += entry.duration.to_i
+    end
+
+    width = summary.keys.max { |a, b| a.length <=> b.length }.length
+    summary.sort.each do |key, value|
+      duration = RichUnits::Duration.new(value)
+      duration.reset_segments(:hours, :minutes)
+      outstream.puts "#{key.rjust(width)} #{duration.strftime("%hh").rjust(4)}#{duration.strftime("%mm").rjust(4)}"
+    end
+
+    total_duration = RichUnits::Duration.new(total)
+    total_duration.reset_segments(:hours, :minutes)
+    outstream.puts "-" * (width + 4 + 4 + 1)
+    outstream.puts "#{"Total".rjust(width)} #{total_duration.strftime("%hh").rjust(4)}#{total_duration.strftime("%mm").rjust(4)}"
+  end
+
+  def byday_report(outstream)
+
+    hash = {}
+    comments = {}
+    @entries.each do |entry|
+      start_date = Date.new(entry.start_time.year, entry.start_time.month, entry.start_time.day)
+      hash[start_date] ||= Hash.new(0)
+      hash[start_date][entry.project] += entry.duration.to_i
+
+      comments[start_date] ||= Hash.new { |h, k| h[k] = [] }
+      comments[start_date][entry.project] << entry.comment
+    end
+
+    hash.sort.each do |entry_date, project_hash|
+      outstream.puts entry_date.strftime("%D")
+      project_hash.sort.each do |project, duration|
+        project_time = RichUnits::Duration.new(duration)
+        project_time.reset_segments(:hours, :minutes)
+        outstream.puts "\t#{project} #{project_time.strftime("%hh %mm")}"
+        comments[entry_date][project].each do |comment|
+          outstream.puts "\t - #{comment}"
+        end
+      end
+    end
+  end
+
+end