timeless 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a45d84d4290e39bba5b6fe3a99fd101cefd7f97c
-  data.tar.gz: 761ab4cf1594beb69534198f556a11f936806801
+  metadata.gz: 06ba9bc95d407ecb088dc4c016fc7a66c78417cf
+  data.tar.gz: 560ac4abb81ef3f80476a0b7baa154ff3e3257e2
 SHA512:
-  metadata.gz: 5b97c16e7cc2fc1b1b919c93518a11c7ae6a115e11ff1138251bf26bd699da7d18b11f59b0a222c4ca242105d596528b52e1bb6149abd4f1df8f4c37adeffd3f
-  data.tar.gz: 72160f36426d2659db29cb1cfc57deb81948e1a24d483639197f881c0068c65b7b06455fc684d018793e091d7d85b0bd5e22d3c96d9b485d116d175affe9fddd
+  metadata.gz: f7b8f73506f3c399c5f17b0ce60620cfb31d63b09d87fb1bf89f3bf0babeb16cda0fae91d383405e9d848929837517e5567f186c5197c9b6cea2e49363c30a46
+  data.tar.gz: d44c950c14ba467675f0d0cb9c8f4a58b6ffd8ea93bba6329709944cc39aa4b9f3b45455f478a5aa39ec20c00d2cb17826e34dc5b70a2a23e235c002302f2dee

data/Gemfile

@@ -1,4 +1,6 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in timeless.gemspec
 gemspec

data/LICENSE.txt

@@ -1,22 +1,21 @@
-Copyright (c) 2015 Adolfo Villafiorita
+The MIT License (MIT)
 
-MIT License
+Copyright (c) 2015-2017 Adolfo Villafiorita
 
-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:
+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 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.
+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/README.md

