timeless 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89d84ba2c5ef3404ab9ca4e2168b04990a1889f79b17c95e7762c618937b2c6e
-  data.tar.gz: ef7e2525c43a7d5479206ffbeebc9495699c093d55d817310e2c0127237ea898
+  metadata.gz: f271794edee45ff107dcd0d7858e9fb01c4f670e8b98b76e2c70de39d3353498
+  data.tar.gz: 9e80d347a218de303b7697265e07410d1a460b4262c928fe48bfe711a83002fe
 SHA512:
-  metadata.gz: 5c8d3766566e43d4766087c1bcb955f5167fed66c50b9809045c7d607745d3b006153396b283c67ae88110854f8c134697f22c473c851eab73ad95eb3a6d97b0
-  data.tar.gz: 14953c9913b8ef6b6d29056d880086f27d62b0a210bfab4b297e98c71699ba85ee7061b030a0f1c6352741f8e24d6bc254d5589a2d0af05aa5d67af180b0ef0b
+  metadata.gz: c7d5c0d76111c83e186b38f6be6ccb1d4170ccd27e427f775fa81ce3bcfd69173228b8fe47adea40e926c37f61cb3d1b6c75e808c6926eeb801d9119ce3a5400
+  data.tar.gz: 95b7c4020f915c4807b71c5d3afa05da17e1c1da18bd9b161bfc346a554e935e006d6305b326743d57363ce1a7bb75172a4e24330d913147514e4f73a4cbdf54

data/README.org

@@ -0,0 +1,202 @@
+#+TITLE: Timeless README
+#+AUTHOR: Adolfo Villafiorita
+#+STARTUP: showall
+
+Timeless is a simple command line time tracker which supports
+stopwatches, pomodoro timers, and key-value pair in notes.
+
+Some non nominal conditions are also handled (e.g., starting a clock
+twice, trying to stop when no clock was started).
+
+* Installation
+   :PROPERTIES:
+   :CUSTOM_ID: installation
+   :END:
+
+Install the gem:
+
+#+BEGIN_EXAMPLE
+  $ gem install timeless
+#+END_EXAMPLE
+
+* Usage
+   :PROPERTIES:
+   :CUSTOM_ID: usage
+   :END:
+
+Run a pomodoro timer:
+
+#+BEGIN_EXAMPLE
+  timeless pom p:project meeting with c:john
+  timeless pom --duration 60 p:prj2
+  timeless pom --long # default to 50 minutes
+#+END_EXAMPLE
+
+Start clocking using a stopwatch:
+
+#+BEGIN_EXAMPLE
+  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
+#+END_EXAMPLE
+
+Stop clocking:
+
+#+BEGIN_EXAMPLE
+  timeless stop 
+  timeless stop forgot notes on start
+  timeless stop --last # reuse the notes of previous entry
+  timeless stop --at 'five minutes ago'
+  timeless stop --start '1 hour ago' --at 'now' clocked a full entry
+#+END_EXAMPLE
+
+Enter a full entry:
+
+#+BEGIN_EXAMPLE
+  timeless clock activity on p:project # from end of last entry to now
+  timeless clock --start 'three hours ago' --stop 'five minutes ago'
+#+END_EXAMPLE
+
+What was i doing?
+
+#+BEGIN_EXAMPLE
+  timeless current  # print current entry
+  timeless forget   # forget pending clock
+#+END_EXAMPLE
+
+What did I do?
+
+#+BEGIN_EXAMPLE
+  timeless last     # print last entry
+#+END_EXAMPLE
+
+Reporting and exporting
+
+#+BEGIN_EXAMPLE
+  timeless statement
+  timeless balance --from yesterday --filter p:project
+  timeless export
+#+END_EXAMPLE
+
+Notice that even though =timeless= uses CSV as its native format, the
+export command generates a CSV file which is more easily parsed by a
+spreadsheet application such as LibreOffice.
+
+If you do not want to type =timeless= every time, you can invoke a
+console:
+
+#+BEGIN_EXAMPLE
+  timeless console
+  timeless:000> start
+  timeless:001> stop
+  timeless:002>
+#+END_EXAMPLE
+
+More information with:
+
+#+BEGIN_EXAMPLE
+  timeless help                          # get list of available commands
+  timeless help command                  # help about command
+  timeless man                           # output this README file
+#+END_EXAMPLE
+
+* Key-Value pairs
+   :PROPERTIES:
+   :CUSTOM_ID: key-value-pairs
+   :END:
+
+Timeless has some basic support for key-pair values in the notes
+field.
+
+A key-pair value is entered as:
+
+#+BEGIN_EXAMPLE
+  key:value
+#+END_EXAMPLE
+
+where =key= is any string starting with a letter and containing letters,
+numbers, and underscores; and =value= is *anything but a space*.
+
+For instance a note field could look like:
+
+#+BEGIN_EXAMPLE
+  working for c:john_smith on a:writing_documentation
+#+END_EXAMPLE
+
+Key value pairs can be used to assign a special meaning to some
+strings and improve filtering and exporting.
+
+Three special keys are =p= for projects, =c= for clients, and =a= for
+activity.  These keys get dedicated columns in the csv file when using
+the =export= command.
+
+* If something goes wrong
+   :PROPERTIES:
+   :CUSTOM_ID: if-something-goes-wrong
+   :END:
+
+Timeless writes entries on =~/.timeless.csv=, storing the following
+information:
+
+1. start date and time
+2. end date and time
+3. notes
+
+You can edit the file to manually fix entries if you make some
+mistake.
+
+The =~/timeless.csv= file should contain only correct entries, that
+is, entries with start, stop, and (possibly empty) notes.
+
+When using a stopwatch, a temporary file =~/.timeless-tmp.csv= is used
+to store the timestamp of the start command.
+
+* Version History
+   :PROPERTIES:
+   :CUSTOM_ID: version-history
+   :END:
+
+*** 0.6.0
+
+- support for generic keys in notes. Possibility of specifying the same
+  key multiple times in a single note field
+- balance now produces distinct reports for each key (on top of the three
+  already generated for projects, activities, and clients)
+- management of empty lines in ~/timeless.csv
+
+*** 0.5.0
+
+- updated origin in Gem specification
+
+*** 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
+   :PROPERTIES:
+   :CUSTOM_ID: license
+   :END:
+
+Licensed under the terms of the MIT License.
+
+** Contributing
+   :PROPERTIES:
+   :CUSTOM_ID: contributing
+   :END:
+
+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/elisp/forms.el

