timet 0.8.2 → 0.9.1

data/lib/timet/time_report.rb

@@ -12,8 +12,26 @@ module Timet
   class TimeReport
     include Formatter
 
-    attr_reader :db, :items, :filename
+    # Provides access to the database instance.
+    attr_reader :db
 
+    # Provides access to the filtered items.
+    attr_reader :items
+
+    # Provides access to the CSV filename.
+    attr_reader :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.
+    #
+    # @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)
       @db = db
       @filename = csv
@@ -21,6 +39,14 @@ module Timet
       @items = filter ? filter_items(@filter, tag) : @db.all_items
     end
 
+    # Displays the report of tracked time entries.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing the report.
+    #
+    # @example Display the report
+    #   time_report.display
+    #
+    # @note The method formats and prints the table header, rows, and total duration.
     def display
       return puts 'No tracked time found for the specified filter.' if items.empty?
 
@@ -33,6 +59,16 @@ module Timet
       total
     end
 
+    # Displays a single row of the report.
+    #
+    # @param item [Array] The item to display.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing the row.
+    #
+    # @example Display a single row
+    #   time_report.show_row(item)
+    #
+    # @note The method formats and prints the table header, row, and total duration.
     def show_row(item)
       format_table_header
       display_time_entry(item)
@@ -40,6 +76,14 @@ 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)
@@ -49,6 +93,16 @@ module Timet
 
     private
 
+    # Writes the items to a CSV file.
+    #
+    # @param file_name [String] The name of the CSV file to write.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as writing the CSV file.
+    #
+    # @example Write items to a CSV file
+    #   write_csv('report.csv')
+    #
+    # @note The method writes the items to the specified CSV file.
     def write_csv(file_name)
       CSV.open(file_name, 'w') do |csv|
         csv << %w[ID Start End Tag Notes]
@@ -58,6 +112,16 @@ module Timet
       end
     end
 
+    # Formats an item for CSV export.
+    #
+    # @param item [Array] The item to format.
+    #
+    # @return [Array] The formatted item.
+    #
+    # @example Format an item for CSV export
+    #   format_item(item)
+    #
+    # @note The method formats the item's ID, start time, end time, tag, and notes.
     def format_item(item)
       id, start_time, end_time, tags, notes = item
       [
@@ -69,6 +133,17 @@ module Timet
       ]
     end
 
+    # Displays a single time entry in the report.
+    #
+    # @param item [Array] The item to display.
+    # @param date [String, nil] The date to display. If nil, the date is not displayed.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing the row.
+    #
+    # @example Display a time entry
+    #   display_time_entry(item, '2021-10-01')
+    #
+    # @note The method formats and prints the row for the time entry.
     def display_time_entry(item, date = nil)
       return puts 'Missing time entry data.' unless item
 
@@ -80,6 +155,14 @@ module Timet
       puts format_table_row(id, tag_name[0..5], start_date, start_time, end_time, duration, notes)
     end
 
+    # Displays the total duration of the tracked time entries.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing the total duration.
+    #
+    # @example Display the total duration
+    #   total
+    #
+    # @note The method calculates and prints the total duration of the tracked time entries.
     def total
       total = @items.map do |item|
         TimeHelper.calculate_duration(item[1], item[2])
@@ -88,16 +171,38 @@ module Timet
       puts format_table_separator
     end
 
+    # Filters the items based on the specified filter and tag.
+    #
+    # @param filter [String] The filter to apply.
+    # @param tag [String, nil] The tag to filter the items by.
+    #
+    # @return [Array] The filtered items.
+    #
+    # @example Filter items by date range and tag
+    #   filter_items('2021-10-01..2021-10-31', 'work')
+    #
+    # @note The method filters the items based on the specified date range and tag.
     def filter_items(filter, tag)
       if date_ranges.key?(filter)
         start_date, end_date = date_ranges[filter]
         filter_by_date_range(start_date, end_date, tag)
+      elsif valid_date_format?(filter)
+        start_date, end_date = filter.split('..').map { |x| Date.parse(x) }
+        filter_by_date_range(start_date, end_date, tag)
       else
         puts 'Invalid filter. Supported filters: today, yesterday, week, month'
         []
       end
     end
 
+    # Provides predefined date ranges for filtering.
+    #
+    # @return [Hash] A hash containing predefined date ranges.
+    #
+    # @example Get the predefined date ranges
+    #   date_ranges
+    #
+    # @note The method returns a hash with predefined date ranges for 'today', 'yesterday', 'week', and 'month'.
     def date_ranges
       today = Date.today
       {
@@ -108,6 +213,18 @@ module Timet
       }
     end
 
