timet 1.4.2 → 1.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c57d8e7c61f25526dda2e7a5d1208814cadbc93192b7c60c342399c83f0b545
-  data.tar.gz: 625f4ba71e547e2ebb483d93f1de3812a8b075cacc7afaff7c80554267e5bcc1
+  metadata.gz: c617b0cdad056a121039feaacfb0fe04df4e3e21cea8d9261e0414a01c2e9014
+  data.tar.gz: cac525344920d23e05ed0cab8798aa70e0153337328cac6bb170c6d96b9b509a
 SHA512:
-  metadata.gz: 99b2d1783c14024620865d826d11e16c42146ce220a50ae066cf762231129c42d683d88e4bb50086a5743cc923cdacd1d88f6fd4a4af4f5b5934017bfbb7b476
-  data.tar.gz: 7d3cb54c375f6fe2b86f0ffedb290d31c5d2348ec877a0848fc9c20d47c90422db6573a5ab0265ef4c0d8f6f89465dda7916f2f6dae59c2296511761b2f63705
+  metadata.gz: e48e71078a2cfb0e7f92a67b008f323b487366ad41392e0027a1d229e29680018dbcf1b13012322735f94302e5c0e03576d544dd7b1897fd3973cf49ee7cc1d1
+  data.tar.gz: 2a5a3fdabd064518b57aac6142c690dba881ce3d68ace78bd6770d5679fc11f24a71878a7422a80482aaaffb0e723bd8aa4c9a0ebf2de2fa5b8ee35a3082d98d

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 ## [Unreleased]
 
+## [1.4.4] - 2024-11-12
+
+**Improvements:**
+- Refactored tag distribution and time statistics methods:
+  - Split `process_and_print_tags` into `print_summary` and `print_tags_info` for better modularity and readability.
+  - Added Yardoc comments to document the new methods and updated existing comments for clarity.
+  - Introduced `totals` method in `TimeStatistics` to calculate and return total duration, average duration, and standard deviation.
+- Refactored export methods to `TimeReportHelper`:
+  - Moved `export_csv` and `export_icalendar` methods from `TimeReport` to `TimeReportHelper`.
+  - Created private methods `add_events`, `create_event`, and `convert_to_datetime` in `TimeReportHelper` to handle iCalendar event creation and conversion.
+  - Ensured that the iCalendar file generation logic is encapsulated within the `TimeReportHelper` module.
+
+**Tasks:**
+- Bumped version to 1.4.4.
+- Updated `Gemfile.lock`.
+
+## [1.4.3] - 2024-11-06
+
+**Improvements:**
+- **Refactor export logic**: Introduced a new `ReportExporter` class to handle the export of reports to CSV and iCalendar formats, addressing the Feature Envy code smell and making the `ApplicationHelper` module more modular.
+- **Update gem dependencies**: Updated several gems to their latest versions, including `icalendar`, `sqlite3`, `json`, `parser`, `rubocop`, and `rubocop-ast`.
+- **Refactor `TimeReport` initialization**: Refactored `TimeReport` initialization to use an options hash instead of individual parameters, and added support for exporting tracking summaries to iCalendar format.
+- **Enhance command descriptions**: Improved the descriptions of the `start`, `stop`, `resume`, `summary`, `edit`, `delete`, and `cancel` commands, and added an `--ics` option to the `summary` command for iCalendar export.
+- **Add `icalendar` gem**: Added the `icalendar` gem to support iCalendar functionality and updated the `timet` gem version to `1.4.3`.
+
+**Bug Fixes:**
+- Corrected platform names in the lockfile.
+- Updated the `TimeReport` spec to use the new options hash in the `TimeReport` initialization.
+
+
 ## [1.4.2] - 2024-11-01
 
 **Improvements:**

data/README.md

@@ -22,6 +22,7 @@
 - **Block Time Plot:** Visualizes the distribution of tracked time across a specified range of dates. Each column represents the amount of time tracked during a specific hour, with a header showing the hours and a row for each date displaying the time blocks for each hour.
 - **Tag Distribution Plot:** Illustrates the proportion of total tracked time allocated to each tag, showing the relative contribution of each tag to the overall time tracked.
 - **Detailed Statistics:** Displays detailed statistics for each tag, including total duration, average duration, and standard deviation.
+- **iCalendar Export:** Easily export your time tracking data to iCalendar format for integration with calendar applications.
 
 **Examples:**
 
@@ -181,7 +182,8 @@ gem install timet
 | `timet summary yesterday (y)`                | Display a report of tracked time for yesterday.                             | `timet su y`                      |
 | `timet summary week (w)`                     | Display a report of tracked time for the week.                              | `timet su w`                      |
 | `timet summary month (m)`                    | Display a report of tracked time for the month.                             | `timet su m`                      |
-| `timet su t --csv=[filename]`                | Display a report of tracked time for today and export it to `filename.csv`. | `timet su t --csv=file.csv`       |
+| `timet su t --csv=[filename]`                | Display a report of tracked time for today and export to CSV file | `timet su t --csv=file.csv`       |
+| `timet su w --ics=[filename]`                | Display a report of tracked time for week and export to iCalendar file | `timet su w --ics=file.csv`       |
 | `timet delete [id]`                          | Delete a task by its ID.                                                    | `timet d [id]`                    |
 | `timet cancel`                               | Cancel active time tracking.                                                | `timet c`                         |
 | `timet edit [id]`                            | Update a task's notes, tag, start, or end fields.                           | `timet e [id]`                    |

data/lib/timet/application.rb

@@ -36,8 +36,9 @@ module Timet
     VALID_STATUSES_FOR_INSERTION = %i[no_items complete].freeze
 
     desc "start [tag] --notes='' --pomodoro=[min]",
-         'Starts tracking time for a task labeled with the provided [tag],  notes and "pomodoro time" in minutes
-         (optional).'
+         'Start time tracking for a task labeled with the provided [tag], notes and "pomodoro time"
+        in minutes (optional).
+        tt start project1 "Starting project1" --pomodoro=25'
     option :notes, type: :string, desc: 'Add a note'
     option :pomodoro, type: :numeric, desc: 'Pomodoro time in minutes'
     # Starts a new tracking session with the given tag and optional notes.
@@ -76,7 +77,7 @@ module Timet
       summary
     end
 
-    desc 'stop', 'stop time tracking'
+    desc 'stop', 'Stop time tracking'
     # Stops the current tracking session if there is one in progress.
     #
     # @return [void] This method does not return a value; it performs side effects such as updating the tracking item
@@ -99,7 +100,7 @@ module Timet
       summary unless display
     end
 
-    desc 'resume (r) [id]', 'resume last task'
+    desc 'resume (r) [id]', 'Resume last task (id is an optional parameter) => tt resume'
     # Resumes the last tracking session if it was completed.
     #
     # @return [void] This method does not return a value; it performs side effects such as resuming a tracking session
@@ -131,48 +132,34 @@ module Timet
       end
     end
 
-    desc 'summary (su) [time_scope] [tag] --csv=csv_filename',
-         '[time_scope] => [today (t), yesterday (y), week (w), month (m), [start_date]..[end_date]]  [tag]'
-    option :csv, type: :string, desc: 'Export to CSV file'
+    desc 'summary (su) [time_scope] [tag] --csv=csv_filename --ics=ics_filename',
+         'Display a summary of tracked time and export to CSV.
+          [time_scope] => [today (t), yesterday (y), week (w), month (m). => tt su yesterday
+          [start_date]..[end_date]] => tt su 2024-10-03..2024-10-20
+          [tag] => tt su Task1
+          --csv=csv_filename => tt su month --csv=myfile
+          --ics=ics_filename => tt su week --csv=mycalendar'
+    option :csv, type: :string, desc: 'Export to CSV'
+    option :ics, type: :string, desc: 'Export to iCalendar'
     # Generates a summary of tracking items based on the provided time_scope and tag, and optionally exports the summary
-    # to a CSV file.
+    # to a CSV file and/or an iCalendar file.
     #