@@ -1,5 +1,7 @@
 ;; forms-mode for timeless     -*- emacs-lisp -*-
 
+(require 'forms)
+
 (setq forms-file (expand-file-name "~/.timeless.csv"))
 
  ;; Use `forms-enumerate' to set field names and number thereof.

data/lib/timeless/cli/command_semantics.rb

@@ -17,7 +17,7 @@ module Timeless
     end
 
     def self.man opts = nil, argv = []
-      path = File.join(File.dirname(__FILE__), "/../../../README.md")
+      path = File.join(File.dirname(__FILE__), "/../../../README.org")
       file = File.open(path, "r")
       contents = file.read
       puts contents
@@ -215,6 +215,7 @@ module Timeless
       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
@@ -248,42 +249,31 @@ module Timeless
       # {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)
+      report "Projects", "p", hash
+      report "Clients", "c", hash
+      report "Activities", "a", hash
 
-      total = 0
-      puts ""
-      puts "Clients"
-      puts "======="
-      hash["c"].each do |key, value|
-        printf "%-20s%5s\n", key, in_hours(value)
-        total += value
+      remaining_tags = hash.reject! { |k| ["p", "c", "a"].include? k }
+      remaining_tags.keys.each do |k|
+        report k, k, remaining_tags
       end
-      puts "-------------------------"
-      printf "%-20s%5s\n", "Total", in_hours(total)
+    end
+
+    private
 
+    def self.report title, key, hash
       total = 0
       puts ""
-      puts "Activities"
-      puts "=========="
-      hash["a"].each do |key, value|
-        printf "%-20s%5s\n", key, in_hours(value)
-        total += value
+      puts title
+      puts "=" * title.size
+      (hash[key] || []).each do |k, v|
+        printf "%-20s%5s\n", k, in_hours(v)
+        total += v
       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

data/lib/timeless/cli/command_syntax.rb

@@ -372,7 +372,12 @@ DESCRIPTION
    a project "project_1", using "p:project_1"
 
 EXAMPLES
+   # extract all entries which have the string p:project_1 in the notes field
+   # (that is, all entries related to project_1)
    timeless statement --filter p:project_1
+
+   # extract all entries which have the word documentation in the notes field
+   timeless statement --filter documentation
 EOS
       return { statement: [opts, :statement, help] }
     end
@@ -407,5 +412,36 @@ EXAMPLES
 EOS
       return { balance: [opts, :balance, help] }
     end
+
+    def self.export_opts
+      opts = Slop::Options.new
+      opts.banner = "export -- export timeless.csv to CSV"
+      help = <<EOS
+NAME
+   #{opts.banner}
+
+SYNOPSYS
+   #{opts.to_s}
+
+DESCRIPTION
+   Print data to CSV, with the following columns:
+
+   - Start Date
+   - Start Time
+   - End Date
+   - End Time
+   - Duration in seconds
+   - First project found in notes
+   - First activity found in notes
+   - First client found in notes
+   - Notes attached to entry
+
+EXAMPLES
+   timeless export 
+   timeless export > data.csv
+EOS
+      return { export: [opts, :export, help] }
+    end
+
   end
 end

data/lib/timeless/storage.rb

@@ -11,11 +11,11 @@ module Timeless
     end
 
     def self.last
-      CSV.read(TIMELESS_FILE).sort { |x, y| x[1] <=> y[1] }.last
+      my_read(TIMELESS_FILE).sort { |x, y| x[1] <=> y[1] }.last
     end
 
     def self.get from_date=nil, to_date=nil, filter=nil
-      entries = CSV.read(TIMELESS_FILE)
+      entries = my_read(TIMELESS_FILE)
       entries.select do |x|
         (from_date ? Time.parse(x[0]) >= from_date : true) and
           (to_date ? Time.parse(x[1]) <= to_date : true) and
@@ -23,70 +23,85 @@ module Timeless
       end
     end
 
-    # get all unique keys of a given type in file
-    def self.get_key key
-      entries = CSV.read(TIMELESS_FILE)
-      entries.map { |x| extract_kpv key, x[2] }.uniq.sort
+    # get all unique tags in file
+    def self.get_tags
+      tags_regexp = /([a-zA-Z][0-9a-zA-Z_]*):([^ ]+)/
+
+      entries = my_read(TIMELESS_FILE)
+      entries.map { |x|
+        # match returns only the first match, while scan does it for the string
+        # scan returns an array of array ("a:b c:d".scan(tags_regexp) => [["a", "b"], ["c", "d"]]
+        (x[2] || "").scan(tags_regexp).map { |x| x[0] }
+      }.flatten.uniq
+    end
+      
+    # get all unique keys of a given tag in file
+    def self.get_key tag
+      entries = my_read(TIMELESS_FILE)
+      entries.map { |x| extract_kpv tag, x[2] }.flatten.uniq.sort
     end
 
     def self.balance from, to, filter
-      entries = Timeless::Storage.get(from, to, filter)
-
-      hash = {"p" => {}, "c" => {}, "a" => {}}
+      # hash of all keys defined in file
+      array = get_tags
+      hash = Hash[array.collect { |item| [item, {}] } ]
 
+      entries = Timeless::Storage.get(from, to, filter)
       entries.each do |entry|
         start = Time.parse(entry[0])
         stop = Time.parse(entry[1])
         duration = (stop - start) / 60
 
-        project = extract_kpv "p", entry[2]
-        client = extract_kpv "c", entry[2]
-        activity = extract_kpv "a", entry[2]
-
-        hash["p"][project] = (hash["p"][project] || 0) + duration if project != ""
-        hash["c"][client] = (hash["c"][client] || 0) + duration if client != ""
-        hash["a"][activity] = (hash["a"][activity] || 0) + duration if activity != ""
-
+        hash.keys.each do |key|
+          values = extract_kpv key, entry[2]
+          values.each do |value|
+            hash[key][value] = (hash[key][value] || 0) + duration
+          end
+        end
       end
       hash
     end
-
-
     def self.export
-      entries = CSV.read(TIMELESS_FILE)
+      entries = my_read(TIMELESS_FILE)
 
       CSV { |csvout| csvout << ["Start Date", "Start Time", "End Date", "End Time", "Duration (s)", "Project", "Client", "Activity", "Notes"] }
       CSV do |csvout|
         entries.each do |entry|
-          start = Time.parse(entry[0])
-          stop = Time.parse(entry[1])
-          
-          start_date = start.strftime("%Y-%m-%d")
-          start_time = start.strftime("%H:%M:%S")
-          
-          stop_date = stop.strftime("%Y-%m-%d")
-          stop_time = stop.strftime("%H:%M:%S")
-          
-          duration = stop - start
-        
-          # extract project and client, if present
-          project = extract_kpv "p", entry[2]
-          client = extract_kpv "c", entry[2]
-          activity = extract_kpv "a", entry[2]
-
-          notes = entry[2]
-
-          csvout << [start_date, start_time, stop_date, stop_time, duration, project, client, activity, notes]
+          if entry[0] and entry[1]
+            start = Time.parse(entry[0])
+            stop = Time.parse(entry[1])
+            
+            start_date = start.strftime("%Y-%m-%d")
+            start_time = start.strftime("%H:%M:%S")
+            
+            stop_date = stop.strftime("%Y-%m-%d")
+            stop_time = stop.strftime("%H:%M:%S")
+            
+            duration = stop - start
+            
+            # extract first project,  first client, and first activity, if present
+            project = extract_kpv("p", entry[2]).first
+            client = extract_kpv("c", entry[2]).first
+            activity = extract_kpv("a", entry[2]).first
+
+            notes = entry[2]
+
+            csvout << [start_date, start_time, stop_date, stop_time, duration, project, client, activity, notes]
+          end
         end
       end
     end
 
     private
 
-    # return the value of a key-pair value in string or "" if not present
+    # read the timeless file into a CSV skipping lines with empty start end stop time
+    def self.my_read timeless_file
+      CSV.read(timeless_file).select { |x| x[0] != nil and x[1] != nil }
+    end
+
+    # return all the values of a given key in string
     def self.extract_kpv key, string
-      match = string.match(/#{key}:([^ ]+)/)
-      match ? match[1] : ""
+      (string || "").scan(/(#{key}):([^ ]+)/).map { |x| x[1] }
     end
   end
 end

data/lib/timeless/version.rb

@@ -1,3 +1,3 @@
 module Timeless
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timeless
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Adolfo Villafiorita
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-30 00:00:00.000000000 Z
+date: 2020-01-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -107,7 +107,7 @@ files:
 - ".gitignore"
 - Gemfile
 - LICENSE.txt
-- README.md
+- README.org
 - Rakefile
 - bin/console
 - bin/setup

data/README.md

@@ -1,152 +0,0 @@
-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
-