+    # Filters the items by date range and tag.
+    #
+    # @param start_date [Date] The start date of the range.
+    # @param end_date [Date, nil] The end date of the range. If nil, the end date is the start date + 1 day.
+    # @param tag [String, nil] The tag to filter the items by.
+    #
+    # @return [Array] The filtered items.
+    #
+    # @example Filter items by date range and tag
+    #   filter_by_date_range(Date.new(2021, 10, 1), Date.new(2021, 10, 31), 'work')
+    #
+    # @note The method filters the items based on the specified date range and tag.
     def filter_by_date_range(start_date, end_date = nil, tag = nil)
       start_time = TimeHelper.date_to_timestamp(start_date)
       end_time = TimeHelper.calculate_end_time(start_date, end_date)
@@ -117,13 +234,48 @@ module Timet
       )
     end
 
+    # Formats the filter string.
+    #
+    # @param filter [String, nil] The filter string to format.
+    #
+    # @return [String] The formatted filter string.
+    #
+    # @example Format the filter string
+    #   formatted_filter('t') # => 'today'
+    #
+    # @note The method maps shorthand filters to their full names and validates date formats.
     def formatted_filter(filter)
-      return 'today' if %w[today t].include?(filter)
-      return 'yesterday' if %w[yesterday y].include?(filter)
-      return 'week' if %w[week w].include?(filter)
-      return 'month' if %w[month m].include?(filter)
+      filter_map = {
+        'today' => %w[today t],
+        'yesterday' => %w[yesterday y],
+        'week' => %w[week w],
+        'month' => %w[month m]
+      }
+
+      filter_map.each do |key, values|
+        return key if values.include?(filter)
+      end
+
+      return filter if filter && valid_date_format?(filter)
 
       'today'
     end
+
+    # Validates the date format.
+    #
+    # @param date_string [String] The date string to validate.
+    #
+    # @return [Boolean] True if the date format is valid, otherwise false.
+    #
+    # @example Validate the date format
+    #   valid_date_format?('2021-10-01') # => true
+    #
+    # @note The method validates the date format for single dates and date ranges.
+    def valid_date_format?(date_string)
+      date_format_single = /^\d{4}-\d{2}-\d{2}$/
+      date_format_range = /^\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}$/
+
+      date_string.match?(date_format_single) || date_string.match?(date_format_range)
+    end
   end
 end

data/lib/timet/validation_edit_helper.rb

@@ -6,8 +6,23 @@ module Timet
   # If the field is 'start' or 'end', it checks and updates the value accordingly.
   # Otherwise, it directly updates the field with the new value.
   module ValidationEditHelper
+    # Constants for time fields.
     TIME_FIELDS = %w[start end].freeze
 
+    # Validates and updates a tracking item's field with a new value.
+    #
+    # @param item [Array] The tracking item to be updated.
+    # @param field [String] The field to be updated.
+    # @param new_value [String, nil] The new value to be set for the specified field.
+    #
+    # @return [Array, nil] The updated tracking item if the update was successful, otherwise nil.
+    #
+    # @example Validate and update the 'notes' field of a tracking item
+    #   validate_and_update(item, 'notes', 'Updated notes')
+    #
+    # @note The method checks if the field is a time field (start or end) and processes it accordingly.
+    # @note If the field is not a time field, it directly updates the field with the new value.
+    # @note The method returns the updated tracking item if the update was successful.
     def validate_and_update(item, field, new_value)
       return if new_value.nil?
 
@@ -18,10 +33,24 @@ module Timet
       else
         @db.update_item(id, field, new_value)
       end
+
+      @db.find_item(id)
     end
 
     private
 
+    # Processes and updates a time field (start or end) of a tracking item.
+    #
+    # @param item [Array] The tracking item to be updated.
+    # @param field [String] The time field to be updated.
+    # @param date_value [String] The new value for the time field.
+    # @param id [Integer] The ID of the tracking item.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as updating the time field.
+    #
+    # @note The method formats the date value and checks if it is valid.
+    # @note If the date value is valid, it updates the time field with the new value.
+    # @note If the date value is invalid, it prints an error message.
     def process_and_update_time_field(item, field, date_value, id)
       formatted_date = TimeHelper.format_time_string(date_value)
 
@@ -37,10 +66,28 @@ module Timet
       end
     end
 
+    # Prints an error message for an invalid date.
+    #
+    # @param message [String] The error message to be printed.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing an error message.
+    #
+    # @example Print an error message for an invalid date
+    #   print_error('Invalid date: 2023-13-32')
     def print_error(message)
       puts "\u001b[31mInvalid date: #{message}\033[0m"
     end
 
+    # Updates a time field (start or end) of a tracking item with a formatted date value.
+    #
+    # @param item [Array] The tracking item to be updated.
+    # @param field [String] The time field to be updated.
+    # @param formatted_value [String] The formatted date value.
+    #
+    # @return [Time] The updated time value.
+    #
+    # @example Update the 'start' field of a tracking item with a formatted date value
+    #   update_time_field(item, 'start', '2023-10-01 12:00:00')
     def update_time_field(item, field, formatted_value)
       field_index = Timet::Application::FIELD_INDEX[field]
       timestamp = item[field_index]
@@ -49,6 +96,17 @@ module Timet
       DateTime.strptime(current_time.join(' '), '%Y-%m-%d %H:%M:%S %z').to_time
     end
 
+    # Validates if a new time value is valid for a specific time field (start or end).
+    #
+    # @param item [Array] The tracking item to be validated.
+    # @param field [String] The time field to be validated.
+    # @param new_value_epoch [Integer] The new time value in epoch format.
+    # @param id [Integer] The ID of the tracking item.
+    #
+    # @return [Boolean] Returns true if the new time value is valid, otherwise false.
+    #
+    # @example Validate a new 'start' time value
+    #   valid_time_value?(item, 'start', 1633072800, 1)
     def valid_time_value?(item, field, new_value_epoch, id)
       item_start = fetch_item_start(item)
       item_end = fetch_item_end(item)
@@ -62,18 +120,51 @@ module Timet
       end
     end
 
+    # Fetches the start time of a tracking item.
+    #
+    # @param item [Array] The tracking item.
+    #
+    # @return [Integer] The start time in epoch format.
+    #
+    # @example Fetch the start time of a tracking item
+    #   fetch_item_start(item)
     def fetch_item_start(item)
       item[Timet::Application::FIELD_INDEX['start']]
     end
 
+    # Fetches the end time of a tracking item.
+    #
+    # @param item [Array] The tracking item.
+    #
+    # @return [Integer] The end time in epoch format.
+    #
+    # @example Fetch the end time of a tracking item
+    #   fetch_item_end(item)
     def fetch_item_end(item)
       item[Timet::Application::FIELD_INDEX['end']] || TimeHelper.current_timestamp
     end
 
+    # Fetches the end time of the tracking item before the current one.
+    #
+    # @param id [Integer] The ID of the current tracking item.
+    # @param item_start [Integer] The start time of the current tracking item.
+    #
+    # @return [Integer] The end time of the previous tracking item in epoch format.
+    #
+    # @example Fetch the end time of the previous tracking item
+    #   fetch_item_before_end(1, 1633072800)
     def fetch_item_before_end(id, item_start)
       @db.find_item(id - 1)&.dig(Timet::Application::FIELD_INDEX['end']) || item_start
     end
 
+    # Fetches the start time of the tracking item after the current one.
+    #
+    # @param id [Integer] The ID of the current tracking item.
+    #
+    # @return [Integer] The start time of the next tracking item in epoch format.
+    #
+    # @example Fetch the start time of the next tracking item
+    #   fetch_item_after_start(1)
     def fetch_item_after_start(id)
       @db.find_item(id + 1)&.dig(Timet::Application::FIELD_INDEX['start']) || TimeHelper.current_timestamp
     end

data/lib/timet/version.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
 module Timet
-  VERSION = '0.8.2'
+  # The version of the Timet application.
+  #
+  # @return [String] The version number in the format 'major.minor.patch'.
+  #
+  # @example Get the version of the Timet application
+  #   Timet::VERSION # => '0.9.1'
+  VERSION = '0.9.1'
 end

data/lib/timet.rb

@@ -1,5 +1,16 @@
 # frozen_string_literal: true
 
+# Require the Timet::Application class from the 'timet/application' file.
+#
+# @note This statement loads the Timet::Application class, which is responsible for handling the command-line interface and user commands.
 require_relative 'timet/application'
+
+# Require the Timet::Database class from the 'timet/database' file.
+#
+# @note This statement loads the Timet::Database class, which provides database access for managing time tracking data.
 require_relative 'timet/database'
+
+# Require the Timet::TimeReport class from the 'timet/time_report' file.
+#
+# @note This statement loads the Timet::TimeReport class, which is responsible for displaying a report of tracked time entries.
 require_relative 'timet/time_report'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timet
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.9.1
 platform: ruby
 authors:
 - Frank Vielma
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-02 00:00:00.000000000 Z
+date: 2024-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -93,6 +93,7 @@ metadata:
   homepage_uri: https://frankvielma.github.io/posts/timet-a-powerful-command-line-tool-for-tracking-your-time/
   source_code_uri: https://github.com/frankvielma/timet
   changelog_uri: https://github.com/frankvielma/timet/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/timet
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []