timet 1.4.2 → 1.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c57d8e7c61f25526dda2e7a5d1208814cadbc93192b7c60c342399c83f0b545
-  data.tar.gz: 625f4ba71e547e2ebb483d93f1de3812a8b075cacc7afaff7c80554267e5bcc1
+  metadata.gz: 7754392fd614ebc62c53293166db637a9593f8497b4cc22ea3ea602bc51546f7
+  data.tar.gz: e4f699cf2725be5cf6849a5946323270d078ab1d6fa13892877f17ce161b1d1b
 SHA512:
-  metadata.gz: 99b2d1783c14024620865d826d11e16c42146ce220a50ae066cf762231129c42d683d88e4bb50086a5743cc923cdacd1d88f6fd4a4af4f5b5934017bfbb7b476
-  data.tar.gz: 7d3cb54c375f6fe2b86f0ffedb290d31c5d2348ec877a0848fc9c20d47c90422db6573a5ab0265ef4c0d8f6f89465dda7916f2f6dae59c2296511761b2f63705
+  metadata.gz: 2a8be74697ff40c179a0546662fc7b067d0ceddf4da159ea3107c87fef68b3f6cb7a7c3e61ff9c9115bcc799d5d5278fe209629a892077783aa56c77c772c81f
+  data.tar.gz: bd9131bccca060ea7d8a7710d9a96b6c784cfeca7312a9146f8fa5c31d8bd0e40b3a58e82ec670328baf5e92d0d2f8b3fa8e80a47a25a0f771c2cb1a6c5e667b

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/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.
@@ -94,16 +101,42 @@ module Timet
     # @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
+    #   time_report.export_csv
     #
     # @note The method writes the items to a CSV file and prints a confirmation message.
-    def export_sheet
-      file_name = "#{filename}.csv"
+    def export_csv
+      file_name = "#{csv_filename}.csv"
       write_csv(file_name)
 
       puts "The #{file_name} has been exported."
     end
 
+    def export_icalendar
+      file_name = "#{ics_filename}.ics"
+
+      cal = Icalendar::Calendar.new
+      items.each do |item|
+        dtstart = Time.at(item[1]).to_datetime
+        end_time = item[2] || TimeHelper.current_timestamp
+        dtend = Time.at(end_time).to_datetime
+
+        tag = item[3]
+        notes = item[4]
+        cal.event do |e|
+          e.dtstart     = dtstart
+          e.dtend       = dtend
+          e.summary     = tag
+          e.description = notes
+          e.ip_class    = 'PRIVATE'
+        end
+      end
+      cal.publish
+
+      File.write(file_name, cal.to_ical)
+
+      puts "The #{file_name} has been generated."
+    end
+
     private
 
     # Writes the items to a CSV file.

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.3'
+  VERSION = '1.4.3'
 end

metadata

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