time-sheet 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 461fe4226d6a5980fa168c7c918b01b35fb27aebef3110ff25d6d295709c6551
-  data.tar.gz: 830f66bef87e5925b117e32a2e82647736997381a07efe12a8e8151123e7d9cd
+  metadata.gz: fe61ceab6f7a30eaeb9a0e54854776f8dc09b1ba55f4578e98937b9ad7669388
+  data.tar.gz: 3fed81fb509d8df3d81118364bad0e6deaec9163ad75ecd7adfe128e432534ae
 SHA512:
-  metadata.gz: 6b99531029582021e5eff7c47a1483e24ad6ceb86b0865c2abd7b6af0496225b9e0f222c958538f073553e6ce5b4e4fe36d8e9ec10d3d2ab9b7ed8e1b83523f7
-  data.tar.gz: 358e04d3c9f16416d451d192ed5ad2a94545ef135250ecb3836ce75d5f551b3295e65b1d44b3a36f9b71ab95386acd466e866e2c27457e61c8ed4b853d311ad5
+  metadata.gz: 3f7bf35eb5afa3c311ccc945b4db80365425e0d5547e1e62d2ddd79942a25022b3604f950651892052d84b87a741ee196b1feb5129bd49642e1f9d771b21bde0
+  data.tar.gz: e8aef98393c7845993e87fc39703981891943e01847edd74451d5eabe9edb138218a5fdfcacdcaf822ffe0567809167639cca27c60512da56d57981d82dba299

data/README.md

@@ -5,6 +5,11 @@ generate various statistics suitable for invoices and project effort estimates.
 
 ## Changelog
 
