timetrap 1.5.3 → 1.6.0

data/.gitignore

@@ -1,2 +1,3 @@
 tags
 pkg
+*.swp

data/README.md

@@ -4,18 +4,8 @@ Timetrap
 Timetrap is a simple command line time tracker written in ruby. It provides an
 easy to use command line interface for tracking what you spend your time on.
 
-It began as a ruby port of Trevor Caira's Timebook, a small python utility.  It
-contains several enhancement over Timebook, notably the ability to parse
-natural language times (e.g. "30 minutes ago"), additional commands such as
-`archive` and `configure`, and support for rounding.
-
-Timetrap is also able to export entries to several formats (e.g. ical, csv) and
-is designed to be easily extended to support additional export formats, by
-creating a new formatter class (in ruby.)
-
-Timetrap maintains its state in a sqlite3 database.
-
-Timetrap is available as a gem on gemcutter (http://gemcutter.org/gems/timetrap)
+Getting Started
+---------------
 
 To install:
 
@@ -23,67 +13,88 @@ To install:
 
 This will place a ``t`` executable in your path.
 
-Original Timebook available at:
-http://bitbucket.org/trevor/timebook/src/
+### Basic Usage
 
+    $ # get help
+    $ t --help
 
-Concepts
---------
+Timetrap maintains a list of *timesheets*.
 
-Timetrap maintains a list of *timesheets* -- distinct lists of timed *periods*.
-Each period has a start and end time, with the exception of the most recent
-period, which may have no end time set. This indicates that this period is
-still running. Timesheets containing such periods are considered *active*. It
-is possible to have multiple timesheets active simultaneously, though a single
-time sheet may only have one period running at once.
-
-Interactions with timetrap are performed through the ``t`` command on the
-command line. ``t`` is followed by one of timetrap's subcommands.  Often used
-subcommands include ``in``, ``out``, ``switch``, ``now``, ``list`` and
-``display``. *Commands may be abbreviated as long as they are unambiguous.* thus
-``t switch foo`` and ``t s foo`` are identical.  With the default command set,
-no two commands share the first same letter, thus it is only necessary to type
-the first letter of a command.  Likewise, commands which display timesheets
-accept abbreviated timesheet names. ``t display f`` is thus equivalent to ``t
-display foo`` if ``foo`` is the only timesheet which begins with "f". Note that
-this does not apply to ``t switch``, since this command also creates
-timesheets.  (Using the earlier example, if ``t switch f`` is entered, it would
-thus be ambiguous whether a new timesheet ``f`` or switching to the existing
-timesheet ``foo`` was desired).
-
-Usage
------
-
-The basic usage is as follows:
-
-    $ # create the "writing" timesheet
-    $ t switch writing
-
-    $ # check in 5 minutes ago
-    $ t in document timetrap --at "10 minutes ago"
-
-    $ # check out
-    $ t out
+    $ # create the "coding" timesheet
+    $ t sheet coding
+    Switching to sheet coding
+
+All commands can be abbreviated.
+
+    $ # same as "t sheet coding"
+    $ t s coding
+    Switching to sheet coding
+
+Each timesheet contains *entries*.  Each entry has a start and end time, and a
+note associated with it.  An entry without an end time set is considered to be
+*running*.
+
+You check in to the current sheet with the `in` command.
+
+    $ # check in with "document timetrap" note
+    $ t in document timetrap
+    Checked into sheet "coding".
+
+Commands like `display` and `now` will show you the running entry.
 
-    $ # view current timesheet
     $ t display
+    Timesheet: coding
+        Day                Start      End        Duration   Notes
+        Sun Nov 28, 2010   12:26:10 -            0:00:03    document timetrap
+                                                 0:00:03
+        ---------------------------------------------------------
+        Total                                    0:00:03
+
+    $ t now
+    *coding: 0:01:02 (document timetrap)
+
+If you make a mistake use the `edit` command.
+
+    $ # edit the running entry's note
+    $ t edit writing readme
+    editing entry #42
+
+You check out with the `out` command.
+
+    $ t out
+    Checked out of sheet "coding"
+
+### Natural Language Times
+
+Commands such as `in`, `out`, `edit`, and `display` have flags that accept
+times as arguments.  Any time you pass Timetrap a time it will try to parse it
+as a natural language time.
+
+This is very handy if you start working and forget to start Timetrap.  You can
+check in 5 minutes ago using `in`'s `--at` flag.
+
+    $ t in --at "5 minutes ago"
 
-The first command, ``t switch writing``, switches to the timesheet "writing"
-(or creates it if it does not exist). ``t in document timetrap --at "10 minutes
-ago"`` creates a new period in the current timesheet, and annotates it with the
-description "document timetrap". The optional ``--at`` flag can be passed to start
-the entry at a time other than the present.  The ``--at`` flag is able to parse
-natural language times (via Chronic: http://chronic.rubyforge.org/) and will
-understand 'friday 13:00', 'mon 2:35', '4pm', etc. (also true of the ``edit``
-command's ``--start`` and ``--end`` flags.)  Note that this command would be in
-error if the ``writing`` timesheet was already active.  Finally, ``t out``
-records the current time as the end time for the most recent period in the
-``writing`` timesheet.
+Command line flags also have short versions.
 
-To display the current timesheet, invoke the ``t display`` command::
+    $ # equivilent to the command above
+    $ t i -a "5 minutes ago"
+
+You can consult the Chronic gem (http://chronic.rubyforge.org/) for a full
+list of parsable time formats, but all of these should work.
+
+    $ t out --at "in 30 minutes"
+    $ t edit --start "last monday at 10:30am"
+    $ t edit --end "tomorrow at noon"
+    $ t display --start "10am" --end "2pm"
+    $ t i -a "2010-11-29 12:30:00"
+
+### Output Formats
+
+Timetrap supports several output formats.  The default is a plain text format.
 
     $ t display
-    Timesheet: timetrap
+    Timesheet: coding
         Day                Start      End        Duration   Notes
         Mon Apr 13, 2009   15:46:51 - 17:03:50   1:16:59    improved display functionality
                            17:25:59 - 17:26:02   0:00:03
@@ -91,20 +102,31 @@ To display the current timesheet, invoke the ``t display`` command::
                            22:37:38 - 23:38:43   1:01:05    work on kill
                                                  2:18:52
         Tue Apr 14, 2009   00:41:16 - 01:40:19   0:59:03    gem packaging
-                           10:20:00 - 10:48:10   0:28:10    enhance edit
+                           10:20:00 - 10:48:10   0:28:10    working on readme
                                                  1:27:13
         ---------------------------------------------------------
         Total                                    3:46:05
 
-Each period in the timesheet is listed on a row. If the timesheet is active,
-the final period in the timesheet will have no end time. After each day, the
-total time tracked in the timesheet for that day is listed. Note that this is
-computed by summing the durations of the periods beginning in the day. In the
-last row, the total time tracked in the timesheet is shown.
+You can also output csv for easy import into a spreadsheet.
+
+    $ t display --format csv
+    start,end,note,sheet
+    "2010-08-21 11:19:05","2010-08-21 12:12:04","migrated site","coding"
+    "2010-08-21 12:44:09","2010-08-21 12:48:46","DNS emails and install email packages","coding"
+    "2010-08-21 12:49:57","2010-08-21 13:10:12","A records","coding"
+    "2010-08-21 15:09:37","2010-08-21 16:32:26","setup for wiki","coding"
+    "2010-08-25 20:42:55","2010-08-25 21:41:49","rewrote index","coding"
+    "2010-08-29 15:44:39","2010-08-29 16:21:53","recaptcha","coding"
+    "2010-08-29 21:15:58","2010-08-29 21:30:31","backups","coding"
+    "2010-08-29 21:40:56","2010-08-29 22:32:26","backups","coding"
+
+Or to ical format for import into a calendar program (remember commands can be abbreviated).
+
+    $ t d -f ical > MyTimeSheet.ics
 
 Commands
 --------
-**archives**
+**archive**
   Archives the selected entries (by moving them to a sheet called ``_[SHEET]``)
   These entries can be seen by running ``t display _[SHEET]``.
   usage: ``t archive [--start DATE] [--end DATE] [SHEET]``
@@ -145,10 +167,6 @@ Commands
 
   usage: ``t edit [--id ID] [--start TIME] [--end TIME] [--append] [NOTES]``
 
-**format**
-  Deprecated
-  Alias for display
-
 **in**
   Start the timer for the current timesheet. Must be called before out.  Notes
   may be specified for this period. This is exactly equivalent to
@@ -168,32 +186,27 @@ Commands
   usage: ``t list``
 
 **now**
-  Print the current sheet, whether it's active, and if so, how long it has been
-  active and what notes are associated with the current period.
+  Print a description of all running entries.
 
   usage: ``t now``
 
 **out**
   Stop the timer for the current timesheet. Must be called after in. Accepts an
-  optional --at flag.
-
-  usage: ``t out [--at TIME]``
-
-**running**
-  Print all active sheets and any messages associated with them.
+  optional --at flag. Accepts an optional TIMESHEET name to check out of a
+  running, non-current sheet.
 
-  usage: ``t running``
+  usage: ``t out [--at TIME] [TIMESHEET]``
 
-**switch**
-  Switch to a new timesheet. this causes all future operation (except switch)
-  to operate on that timesheet. The default timesheet is called "default".
+**sheet**
+  Switch to a timesheet creating it if necessary. The default timesheet is
+  called "default".
 
-  usage: ``t switch TIMESHEET``
+  usage: ``t sheet TIMESHEET``
 
 **week**
   Shortcut for display with start date set to monday of this week
 
-  usage: ``t week [--ids] [--end DATE] [--format FMT] [SHEET | all]``
+  usage: ``t week [--ids] [--end DATE] [--format FMT] [TIMESHEET | all]``
 
 Global Options
 --------
@@ -217,11 +230,20 @@ Configuration
 Configuration of TimeTrap's behavior can be done through a YAML config file.
 See ``t configure`` for details.  Currently supported options are:
 
- round_in_seconds: The duration of time to use for rounding with the -r flag
+ ``round_in_seconds``: The duration of time to use for rounding with the -r flag
 
- database_file: The file path of the sqlite database
+ ``database_file``: The file path of the sqlite database
 
- append_notes_delimiter: delimiter used when appending notes via ``t edit --append``
+ ``append_notes_delimiter``: delimiter used when appending notes via ``t edit --append``
+
+Special Thanks
+--------------
+
+The initial version of Timetrap was heavily inspired by Trevor Caira's
+Timebook, a small python utility.
+
+Original Timebook available at:
+http://bitbucket.org/trevor/timebook/src/
 
 Bugs and Feature Requests
 --------

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 1
-:minor: 5
-:patch: 3
+:minor: 6
+:patch: 0

data/lib/timetrap.rb

@@ -7,6 +7,7 @@ require 'Getopt/Declare'
 require File.join(File.dirname(__FILE__), 'timetrap', 'config')
 require File.join(File.dirname(__FILE__), 'timetrap', 'helpers')
 require File.join(File.dirname(__FILE__), 'timetrap', 'cli')
+require File.join(File.dirname(__FILE__), 'timetrap', 'timer')
 DB_NAME = defined?(TEST_MODE) ? nil : Timetrap::Config['database_file']
 # connect to database.  This will create one if it doesn't exist
 DB = Sequel.sqlite DB_NAME
@@ -16,67 +17,6 @@ Dir["#{File.dirname(__FILE__)}/timetrap/formatters/*.rb"].each do |path|
 end
 
 module Timetrap
-  extend self
-
-  def current_sheet= sheet
-    m = Meta.find_or_create(:key => 'current_sheet')
-    m.value = sheet
-    m.save
-  end
-
-  def current_sheet
-    unless Meta.find(:key => 'current_sheet')
-      Meta.create(:key => 'current_sheet', :value => 'default')
-    end
-    Meta.find(:key => 'current_sheet').value
-  end
-
-  def entries sheet = nil
-    Entry.filter(:sheet => sheet).order_by(:start)
-  end
-
-  def running?
-    !!active_entry
-  end
-
-  def active_entry
-    Entry.find(:sheet => Timetrap.current_sheet, :end => nil)
-  end
-
-  def stop time = nil
-    while a = active_entry
-      time ||= Time.now
-      a.end = time
-      a.save
-    end
-  end
-
-  def start note, time = nil
-    raise AlreadyRunning if running?
-    time ||= Time.now
-    Entry.create(:sheet => Timetrap.current_sheet, :note => note, :start => time).save
-  rescue => e
-    CLI.say e.message
-  end
-
-  def switch sheet
-    self.current_sheet = sheet
-  end
-
-  def kill_sheet sheet
-    Entry.filter(:sheet => sheet).destroy
-  end
-
-  def format format_klass, entries
-    format_klass.new(entries).output
-  end
-
-  class AlreadyRunning < StandardError
-    def message
-      "Timetrap is already running"
-    end
-  end
-
   CLI.args = Getopt::Declare.new(<<-EOF)
     #{CLI::USAGE}
   EOF

data/lib/timetrap/cli.rb

@@ -64,18 +64,19 @@ COMMAND is one of:
   * list - Show the available timesheets.
     usage: t list
 
-  * now - Show the status of the current timesheet.
+  * now - Show all running entries.
     usage: t now
 
-  * out - Stop the timer for the current timesheet.
-    usage: t out [--at TIME]
+  * out - Stop the timer for the a timesheet.
+    usage: t out [--at TIME] [TIMESHEET]
     -a, --at <time:qs>        Use this time instead of now
 
-  * running - Show all running timesheets.
-    usage: t running
+  * running - Deprecated: alias for now.
 
-  * switch - Switch to a new timesheet.
-    usage: t switch TIMESHEET
+  * sheet - Switch to a timesheet creating it if necessary.
+    usage: t sheet TIMESHEET
+
+  * switch - Deprecated: renamed to sheet.
 
   * week - Shortcut for display with start date set to monday of this week.
     usage: t week [--ids] [--end DATE] [--format FMT] [SHEET | all]
@@ -85,11 +86,12 @@ COMMAND is one of:
   -h, --help              Display this help.
   -r, --round             Round output to 15 minute start and end times.
   -y, --yes               Noninteractive, assume yes as answer to all prompts.
+  --debug                 Display stack traces for errors.
 
   EXAMPLES
 
   # create the "MyTimesheet" timesheet
-  $ t switch MyTimesheet
+  $ t sheet MyTimesheet
 
   # check in 5 minutes ago with a note
   $ t in --at '5 minutes ago' doing some stuff
@@ -108,29 +110,28 @@ COMMAND is one of:
     end
 
     def invoke
-      args['-h'] ? say(USAGE) : invoke_command_if_valid
+      args['-h'] ? puts(USAGE) : invoke_command_if_valid
     rescue => e
-      say e.message
-      exit 1
+      raise e if args['--debug']
+      warn e.message
+      exit 1 unless defined? TEST_MODE
     end
 
     def commands
       Timetrap::CLI::USAGE.scan(/\* \w+/).map{|s| s.gsub(/\* /, '')}
     end
 
-    def say *something
-      puts *something
-    end
-
     def invoke_command_if_valid
       command = args.unused.shift
       set_global_options
       case (valid = commands.select{|name| name =~ %r|^#{command}|}).size
-      when 0 then say "Invalid command: #{command}"
-      when 1 then send valid[0]
+      when 0 then puts "Invalid command: #{command}"
       else
-        say "Ambiguous command: #{command}" if command
-        say(USAGE)
+        if command
+          send valid[0]
+        else
+          puts USAGE
+        end
       end
     end
 
@@ -147,25 +148,30 @@ COMMAND is one of:
           e.update :sheet => "_#{e.sheet}"
         end
       else
-        say "archive aborted!"
+        warn "archive aborted!"
       end
     end
 
     def configure
       Config.configure!
-      say "Config file is at #{Config::PATH.inspect}"
+      puts "Config file is at #{Config::PATH.inspect}"
     end
 
     def edit
-      entry = args['-i'] ? Entry[args['-i']] : Timetrap.active_entry
-      say "can't find entry" && return unless entry
+      entry = args['-i'] ? Entry[args['-i']] : Timer.active_entry
+      unless entry
+        warn "can't find entry"
+        return
+      else
+        warn "editing entry ##{entry.id.inspect}"
+      end
       entry.update :start => args['-s'] if args['-s'] =~ /.+/
       entry.update :end => args['-e'] if args['-e'] =~ /.+/
 
       # update sheet
       if args['-m'] =~ /.+/
-        if entry == Timetrap.active_entry
-          Timetrap.current_sheet = args['-m']
+        if entry == Timer.active_entry
+          Timer.current_sheet = args['-m']
         end
         entry.update :sheet => args['-m']
       end
@@ -185,11 +191,17 @@ COMMAND is one of:
     end
 
     def in
-      Timetrap.start unused_args, args['-a']
+      Timer.start unused_args, args['-a']
+      warn "Checked into sheet #{Timer.current_sheet.inspect}."
     end
 
     def out
-      Timetrap.stop args['-a']
+      sheet = sheet_name_from_string(unused_args)
+      if Timer.stop sheet, args['-a']
+        warn "Checked out of sheet #{sheet.inspect}."
+      else
+        warn "No running entry on sheet #{sheet.inspect}."
+      end
     end
 
     def kill
@@ -198,21 +210,21 @@ COMMAND is one of:
         out << "(#{e.note}) " if e.note.to_s =~ /.+/
         if ask_user out
           e.destroy
-          say "it's dead"
+          warn "it's dead"
         else
-          say "will not kill"
+          warn "will not kill"
         end
       elsif (sheets = Entry.map{|e| e.sheet }.uniq).include?(sheet = unused_args)
         victims = Entry.filter(:sheet => sheet).count
         if ask_user "are you sure you want to delete #{victims} entries on sheet #{sheet.inspect}? "
-          Timetrap.kill_sheet sheet
-          say "killed #{victims} entries"
+          Entry.filter(:sheet => sheet).destroy
+          warn "killed #{victims} entries"
         else
-          say "will not kill"
+          warn "will not kill"
         end
       else
         victim = args['-i'] ? args['-i'].to_s.inspect : sheet.inspect
-        say "can't find #{victim} to kill", 'sheets:', *sheets
+        warn "can't find #{victim} to kill", 'sheets:', *sheets
       end
     end
 
@@ -224,38 +236,52 @@ COMMAND is one of:
           Timetrap::Formatters::Text
         end
       rescue
-        say "Invalid format specified `#{args['-f']}'"
+        warn "Invalid format #{args['-f'].inspect} specified."
         return
       end
-      say Timetrap.format(fmt_klass, selected_entries.order(:start).all)
+      entries = selected_entries.order(:start).all
+      if entries == []
+        warn "No entries were selected to display."
+      else
+        puts fmt_klass.new(entries).output
+      end
     end
     alias_method :format, :display
 
-
-    def switch
+    def sheet
       sheet = unused_args
-      if not sheet =~ /.+/ then say "No sheet specified"; return end
-      say "Switching to sheet " + Timetrap.switch(sheet)
+      unless sheet =~ /.+/
+        warn "No sheet specified"
+      else
+        Timer.current_sheet = sheet
+        warn "Switching to sheet #{sheet.inspect}"
+      end
     end
 
+    alias_method :switch, :sheet
+
     def list
-      sheets = Entry.sheets.map do |sheet|
+      sheets = ([Timer.current_sheet] | Entry.sheets).map do |sheet|
         sheet_atts = {:total => 0, :running => 0, :today => 0}
-        Timetrap::Entry.filter(:sheet => sheet).inject(sheet_atts) do |m, e|
-          e_end = e.end_or_now
-          m[:name] ||= sheet
-          m[:total] += (e_end.to_i - e.start.to_i)
-          m[:running] += (e_end.to_i - e.start.to_i) unless e.end
-          m[:today] += (e_end.to_i - e.start.to_i) if same_day?(Time.now, e.start)
-          m
+        entries = Timetrap::Entry.filter(:sheet => sheet)
+        if entries.empty?
+          sheet_atts.merge(:name => sheet)
+        else
+          entries.inject(sheet_atts) do |m, e|
+            e_end = e.end_or_now
+            m[:name] ||= sheet
+            m[:total] += (e_end.to_i - e.start.to_i)
+            m[:running] += (e_end.to_i - e.start.to_i) unless e.end
+            m[:today] += (e_end.to_i - e.start.to_i) if same_day?(Time.now, e.start)
+            m
+          end
         end
-      end
-      if sheets.empty? then say "No sheets found"; return end
+      end.sort_by{|sheet| sheet[:name].downcase}
       width = sheets.sort_by{|h|h[:name].length }.last[:name].length + 4
-      say " %-#{width}s%-12s%-12s%s" % ["Timesheet", "Running", "Today", "Total Time"]
+      puts " %-#{width}s%-12s%-12s%s" % ["Timesheet", "Running", "Today", "Total Time"]
       sheets.each do |sheet|
-        star = sheet[:name] == Timetrap.current_sheet ? '*' : ' '
-        say "#{star}%-#{width}s%-12s%-12s%s" % [
+        star = sheet[:name] == Timer.current_sheet ? '*' : ' '
+        puts "#{star}%-#{width}s%-12s%-12s%s" % [
           sheet[:running],
           sheet[:today],
           sheet[:total]
@@ -264,19 +290,18 @@ COMMAND is one of:
     end
 
     def now
-      if Timetrap.running?
-        out = "#{Timetrap.current_sheet}: #{format_duration(Timetrap.active_entry.start, Timetrap.active_entry.end_or_now)}".gsub(/  /, ' ')
-        out << " (#{Timetrap.active_entry.note})" if Timetrap.active_entry.note =~ /.+/
-        say out
-      else
-        say "#{Timetrap.current_sheet}: not running"
+      if !Timer.running?
+        puts "*#{Timer.current_sheet}: not running"
+      end
+      Timer.running_entries.each do |entry|
+        current = entry[:sheet] == Timer.current_sheet
+        out = current ? '*' : ' '
+        out << "#{entry[:sheet]}: #{format_duration(entry.start, entry.end_or_now)}".gsub(/  /, ' ')
+        out << " (#{entry.note})" if entry.note =~ /.+/
+        puts out
       end
     end
-
-    def running
-      say "Running Timesheets:"
-      say Timetrap::Entry.filter(:end => nil).map{|e| "  #{e.sheet}: #{e.note}"}.uniq.sort
-    end
+    alias_method :running, :display
 
     def week
       args['-s'] = Date.today.wday == 1 ? Date.today.to_s : Date.parse(Chronic.parse(%q(last monday)).to_s).to_s
@@ -291,7 +316,7 @@ COMMAND is one of:
 
     def ask_user question
       return true if args['-y']
-      print question
+      $stderr.print question
       $stdin.gets =~ /\Aye?s?\Z/i
     end