-    # @param time_scope [String, nil] The time_scope to apply when generating the summary. Possible values include
-    # 'today', 'yesterday', 'week', 'month', or a date range in the format '[start_date]..[end_date]'.
-    # @param tag [String, nil] The tag to time_scope the tracking items by.
+    # @param time_scope [String, nil] The filter to apply when fetching items. Possible values include 'today',
+    #   'yesterday', 'week', 'month', or a date range in the format 'YYYY-MM-DD..YYYY-MM-DD'.
+    # @param tag [String, nil] The tag to filter the items by.
     #
-    # @return [void] This method does not return a value; it performs side effects such as displaying the summary and
-    # exporting to CSV if specified.
-    #
-    # @example Generate a summary for today
-    #   summary('today')
-    #
-    # @example Generate a summary for a specific tag
-    #   summary(nil, 'work')
-    #
-    # @example Generate a summary for a date range and export to CSV
-    #   summary('2023-01-01..2023-01-31', nil, csv: 'summary.csv')
-    #
-    # @note The method initializes a `TimeReport` object with the database, time_scope, tag, and optional CSV filename.
-    # @note The method calls `display` on the `TimeReport` object to show the summary.
-    # @note If a CSV filename is provided and there are items to export, the method calls `export_sheet` to export the
-    # summary to a CSV file.
-    # @note If no items are found to export, it prints a message indicating that no items were found.
+    # @return [void] This method does not return a value; it performs side effects such as displaying
+    # and exporting the report.
     def summary(time_scope = nil, tag = nil)
-      csv_filename = options[:csv]&.split('.')&.first
-      report = TimeReport.new(@db, time_scope, tag, csv_filename)
-
-      report.display
-      items = report.items
-      if csv_filename && items.any?
-        report.export_sheet
-      elsif items.empty?
-        puts 'No items found to export'
-      end
+      options = build_options(time_scope, tag)
+      report = TimeReport.new(@db, options)
+      display_and_export_report(report, options)
     end
 
     desc 'edit (e) [id] [field] [value]',
-         'edit a task, [field] (notes, tag, start or end) and [value] are optional parameters'
+         'Edit task, [field] (notes, tag, start or end) and [value] are optional parameters.
+          Update notes => tt edit 12 notes "Update note"
+          Update start time => tt edit 12 start 12:33'
     # Edits a specific tracking item by its ID, allowing the user to modify fields such as notes, tag, start time, or
     # end time.
     #
@@ -211,7 +198,7 @@ module Timet
       display_item(updated_item || item)
     end
 
-    desc 'delete (d) [id]', 'delete a task'
+    desc 'delete (d) [id]', 'Delete task => tt d 23'
     # Deletes a specific tracking item by its ID after confirming with the user.
     #
     # @param id [Integer] The ID of the tracking item to be deleted.
@@ -238,7 +225,7 @@ module Timet
       delete_item_and_print_message(id, "Deleted #{id}")
     end
 
-    desc 'cancel (c)', 'cancel active time tracking'
+    desc 'cancel (c)', 'Cancel active time tracking => tt c'
     # Cancels the active time tracking session by deleting the last tracking item.
     #
     # @return [void] This method does not return a value; it performs side effects such as deleting the active tracking

data/lib/timet/application_helper.rb

@@ -184,5 +184,81 @@ module Timet
       tag, notes = item.values_at(Application::FIELD_INDEX['tag'], Application::FIELD_INDEX['notes'])
       start(tag, notes)
     end
