trak 0.0.0

data/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Change log
+
+## v0.0.0 (2012-04-25)
+
+Tracker is now known as trak, and it's a RubyGem!
+
+Changed:
+
+* Trak has now been ported from Perl to Ruby. The main reason for this
+  was for the ability to support the awesome gem Chronic for natural
+  language date parsing in an upcoming release. But beyond that,
+  RubyGems is fantastic for packaging and distribution and the plan is
+  to make this code seriously more modular over the next little while
+  (the code is a joke at the moment :O).
+
+## v0.4 (2011-10-17)
+
+Added:
+
+* If the EDITOR environment variable is set, this is now used by default
+  to edit a log file with `track -e`.
+
+* The current time is displayed at the end of the report, like so:
+
+        # Today's logged work
+        ...
+        Hours logged until 9:30 AM (since 9:15 AM). Currently 10:13 AM.
+
+## v0.3
+
+Added:
+
+* Report now calculates the total time spent on each task throughout the
+  day
+* Time can now be logged as either minutes or hours. The time argument
+  can take the format `##<denom>`, where `##` is the amount of time
+  spent, and `<denom>` signifies hours (`h/hr/hour/hours`) or minutes
+  (`m/min/minute/minutes`).
+
+Changed:
+
+* Report formatting improvements
+
+Fixed:
+
+* Time wrap-around bug where if time logged passed midnight AM/PM would
+  display incorrectly.
+
+## v0.2.1
+
+Changed:
+
+* Change log is now found in CHANGELOG.md rather than README.md.
+
+Fixed:
+
+* Fixed a bug where invoking with no arguments would create an entry in
+  the log with no time or message. No arguments is a synonym for `-l` or
+  `-r`.
+
+## v0.2
+
+Added:
+
+* Tracker now automatically calculates the time you started your day
+  based on your first log for that day. This is stored in the time log
+  after the date, and used to calculate how far into the day you have
+  tracked time.
+
+Changed:
+
+* Everything after the first argument (the amount of time) is now
+  considered to be the task name (i.e., the task is no longer truncated
+  to the first word).
+* Formatting improvements
+
+## v0.1
+
+Added:
+
+* Tracker.pl -l will now tell you what time you've logged time until.
+  For example, if your start time is 8:00 AM and you've logged 3 hours,
+  it will output the following:
+
+        Hours logged until 11:00 AM (since 8:00 AM).
+
+Changed:
+
+* `-l` and `-r` switches are now synonyms
+* Formatting improvements

data/README.md

@@ -0,0 +1,107 @@
+# Trak: track chunks of time from the command line
+
+Trak, v0.0.0 (Apr 25, 2012)  
+Written by Adam Sharp
+
+## Notice
+
+Trak was recently (i.e., last week) a Perl script. It has been ported to
+Ruby, but the code really looks like it's taken a beating and is
+definitely NOT what I want it to ultimately look like. Much more
+ruby-fying to happen yet, as well as support for the excellent
+[Chronic](https://github.com/mojombo/chronic) gem for natural language
+date parsing in the pipeline.
+
+It's now structured as a RubyGem and should hopefully be available on
+RubyGems soon.
+
+Stay tuned.
+
+## Description
+
+Trak is a utility for Mac OS X that allows you to quickly make a record
+of how much time you've spent on various tasks throughout the day.
+
+Work logs are stored in `/Users/yourusername/Documents/Tracker/` with
+the format `YEAR-MONTH-DAY-time-log.txt`.
+
+An example work log that trak will create:
+
+    2011-09-01 9:00
+    30: nap
+    45: procrastinate
+    30: uni
+    120: trak
+
+## Installation
+
+Check out this repository and then create a symlink to bin/trak
+somewhere in your path:
+
+        $ ln -s <repo>/bin/trak /usr/bin/trak
+
+## Usage
+
+    trak [-d|--date DATE] ##<denom> <description>  # => data entry
+    trak [-d|--date DATE] [-r|-l]                  # => reporting
+    trak [-d|--date DATE] -e                       # => manually edit time log
+
+Where:
+
+* `##` is a decimal signifying how much time has been spent.
+* `<denom>` is either hours (`h/hr/hour/hours`) or minutes
+  (`m/min/minute/minutes`). `<denom>` is optional and if ommitted,
+  Tracker will interpret the time entered as minutes.
+* `<description>` is a string containing a brief description of the
+  activity.
+* `DATE` is a string of the format `YYYY-MM-DD` which represents any
+  date. This effects any of Tracker's modes, i.e., insertion, editing or
+  reporting.
+
+### Descriptions
+
+You can use either
+
+    $ trak 30 "Foo bar"
+    
+or
+
+    $ trak 30 Foo bar
+
+as everything after the first argument is considered the name of the
+task.
+
+### Entering time
+
+These are all valid commands:
+
+    $ trak 1h Write trak documentation       # => 1 hour
+    $ trak 30min Rewrite trak documentation  # => 30 minutes
+    $ trak 4hours Refactor trak              # => 4 hours
+    $ trak 15 Lunch                          # => 15 minutes
+
+## To do
+
+* Proper handling of incorrectly formatted dates
+* Write a report that gives a weekly breakdown given a date in that week
+* Add a `-h` usage/help switch
+* Make the personal time search more configurable by putting keywords to
+  search in an array
+* Have the different types of reports, and keywords for those reports,
+  completely stored in a configuration file. The last category in the
+  file is the default report. Because keywords for custom reports would
+  work on a whitelist system, everything that doesn't match goes into
+  the default. For example:
+
+        # Personal
+        lunch
+        uni
+        news
+        # Default
+        Work
+
+* Have the keywords in the configuration file actually be regexes. When
+  reading the config file, any empty lines or whitespace are ignored.
+* Give an estimate of completion time, with a configurable default for
+  the length of the work day. Also take into account the default length
+  of lunch break (configurable) if lunch hasn't yet been logged.

data/bin/trak

@@ -0,0 +1,2 @@
+#!/usr/bin/env ruby
+require 'trak'

data/lib/trak.rb

@@ -0,0 +1,168 @@
+#!/usr/bin/env ruby
+
+# command:
+#   $ Tracker.pl 30 "I did stuff"
+#   $ Tracker.pl 1h "I did twice as much stuff"
+#
+# format:
+#   - First arg is how much time spent
+#   - Second arg is a description
+
+require 'trollop'
+require 'debugger'
+
+require "trak/tracker_util"
+
+# place where data is stored
+datadir = "#{ENV['HOME']}/Documents/Tracker/"
+%x[mkdir -p #{datadir}]
+
+# define command line options
+opts = Trollop::options do
+  opt :report, "Reporting mode", :short => "-l"
+  opt :edit, "Edit mode"
+  opt :date, "The date", :type => String, :short => "-d"
+  opt :debug, "Debugging mode", :short => "-i"
+end
+
+$g_opts = opts
+def debug(steps = 1)
+  debugger if $g_opts[:debug]
+end
+
+# all valid options have been processed, so figure out which mode
+# we're in...
+#
+# if we found a -r or -l option, ignore everything else
+if opts[:report]
+  MODE = 'report'
+# now check if the user wants edit mode
+elsif opts[:edit]
+  MODE = 'edit'
+# if there are still unprocessed args (that didn't look like switches),
+# we're in insert mode
+elsif ARGV.length > 0
+  MODE = 'insert'
+# if all else fails, there were probably no args to begin with, so we're
+# in report mode
+else
+  MODE = 'report'
+end
+
+today = Time.now.strftime '%F'
+
+# did the user supply a date argument that isn't today?
+if opts[:date] && opts[:date] != today
+  fdate = opts[:date]
+# otherwise use today's date, formatted, and set date_arg to be false
+else
+  fdate = today
+  opts[:date] = nil
+end
+
+# set the output file name
+filename = "#{datadir}#{fdate}-time-log.txt"
+
+if MODE == 'report'
+  if File.exist? filename
+    # open the file and get it as an array
+    begin
+      file = File.open(filename).readlines.map &:chomp
+    rescue
+      STDERR.puts "#{__FILE__}: #{$!}"
+      exit 1
+    end
+    
+    # The keys for each hash are the titles of the various tasks logged.
+    # The values are the total time spent on the task.
+    work = {}
+    personal = {}
+    
+    # find the start time for the day we're reporting on
+    startTime = file.first.split[1]
+    
+    # process each line of the file
+    file[1..file.size].each do |line|
+      minutes, text = line.split(': ')
+      unless text =~ /personal|uni|lunch|home/
+        work[text] = 0 unless work.include? text
+        work[text] += minutes.to_i
+      else
+        personal[text] = 0 unless personal.include? text
+        personal[text] += minutes.to_i
+      end
+    end
+    
+    # print the report
+    if opts[:date]
+        puts "# Logged work for #{fdate}"
+    else
+        puts "# Today's logged work"
+    end
+    
+    workTotal = TrackerUtil::printSubReport(work, "Work")
+    personalTotal = TrackerUtil::printSubReport(personal, "Personal")
+    
+    newTimeString = TrackerUtil::to12HourTime(TrackerUtil::newTimeWithMinutes(startTime, workTotal + personalTotal))
+    puts "Hours logged until #{newTimeString} (since #{TrackerUtil::to12HourTime(startTime)}). "
+    
+    # if we're reporting for today, print the current time
+    puts "Currently #{TrackerUtil::to12HourTime(TrackerUtil::currentTimeFormatted())}." unless opts[:date]
+  else
+    if opts[:date]
+      STDERR.puts "No time log for #{fdate}. Track some time first."
+    else
+      STDERR.puts "No time log for today. Track some time first.\n"
+    end
+  end
+
+elsif MODE == 'edit'
+  if File.exist? filename
+    if ENV['EDITOR']
+      exec "#{ENV['EDITOR']} #{filename}"
+    else
+      exec "open", filename
+    end
+    exit
+  else
+    STDERR.puts "#{__FILE__}: #{filename} does not exist or unable to open."
+    exit 1
+  end
+
+elsif MODE == 'insert'
+  if opts[:date]
+    puts "WARNING: Adding time to a day other than today is not recommended."
+    print "Continue? (y/n) "
+    input = STDIN.readline.chomp
+    unless input =~ /^y(es)?/i
+        STDERR.puts "Timelog update cancelled."
+        exit 1
+    end
+  end
+  
+  # process arguments
+  debug
+  minutes = TrackerUtil::processTimeArgument ARGV.shift
+  message = ARGV.join(" ")
+  
+  # open the output file
+  first_time = !File.exist?(filename)
+  # debug
+  begin
+    File.open filename, 'a', :autoclose => true do |file|
+      if first_time
+        currentTimeInMinutes = TrackerUtil::timeToMinutes(TrackerUtil::currentTimeFormatted)
+        startTime = TrackerUtil::minutesToTime((currentTimeInMinutes - minutes).round_to_nearest 15)
+        file.puts "#{fdate} #{startTime}"
+      end
+      file.puts "#{minutes}: #{message}"
+    end
+  rescue
+    STDERR.puts "Couldn't open #{filename}: #{$!}"
+    exit 1
+  end
+
+else
+    STDERR.puts "Couldn't determine the correct mode (I was given '#{MODE}'): #{$!}"
+    exit 1
+end

data/lib/trak/blank.rb

@@ -0,0 +1,16 @@
+# https://github.com/rails/rails/blob/2a371368c91789a4d689d6a84eb20b238c37678a/activesupport/lib/active_support/core_ext/object/blank.rb#L91
+class String
+  # 0x3000: fullwidth whitespace
+  NON_WHITESPACE_REGEXP = %r![^\s#{[0x3000].pack("U")}]!
+
+  # A string is blank if it's empty or contains whitespaces only:
+  #
+  #   "".blank?                 # => true
+  #   "   ".blank?              # => true
+  #   "　".blank?               # => true
+  #   " something here ".blank? # => false
+  #
+  def blank?
+    self !~ NON_WHITESPACE_REGEXP
+  end
+end

data/lib/trak/round_to_nearest.rb

@@ -0,0 +1,9 @@
+class Integer
+  def round_to_nearest(integer = 1)
+    if integer == 1
+      self.round
+    else
+      ((self.to_f / integer).round * integer).to_i
+    end
+  end
+end

data/lib/trak/tracker_util.rb

@@ -0,0 +1,103 @@
+require "trak/blank"
+require "trak/round_to_nearest"
+
+module TrackerUtil
+  TIME_FORMAT_12HOUR = "%l:%M %p"
+  TIME_FORMAT_24HOUR = "%k:%M"
+  
+  # expects a hash of tasks mapped to time spent, and a sub-report name
+  #   (e.g., work, personal)
+  # prints a formatted sub-report
+  # returns the total hours worked
+  def self.printSubReport(report_hash, report_title)
+    total = 0
+    unless report_hash.empty?
+      count = 0
+      report_out = ""
+      report_hash.each do |title, minutes|
+        total += minutes.to_i
+        count += 1
+        report_out += "=> #{timeString(minutes)}: #{title}"
+        report_out += "\n" unless count == report_hash.size
+      end
+      puts "# #{report_title} time (#{timeString(total)})"
+      puts report_out
+    end
+    total
+  end
+  
+  def self.time_with_hours_minutes(*hm)
+    dmy = Time.now.to_a[3..5].reverse
+    Time.new(*dmy, *hm)
+  end
+  
+  # expects a number of minutes
+  # if less than 60 returns the number with an "m"
+  # otherwise converts to hours and adds an "h"
+  def self.timeString(minutes)
+    if minutes >= 60
+      hours = minutes/60.0
+      if hours % 1 == 0
+        hours = hours.to_i
+      end
+      "#{hours}h"
+    else
+      "#{minutes}m"
+    end
+  end
+  
+  def self.newTimeWithMinutes(start_time, minutes)
+    hm = start_time.split ':'
+    Time.at(time_with_hours_minutes(*hm).to_i + minutes.to_i*60).strftime(TIME_FORMAT_24HOUR).strip
+  end
+  
+  def self.to12HourTime(time)
+    unless time.blank?
+      hm = time.split ':'
+      time_with_hours_minutes(*hm).strftime(TIME_FORMAT_12HOUR).strip
+    end
+  end
+  
+  def self.currentTimeFormatted
+    Time.now.strftime(TIME_FORMAT_24HOUR)
+  end
+
+  # expects a single argument - the time argument in the format ##m or ##h
+  # if argument has no m/h qualifier, assume m
+  # returns a number of minutes
+  def self.processTimeArgument(time_string)
+    if time_string =~ /^(\d*\.?\d+)((m|min|minute|minutes)|(h|hr|hour|hours))?$/i
+      time = $1.to_i
+      modifier = $2
+      minutes = (modifier =~ /h.*/) ? time * 60 : time
+
+      # check enough time has been logged
+      if minutes < 15
+        STDERR.puts "You must log at least 15 minutes."
+        exit 1
+      end
+
+      minutes.round_to_nearest 15
+    else
+      STDERR.puts "Incorrectly formatted argument."
+      exit 1
+    end
+  end
+
+  # expects a time string formatted HH24:MM
+  def self.timeToMinutes(time)
+    hours, minutes = time.split(':')
+    hours*60 + minutes
+  end
+
+  # expects an integer
+  def self.minutesToTime(minutes)
+    time_with_hours_minutes(minutes / 60, minutes % 60).sprintf TIME_FORMAT_24HOUR
+  end
+
+  # expects an integer which is the amount of minutes logged
+  def self.startTimeInMinutes(minutes)
+    currentTimeInMinutes = timeToMinutes(currentTimeFormatted).round_to_nearest 15
+    currentTimeInMinutes - minutes
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: trak
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Adam Sharp
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: trollop
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.16'
+description: ! 'Problem: when tracking time, I don''t want to have to
+
+  start and stop a timer. Trak is a tool that lets me say "I just spent
+
+  15 minutes working on email", instead of "I''m starting to email
+
+  now...whoops! I forgot to tell the computer I stopped." Then later in
+
+  the day when you spend some more time emailing, you don''t have to keep
+
+  the total time you''ve spent for the day in your head. When you tell trak
+
+  to report on your time spent for the day, it tallies each task and gives
+
+  you a breakdown.'
+email:
+- adsharp@me.com
+executables:
+- trak
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/trak/blank.rb
+- lib/trak/round_to_nearest.rb
+- lib/trak/tracker_util.rb
+- lib/trak.rb
+- bin/trak
+- CHANGELOG.md
+- README.md
+homepage: http://github.com/sharplet/trak
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.21
+signing_key: 
+specification_version: 3
+summary: A command line tool for tracking chunks of time
+test_files: []