+v1.0.0
+
+* input files need to be .xlsx files now because we needed to replace the
+  spreadsheet parser, see [#1](https://github.com/moritzschepp/time-sheet/issues/1)
+
 v0.9.0
 
 * introduced employee data column: To use it, add a column "employee" to the
@@ -26,6 +31,24 @@ The gem bundles an executable which includes a help command, just run
 A config file at `~/.time-sheet.conf` is read if it exists. The only possible
 option is `location: /path/to/excel/sheets`. It can be specified multiple times.
 
+The spreadsheet may carry a `tags` column holding a comma-separated list of tags
+per row. A blank `tags` cell is inherited from the previous row when the project,
+activity and description are unchanged, so a run of rows describing one task only
+needs to be tagged once. The `report` and `invoice` commands append a `Tags:`
+section showing how much of the reported time falls on each tag.
+
+Tag times can be scaled per tag with `-b` / `--tag-boosts`, e.g.
+`time-sheet.rb -b ai:1.4,physical:0.75`. Each entry's time is multiplied by the
+product of the factors of the tags it carries; untagged or unboosted entries are
+left unchanged. The `Tags:` section always reports unboosted time.
+
+The rendered descriptions can be cleaned up with `--filter-descriptions`, a
+single unanchored regular expression whose matches are removed from the output
+(reapplied until no match remains):
+`time-sheet.rb --filter-descriptions "mail to (Tom|Lana)"` turns *"mail to Tom
+about the report"* into *" about the report"*. It only affects what is printed;
+no rows are excluded.
+
 ### Processing data with other tools
 
 You can simply let the tool output a full list of time entries that are easy to

data/lib/time_sheet/time/cmd.rb

@@ -1,9 +1,11 @@
+require 'yaml'
+
 require 'slop'
 require 'time'
 
 class TimeSheet::Time::Cmd
   def run
-    TimeSheet.options = options
+    options[:tag_boosts] = parse_tag_boosts(options[:tag_boosts])
 
     if d = options[:from]
       if d.match(/^\d\d?-\d\d?$/)
@@ -85,17 +87,22 @@ class TimeSheet::Time::Cmd
     end
   end
 
-  def default_location
-    result = []
-    config_file = "#{ENV['HOME']}/.time-sheet.conf"
-    if File.exist?(config_file)
-      File.read(config_file).split("\n").each do |line|
-        if m = line.match(/^([a-z_]+):(.*)$/)
-          result << m[2].strip if m[1] == 'location'
-        end
-      end
+  def config
+    defaults = {
+      'location' => "#{ENV['HOME']}/time",
+      'carry_over_activity' => 'previous'
+    }
+
+    file = "#{ENV['HOME']}/.time-sheet.conf"
+    return defaults unless File.exist?(file)
+
+    result = YAML.load_file(file)
+    result = defaults.merge(result)
+
+    unless result['location'].is_a?(Array)
+      result['location'] = [result['location']]
     end
-    result << "#{ENV['HOME']}/time-sheet" if result.empty?
+
     result
   end
 
@@ -114,15 +121,23 @@ class TimeSheet::Time::Cmd
       o.boolean '-h', '--help', 'show help'
       o.boolean '--version', 'show the version'
       o.array('-l', '--location', 'a location to gather data from (file, directory or google docs share-url)',
-        default: default_location
+        default: config['location']
       )
       o.string '-f', '--from', 'ignore entries older than the date given'
       o.string '-t', '--to', 'ignore entries more recent than the date given'
       o.string '-p', '--project', 'take only entries of this project into account'
       o.string '-a', '--activity', 'take only entries of this activity into account'
       o.string '--tags', 'filter by tag (comma separated, not case sensitive, prefix tag with ! to exclude)'
+      o.string '-b', '--tag-boosts', 'multiply the time of entries by a factor per tag, e.g. ai:1.4,physical:0.75'
       o.string '-d', '--description', 'consider only entries matching this description'
+      o.string '--filter-descriptions', 'drop the parts of output descriptions matching this unanchored regex'
       o.string '-e', '--employee', 'consider only entries for this employee'
+      o.string(
+        '--carry-over-activity',
+        'mode for carrying over activity (previous|same-description)',
+        default: config['carry_over_activity']
+      )
+      o.string '--default-activity', 'default activity', default: config['default_activity']
       o.float '-r', '--rate', 'use an alternative hourly rate (default: 80.0)', default: 80.00
       o.boolean '-s', '--summary', 'when reporting, add summary section'
       o.boolean '--trim', 'compact the output for processing as CSV', default: false
@@ -138,6 +153,15 @@ class TimeSheet::Time::Cmd
     options.arguments.shift || 'default'
   end
 
+  def parse_tag_boosts(value)
+    return {} if value.nil? || value.to_s.strip.empty?
+
+    value.split(/\s*,\s*/).each_with_object({}) do |pair, result|
+      tag, factor = pair.split(/\s*:\s*/, 2)
+      result[tag.to_s.downcase] = factor.to_f
+    end
+  end
+
   def convert_to_time
     if options[:from]
       options[:from] = options[:from].to_time
@@ -148,6 +172,8 @@ class TimeSheet::Time::Cmd
   end
 
   def verify
+    TimeSheet.options = options
+
     convert_to_time
 
     entries = TimeSheet::Time::Parser.new(options[:location]).entries
@@ -170,7 +196,8 @@ class TimeSheet::Time::Cmd
   def invoice
     convert_to_time
 
-    data = TimeSheet::Time.invoice(options)
+    entries = TimeSheet::Time.matching_entries(options)
+    data = TimeSheet::Time.invoice_entries(entries, options)
 
     data.each do |package|
       tp = TimeSheet::TablePrinter.new package, options
@@ -178,7 +205,7 @@ class TimeSheet::Time::Cmd
       puts "\n"
     end
 
-    if options[:package]
+    if options[:package].to_f > 0
       package = (data.last.nil? ? 0 : data.last.map{|entry| entry[1]}.sum)
       total = options[:package] * 60
       percent = (package / total.to_f * 100)
@@ -189,6 +216,8 @@ class TimeSheet::Time::Cmd
         "#{percent.round 2}%)"
       ].join(' ')
     end
+
+    print_tags(TimeSheet::Time.tag_totals(entries), entries.sum(&:raw_duration))
   end
 
   def report
@@ -222,7 +251,7 @@ class TimeSheet::Time::Cmd
           TimeSheet::Time::Util.hours(pdata['total']),
           TimeSheet::Time::Util.price(pdata['total'], options[:rate])
         ]