+
+    # Builds a hash of options to be used when initializing a TimeReport instance.
+    #
+    # @param time_scope [String, nil] The filter to apply when fetching items. Possible values include 'today',
+    #   'yesterday', 'week', 'month', or a date range in the format 'YYYY-MM-DD..YYYY-MM-DD'.
+    # @param tag [String, nil] The tag to filter the items by.
+    #
+    # @return [Hash] A hash containing the filter, tag, CSV filename, and iCalendar filename.
+    #
+    # @example Build options with a filter and tag
+    #   build_options('today', 'work') # => { filter: 'today', tag: 'work', csv: nil, ics: nil }
+    def build_options(time_scope, tag)
+      csv_filename = options[:csv]&.split('.')&.first
+      ics_filename = options[:ics]&.split('.')&.first
+      {
+        filter: time_scope,
+        tag: tag,
+        csv: csv_filename,
+        ics: ics_filename
+      }
+    end
+
+    # @note This class is responsible for exporting reports to CSV and iCalendar formats.
+    class ReportExporter
+      # Exports the report to a CSV file if the `csv` option is provided.
+      #
+      # @param report [TimeReport] The report object to export.
+      # @param options [Hash] The options hash containing export settings.
+      # @option options [String] :csv The filename to use when exporting the report to CSV.
+      # @return [void]
+      def self.export_csv_report(report, options)
+        report.export_csv if options[:csv]
+      end
+
+      # Exports the report to an iCalendar file if the `ics` option is provided.
+      #
+      # @param report [TimeReport] The report object to export.
+      # @param options [Hash] The options hash containing export settings.
+      # @option options [String] :ics The filename to use when exporting the report to iCalendar.
+      # @return [void]
+      def self.export_icalendar_report(report, options)
+        report.export_icalendar if options[:ics]
+      end
+    end
+
+    # Displays the report and exports it to a CSV file and/or an iCalendar file if specified.
+    #
+    # @param report [TimeReport] The TimeReport instance to display and export.
+    # @param options [Hash] A hash containing the options for exporting the report.
+    # @option options [String, nil] :csv The filename to use when exporting the report to CSV.
+    # @option options [String, nil] :ics The filename to use when exporting the report to iCalendar.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as displaying
+    # and exporting the report.
+    #
+    # @example Display and export the report to CSV and iCalendar
+    #   display_and_export_report(report, { csv: 'report.csv', ics: 'icalendar.ics' })
+    def display_and_export_report(report, options)
+      report.display
+      export_report(report, options)
+    end
+
+    # Exports the given report in CSV and iCalendar formats if there are items, otherwise prints a message.
+    #
+    # @param report [Report] The report to be exported.
+    # @param options [Hash] The options to pass to the exporter.
+    # @return [void]
+    def export_report(report, options)
+      items = report.items
+      if items.any?
+        ReportExporter.export_csv_report(report, options)
+        ReportExporter.export_icalendar_report(report, options)
+      else
+        puts 'No items found to export'
+      end
+    end
   end
 end

data/lib/timet/tag_distribution.rb

@@ -34,31 +34,43 @@ module Timet
 
     # Processes and prints the tag distribution information.
     #
-    # @param sorted_duration_by_tag [Array<Array(String, Numeric)>] An array of arrays where each inner array contains a
-    # tag and its corresponding duration, sorted by duration in descending order.
+    # @param time_stats [Object] An object containing the time statistics, including totals and sorted durations by tag.
     # @param total [Numeric] The total duration of all tags combined.
+    # @param colors [Object] An object containing color formatting methods.
     # @return [void] This method outputs the tag distribution information to the standard output.
     def process_and_print_tags(time_stats, total, colors)
-      time_stats.sorted_duration_by_tag.each do |tag, duration|
-        print_tag_info(tag, duration, total, time_stats, colors)
-      end
+      print_summary(time_stats, total)
+      print_tags_info(time_stats, total, colors)
     end
 
-    # Prints the detailed information for a specific tag.
+    # Prints the summary information including total duration, average duration, and standard deviation.
     #
-    # @param tag [String] The tag for which to print the information.
-    # @param duration [Numeric] The duration associated with the tag.
+    # @param time_stats [Object] An object containing the time statistics, including totals.
     # @param total [Numeric] The total duration of all tags combined.