@@ -0,0 +1,152 @@
+Timeless
+========
+
+Timeless is a simple command line time tracker.
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+    ruby
+    gem 'timeless'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install timeless
+
+Usage
+-----
+
+timeless is a simple command line time tracker. Entries store the
+following information:
+
+1.  start time
+2.  end time
+3.  notes
+
+timeless allows one to
+
+-   run a pomodoro timer
+-   clock time using a "stopwatch" (with start and stop commands)
+-   manually entering data
+-   print a text report, possibly filtered by date ranges of notes'
+    content
+-   export to csv
+
+Timeless has also some basic support for key-pair values in the notes
+form. They can be used to assign a special meaning to some strings and
+improve filtering and exporting. Two special keys are `p` for projects
+and `c` for clients. These two keys are exported in dedicated columns
+when exporting data to csv.
+
+Some non nominal conditions are also handled (e.g., starting a clock
+twice, trying to stop when no clock was started).
+
+If you do not want to type `timeless` every time, you can invoke a console:
+
+    timeless console
+    timeless:000> start
+    timeless:001> stop
+    timeless:002>
+
+More information with:
+
+    timeless help                          # get list of available commands
+    timeless help command                  # help about command
+    timeless man                           # output this README file
+
+
+Examples
+--------
+
+Get information about command syntax:
+
+    timeless -h
+
+Run a pomodoro timer:
+
+    timeless pom p:project meeting with c:john
+    timeless pom --duration 60 p:prj2
+    timeless pom --long # default to 50 minutes
+
+Start clocking using a stopwatch:
+
+    timeless start requirements doc
+    timeless start --at 'thirty minutes ago' fixing bug 182 for c:tim
+    timeless start --force --at 'five minutes ago' requirements document for p:prj1
+
+    Stop clocking:
+
+    timeless stop 
+    timeless stop forgot notes on start
+    timeless stop --last # reuse the notes of last entry
+    timeless stop --at 'five minutes ago'
+    timeless stop --start '1 hour ago' --at 'now' clocked a full entry
+
+Enter a full entry:
+
+    timeless clock activity on p:project # from end of last entry to now
+    timeless clock --start 'three hours ago' --stop 'five minutes ago'
+
+What was i doing?
+
+    timeless current  # print current entry
+    timeless forget   # forget pending clock
+
+What did I do?
+
+    timeless last     # print last entry
+
+Reporting and exporting
+
+    timeless statement
+    timeless balance --from yesterday --filter p:project
+    timeless export
+
+Notice that even though `timeless` uses CSV as its native format, the
+export command exports to a CSV file which is more easily parsed by a
+Spreadsheet such as LibreOffice.
+
+If something goes wrong
+-----------------------
+
+Data is stored in the CSV file `~/.timeless.csv`. You can edit the file
+to manually fix entries if you make some mistake.
+
+Version History
+---------------
+
+**0.4.0**
+
+- second public release
+- new `balance` command
+- the `report` command has been renamed `statement`
+- interactive `console`
+- more detailed help for commands
+- fixed a bug in the last command: now it returns the last activity in
+  chronological order (rather than the last activity which has been clocked)
+
+**0.2.0**
+- initial public release
+
+
+
+License
+-------
+
+Licensed under the terms of the MIT License.
+
+Contributing
+------------
+
+1.  Fork it ( https://github.com/\[my-github-username\]/timeless/fork )
+2.  Create your feature branch (\`git checkout -b my-new-feature\`)
+3.  Commit your changes (\`git commit -am 'Add some feature'\`)
+4.  Push to the branch (\`git push origin my-new-feature\`)
+5.  Create a new Pull Request
+

data/Rakefile

@@ -1,2 +1,2 @@
 require "bundler/gem_tasks"
-
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "timeless"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/elisp/forms.el

@@ -0,0 +1,22 @@
+;; forms-mode for timeless     -*- emacs-lisp -*-
+
+(setq forms-file (expand-file-name "~/.timeless.csv"))
+
+ ;; Use `forms-enumerate' to set field names and number thereof.
+(setq forms-number-of-fields
+      (forms-enumerate
+       '(start-datetime
+	 end-datetime
+	 description)))
+
+(setq forms-field-sep ",")
+
+;; The format list.
+(setq forms-format-list
+      (list
+       "====== Timeless Record ======\n\n"
+       "Start:       " start-datetime "\n"
+       "End:         " end-datetime "\n"
+       "Description: " description "\n"
+       ))
+

data/exe/timeless

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'timeless'
+
+Timeless::CommandSemantics.reps Timeless::CommandSyntax.commands, ARGV

data/lib/timeless.rb

@@ -1,7 +1,8 @@
 require "timeless/version"
 
-module Timeless
-  require "timeless/pomodoro"
-  require "timeless/stopwatch"
-  require "timeless/storage"
-end
+require "timeless/storage"
+require "timeless/stopwatch"
+require "timeless/pomodoro"
+
+require "timeless/cli/command_syntax"
+require "timeless/cli/command_semantics"

data/lib/timeless/cli/command_semantics.rb

@@ -0,0 +1,352 @@
+require 'timeless'
+
+require 'chronic'
+require 'readline'
+require 'fileutils'
+
+module Timeless
+  module CommandSemantics
+    APPNAME = 'timeless'
+    VERSION = Timeless::VERSION
+
+    #
+    # Main App Starts Here!
+    #
+    def self.version opts = nil, argv = []
+      puts "#{APPNAME} version #{VERSION}"
+    end
+
+    def self.man opts = nil, argv = []
+      path = File.join(File.dirname(__FILE__), "/../../../README.md")
+      file = File.open(path, "r")
+      contents = file.read
+      puts contents
+    end
+
+    def self.help opts = nil, argv = []
+      all_commands = CommandSyntax.commands
+      
+      if argv != []
+        argv.map { |x| puts all_commands[x.to_sym][2] }
+      else
+        puts "#{APPNAME} command [options] [args]"
+        puts ""
+        puts "Available commands:"
+        puts ""
+        all_commands.keys.each do |key|
+          puts "  " + all_commands[key][0].banner
+        end
+      end
+    end
+
+    def self.console opts, argv = []
+      all_commands = CommandSyntax.commands
+      all_commands.delete(:console)
+      
+      i = 0
+      while true
+        string = Readline.readline("#{APPNAME}:%03d> " % i, true)
+        string.gsub!(/^#{APPNAME} /, "") # as a courtesy, remove any leading appname string
+        if string == "exit" or string == "quit" or string == "." then
+          exit 0
+        end
+        reps all_commands, string.split(' ')
+        i = i + 1
+      end
+    end
+
+    # read-eval-print step
+    def self.reps all_commands, argv
+      if argv == [] or argv[0] == "--help" or argv[0] == "-h"
+        CommandSemantics.help
+        exit 0
+      else
+        command = argv[0]
+        syntax_and_semantics = all_commands[command.to_sym]
+        if syntax_and_semantics
+          opts = syntax_and_semantics[0]
+          function = syntax_and_semantics[1]
+          
+          begin
+            parser = Slop::Parser.new(opts)
+
+            result = parser.parse(argv[1..-1])
+            options = result.to_hash
+            arguments = result.arguments
+
+            eval "CommandSemantics::#{function}(options, arguments)"
+          rescue Slop::Error => e
+            puts "#{APPNAME}: #{e}"
+          rescue Exception => e
+            puts e
+          end
+        else
+          puts "#{APPNAME}: '#{command}' is not a valid command. See '#{APPNAME} help'"
+        end
+      end
+    end
+
+    #
+    # APP SPECIFIC COMMANDS
+    #
+    def self.pom opts, argv
+      duration = opts.to_hash[:duration] ||
+                 (opts.to_hash[:long] ? Timeless::Pomodoro::WORKING_LONG : Timeless::Pomodoro::WORKING)
+
+      start, stop, notes = Timeless::Pomodoro.run_pomodoro_timer(duration, argv.join(" "))
+      Timeless::Storage.store(start, stop, notes)
+      puts last_entry 
+    end
+
+
+    def self.start opts, argv
+      start = Chronic.parse(opts.to_hash[:at]) # nil if no option specified
+      notes = argv.join(" ")                   # empty string is no args specified
+      force = opts.to_hash[:force]
+
+      if Timeless::Stopwatch.clocking? and not force 
+        start, notes = Timeless::Stopwatch.get_start # for information purposes only
+        puts "There is a clock started at #{start} (notes: \"#{notes}\").  Use --force to override."
+      else
+        Timeless::Stopwatch.start(start, notes)
+        puts "Clock started at #{start ? start : Time.now}."
+        puts "You may want to specify notes for the entry when you stop clocking." if notes == ""
+      end
+    end
+
+    def self.forget opts, argv
+      if File.exists?(Timeless::Stopwatch::START_FILENAME)
+        entry = Timeless::Storage.last
+        Timeless::Stopwatch.forget
+        puts "Forgotten timer started at #{entry[0]} (#{entry[2]})."
+      else
+        puts "You don't have an active timer"
+      end
+    end
+
+    def self.stop opts, argv
+      start = Chronic.parse(opts.to_hash[:start])  # nil if no option specified
+      stop  = Chronic.parse(opts.to_hash[:at])     # nil if no option specified
+      notes = argv.join(" ")                       # empty string if no args specified
+
+      manage_stop start, stop, notes, opts[:last]
+    end
+
+    def self.clock opts, argv
+      start = Chronic.parse(opts.to_hash[:start])   # nil if no option specified
+      stop_opt = Chronic.parse(opts.to_hash[:stop]) # nil if no option specified
+      end_opt  = Chronic.parse(opts.to_hash[:end])  # nil if no option specified
+      stop = stop_opt ? stop_opt : end_opt          # stop_opt if --stop, end_opt if --end, nil otherwise
+      notes = argv.join(" ")                        # empty string if no args specified
+
+      if stop_opt and end_opt then
+        puts "Timeless error: specify end time with either --end or --stop (not both)"
+        exit
+      end
+
+      manage_stop start, stop, notes, opts[:last]
+    end
+
+    def self.current opts, argv
+      if Timeless::Stopwatch.clocking? then
+        start, notes = Timeless::Stopwatch.get_start
+        puts "Timeless: you have been clocking #{"%.0d" % ((Time.now- Time.parse(start)) / 60)} minutes"
+        puts "on: #{notes}" if notes
+      else
+        puts "There is no clock started."
+      end
+    end
+    
+    def self.last opts, argv
+      puts last_entry
+    end
+
+    def self.list opts, argv
+      values = Timeless::Storage.get_key argv[0]
+      puts "Timeless: list of keys #{argv[0]} found in timesheets:"
+      values.each do |value|
+        puts value
+      end
+    end
+
+    def self.export opts, argv
+      Timeless::Storage.export
+    end
+
+    def self.gaps opts, argv
+      from = opts.to_hash[:from] ? Chronic.parse(opts.to_hash[:from]) : nil
+      to = opts.to_hash[:to] ? Chronic.parse(opts.to_hash[:to]) : nil
+      interval = opts.to_hash[:interval] || 1
+        
+      entries = Timeless::Storage.get(from, to)
+      previous_stop = from || Time.parse(entries[0][0])
+      day = ""
+
+      printf "%-18s %-5s - %-5s   %-6s  %-s\n", "Day", "Start", "End", "Gap", "Command to fix"
+      entries.sort { |x,y| Time.parse(x[0]) <=> Time.parse(y[0]) }.each do |entry|
+        current_start = Time.parse(entry[0])
+        
+        current_day = current_start.strftime("%a %b %d, %Y")
+
+        if (current_start.day == previous_stop.day and current_start - previous_stop > interval * 60) then
+
+          if current_day != day then
+            day = current_day
+          else
+            current_day = "" # avoid printing the day if same as before
+          end
+
+          duration = (current_start - previous_stop) / 60
+          printf "%-18s %5s - %5s   %02i:%02i   %s\n",
+                 current_day,
+                 previous_stop.strftime("%H:%M"),
+                 current_start.strftime("%H:%M"),
+                 duration / 60, duration % 60, 
+                 "timeless clock --start '#{previous_stop}' --end '#{current_start}'"
+
+        end
+        previous_stop = Time.parse(entry[1])
+      end
+    end
+      
+
+    def self.statement opts, argv
+      from = opts.to_hash[:from] ? Chronic.parse(opts.to_hash[:from]) : nil
+      to = opts.to_hash[:to] ? Chronic.parse(opts.to_hash[:to]) : nil
+
+      entries = Timeless::Storage.get(from, to, opts.to_hash[:filter])
+      # it could become a function of a reporting module
+      printf "%-18s %-5s - %-5s %-8s  %-s\n", "Day", "Start", "End", "Duration", "Notes"
+      total = 0
+      day = ""
+      entries.sort { |x,y| Time.parse(x[0]) <=> Time.parse(y[0]) }.each do |entry|
+        current_day = Time.parse(entry[0]).strftime("%a %b %d, %Y")
+        if current_day != day then
+          day = current_day
+        else
+          current_day = "" # avoid printing the day if same as before
+        end
+        
+        duration = (Time.parse(entry[1]) - Time.parse(entry[0])) / 60
+        total = total + duration
+
+        printf "%-18s %5s - %5s   %5s   %s\n",
+               current_day,
+               Time.parse(entry[0]).strftime("%H:%M"),
+               Time.parse(entry[1]).strftime("%H:%M"),
+               in_hours(duration),
+               entry[2]
+      end
+      puts "----------------------------------------------------------------------"
+      printf "Total                              %02i:%02i\n", total / 60, total % 60
+    end
+
+    def self.balance opts, argv
+      from = opts.to_hash[:from] ? Chronic.parse(opts.to_hash[:from]) : nil
+      to = opts.to_hash[:to] ? Chronic.parse(opts.to_hash[:to]) : nil
+
+      # {key1 => {value1 => total .. } , ... }
+      hash = Timeless::Storage::balance from, to, opts.to_hash[:filter]
+
+      total = 0
+      puts "Projects"
+      puts "========"
+      hash["p"].each do |key, value|
+        printf "%-20s%5s\n", key, in_hours(value)
+        total += value
+      end
+      puts "-------------------------"
+      printf "%-20s%5s\n", "Total", in_hours(total)
+
+      total = 0
+      puts ""
+      puts "Clients"
+      puts "======="
+      hash["c"].each do |key, value|
+        printf "%-20s%5s\n", key, in_hours(value)
+        total += value
+      end
+      puts "-------------------------"
+      printf "%-20s%5s\n", "Total", in_hours(total)
+
+      total = 0
+      puts ""
+      puts "Activities"
+      puts "=========="
+      hash["a"].each do |key, value|
+        printf "%-20s%5s\n", key, in_hours(value)
+        total += value
+      end
+      puts "-------------------------"
+      printf "%-20s%5s\n", "Total", in_hours(total)
+    end
+
+
+    private
+
+    def self.in_hours value
+      sprintf "%02i:%02i", value / 60, value % 60
+    end
+    
+    def self.last_entry
+      start, stop, notes = Timeless::Storage.last
+
+      interval = Time.parse(stop) - Time.parse(start)
+      seconds = interval % 60
+      minutes = (interval / 60) % 60
+      hours = interval / 3600
+      
+      sprintf "Timeless: you clocked %02d:%02d:%02d on %s\nYou stopped clocking at: %s", hours, minutes, seconds, notes, stop
+    end
+
+    #
+    # code shared by stop and clock (which accept slightly different options,
+    # but behave in the same way
+    #
+    def self.manage_stop start, stop, notes, reuse_last
+      # syntax check:
+      # - --start is illegal if there is a running clock
+      # - --last is illegal if there are notes
+      #
+      # however:
+      # - --last and notes prevail over notes stored when starting the clock
+      if Timeless::Stopwatch.clocking? and start
+        puts "Timeless error: you specified --start with a running clock.  Use 'timeless forget' or drop --start"
+      end
+      if reuse_last and notes != "" then
+        puts "Timeless error: you specified both --last and notes.  Choose one or the other"
+      end
+
+      if reuse_last then
+        _, _, notes = Timeless::Storage.last
+      end
+      
+      if Timeless::Stopwatch.clocking?
+        start, stop, notes = Timeless::Stopwatch.stop(start, stop, notes) # merge passed with data in running clock
+        Timeless::Storage.store(start, stop, notes)
+
+        puts "Clock stopped at #{stop}."
+        puts last_entry
+      else
+        start = start ? start : Timeless::Storage.last[1]
+        stop = stop ? stop : Time.now
+        Timeless::Storage.store(start, stop, notes)
+
+        puts "Clock stopped at #{stop}."
+        puts last_entry
+      end
+    end
+
+    # GENERAL UTILITIES
+
+    def self.backup filename
+      FileUtils::cp filename, filename + "~"
+      puts "Backup copy #{filename} created in #{filename}~."
+    end
+
+    def self.backup_and_write filename, content
+      backup(filename) if File.exist?(filename)
+      File.open(filename, "w") { |f| f.puts content }
+    end
+  end
+end