-        
+
         pdata['activities'].sort_by{|k, v| v}.reverse.to_h.each do |aname, atotal|
           tdata << [
             '',
@@ -248,6 +277,18 @@ class TimeSheet::Time::Cmd
         "h/month(30 days): #{data['averages']['hours_per_month'].round(2)}"
       ].join(', ')
     end
+
+    print_tags(data['tags'], data['raw_total'])
+  end
+
+  def print_tags(tags, total)
+    tags ||= {}
+    return if tags.empty?
+
+    puts "\nTags:"
+    tags.sort_by{|tag, minutes| [-minutes, tag]}.each do |tag, minutes|
+      puts "#{tag}: #{TimeSheet::Time::Util.hours(minutes)} h (#{TimeSheet::Time::Util.share(minutes, total)}%)"
+    end
   end
 
-end
+end

data/lib/time_sheet/time/entry.rb

@@ -14,7 +14,20 @@ class TimeSheet::Time::Entry
   end
 
   def activity
-    @data['activity'] ||= self.prev.activity
+    if !@data['activity']
+      carry_mode = TimeSheet.options[:carry_over_activity]
+      use_prev = (
+        carry_mode == 'previous' ||
+        (carry_mode == 'same-description' && self.prev.description == description)
+      )
+      if use_prev
+        @data['activity'] = self.prev.activity
+      end
+
+      @data['activity'] ||= TimeSheet.options[:default_activity] || ''
+    end
+
+    @data['activity']
   end
 
   def description
@@ -96,11 +109,37 @@ class TimeSheet::Time::Entry
   # end
 
   def duration
+    raw_duration * factor
+  end
+
+  def raw_duration
     (self.end - self.start) / 60
   end
 
+  # Multiplier applied to this entry's time: the product of the boost factors of
+  # all its tags. Tags without a boost factor leave the time unchanged.
+  def factor
+    boosts = (TimeSheet.options && TimeSheet.options[:tag_boosts]) || {}
+    tags.inject(1.0){|f, tag| f * (boosts[tag] || 1.0)}
+  end
+
   def tags
-    self.class.parse_tags(@data['tags'])
+    self.class.parse_tags(tag_source)
+  end
+
+  # Tags carry over from the previous entry when project, activity and
+  # description are the same, so a group of rows describing one task only needs
+  # to be tagged on its first row. Any other row has no tags.
+  def tag_source
+    raw = @data['tags']
+    return raw if raw && !raw.to_s.strip.empty?
+
+    if self.prev &&
+       self.prev.project == project &&
+       self.prev.activity == activity &&
+       self.prev.description == description
+      self.prev.tag_source
+    end
   end
 
   def working_day?
@@ -152,7 +191,7 @@ class TimeSheet::Time::Entry
       raise TimeSheet::Time::Exception.new('time entry has no start')
     end
 
-    if duration <= 0
+    if raw_duration <= 0
       raise TimeSheet::Time::Exception.new('time entry duration is 0 or less')
     end
 
@@ -168,10 +207,28 @@ class TimeSheet::Time::Entry
   def to_row
     [
       employee, date, start, self.end, duration.to_i, project, activity,
-      description
+      self.class.filter_description(description, TimeSheet.options)
     ]
   end
 
+  # Drops the parts of a description matching the --filter-descriptions regex,
+  # repeating until no further match remains. The match is unanchored; rows are
+  # never excluded, only the rendered text is changed.
+  def self.filter_description(value, options)
+    pattern = options && options[:filter_descriptions]
+    return value if pattern.nil? || pattern.to_s.empty?
+
+    regexp = Regexp.new(pattern)
+    result = value.to_s
+    loop do
+      filtered = result.gsub(regexp, '')
+      break if filtered == result
+
+      result = filtered
+    end
+    result
+  end
+
   def to_s
     values = [
       employee,
@@ -215,4 +272,4 @@ class TimeSheet::Time::Entry
     (string || '').to_s.downcase.split(/\s*,\s*/).map{|t| t.strip}
   end
 
-end
+end

data/lib/time_sheet/time/util.rb

@@ -58,4 +58,10 @@ module TimeSheet::Time::Util
     (self.hours(duration) * rate).round(2)
   end
 
+  def self.share(part, whole)
+    return 0.0 if whole.nil? || whole.to_f.zero?
+
+    (part / whole.to_f * 100).round(1)
+  end
+
 end

data/lib/time_sheet/time.rb

@@ -11,36 +11,55 @@ module TimeSheet::Time
     results = {
       'entries' => [],
       'total' => 0.0,
-      'projects' => {}
+      'raw_total' => 0.0,
+      'projects' => {},
+      'tags' => {}
     }
 
-    x = nil
-    Parser.new(options[:location]).entries.each do |e|
-      unless x
-        x = true
-      end
-      if e.matches?(options)
-        results['total'] += e.duration
-        results['projects'][e.project] ||= {'total' => 0.0, 'activities' => {}}
-        results['projects'][e.project]['total'] += e.duration
-        results['projects'][e.project]['activities'][e.activity] ||= 0.0
-        results['projects'][e.project]['activities'][e.activity] += e.duration
-
-        results['entries'] << e.to_row
-      end
+    matching = matching_entries(options)
+    matching.each do |e|
+      results['total'] += e.duration
+      results['projects'][e.project] ||= {'total' => 0.0, 'activities' => {}}
+      results['projects'][e.project]['total'] += e.duration
+      results['projects'][e.project]['activities'][e.activity] ||= 0.0
+      results['projects'][e.project]['activities'][e.activity] += e.duration
+
+      results['entries'] << e.to_row
     end
 
+    results['tags'] = tag_totals(matching)
+    results['raw_total'] = matching.sum(&:raw_duration)
+
     averages(results, options)
 
     results
   end
 
+  # All entries matching the given filters. Sets TimeSheet.options first so that
+  # the carry-over rules apply while the entries are read.
+  def self.matching_entries(options)
+    TimeSheet.options = options
+    Parser.new(options[:location]).entries.select { |e| e.matches?(options) }
+  end
+
+  # Sums the unboosted duration of entries carrying a tag, so the tag breakdown
+  # reflects actual time regardless of any --tag-boosts factors. An entry with
+  # several tags contributes its full duration to each of them, so the per-tag
+  # totals do not necessarily add up to the overall total.
+  def self.tag_totals(entries)
+    totals = Hash.new(0.0)
+    entries.each do |e|
+      e.tags.each { |tag| totals[tag] += e.raw_duration }
+    end
+    totals
+  end
+
   def self.averages(results, options)
     days = 1
 
     unless results['entries'].empty?
       time = (
-        (options[:to] || Util.day_end) - 
+        (options[:to] || Util.day_end) -
         (options[:from] || results['entries'].first[1].to_time)
       ).to_i
       days = (time.to_f / 60 / 60 / 24).round
@@ -65,15 +84,17 @@ module TimeSheet::Time
   end
 
   def self.invoice(options)
+    invoice_entries(matching_entries(options), options)
+  end
+
+  def self.invoice_entries(entries, options)
     grouped = {}
-    Parser.new(options[:location]).entries.each do |e|
-      if e.matches?(options)
-        grouped[[e.date, e.description]] ||= 0
-        grouped[[e.date, e.description]] += e.duration.to_i
-      end
+    entries.each do |e|
+      grouped[[e.date, e.description]] ||= 0
+      grouped[[e.date, e.description]] += e.duration.to_i
     end
     rows = []
-    grouped.each{|k, d| rows << [k.first, d, k.last]}
+    grouped.each{|k, d| rows << [k.first, d, Entry.filter_description(k.last, options)]}
     packages = [[]]
     ptotal = 0
 
@@ -102,7 +123,7 @@ module TimeSheet::Time
           next
         end
       end
-      
+
       packages.last << row
       ptotal += row[1]
     end
@@ -131,4 +152,4 @@ module TimeSheet::Time
     packages
   end
 
-end
+end

data/lib/time_sheet/version.rb

@@ -1,3 +1,3 @@
 module TimeSheet
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: time-sheet
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Moritz Schepp
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-02-07 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: roo
@@ -141,7 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: a time tracking solution based on spreadsheets