timet 0.8.2 → 0.9.1

data/lib/timet/database.rb

@@ -1,19 +1,42 @@
 # frozen_string_literal: true
 
 require 'sqlite3'
-
+require_relative 'status_helper'
 module Timet
   # Provides database access for managing time tracking data.
   class Database
+    include StatusHelper
+
+    # The default path to the SQLite database file.
     DEFAULT_DATABASE_PATH = File.join(Dir.home, '.timet.db')
 
+    # Initializes a new instance of the Database class.
+    #
+    # @param database_path [String] The path to the SQLite database file. Defaults to DEFAULT_DATABASE_PATH.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as initializing the database connection and creating the necessary tables.
+    #
+    # @example Initialize a new Database instance with the default path
+    #   Database.new
+    #
+    # @example Initialize a new Database instance with a custom path
+    #   Database.new('/path/to/custom.db')
+    #
+    # @note The method creates a new SQLite3 database connection and initializes the necessary tables if they do not already exist.
     def initialize(database_path = DEFAULT_DATABASE_PATH)
       @db = SQLite3::Database.new(database_path)
       create_table
       add_notes
     end
 
-    # Creates the items table if it doesn't already exist
+    # Creates the items table if it doesn't already exist.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL to create the table.
+    #
+    # @example Create the items table
+    #   create_table
+    #
+    # @note The method executes SQL to create the 'items' table with columns for id, start, end, and tag.
     def create_table
       execute_sql(<<-SQL)
         CREATE TABLE IF NOT EXISTS items (
@@ -26,6 +49,13 @@ module Timet
     end
 
     # Adds a new column named "notes" to the "items" table if it doesn't exist.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL to add the column.
+    #
+    # @example Add the notes column to the items table
+    #   add_notes
+    #
+    # @note The method checks if the 'notes' column already exists and adds it if it does not.
     def add_notes
       table_name = 'items'
       new_column_name = 'notes'
@@ -37,65 +67,129 @@ module Timet
       puts "Column '#{new_column_name}' added to table '#{table_name}'."
     end
 
-    # Inserts a new item into the items table
+    # Inserts a new item into the items table.
+    #
+    # @param start [Integer] The start time of the item.
+    # @param tag [String] The tag associated with the item.
+    # @param notes [String] The notes associated with the item.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL to insert the item.
+    #
+    # @example Insert a new item into the items table
+    #   insert_item(1633072800, 'work', 'Completed task X')
+    #
+    # @note The method executes SQL to insert a new row into the 'items' table.
     def insert_item(start, tag, notes)
       execute_sql('INSERT INTO items (start, tag, notes) VALUES (?, ?, ?)', [start, tag, notes])
     end
 
-    # Updates the end time of the last item
-    def update(stop)
-      last_id = fetch_last_id
-      return unless last_id
+    # Updates an existing item in the items table.
+    #
+    # @param id [Integer] The ID of the item to be updated.
+    # @param field [String] The field to be updated.
+    # @param value [String, Integer, nil] The new value for the specified field.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL to update the item.
+    #
+    # @example Update the tag of an item with ID 1
+    #   update_item(1, 'tag', 'updated_work')
+    #
+    # @note The method executes SQL to update the specified field of the item with the given ID.
+    def update_item(id, field, value)
+      return if %w[start end].include?(field) && value.nil?
 
-      execute_sql('UPDATE items SET end = ? WHERE id = ?', [stop, last_id])
+      execute_sql("UPDATE items SET #{field}='#{value}' WHERE id = #{id}")
     end
 
+    # Deletes an item from the items table.
+    #
+    # @param id [Integer] The ID of the item to be deleted.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL to delete the item.
+    #
+    # @example Delete an item with ID 1
+    #   delete_item(1)
+    #
+    # @note The method executes SQL to delete the item with the given ID from the 'items' table.
     def delete_item(id)
       execute_sql("DELETE FROM items WHERE id = #{id}")
     end
 
-    def update_item(id, field, value)
-      return if %w[start end].include?(field) && value.nil?
-
-      execute_sql("UPDATE items SET #{field}='#{value}' WHERE id = #{id}")
-    end
-
-    # Fetches the ID of the last inserted item
+    # Fetches the ID of the last inserted item.
+    #
+    # @return [Integer, nil] The ID of the last inserted item, or nil if no items exist.
+    #
+    # @example Fetch the last inserted item ID
+    #   fetch_last_id
+    #
+    # @note The method executes SQL to fetch the ID of the last inserted item.
     def fetch_last_id
       result = execute_sql('SELECT id FROM items ORDER BY id DESC LIMIT 1').first
       result ? result[0] : nil
     end
 
+    # Fetches the last item from the items table.
+    #
+    # @return [Array, nil] The last item as an array, or nil if no items exist.
+    #
+    # @example Fetch the last item
+    #   last_item
+    #
+    # @note The method executes SQL to fetch the last item from the 'items' table.
     def last_item
       execute_sql('SELECT * FROM items ORDER BY id DESC LIMIT 1').first
     end
 
+    # Determines the status of the last item in the items table.
+    #
+    # @return [Symbol] The status of the last item. Possible values are :no_items, :in_progress, or :complete.
+    #
+    # @example Determine the status of the last item
+    #   last_item_status
+    #
+    # @note The method executes SQL to fetch the last item and determines its status using the `StatusHelper` module.
     def last_item_status
       result = execute_sql('SELECT id, end FROM items ORDER BY id DESC LIMIT 1')
       StatusHelper.determine_status(result)
     end
 
+    # Finds an item in the items table by its ID.
+    #
+    # @param id [Integer] The ID of the item to be found.
+    #
+    # @return [Array, nil] The item as an array, or nil if the item does not exist.
+    #
+    # @example Find an item with ID 1
+    #   find_item(1)
+    #
+    # @note The method executes SQL to find the item with the given ID in the 'items' table.
     def find_item(id)
       execute_sql("select * from items where id=#{id}").first
     end
 
-    # Calculates the total time elapsed since the last recorded time.
-    def total_time
-      last_item = execute_sql('SELECT * FROM items ORDER BY id DESC LIMIT 1').first
-      return '00:00:00' unless last_item
-
-      start_time = last_item[1]
-      end_time = last_item[2]
-
-      total_seconds = end_time ? end_time - start_time : TimeHelper.current_timestamp - start_time
-      seconds_to_hms(total_seconds)
-    end
-
+    # Fetches all items from the items table that have a start time greater than or equal to today.
+    #
+    # @return [Array] An array of items.
+    #
+    # @example Fetch all items from today
+    #   all_items
+    #
+    # @note The method executes SQL to fetch all items from the 'items' table that have a start time greater than or equal to today.
     def all_items
       execute_sql("SELECT * FROM items where start >= '#{Date.today.to_time.to_i}' ORDER BY id DESC")
     end
 
-    # Executes a SQL query and returns the result
+    # Executes a SQL query and returns the result.
+    #
+    # @param sql [String] The SQL query to execute.
+    # @param params [Array] The parameters to bind to the SQL query.
+    #
+    # @return [Array] The result of the SQL query.
+    #
+    # @example Execute a SQL query
+    #   execute_sql('SELECT * FROM items WHERE id = ?', [1])
+    #
+    # @note The method executes the given SQL query with the provided parameters and returns the result.
     def execute_sql(sql, params = [])
       @db.execute(sql, params)
     rescue SQLite3::SQLException => e
@@ -103,12 +197,28 @@ module Timet
       []
     end
 
-    # Closes the database connection
+    # Closes the database connection.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as closing the database connection.
+    #
+    # @example Close the database connection
+    #   close
+    #
+    # @note The method closes the SQLite3 database connection.
     def close
       @db&.close
     end
 
     # Converts a given number of seconds into a human-readable HH:MM:SS format.
+    #
+    # @param seconds [Integer] The number of seconds to convert.
+    #
+    # @return [String] The formatted time in HH:MM:SS format.
+    #
+    # @example Convert 3661 seconds to HH:MM:SS format
+    #   seconds_to_hms(3661) # => '01:01:01'
+    #
+    # @note The method converts the given number of seconds into hours, minutes, and seconds, and formats them as HH:MM:SS.
     def seconds_to_hms(seconds)
       hours, remainder = seconds.divmod(3600)
       minutes, seconds = remainder.divmod(60)

data/lib/timet/formatter.rb

@@ -4,6 +4,14 @@ module Timet
   # This module is responsible for formatting the output of the `timet` application.
   # It provides methods for formatting the table header, separators, and rows.
   module Formatter
+    # Formats the header of the time tracking report table.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing the formatted header.
+    #
+    # @example Format and print the table header
+    #   format_table_header
+    #
+    # @note The method constructs a string representing the table header and prints it.
     def format_table_header
       header = <<~TABLE
         Tracked time report \u001b[31m[#{@filter}]\033[0m:
@@ -14,16 +22,42 @@ module Timet
       puts header
     end
 
+    # Formats the separator line for the time tracking report table.
+    #
+    # @return [String] The formatted separator line.
+    #
+    # @example Get the formatted table separator
+    #   format_table_separator # => '+-------+------------+--------+----------+----------+----------+--------------------------+'
+    #
+    # @note The method returns a string representing the separator line for the table.
     def format_table_separator
       '+-------+------------+--------+----------+----------+----------+--------------------------+'
     end
 
+    # Formats a row of the time tracking report table.
+    #
+    # @param row [Array] The row data to be formatted.
+    # @return [String] The formatted row.
+    #
+    # @example Format a table row
+    #   format_table_row(1, 'work', '2023-10-01', '12:00:00', '14:00:00', 7200, 'Completed task X')
+    #
+    # @note The method formats each element of the row and constructs a string representing the formatted row.
     def format_table_row(*row)
       id, tag, start_date, start_time, end_time, duration, notes = row
       "| #{id.to_s.rjust(5)} | #{start_date} | #{tag.ljust(6)} | #{start_time.split[1]} | " \
         "#{end_time.split[1].rjust(8)} | #{@db.seconds_to_hms(duration).rjust(8)} | #{format_notes(notes)}  |"
     end
 
+    # Formats the notes column of the time tracking report table.
+    #
+    # @param notes [String, nil] The notes to be formatted.
+    # @return [String] The formatted notes.
+    #
+    # @example Format notes
+    #   format_notes('This is a long note that needs to be truncated')
+    #
+    # @note The method truncates the notes to a maximum of 20 characters and pads them to a fixed width.
     def format_notes(notes)
       return ' ' * 23 if notes.nil?
 

data/lib/timet/status_helper.rb

@@ -1,8 +1,26 @@
 # frozen_string_literal: true
 
 module Timet
-  # Determines the status of a time tracking result based on the presence and end time of items.
+  # Provides helper methods to determine the status of time tracking results.
   module StatusHelper
+    # Determines the status of a time tracking result based on the presence and end time of items.
+    #
+    # @param result [Array] The result set containing time tracking items.
+    #
+    # @return [Symbol] The status of the time tracking result. Possible values are :no_items, :in_progress, or :complete.
+    #
+    # @example Determine the status of an empty result set
+    #   StatusHelper.determine_status([]) # => :no_items
+    #
+    # @example Determine the status of a result set with an in-progress item
+    #   StatusHelper.determine_status([[1, nil]]) # => :in_progress
+    #
+    # @example Determine the status of a result set with a completed item
+    #   StatusHelper.determine_status([[1, 1633072800]]) # => :complete
+    #
+    # @note The method checks if the result set is empty and returns :no_items if true.
+    # @note If the last item in the result set has no end time, it returns :in_progress.
+    # @note If the last item in the result set has an end time, it returns :complete.
     def self.determine_status(result)
       return :no_items if result.empty?
 

data/lib/timet/time_helper.rb

@@ -7,38 +7,91 @@ module Timet
   # - calculating the duration between two timestamps
   # - converting a Date object to a timestamp
   module TimeHelper
+    # Formats a timestamp into a specific format.
+    #
+    # @param timestamp [Integer] The timestamp to format.
+    # @return [String, nil] The formatted time string in 'YYYY-MM-DD HH:MM:SS' format, or nil if the timestamp is nil.
+    #
+    # @example Format a timestamp
+    #   TimeHelper.format_time(1633072800) # => '2021-10-01 12:00:00'
     def self.format_time(timestamp)
       return nil if timestamp.nil?
 
       Time.at(timestamp).strftime('%Y-%m-%d %H:%M:%S')
     end
 
+    # Converts a timestamp to a date string.
+    #
+    # @param timestamp [Integer] The timestamp to convert.
+    # @return [String, nil] The date string in 'YYYY-MM-DD' format, or nil if the timestamp is nil.
+    #
+    # @example Convert a timestamp to a date string
+    #   TimeHelper.timestamp_to_date(1633072800) # => '2021-10-01'
     def self.timestamp_to_date(timestamp)
       return nil if timestamp.nil?
 
       Time.at(timestamp).strftime('%Y-%m-%d')
     end
 
+    # Converts a timestamp to a time string.
+    #
+    # @param timestamp [Integer] The timestamp to convert.
+    # @return [String, nil] The time string in 'HH:MM:SS' format, or nil if the timestamp is nil.
+    #
+    # @example Convert a timestamp to a time string
+    #   TimeHelper.timestamp_to_time(1633072800) # => '12:00:00'
     def self.timestamp_to_time(timestamp)
       return nil if timestamp.nil?
 
       Time.at(timestamp).strftime('%H:%M:%S')
     end
 
+    # Calculates the duration between two timestamps.
+    #
+    # @param start_time [Integer] The start timestamp.
+    # @param end_time [Integer, nil] The end timestamp. If nil, the current timestamp is used.
+    # @return [Integer] The duration in seconds.
+    #
+    # @example Calculate the duration between two timestamps
+    #   TimeHelper.calculate_duration(1633072800, 1633076400) # => 3600
     def self.calculate_duration(start_time, end_time)
       end_time = end_time ? Time.at(end_time) : current_timestamp
       (end_time - start_time).to_i
     end
 
+    # Converts a Date object to a timestamp.
+    #
+    # @param date [Date] The Date object to convert.
+    # @return [Integer] The timestamp.
+    #
+    # @example Convert a Date object to a timestamp
+    #   TimeHelper.date_to_timestamp(Date.new(2021, 10, 1)) # => 1633072800
     def self.date_to_timestamp(date)
       date.to_time.to_i
     end
 
+    # Calculates the end time based on the start date and end date.
+    #
+    # @param start_date [Date] The start date.
+    # @param end_date [Date, nil] The end date. If nil, the start date + 1 day is used.
+    # @return [Integer] The end timestamp.
+    #
+    # @example Calculate the end time
+    #   TimeHelper.calculate_end_time(Date.new(2021, 10, 1), Date.new(2021, 10, 2)) # => 1633159200
     def self.calculate_end_time(start_date, end_date)
-      end_date ||= start_date + 1
+      end_date = end_date ? end_date + 1 : start_date + 1
       date_to_timestamp(end_date)
     end
 
+    # Extracts the date from a list of items based on the index.
+    #
+    # @param items [Array] The list of items.
+    # @param idx [Integer] The index of the current item.
+    # @return [String, nil] The date string in 'YYYY-MM-DD' format, or nil if the date is the same as the previous item.
+    #
+    # @example Extract the date from a list of items
+    #   items = [[1, 1633072800], [2, 1633159200]]
+    #   TimeHelper.extract_date(items, 1) # => '2021-10-02'
     def self.extract_date(items, idx)
       current_start_date = items[idx][1]
       date = TimeHelper.timestamp_to_date(current_start_date)
@@ -50,17 +103,17 @@ module Timet
     # Formats a time string into a standard HH:MM:SS format.
     #
     # @param input [String] The input string to format.
-    # @return [String] The formatted time string in HH:MM:SS format, or nil if the input is invalid.
-    #
-    # @example
-    #  TimeHelper.format_time_string('123456') # => "12:34:56"
-    #  TimeHelper.format_time_string('1234567') # => "12:34:56"
-    #  TimeHelper.format_time_string('1234') # => "12:34:00"
-    #  TimeHelper.format_time_string('123') # => "12:30:00"
-    #  TimeHelper.format_time_string('12') # => "12:00:00"
-    #  TimeHelper.format_time_string('1') # => "01:00:00"
-    #  TimeHelper.format_time_string('127122') # => nil
-    #  TimeHelper.format_time_string('abc') # => nil
+    # @return [String, nil] The formatted time string in HH:MM:SS format, or nil if the input is invalid.
+    #
+    # @example Format a time string
+    #   TimeHelper.format_time_string('123456') # => "12:34:56"
+    #   TimeHelper.format_time_string('1234567') # => "12:34:56"
+    #   TimeHelper.format_time_string('1234') # => "12:34:00"
+    #   TimeHelper.format_time_string('123') # => "12:30:00"
+    #   TimeHelper.format_time_string('12') # => "12:00:00"
+    #   TimeHelper.format_time_string('1') # => "01:00:00"
+    #   TimeHelper.format_time_string('127122') # => nil
+    #   TimeHelper.format_time_string('abc') # => nil
     def self.format_time_string(input)
       return nil if input.nil? || input.empty?
 
@@ -73,6 +126,13 @@ module Timet
       format('%<hours>02d:%<minutes>02d:%<seconds>02d', hours: hours, minutes: minutes, seconds: seconds)
     end
 
+    # Parses time components from a string of digits.
+    #
+    # @param digits [String] The string of digits to parse.
+    # @return [Array] An array containing the hours, minutes, and seconds.
+    #
+    # @example Parse time components
+    #   TimeHelper.parse_time_components('123456') # => [12, 34, 56]
     def self.parse_time_components(digits)
       padded_digits = case digits.size
                       when 1 then "0#{digits}0000"
@@ -85,10 +145,26 @@ module Timet
       padded_digits.scan(/.{2}/).map(&:to_i)
     end
 
+    # Validates the time components.
+    #
+    # @param hours [Integer] The hours component.
+    # @param minutes [Integer] The minutes component.
+    # @param seconds [Integer] The seconds component.
+    # @return [Boolean] True if the time components are valid, otherwise false.
+    #
+    # @example Validate time components
+    #   TimeHelper.valid_time?(12, 34, 56) # => true
+    #   TimeHelper.valid_time?(25, 34, 56) # => false
     def self.valid_time?(hours, minutes, seconds)
       hours < 24 && minutes < 60 && seconds < 60
     end
 
+    # Returns the current timestamp.
+    #
+    # @return [Integer] The current timestamp.
+    #
+    # @example Get the current timestamp
+    #   TimeHelper.current_timestamp
     def self.current_timestamp
       Time.now.utc.to_i
     end