-    # @param time_stats [Object] An object containing time statistics for the tags.
-    # @param colors [Hash] A hash mapping tags to color indices for display.
-    # @return [void] This method outputs the tag information to the standard output.
-    def print_tag_info(tag, duration, total, time_stats, colors)
-      value, bar_length = calculate_value_and_bar_length(duration, total)
-      horizontal_bar = generate_horizontal_bar(bar_length, colors[tag])
-      formatted_tag = tag[0...TAG_SIZE].rjust(TAG_SIZE)
-      stats = generate_stats(tag, time_stats)
+    # @return [void] This method outputs the summary information to the standard output.
+    def print_summary(time_stats, total)
+      avg = (time_stats.totals[:avg] / 60.0).round(1)
+      sd = (time_stats.totals[:sd] / 60.0).round(1)
+      summary = "#{' ' * TAG_SIZE} #{'Summary'.underline}: "
+      summary += "[T: #{(total / 3600.0).round(1)}h, AVG: #{avg}min SD: #{sd}min]".white
+      puts summary
+    end
 
-      puts "#{formatted_tag}: #{value.to_s.rjust(5)}%  #{horizontal_bar} [#{stats}]"
+    # Prints the detailed information for each tag.
+    #
+    # @param time_stats [Object] An object containing the time statistics, including sorted durations by tag.
+    # @param total [Numeric] The total duration of all tags combined.
+    # @param colors [Object] An object containing color formatting methods.
+    # @return [void] This method outputs the detailed tag information to the standard output.
+    def print_tags_info(time_stats, total, colors)
+      time_stats.sorted_duration_by_tag.each do |tag, duration|
+        value, bar_length = calculate_value_and_bar_length(duration, total)
+        horizontal_bar = generate_horizontal_bar(bar_length, colors[tag])
+        formatted_tag = tag[0...TAG_SIZE].rjust(TAG_SIZE)
+        stats = generate_stats(tag, time_stats)
+
+        puts "#{formatted_tag}: #{value.to_s.rjust(5)}%  #{horizontal_bar} [#{stats}]"
+      end
     end
 
     # Generates a horizontal bar for display based on the bar length and color index.

data/lib/timet/time_report.rb

@@ -2,6 +2,7 @@
 
 require 'date'
 require 'csv'
+require 'icalendar'
 require_relative 'time_report_helper'
 require_relative 'table'
 require_relative 'time_block_chart'
@@ -24,26 +25,32 @@ module Timet
     attr_reader :items
 
     # Provides access to the CSV filename.
-    attr_reader :filename
+    attr_reader :csv_filename
+
+    # Provides access to the ICS filename.
+    attr_reader :ics_filename
 
     # Initializes a new instance of the TimeReport class.
     #
     # @param db [Database] The database instance to use for fetching data.
-    # @param filter [String, nil] The filter to apply when fetching items. Possible values include 'today',
-    # 'yesterday', 'week', 'month', or a date range in the format 'YYYY-MM-DD..YYYY-MM-DD'.
-    # @param tag [String, nil] The tag to filter the items by.
-    # @param csv [String, nil] The filename to use when exporting the report to CSV.
+    # @param options [Hash] A hash containing optional parameters.
+    # @option options [String, nil] :filter The filter to apply when fetching items. Possible values include 'today',
+    #   'yesterday', 'week', 'month', or a date range in the format 'YYYY-MM-DD..YYYY-MM-DD'.
+    # @option options [String, nil] :tag The tag to filter the items by.
+    # @option options [String, nil] :csv The filename to use when exporting the report to CSV.
+    # @option options [String, nil] :ics The filename to use when exporting the report to iCalendar.
     #
     # @return [void] This method does not return a value; it performs side effects such as initializing the
     # instance variables.
     #
     # @example Initialize a new TimeReport instance with a filter and tag
-    #   TimeReport.new(db, 'today', 'work', 'report.csv')
-    def initialize(db, filter = nil, tag = nil, csv = nil)
+    #   TimeReport.new(db, filter: 'today', tag: 'work', csv: 'report.csv', ics: 'icalendar.ics')
+    def initialize(db, options = {})
       @db = db
-      @filename = csv
-      @filter = formatted_filter(filter)
-      @items = filter ? filter_items(@filter, tag) : @db.all_items
+      @csv_filename = options[:csv]
+      @ics_filename = options[:ics]
+      @filter = formatted_filter(options[:filter])
+      @items = options[:filter] ? filter_items(@filter, options[:tag]) : @db.all_items
     end
 
     # Displays the report of tracked time entries.
@@ -89,21 +96,6 @@ module Timet
       total
     end
 
-    # Exports the report to a CSV file.
-    #
-    # @return [void] This method does not return a value; it performs side effects such as writing the CSV file.
-    #
-    # @example Export the report to a CSV file
-    #   time_report.export_sheet
-    #
-    # @note The method writes the items to a CSV file and prints a confirmation message.
-    def export_sheet
-      file_name = "#{filename}.csv"
-      write_csv(file_name)
-
-      puts "The #{file_name} has been exported."
-    end
-
     private
 
     # Writes the items to a CSV file.

data/lib/timet/time_report_helper.rb

@@ -80,5 +80,72 @@ module Timet
         [summed_number, old_value[1]]
       end
     end
+
+    # Exports the report to a CSV file.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as writing the CSV file.
+    #
+    # @example Export the report to a CSV file
+    #   time_report.export_csv
+    #
+    # @note The method writes the items to a CSV file and prints a confirmation message.
+    def export_csv
+      file_name = "#{csv_filename}.csv"
+      write_csv(file_name)
+
+      puts "The #{file_name} has been exported."
+    end
+
+    # Generates an iCalendar file and writes it to disk.
+    #
+    # @return [void]
+    def export_icalendar
+      file_name = "#{ics_filename}.ics"
+      cal = add_events
+
+      File.write(file_name, cal.to_ical)
+
+      puts "The #{file_name} has been generated."
+    end
+
+    private
+
+    # Creates an iCalendar object and adds events to it.
+    #
+    # @return [Icalendar::Calendar] the populated iCalendar object
+    def add_events
+      cal = Icalendar::Calendar.new
+      items.each do |item|
+        event = create_event(item)
+        cal.add_event(event)
+      end
+      cal.publish
+      cal
+    end
+
+    # Creates an iCalendar event from the given item.
+    #
+    # @param item [Array] the item containing event details
+    # @return [Icalendar::Event] the created event
+    def create_event(item)
+      dtstart = convert_to_datetime(item[1])
+      dtend = convert_to_datetime(item[2] || TimeHelper.current_timestamp)
+
+      Icalendar::Event.new.tap do |e|
+        e.dtstart     = dtstart
+        e.dtend       = dtend
+        e.summary     = item[3]
+        e.description = item[4]
+        e.ip_class    = 'PRIVATE'
+      end
+    end
+
+    # Converts a timestamp to a DateTime object.
+    #
+    # @param timestamp [Integer] the timestamp to convert
+    # @return [DateTime] the converted DateTime object
+    def convert_to_datetime(timestamp)
+      Time.at(timestamp).to_datetime
+    end
   end
 end

data/lib/timet/time_statistics.rb

@@ -27,6 +27,19 @@ module Timet
       calculate_durations_by_tag
     end
 
+    # Returns a hash containing the total duration, average duration, and standard deviation of durations.
+    #
+    # @return [Hash] A hash with the following keys:
+    #   - :total [Numeric] The total duration.
+    #   - :avg [Numeric] The average duration.
+    #   - :sd [Numeric] The standard deviation of the durations.
+    def totals
+      @duration_by_tag.values.flatten
+
+      durations = @duration_by_tag.values.flatten
+      { total: @total_duration, avg: durations.mean, sd: durations.standard_deviation }
+    end
+
     # Calculates the duration for each tag and updates the @duration_by_tag and @total_duration attributes.
     #
     # @return [void]

data/lib/timet/version.rb

@@ -6,6 +6,6 @@ module Timet
   # @return [String] The version number in the format 'major.minor.patch'.
   #
   # @example Get the version of the Timet application
-  #   Timet::VERSION # => '1.4.2'
-  VERSION = '1.4.2'
+  #   Timet::VERSION # => '1.4.4'
+  VERSION = '1.4.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timet
 version: !ruby/object:Gem::Version
-  version: 1.4.2
+  version: 1.4.4
 platform: ruby
 authors:
 - Frank Vielma
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-01 00:00:00.000000000 Z
+date: 2024-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor