dotime 0.0.3

data/History.txt

@@ -0,0 +1,13 @@
+== 0.0.3 / 2006-12-23
+
+* Added to RubyForge
+* Fixing bug which appeared when more than 9 todo items are present and always started the todo whose position was the first digit pressed (when starting/stopping a todo)
+* Adding textual indications of what's happening when loading initial projects/lists
+
+== 0.0.2 / 2006-09-18
+
+* Feature addition & bug fixes
+
+== 0.0.1 / 2006-09-12
+
+* Initial version

data/Manifest.txt

@@ -0,0 +1,8 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/dotime
+lib/do_time.rb
+lib/basecamp.rb
+test/test_do_time.rb

data/README.txt

@@ -0,0 +1,81 @@
+DoTime
+    by Saimon Moore
+    http://rubyforge.org/projects/dotime/
+
+== DESCRIPTION:
+
+This is a cheap time tracking substitute for those of us who can't afford the
+extra cash (or believe all basecamp projects require time tracking) for
+Basecamp (http://www.basecamphq.com) plans
+with the time tracking feature.
+
+How it works:
+
+DoTime cheats by keeping track of the time worked on a todo within the todo itself.
+It specifies a text format to keep track of the elapsed hours and then just updates it as necessary.
+
+== FEATURES/PROBLEMS:
+
+* easy to use single-key menu navigation
+* start/stop timers (even in parallel but that's naughty ;) by selecting a todo's position in the list
+* 'space' key start/stops next available todo
+* 'enter' key completes currently running todo
+* complete a specific todo if more than one todo is currently running
+* change project/todo lists at any time
+* refresh currently selected list to get changes from server
+* Automatically filters projects/lists & todos for the current logged in user.
+* elapsed time indication per todo/per list
+
+== TODOS:
+* Show total elapsed time per project
+* Show running timer for running tasks.
+* Update tasks every x minutes
+* For future bc api versions allow all
+* people involved in a project to access tasks.
+* (This will make find_logged_in_user redundant)
+* Refactor code to get todo-list with todos
+* Make OS independant (Linux & Macs work, check Windows)
+* Make space bar also do:
+*  - start last running task if not completed (missing, it now just starts running the first task again)
+*  - start next task if previous one completed (not tested)
+* Add 'working' indicator between long waits
+
+== SYNOPSYS:
+
+  dotime basecamp_login basecamp_password
+
+  (Then just follow the menu options)
+
+== REQUIREMENTS:
+
+* xml-simple     >= 1.0.8
+* highline       >= 1.2.1
+
+== INSTALL:
+
+* sudo gem install dotime -y
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2006 Saimon Moore
+
+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,21 @@
+#:mode=ruby:
+
+require 'rubygems'
+require 'hoe'
+require './lib/do_time.rb'
+
+Hoe.new('dotime', DoTime::VERSION) do |p|
+  p.rubyforge_name = 'dotime'
+  p.author = 'Saimon Moore'
+  p.summary = 'Cheap time tracking for Basecamp todo lists'
+  p.description = p.paragraphs_of('README.txt', 2..5).join("\n\n")
+  p.url = p.paragraphs_of('README.txt', 0).first.split(/\n/)[1..-1]
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.extra_deps = [["xml-simple", ">= 1.0.8"],["highline", ">= 1.2.1"]]
+  p.spec_extras = {
+    :autorequire => "do_time",
+    :bindir => "bin",                               # Use these for applications.
+    :executables => ["dotime"],
+    :default_executable => "dotime"
+  }
+end

data/bin/dotime

@@ -0,0 +1,50 @@
+#:mode=ruby:
+OPTIONS = {
+  :login     => nil,
+  :password  => nil,
+  :use_ssl => false
+}
+
+ARGV.options do |opts|
+  opts.banner = "Usage: dotime [options]"
+
+  opts.separator ""
+
+  opts.on <<-EOF
+  Description:
+    This is a cheap time tracking substitute for those of us who can't afford the
+    extra cash (or believe all basecamp projects require time tracking) for
+    Basecamp (http://www.basecamphq.com) plans
+    without the time tracking feature.
+
+    How it works:
+
+      DoTime cheats by keeping track of the time done on a todo within the todo itself.
+      It specifies a format to keep track of the elapsed hours and then just updates it as necessary.
+
+      DoTime is very easy to use. Just follow the menu options.
+
+
+  Examples:
+    dotime -u my_basecamp_login -p my_basecamp_password
+  EOF
+
+  opts.on("  Required:")
+
+  opts.on("-u", "--user=login", "A Basecamp account login", String)  { |OPTIONS[:login]| }
+  opts.on("-p", "--password=password", "A Basecamp account password", String) { |OPTIONS[:password]| }
+
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on("-s", "--[no-]ssl", "Use SSL when connecting (Default: #{OPTIONS[:use_ssl]})", String) { |OPTIONS[:use_ssl]| }
+  opts.on("-h", "--help", "Show this help message.") { puts opts; exit }
+
+  opts.parse!
+end
+
+unless OPTIONS[:login] && OPTIONS[:password]
+  puts ARGV.options; exit
+else
+  DoTime.new([OPTIONS[:login], OPTIONS[:password], OPTIONS[:use_ssl]]).run
+end

data/lib/basecamp.rb

@@ -0,0 +1,475 @@
+# the following are all standard ruby libraries
+require 'net/https'
+require 'yaml'
+require 'date'
+require 'time'
+
+begin
+  require 'xmlsimple'
+rescue LoadError
+  begin
+    require 'rubygems'
+    require_gem 'xml-simple'
+  rescue LoadError
+    abort <<-ERROR
+The 'xml-simple' library could not be loaded. If you have RubyGems installed
+you can install xml-simple by doing "gem install xml-simple".
+ERROR
+  end
+end
+
+# An interface to the Basecamp web-services API. Usage is straightforward:
+#
+#   session = Basecamp.new('your.basecamp.com', 'username', 'password')
+#   puts "projects: #{session.projects.length}"
+class Basecamp
+
+  # A wrapper to encapsulate the data returned by Basecamp, for easier access.
+  class Record #:nodoc:
+    attr_reader :type
+
+    def initialize(type, hash)
+      @type = type
+      @hash = hash
+    end
+
+    def [](name)
+      name = dashify(name)
+      case @hash[name]
+        when Hash then
+          @hash[name] = (@hash[name].keys.length == 1 && Array === @hash[name].values.first) ?
+            @hash[name].values.first.map { |v| Record.new(@hash[name].keys.first, v) } :
+            Record.new(name, @hash[name])
+        else @hash[name]
+      end
+    end
+
+    def id
+      @hash["id"]
+    end
+
+    def attributes
+      @hash.keys
+    end
+
+    def respond_to?(sym)
+      super || @hash.has_key?(dashify(sym))
+    end
+
+    def method_missing(sym, *args)
+      if args.empty? && !block_given? && respond_to?(sym)
+        self[sym]
+      else
+        super
+      end
+    end
+
+    def to_s
+      "\#<Record(#{@type}) #{@hash.inspect[1..-2]}>"
+    end
+
+    def inspect
+      to_s
+    end
+
+    private
+
+      def dashify(name)
+        name.to_s.tr("_", "-")
+      end
+  end
+
+  # A wrapper to represent a file that should be uploaded. This is used so that
+  # the form/multi-part encoder knows when to encode a field as a file, versus
+  # when to encode it as a simple field.
+  class FileUpload
+    attr_reader :filename, :content
+
+    def initialize(filename, content)
+      @filename = filename
+      @content = content
+    end
+  end
+
+  attr_accessor :use_xml
+
+  # Connects
+  def initialize(url, user_name, password, use_ssl = false)
+    @use_xml = false
+    @user_name, @password = user_name, password
+    connect!(url, use_ssl)
+  end
+
+  # Return the list of all accessible projects.
+  def projects
+    records "project", "/project/list"
+  end
+
+  # Returns the list of message categories for the given project
+  def message_categories(project_id)
+    records "post-category", "/projects/#{project_id}/post_categories"
+  end
+
+  # Returns the list of file categories for the given project
+  def file_categories(project_id)
+    records "attachment-category", "/projects/#{project_id}/attachment_categories"
+  end
+
+  # Return information for the company with the given id
+  def company(id)
+    record "/contacts/company/#{id}"
+  end
+
+  # Return an array of the people in the given company. If the project-id is
+  # given, only people who have access to the given project will be returned.
+  def people(company_id, project_id=nil)
+    url = project_id ? "/projects/#{project_id}" : ""
+    url << "/contacts/people/#{company_id}"
+    records "person", url
+  end
+
+  # Return information about the person with the given id
+  def person(id)
+    record "/contacts/person/#{id}"
+  end
+
+  # Return information about the message(s) with the given id(s). The API
+  # limits you to requesting 25 messages at a time, so if you need to get more
+  # than that, you'll need to do it in multiple requests.
+  def message(*ids)
+    result = records("post", "/msg/get/#{ids.join(",")}")
+    result.length == 1 ? result.first : result
+  end
+
+  # Returns a summary of all messages in the given project (and category, if
+  # specified). The summary is simply the title and category of the message,
+  # as well as the number of attachments (if any).
+  def message_list(project_id, category_id=nil)
+    url = "/projects/#{project_id}/msg"
+    url << "/cat/#{category_id}" if category_id
+    url << "/archive"
+
+    records "post", url
+  end
+
+  # Create a new message in the given project. The +message+ parameter should
+  # be a hash. The +email_to+ parameter must be an array of person-id's that
+  # should be notified of the post.
+  #
+  # If you want to add attachments to the message, the +attachments+ parameter
+  # should be an array of hashes, where each has has a :name key (optional),
+  # and a :file key (required). The :file key must refer to a Basecamp::FileUpload
+  # instance.
+  #
+  #   msg = session.post_message(158141,
+  #      { :title => "Requirements",
+  #        :body => "Here are the requirements documents you asked for.",
+  #        :category_id => 2301121 },
+  #      [john.id, martha.id],
+  #      [ { :name => "Primary Requirements",
+  #          :file => Basecamp::FileUpload.new('primary.doc", File.read('primary.doc')) },
+  #        { :file => Basecamp::FileUpload.new('other.doc', File.read('other.doc')) } ])
+  def post_message(project_id, message, notify=[], attachments=[])
+    prepare_attachments(attachments)
+    record "/projects/#{project_id}/msg/create",
+      :post => message,
+      :notify => notify,
+      :attachments => attachments
+  end
+
+  # Edit the message with the given id. The +message+ parameter should
+  # be a hash. The +email_to+ parameter must be an array of person-id's that
+  # should be notified of the post.
+  #
+  # The +attachments+ parameter, if used, should be the same as described for
+  # #post_message.
+  def update_message(id, message, notify=[], attachments=[])
+    prepare_attachments(attachments)
+    record "/msg/update/#{id}",
+      :post => message,
+      :notify => notify,
+      :attachments => attachments
+  end
+
+  # Deletes the message with the given id, and returns it.
+  def delete_message(id)
+    record "/msg/delete/#{id}"
+  end
+
+  # Return a list of the comments for the specified message.
+  def comments(post_id)
+    records "comment", "/msg/comments/#{post_id}"
+  end
+
+  # Retrieve a specific comment
+  def comment(id)
+    record "/msg/comment/#{id}"
+  end
+
+  # Add a new comment to a message. +comment+ must be a hash describing the
+  # comment. You can add attachments to the comment, too, by giving them in
+  # an array. See the #post_message method for a description of how to do that.
+  def create_comment(post_id, comment, attachments=[])
+    prepare_attachments(attachments)
+    record "/msg/create_comment", :comment => comment.merge(:post_id => post_id),
+      :attachments => attachments
+  end
+
+  # Update the given comment. Attachments follow the same format as #post_message.
+  def update_comment(id, comment, attachments=[])
+    prepare_attachments(attachments)
+    record "/msg/update_comment", :comment_id => id,
+      :comment => comment, :attachments => attachments
+  end
+
+  # Deletes (and returns) the given comment.
+  def delete_comment(id)
+    record "/msg/delete_comment/#{id}"
+  end
+
+  # =========================================================================
+  # TODO LISTS AND ITEMS
+  # =========================================================================
+
+  # Marks the given item completed.
+  def complete_item(id)
+    record "/todos/complete_item/#{id}"
+  end
+
+  # Marks the given item uncompleted.
+  def uncomplete_item(id)
+    record "/todos/uncomplete_item/#{id}"
+  end
+
+  # Creates a new to-do item.
+  def create_item(list_id, content, responsible_party=nil, notify=true)
+    record "/todos/create_item/#{list_id}",
+      :content => content, :responsible_party => responsible_party,
+      :notify => notify
+  end
+
+  # Creates a new list using the given hash of list metadata.
+  def create_list(project_id, list)
+    record "/projects/#{project_id}/todos/create_list", list
+  end
+
+  # Deletes the given item from it's parent list.
+  def delete_item(id)
+    record "/todos/delete_item/#{id}"
+  end
+
+  # Deletes the given list and all of its items.
+  def delete_list(id)
+    record "/todos/delete_list/#{id}"
+  end
+
+  # Retrieves the specified list, and all of its items.
+  def get_list(id)
+    record "/todos/list/#{id}"
+  end
+
+  # Return all lists for a project. If complete is true, only completed lists
+  # are returned. If complete is false, only uncompleted lists are returned.
+  def lists(project_id, complete=nil)
+    records "todo-list", "/projects/#{project_id}/todos/lists", :complete => complete
+  end
+
+  # Repositions an item to be at the given position in its list
+  def move_item(id, to)
+    record "/todos/move_item/#{id}", :to => to
+  end
+
+  # Repositions a list to be at the given position in its project
+  def move_list(id, to)
+    record "/todos/move_list/#{id}", :to => to
+  end
+
+  # Updates the given item
+  def update_item(id, content, responsible_party=nil, notify=true)
+    record "/todos/update_item/#{id}",
+      :item => { :content => content }, :responsible_party => responsible_party,
+      :notify => notify
+  end
+
+  # Updates the given list's metadata
+  def update_list(id, list)
+    record "/todos/update_list/#{id}", :list => list
+  end
+
+  # =========================================================================
+  # MILESTONES
+  # =========================================================================
+
+  # Complete the milestone with the given id
+  def complete_milestone(id)
+    record "/milestones/complete/#{id}"
+  end
+
+  # Create a new milestone for the given project. +data+ must be hash of the
+  # values to set, including +title+, +deadline+, +responsible_party+, and
+  # +notify+.
+  def create_milestone(project_id, data)
+    create_milestones(project_id, [data]).first
+  end
+
+  # As #create_milestone, but can create multiple milestones in a single
+  # request. The +milestones+ parameter must be an array of milestone values as
+  # descrbed in #create_milestone.
+  def create_milestones(project_id, milestones)
+    records "milestone", "/projects/#{project_id}/milestones/create", :milestone => milestones
+  end
+
+  # Destroys the milestone with the given id.
+  def delete_milestone(id)
+    record "/milestones/delete/#{id}"
+  end
+
+  # Returns a list of all milestones for the given project, optionally filtered
+  # by whether they are completed, late, or upcoming.
+  def milestones(project_id, find="all")
+    records "milestone", "/projects/#{project_id}/milestones/list", :find => find
+  end
+
+  # Uncomplete the milestone with the given id
+  def uncomplete_milestone(id)
+    record "/milestones/uncomplete/#{id}"
+  end
+
+  # Updates an existing milestone.
+  def update_milestone(id, data, move=false, move_off_weekends=false)
+    record "/milestones/update/#{id}", :milestone => data,
+      :move_upcoming_milestones => move,
+      :move_upcoming_milestones_off_weekends => move_off_weekends
+  end
+
+  # Make a raw web-service request to Basecamp. This will return a Hash of
+  # Arrays of the response, and may seem a little odd to the uninitiated.
+  def request(path, parameters = {}, second_try = false)
+    response = post(path, convert_body(parameters), "Content-Type" => content_type)
+
+    if response.code.to_i / 100 == 2
+      result = XmlSimple.xml_in(response.body, 'keeproot' => true,
+        'contentkey' => '__content__', 'forcecontent' => true)
+      typecast_value(result)
+    elsif response.code == "302" && !second_try
+      connect!(@url, !@use_ssl)
+      request(path, parameters, true)
+    else
+      raise "#{response.message} (#{response.code})"
+    end
+  end
+
+  # A convenience method for wrapping the result of a query in a Record
+  # object. This assumes that the result is a singleton, not a collection.
+  def record(path, parameters={})
+    result = request(path, parameters)
+    (result && !result.empty?) ? Record.new(result.keys.first, result.values.first) : nil
+  end
+
+  # A convenience method for wrapping the result of a query in Record
+  # objects. This assumes that the result is a collection--any singleton
+  # result will be wrapped in an array.
+  def records(node, path, parameters={})
+    result = request(path, parameters).values.first or return []
+    result = result[node] or return []
+    result = [result] unless Array === result
+    result.map { |row| Record.new(node, row) }
+  end
+
+  private
+
+    def connect!(url, use_ssl)
+      @use_ssl = use_ssl
+      @url = url
+      @connection = Net::HTTP.new(url, use_ssl ? 443 : 80)
+      @connection.use_ssl = @use_ssl
+      @connection.verify_mode = OpenSSL::SSL::VERIFY_NONE if @use_ssl
+    end
+
+    def convert_body(body)
+      body = use_xml ? body.to_xml : body.to_yaml
+    end
+
+    def content_type
+      use_xml ? "application/xml" : "application/x-yaml"
+    end
+
+    def post(path, body, header={})
+      request = Net::HTTP::Post.new(path, header.merge('Accept' => 'application/xml'))
+      request.basic_auth(@user_name, @password)
+      @connection.request(request, body)
+    end
+
+    def store_file(contents)
+      response = post("/upload", contents, 'Content-Type' => 'application/octet-stream',
+        'Accept' => 'application/xml')
+
+      if response.code == "200"
+        result = XmlSimple.xml_in(response.body, 'keeproot' => true, 'forcearray' => false)
+        return result["upload"]["id"]
+      else
+        raise "Could not store file: #{response.message} (#{response.code})"
+      end
+    end
+
+    def typecast_value(value)
+      case value
+      when Hash
+        if value.has_key?("__content__")
+          content = translate_entities(value["__content__"]).strip
+          case value["type"]
+          when "integer"  then content.to_i
+          when "boolean"  then content == "true"
+          when "datetime" then Time.parse(content)
+          when "date"     then Date.parse(content)
+          else                 content
+          end
+        else
+          value.empty? ? nil : value.inject({}) do |h,(k,v)|
+            h[k] = typecast_value(v)
+            h
+          end
+        end
+      when Array
+        value.map! { |i| typecast_value(i) }
+        case value.length
+        when 0 then nil
+        when 1 then value.first
+        else value
+        end
+      else
+        raise "can't typecast #{value.inspect}"
+      end
+    end
+
+    def translate_entities(value)
+      value.gsub(/&lt;/, "<").
+            gsub(/&gt;/, ">").
+            gsub(/&quot;/, '"').
+            gsub(/&apos;/, "'").
+            gsub(/&amp;/, "&")
+    end
+
+    def prepare_attachments(list)
+      (list || []).each do |data|
+        upload = data[:file]
+        id = store_file(upload.content)
+        data[:file] = { :file => id,
+                        :content_type => "application/octet-stream",
+                        :original_filename => upload.filename }
+      end
+    end
+end
+
+# A minor hack to let Xml-Simple serialize symbolic keys in hashes
+class Symbol
+  def [](*args)
+    to_s[*args]
+  end
+end
+
+class Hash
+  def to_xml
+    XmlSimple.xml_out({:request => self}, 'keeproot' => true, 'noattr' => true)
+  end
+end

data/lib/do_time.rb

@@ -0,0 +1,544 @@
+begin
+  require 'rubygems'
+  require "highline/import"
+  require "highline/system_extensions"
+rescue LoadError
+  begin
+    require "highline/system_extensions"
+    require "highline/import"
+  rescue LoadError
+    abort <<-ERROR
+The 'highline' library could not be loaded. If you have RubyGems installed
+you can install HighLine by doing "gem install highline".
+ERROR
+  end
+end
+
+require File.dirname(__FILE__) + '/basecamp'
+require 'optparse'
+
+class DoTime
+  VERSION = '0.0.3'
+
+  include HighLine::SystemExtensions
+
+  ENTER_KEY = 10
+  SPACE_KEY = 32
+
+  BASIC_ACTIONS =  [
+    ['p', 'Select a different project','Select from a list of the active projects belonging to owner'],
+    ['l', 'Select a different list','Select a different todo list from those available in the current projects'],
+    ['r', 'Refresh list','Restart session and refresh status of todos in current list'],
+    ['q', 'Quit DoTime', 'Just exit this app']
+  ]
+
+  ACTIVE_LIST_ACTIONS =  [
+    ['1-9/01-99', 'Start/Stop todo timer','Press the number of the todo to start/stop timing it. If more than 9 items in list use 01-09.'],
+    ['c', 'Complete todo','Complete a running todo e.g. type c3 to complete todo no 3.'],
+    [ENTER_KEY, 'Complete running todo','Completes the only running todo. Otherwise starts next available todo'],
+    [SPACE_KEY, 'Stop running todo','Stop timing the only running todo. Otherwise starts next available todo']
+  ]
+
+  attr_accessor :login, :password, :use_ssl, :session, :current_owner, :current_project, :valid_lists, :current_list, :running_todos
+
+  def initialize(args)
+    @login, @password, @use_ssl = *args
+    init_bc_session
+    @valid_lists = []
+    @running_todos = {}
+  end
+
+  #Entry point to DoTime
+  def run
+    clear_screen
+    unless @current_project
+      select_project
+    end
+
+    no_valid_lists if @valid_lists.empty?
+
+    if !@current_list && (@valid_lists && !@valid_lists.empty?)
+      select_list
+    end
+
+    make_selections
+  end
+
+  protected
+
+    #Starts a new Basecamp API session
+    def init_bc_session
+      @session = Basecamp.new('webtypes.projectpath.com',@login, @password, @use_ssl)
+    end
+
+    #Print no valid lists warning
+    def no_valid_lists
+      say "<%=color('No valid lists for that user! Select either another owner or project.',:red, :bold)%>"
+    end
+
+    #Main key selection loop
+    #Loops until quit is selected performing all actions
+    def make_selections
+      if @current_list
+        actions = ACTIVE_LIST_ACTIONS + BASIC_ACTIONS
+      else
+        actions = BASIC_ACTIONS
+      end
+
+      while /q/i !~ (char = show_todos_and_select_action(actions)).chr
+        char = char.chr unless [ENTER_KEY, SPACE_KEY].include?(char)
+        case char
+          when /p/i
+            clear_screen
+            select_project
+            select_list
+          when /l/i
+            clear_screen
+            select_list
+          when /c/i
+            char = get_character.chr
+            position = get_position(char)
+            clear_screen
+            complete_todo(position)
+          when /r/i
+            clear_screen
+            refresh_and_print
+          when ENTER_KEY
+            clear_screen
+            complete_running_todo
+          when SPACE_KEY
+            clear_screen
+            stop_running_todo
+            puts "SPACE"
+          when /\d/
+            position = get_position(char)
+            clear_screen
+            start_stop_todo(position)
+          else
+            say "<%=color('Unsupported key...',:red, :bold)%>" and sleep 1
+            clear_screen
+        end
+      end
+      say_goodbye
+    end
+
+    def get_position(first_digit)
+      second_digit = nil
+      case all_todos.size
+        when 10..99
+          second_digit = get_character.chr
+        else
+      end
+      unless second_digit
+        position = first_digit
+      else
+        position = first_digit == 0 ? "0#{second_digit}" : "#{first_digit}#{second_digit}"
+      end
+      position
+    end
+
+    def say_goodbye
+      puts
+      puts "Bye..."
+    end
+
+    #Complete a running todo if only one running
+    #else starts next available todo
+    def complete_running_todo
+      unless @running_todos.size == 1
+        puts "Starting next available..."
+        start_next_available_todo
+        return
+      end
+      stop_timing_todo(find_todo_by_id(@running_todos.keys.first), true)
+    end
+
+    #Stop timing a running todo if only one running
+    #else starts next available todo
+    def stop_running_todo
+      unless @running_todos.size == 1
+        puts "Starting next available..."
+        start_next_available_todo
+        return
+      end
+      stop_timing_todo(find_todo_by_id(@running_todos.keys.first), false)
+    end
+
+    #Start timing next available todo
+    #i.e. First todo in list that is not running
+    def start_next_available_todo
+      next_todo = find_next_available_todo
+      unless next_todo
+        say "<%=color('No available todos to start...',:red, :bold)%>" and return
+      end
+      start_timing_todo(next_todo)
+    end
+
+    #Searches list of valid todos and returns first todo that is not running
+    #Note: todos list is ordered by the todo 'position' attribute
+    def find_next_available_todo
+      all_todos.find do |todo|
+        !@running_todos.has_key?(todo.id)
+      end
+    end
+
+    #Find a todo within the currently active list by its 'id' attribute
+    def find_todo_by_id(id)
+      all_todos.find do |todo|
+        todo.id == id
+      end
+    end
+
+    #Prints the list of todos, the available actions
+    #and waits for a user response
+    #Returns the key pressed.
+    def show_todos_and_select_action(actions)
+      print_todos
+      print_actions(actions)
+      get_character
+    end
+
+    #Start or stop a todo found via it's position in the list
+    #Toggles timer for the selected todo
+    def start_stop_todo(position)
+      selected_todo = all_todos[position.to_i - 1]
+      unless selected_todo
+        say "<%=color('Not available',:red,:bold)%>"
+        return
+      end
+      unless @running_todos[selected_todo.id]
+        start_timing_todo(selected_todo)
+      else
+        stop_timing_todo(selected_todo, false)
+      end
+    end
+
+    #Prints the available user actions
+    #Each action is bound to a specific key (case insensitive)
+    def print_actions(actions)
+
+      say "<%=color('Actions',:blue, :bold, :underline)%>"
+      puts
+      actions.each do |option|
+        key = key_to_char(option[0])
+        title = option[1]
+        desc = option[2]
+
+        say "'#{key}' - #{title} (<%=color('#{desc}',:cyan)%>)"
+      end
+
+      puts
+      print 'Choose action? >'
+    end
+
+    #Displays the text character of a key code
+    def key_to_char(key)
+      case key
+        when 10
+         'ENTER'
+        when 32
+         'SPACE'
+        else
+         key
+      end
+    end
+
+    #Returns abbreviated version of the todo's 'content' attribute
+    def brief_todo(todo)
+      todo['content'][0..20]
+    end
+
+    #Complete a todo whose 'id' attribute is supplied.
+    def complete_todo(id)
+      clear_screen
+      selected_todo = all_todos[id.to_i - 1]
+      unless selected_todo
+        say "<%=color('#{id} doesn\\'t correspond to a todo in the current list',:red, :bold)%>"
+        return
+      end
+
+      unless selected_todo && @running_todos.has_key?(selected_todo.id)
+        say "<%=color('Timer hasn\\'t started for \"#{brief_todo(selected_todo)}\"',:red, :bold)%>"
+        return
+      end
+      stop_timing_todo(selected_todo, true)
+    end
+
+    #Add a timer to the supplied todo
+    def start_timing_todo(todo)
+      @running_todos[todo.id] = Time.now
+      say "<%=color('Timer started for \"#{brief_todo(todo)}\"',:green, :bold)%>"
+    end
+
+    #Stop the timer on a selected todo
+    #By adding a complete argument you can specify
+    #wether the todo is completed or not.
+    def stop_timing_todo(todo, complete = false)
+      elapsed_time = Time.now - @running_todos.delete(todo.id)
+      update_todo_with_elapsed_time(todo, elapsed_time, complete)
+      say "<%=color('Stopped timer for \"#{brief_todo(todo)}\"',:green, :bold)%>"
+      say "<%=color('Elapsed time: #{time(elapsed_time)}',:black, :bold)%>"
+      puts
+      refresh
+    end
+
+    #Pretty prints the supplied time (in seconds)
+    #If a minute or more, minutes are used
+    #If an hour or more, hours are used
+    def time(time)
+      case time
+        when 0..59
+          "#{time} seconds"
+        when 60..3599
+          "#{time/60} minutes"
+        else
+          "#{time/3600} hours"
+      end
+    end
+
+    #Filter out any non-active projects
+    def active_projects(cache = true)
+      say "Getting projects ..."
+      @active_projects = nil unless cache
+      @active_projects ||= @session.projects.select do |project|
+        print "."
+        project['status'] == 'active'
+      end
+      clear_screen
+      @active_projects
+    end
+
+    #Find project && select valid lists for current owner
+    def select_project
+      bc_projects = active_projects
+      @current_project = nil
+      @current_project = bc_projects.first if bc_projects.size == 1
+      @current_project ||= bc_projects[select_from("Select a project?", bc_projects.collect {|p| p['name']})[1]]
+
+      clear_screen
+      unless @current_owner
+        find_logged_in_user
+        clear_screen
+      end
+
+      select_valid_lists
+    end
+
+    #Filter out any of current owner's lists
+    #that do not have at least one todo that isn't complete
+    def select_valid_lists
+      say "Selecting valid lists ... <%=color('please wait...',:black, :bold)%>"
+      @valid_lists.clear
+      bc_lists = @session.lists(@current_project.id, false)
+
+      #find lists with todos that belong to person and aren't completed
+      bc_lists.each do |bc_list|
+        print "."
+        list = @session.get_list(bc_list.id)
+        if list['todo-items'].is_a? Array
+          any = list['todo-items'].any? do |todo|
+            todo['responsible-party-id'] == @current_owner.id && !todo['completed']
+          end
+          @valid_lists << list if any
+        else
+          @valid_lists << list if list['todo-items'] && list['todo-items']['todo-item']['responsible-party-id'] == @current_owner.id && !list['todo-items']['todo-item']['completed']
+        end
+      end
+      clear_screen
+    end
+
+    #Select current todo list to work with
+    def select_list
+      @current_list = nil
+      if @valid_lists && !@valid_lists.empty?
+        @current_list = @valid_lists.first if @valid_lists.size == 1
+        @current_list ||= @valid_lists[select_from("Select a todo list?", @valid_lists.collect {|l| l['name']})[1]]
+        clear_screen
+        print_todos
+      else
+        clear_screen
+        no_valid_lists
+      end
+    end
+
+    #Find the logged in users Basecamp api person record
+    #TODO: Deprecate if available in future basecampe api versions
+    def find_logged_in_user
+      say "Finding logged in user ..."
+      category = @session.message_categories(@current_project.id).first
+      fake_message = @session.post_message(@current_project.id,
+                      { :title => "[TEMP] #{Time.now}",
+                        :body => "Must be deleted!",
+                        :category_id => category.id })
+      @current_owner = @session.person(fake_message['author-id'])
+      @session.delete_message(fake_message.id)
+      @current_owner
+    end
+
+    #Returns all valid todos sorted by their 'position' attribute
+    #irrespective of wether they've timers running or not
+    def all_todos
+      sort_todos(list_valid_todos)
+    end
+
+    #Returns a list of the currently running todos
+    def running_todos
+      all_todos.select {|t| @running_todos.keys.include?(t.id)}
+    end
+
+    #Returns a list of all the todos that are currently not running
+    def not_running_todos
+      all_todos - running_todos
+    end
+
+    #Recreate list of valid todos from currently active todo list
+    #By valid todos I mean, todos that are still to be completed
+    def list_valid_todos
+      valid_todos = []
+      if @current_list['todo-items'].is_a? Array
+        @current_list['todo-items'].each do |todo|
+          valid_todos << todo if todo['responsible-party-id'] == @current_owner.id && !todo['completed']
+        end
+      else
+        valid_todos << @current_list['todo-items']['todo-item'] if @current_list['todo-items']['todo-item']['responsible-party-id'] == @current_owner.id && !@current_list['todo-items']['todo-item']['completed']
+      end
+      valid_todos
+    end
+
+
+    #Sort todos by their 'position' attribute
+    def sort_todos(todos)
+      todos.sort {|x,y| x['position'] <=> y['position']}
+    end
+
+    #Print status list for all valid todos
+    def print_todos
+      print_todos_for(all_todos)
+    end
+
+    #Reinitialise the connection to the Basecamp api
+    #and refresh the currently active list
+    def refresh
+      init_bc_session
+      @current_list = @session.get_list(@current_list.id)
+    end
+
+    #Print list of todos showing their current status (Running or not) and elapsed times.
+    def print_todos_for(list)
+      clear_screen
+      say "[<%= color('#{@current_owner['first-name'].to_s}', :bold)%> <%= color('#{@current_owner['last-name'].to_s}',:bold)%>] Project: <%= color('#{@current_project['name'].to_s}',:bold)%>"
+      say "Todo's for list: <%=color('#{@current_list['name'].to_s}', :green, :bold)%> (Total elapsed time: #{time(calc_total_elapsed_time*3600)}):"
+      puts
+      list.each_with_index do |todo, i|
+        hours = extract_elapsed_time_from(todo)
+        running = is_todo_running?(todo) ? "[Running]" : ""
+        say "<%=color('#{(i + 1).to_s}',:black, :bold)%>. - #{todo['content'].gsub(/(\[.*\])/,'').strip}"
+        say "<%=color('Elapsed',:black, :bold)%>: #{time(hours*3600)} <%= color('#{running}',:red, :bold)%>"
+        puts
+      end
+      puts
+      puts
+    end
+
+    #Calculate the total elapsed time for the currently active todo list
+    def calc_total_elapsed_time
+      time = 0.0
+      all_todos.each do |todo|
+        time += extract_elapsed_time_from(todo)
+      end
+      time
+    end
+
+    #Determines wether the supplied todo has a running timer or not
+    def is_todo_running?(todo)
+      @running_todos.has_key?(todo.id)
+    end
+
+    #Extract the elapsed time from the todos 'content' attribute
+    #Should have a string of text at the end of the content in the
+    #following format: [[0.1]]
+    def extract_elapsed_time_from(todo)
+      time = has_time_tracker?(todo) ? has_time_tracker?(todo)[1].to_f : 0.0
+    end
+
+    #Determines wether the todo's 'content' attribute has the time tracking pattern: [[0.1]]
+    def has_time_tracker?(todo)
+      todo['content'].match(/\[\[(.*)\]\]/)
+    end
+
+    #Update a todo's 'content' attribute with the elapsed time.
+    #By passing in the 'complete' argument can toggle wether todo is completed
+    #or not
+    def update_todo_with_elapsed_time(todo, elapsed_time, complete = false)
+      if has_time_tracker?(todo)
+        previous_elapsed_time = extract_elapsed_time_from(todo)
+        new_elapsed_time = previous_elapsed_time + time_for_tracker(elapsed_time)
+        update_todo_with(todo, update_content_with(todo['content'], new_elapsed_time))
+        complete_item(todo) and puts "Completing" if complete
+      else
+        add_time_tracker_to(todo, time_for_tracker(elapsed_time))
+        complete_item(todo) and puts "Completing" if complete
+      end
+    end
+
+    #Actual Basecamp api method to complete a todo
+    def complete_item(todo)
+      @session.complete_item(todo.id)
+    end
+
+    #Add time tracking format string to todo content
+    def add_time_tracker_to(todo, elapsed_time)
+      content = todo['content']
+      content << " [[#{elapsed_time}]]"
+      update_todo_with(todo, content)
+    end
+
+    #Replaces string with format '[[1.1]]' with wlapsed time
+    def update_content_with(content, elapsed_time)
+      content.gsub(/\[\[(.*)\]\]/, "[[#{elapsed_time}]]")
+    end
+
+    #Perform list item update via BaseCamp api
+    def update_todo_with(todo, content)
+      @session.update_item(todo.id, content, @current_owner.id, false)
+    end
+
+    #Calculate time in hours for seconds argument
+    def time_for_tracker(elapsed_time)
+      (((elapsed_time/3600.0) * 100).round)/100.0
+    end
+
+    #Clear screen via OS clear command
+    #TODO: System specific???
+    def clear_screen
+      system("clear")
+    end
+
+    # Choose from a list of options.  +question+ is a prompt displayed
+    # above the list.  +list+ is a list of option strings.
+    # Returns the pair [option_name, option_index].
+    def select_from(question, list)
+      say "<%=color('#{question.strip}',:bold)%>"
+      list.each_with_index do |item, index|
+        puts " #{index+1}. #{item}"
+      end
+      puts " q - quit"
+      print "> "
+      while /q/i !~ (key = get_character.chr)
+        case key.to_i
+          when 1..list.size
+            result = key.to_i - 1
+            return list[result], result
+          else
+            nil
+        end
+      end
+      say_goodbye
+      exit!
+    end
+
+    def refresh_and_print
+      refresh
+      print_todos
+    end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.0
+specification_version: 1
+name: dotime
+version: !ruby/object:Gem::Version 
+  version: 0.0.3
+date: 2006-12-24 00:00:00 +00:00
+summary: Cheap time tracking for Basecamp todo lists
+require_paths: 
+- lib
+email: ryand-ruby@zenspider.com
+homepage: "    by Saimon Moore"
+rubyforge_project: dotime
+description: "This is a cheap time tracking substitute for those of us who can't afford the extra cash (or believe all basecamp projects require time tracking) for Basecamp (http://www.basecamphq.com) plans with the time tracking feature.  How it works:  DoTime cheats by keeping track of the time worked on a todo within the todo itself. It specifies a text format to keep track of the elapsed hours and then just updates it as necessary.  == FEATURES/PROBLEMS:"
+autorequire: do_time
+default_executable: dotime
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Saimon Moore
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- bin/dotime
+- lib/do_time.rb
+- lib/basecamp.rb
+- test/test_do_time.rb
+test_files: 
+- test/test_do_time.rb
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: 
+- dotime
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: xml-simple
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.0.8
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: highline
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.1
+    version: