hackmac 1.8.2 → 1.8.3

data/lib/hackmac/graph.rb

@@ -2,31 +2,139 @@ require 'term/ansicolor'
 require 'tins'
 require 'digest/md5'
 
+# A class that provides graphical display functionality for terminal-based data
+# visualization
+#
+# The Graph class enables the creation of dynamic, real-time visualizations of
+# data values within a terminal environment. It manages the rendering of
+# graphical representations such as line charts or graphs, updating them
+# continuously based on provided data sources. The class handles terminal
+# control operations, including cursor positioning, color management, and
+# screen clearing to ensure smooth visual updates. It also supports
+# configuration of display parameters like title, formatting strategies for
+# values, update intervals, and color schemes for different data series.
+#
+# @example
+#   graph = Hackmac::Graph.new(
+#     title: 'CPU Usage',
+#     value: ->(i) { rand(100) },
+#     format_value: :as_percent,
+#     sleep: 1,
+#     color: 33
+#   )
+#   graph.start
+#   # Starts the graphical display loop
+#
+# @example
+#   graph = Hackmac::Graph.new(
+#     title: 'Memory Usage',
+#     value: ->(i) { `vm_stat`.match(/Pages free: (\d+)/)[1].to_i },
+#     format_value: :as_bytes,
+#     sleep: 2
+#   )
+#   graph.start
+#   # Starts a memory usage graph with custom data source and formatting
 class Hackmac::Graph
   include Term::ANSIColor
 
-  include\
+  # A module that provides various formatting methods for converting numeric
+  # values into human-readable strings with appropriate units and display
+  # formats.
+  #
+  # The Formatters module contains a collection of utility methods designed to
+  # transform raw numeric data into formatted strings that are more suitable
+  # for display purposes. These methods handle common formatting tasks such as
+  # converting byte measurements, frequency values, temperature readings, and
+  # percentages into clean, readable representations.
+  #
+  # Each formatter method in this module is intended to be used with data
+  # visualization or reporting scenarios where presenting numerical information
+  # in an easily understandable format is important. The module also includes
+  # specialized functionality for deriving consistent color values based on
+  # input strings, which can be useful for maintaining visual coherence when
+  # displaying multiple data series.
+  #
+  # @example
+  #   include Hackmac::Graph::Formatters
+  #
+  #   as_bytes(1024 * 1024)        # => "1.000MB"
+  #   as_hertz(2500000000)        # => "2.500GHz"
+  #   as_celsius(37.5)            # => "37.5°"
+  #   as_percent(95.7)            # => "95.7%"
+  #   as_default(42)              # => "42"
   module Formatters
+    # The as_bytes method formats a numeric value into a human-readable byte
+    # representation
+    #
+    # This method takes a numeric input and converts it into a formatted string
+    # representing the value in bytes with appropriate binary prefixes (KB,
+    # MB, GB, etc.)
+    #
+    # @param value [ Numeric ] the numeric value to be formatted as bytes
+    #
+    # @return [ String ] the formatted byte representation with unit suffix
     def as_bytes(value)
       Tins::Unit.format(value, prefix: :uc, format: '%.3f%U', unit: 'B')
     end
 
+    # The as_hertz method formats a numeric value into a human-readable
+    # frequency representation
+    #
+    # This method takes a numeric input and converts it into a formatted string
+    # representing the value in hertz with appropriate metric prefixes (kHz,
+    # MHz, GHz, etc.)
+    #
+    # @param value [ Numeric ] the numeric frequency value to be formatted
+    #
+    # @return [ String ] the formatted frequency representation with unit suffix
     def as_hertz(value)
       Tins::Unit.format(value, prefix: :uc, format: '%.3f%U', unit: 'Hz')
     end
 
+    # The as_celsius method formats a temperature value with a degree symbol
+    #
+    # This method takes a numeric temperature value and returns a string
+    # representation with the degree Celsius symbol appended to it
+    #
+    # @param value [ Numeric ] the temperature value to be formatted
+    #
+    # @return [ String ] the temperature value formatted with a degree Celsius symbol
     def as_celsius(value)
       "#{value}°"
     end
 
+    # The as_percent method formats a numeric value as a percentage string
+    #
+    # This method takes a numeric input and returns a string representation
+    # with a percent sign appended to it, providing a simple way to format
+    # numeric values as percentages for display purposes
+    #
+    # @param value [ Numeric ] the numeric value to be formatted as a percentage
+    #
+    # @return [ String ] the numeric value formatted as a percentage string
     def as_percent(value)
       "#{value}%"
     end
 
+    # The as_default method converts a value to its string representation
+    #
+    # This method takes any input value and converts it to a string using the to_s method
+    # It serves as a fallback formatting option when no specific formatting is required
+    #
+    # @param value [ Object ] the value to be converted to a string
+    #
+    # @return [ String ] the string representation of the input value
     def as_default(value)
       value.to_s
     end
 
+    # The derive_color_from_string method calculates a color value based on the
+    # input string by generating an MD5 hash and selecting from a predefined
+    # set of dark colors
+    #
+    # @param string [ String ] the input string used to derive the color value
+    #
+    # @return [ Integer ] the derived color value from the set of dark ANSI attributes
     def derive_color_from_string(string)
       cs = (21..226).select { |d|
         Term::ANSIColor::Attribute[d].to_rgb_triple.to_hsl_triple.
@@ -38,7 +146,23 @@ class Hackmac::Graph
 
     self
   end
-
+  include Formatters
+
+  # The initialize method sets up a Graph instance by configuring its display
+  # parameters and internal state
+  #
+  # This method configures the graph visualization with title, value provider,
+  # formatting options, update interval, and color settings. It initializes
+  # internal data structures for storing historical values and manages
+  # synchronization through a mutex for thread-safe operations.
+  #
+  # @param title [ String ] the title to display at the bottom of the graph
+  # @param value [ Proc ] a proc that takes an index and returns a numeric value for plotting
+  # @param format_value [ Proc, Symbol, nil ] formatting strategy for displaying values
+  # @param sleep [ Numeric ] time in seconds between updates
+  # @param color [ Integer, Proc, nil ] color index or proc to determine color dynamically
+  #
+  # @raise [ ArgumentError ] if the sleep parameter is negative
   def initialize(
     title:,
     value: -> i { 0 },
@@ -57,12 +181,28 @@ class Hackmac::Graph
     @mutex        = Mutex.new
   end
 
+  # The start method initiates the graphical display process by setting up
+  # signal handlers, performing an initial terminal reset, and entering the
+  # main update loop
+  #
+  # This method serves as the entry point for starting the graph visualization
+  # functionality. It configures the necessary signal handlers for graceful
+  # shutdown and terminal resizing, performs an initial full reset of the
+  # display state, and then begins the continuous loop that updates and renders
+  # graphical data.
   def start
     install_handlers
     full_reset
     start_loop
   end
 
+  # The stop method terminates the graphical display process by performing a
+  # full reset and setting the continue flag to false
+  #
+  # This method serves as the shutdown mechanism for the graph visualization
+  # functionality. It ensures that all display resources are properly cleaned
+  # up and the terminal state is restored to its original condition before
+  # stopping the continuous update loop.
   def stop
     full_reset
     @continue = false
@@ -70,6 +210,16 @@ class Hackmac::Graph
 
   private
 
+  # The start_loop method executes a continuous loop to update and display
+  # graphical data
+  #
+  # This method manages the main execution loop for rendering graphical
+  # representations of data values over time. It initializes display state,
+  # processes incoming data, calculates visual representations, and handles
+  # terminal updates while respecting configured timing intervals.
+  #
+  # It continuously updates the display and handles data processing in a loop
+  # until explicitly stopped.
   def start_loop
     full_reset
     color       = pick_color
@@ -120,23 +270,60 @@ class Hackmac::Graph
   end
 
   def perform(*a)
-    print *a
+    print(*a)
   end
 
+  # The columns method returns the number of columns in the display
+  #
+  # This method provides access to the horizontal dimension of the graphical
+  # display by returning the total number of columns available for rendering
+  # content
+  #
+  # @return [ Integer ] the number of columns (characters per line) in the display object
   def columns
     @display.columns
   end
 
+  # The lines method returns the number of lines in the display
+  #
+  # This method provides access to the vertical dimension of the graphical
+  # display by returning the total number of rows available for rendering
+  # content
+  #
+  # @return [ Integer ] the number of lines (rows) in the display object
   def lines
     @display.lines
   end
 
+  # The data reader method provides access to the data attribute that was set
+  # during object initialization.
+  #
+  # This method returns the value of the data instance variable, which
+  # typically contains structured information that has been processed or
+  # collected by the object.
+  #
+  # @return [ Array<Object>, Hash, nil ] the data value stored in the instance variable, or nil if not set
   attr_reader :data
 
+  # The sleep_duration method returns a string representation of the configured
+  # sleep interval with the 's' suffix appended to indicate seconds.
+  #
+  # @return [ String ] a formatted string containing the sleep duration in seconds
   def sleep_duration
     "#{@sleep}s"
   end
 
+  # The format_value method processes a given value using the configured
+  # formatting strategy
+  #
+  # This method applies the appropriate formatting to a value based on the
+  # @format_value instance variable configuration It supports different
+  # formatting approaches including custom Proc objects, Symbol-based method
+  # calls, and default formatting
+  #
+  # @param value [ Object ] the value to be formatted according to the configured strategy
+  #
+  # @return [ String ] the formatted string representation of the input value
   def format_value(value)
     case @format_value
     when Proc
@@ -148,6 +335,28 @@ class Hackmac::Graph
     end
   end
 
+  # The pick_color method determines and returns an ANSI color attribute based
+  # on the configured color setting
+  #
+  # This method evaluates the @color instance variable to decide how to select
+  # a color attribute. If @color is a Proc, it invokes the proc with the @title
+  # to determine the color. If @color is nil, it derives a color from the title
+  # string. Otherwise, it uses the @color value directly as an index into the
+  # ANSI color attributes.
+  #
+  # @return [ Term::ANSIColor::Attribute ] the selected color attribute object
+  def pick_color
+    Term::ANSIColor::Attribute[
+      case @color
+      when Proc
+        @color.(@title)
+      when nil
+        derive_color_from_string(@title)
+      else
+        @color
+      end
+    ]
+  end
   def pick_color
     Term::ANSIColor::Attribute[
       case @color
@@ -161,6 +370,14 @@ class Hackmac::Graph
     ]
   end
 
+  # The sleep_now method calculates and executes a sleep duration based on the
+  # configured sleep time and elapsed time since start
+  #
+  # This method determines how long to sleep by calculating the difference
+  # between the configured sleep interval and the time elapsed since the last
+  # operation started. If no start time is recorded, it uses the full
+  # configured sleep duration. The method ensures that negative sleep durations
+  # are not used by taking the maximum of the calculated duration and zero.
   def sleep_now
     duration = if @start
                  [ @sleep - (Time.now - @start).to_f, 0 ].max
@@ -170,6 +387,22 @@ class Hackmac::Graph
     sleep duration
   end
 
+  # The perform_display_diff method calculates and displays the difference
+  # between the current and previous display states to update only the changed
+  # portions of the terminal output
+  #
+  # This method synchronizes access to shared display resources using a mutex,
+  # then compares the current display with the previous state to determine what
+  # needs updating. It handles dimension mismatches by resetting the old
+  # display, computes the visual difference, and outputs only the modified
+  # portions to reduce terminal update overhead
+  #
+  # When the DEBUG_BYTESIZE environment variable is set, it also outputs
+  # debugging information about the size of the diff and the time elapsed since
+  # the last debug output
+  #
+  # @return [ void ] Returns nothing but performs terminal output operations
+  #   and updates internal display state
   def perform_display_diff
     @mutex.synchronize do
       unless @old_display && @old_display.dimensions == @display.dimensions
@@ -191,6 +424,18 @@ class Hackmac::Graph
   end
 
 
+  # The normalize_value method converts a value to its appropriate numeric
+  # representation
+  #
+  # This method takes an input value and normalizes it to either a Float or
+  # Integer type depending on its original form. If the value is already a
+  # Float, it is returned as-is. For all other types, the method attempts to
+  # convert the value to an integer using to_i
+  #
+  # @param value [ Object ] the value to be normalized
+  #
+  # @return [ Float, Integer ] the normalized numeric value as either a Float
+  #   or Integer
   def normalize_value(value)
     case value
     when Float
@@ -200,6 +445,15 @@ class Hackmac::Graph
     end
   end
 
+  # The full_reset method performs a complete reset of the display and terminal
+  # state
+  #
+  # This method synchronizes access to shared resources using a mutex, then
+  # executes a series of terminal control operations to reset the terminal
+  # state, clear the screen, move the cursor to the home position, and make the
+  # cursor visible. It also initializes new display objects with the current
+  # terminal dimensions and updates the internal
+  # display state.
   def full_reset
     @mutex.synchronize do
       perform reset, clear_screen, move_home, show_cursor
@@ -211,6 +465,12 @@ class Hackmac::Graph
     end
   end
 
+  # The install_handlers method sets up signal handlers for graceful shutdown
+  # and terminal resize handling
+  #
+  # This method configures two signal handlers: one for the exit hook that
+  # performs a full reset, and another for the SIGWINCH signal that handles
+  # terminal resize events by setting a flag and displaying a sleeping message
   def install_handlers
     at_exit { full_reset }
     trap(:SIGWINCH) do

data/lib/hackmac/ioreg.rb

@@ -1,11 +1,33 @@
 require 'hashie'
 
 module Hackmac
+  # A class that provides access to IORegistry information through plist
+  # parsing
+  #
+  # The IOReg class interfaces with macOS's IORegistry system to retrieve and
+  # parse hardware-related information for a specified key. It executes the
+  # ioreg command with appropriate flags to fetch XML data, processes this data
+  # into a structured hash format, and makes it available for querying through
+  # dynamic method calls.
+  #
+  # @example
+  #   ioreg = Hackmac::IOReg.new(key: 'IOPowerManagement')
+  #   # Provides access to power management information through method calls
   class IOReg
     include Hackmac::Plist
-
+    # The initialize method sets up an IOReg instance by executing a system
+    # command to retrieve hardware registry information for a specific key.
+    #
+    # This method constructs and runs a shell command using the ioreg utility
+    # to fetch detailed information about a specified hardware key from the
+    # IOService registry. It processes the XML output, extends the resulting
+    # hash with deep find capabilities, and stores the largest matching result
+    # set in the instance variable.
+    #
+    # @param key [ String ] the hardware registry key to search for in the
+    #   IOService tree
     def initialize(key:)
-      plist *(%w[ioreg -a -p IOService -r -k ] << key)
+      plist(*(%w[ioreg -a -p IOService -r -k ] << key))
       @plist.extend Hashie::Extensions::DeepFind
       @plist = @plist.deep_find_all(key).max_by(&:size)
     end

data/lib/hackmac/kext.rb

@@ -3,10 +3,33 @@ require 'pathname'
 require 'tins/string_version'
 
 module Hackmac
+
+  # A class that represents a kernel extension (kext) and provides access to
+  # its metadata and remote version information
+  #
+  # The Kext class encapsulates the functionality for working with macOS kernel
+  # extensions, including loading their Info.plist files, extracting metadata
+  # such as identifiers and versions, and determining whether newer versions
+  # are available from remote sources
+  #
+  # @example
+  #   kext = Hackmac::Kext.new(path: '/path/to/MyKext.kext')
+  #   # Provides access to kext metadata through method calls
   class Kext
     include Hackmac::Plist
     include Tins::StringVersion
 
+    # The initialize method sets up a Kext instance by loading and parsing its
+    # Info.plist file
+    #
+    # This method takes a path to a kext directory and optionally a
+    # configuration object, then reads the Info.plist file within the kext's
+    # Contents directory to extract metadata about the kernel extension. The
+    # plist data is parsed and stored for later access through dynamic method
+    # calls.
+    #
+    # @param path [ String ] the filesystem path to the kext directory
+    # @param config [ Object, nil ] optional configuration object that may provide source information
     def initialize(path:, config: nil)
       @path   = path
       info    = Pathname.new(@path) + 'Contents/Info.plist'
@@ -14,16 +37,49 @@ module Hackmac
       @config = config
     end
 
+    # The path reader method provides access to the path attribute that was set
+    # during object initialization.
+    #
+    # This method returns the value of the path instance variable, which
+    # typically represents the filesystem path associated with the object.
+    #
+    # @return [ String ] the path value stored in the instance variable
     attr_reader :path
 
+    # The identifier method retrieves the bundle identifier from the kext's
+    # Info.plist file
+    #
+    # This method accesses the CFBundleIdentifier key from the parsed plist
+    # data of a kernel extension, providing the unique identifier that
+    # distinguishes this particular kext within the system
+    #
+    # @return [ String ] the bundle identifier of the kernel extension
+    # @return [ nil ] returns nil if the CFBundleIdentifier key is not present in the plist
     def identifier
       CFBundleIdentifier()
     end
 
+    # The name method retrieves the display name for the kernel extension
+    #
+    # This method attempts to return the CFBundleName value from the kext's
+    # Info.plist file and falls back to using the basename of the bundle
+    # identifier if that value is not present
+    #
+    # @return [ String ] the human-readable name of the kernel extension
+    # @return [ nil ] returns nil if neither CFBundleName nor identifier is available
     def name
       CFBundleName() || File.basename(identifier)
     end
 
+    # The version method retrieves and caches the version identifier from the
+    # kext's Info.plist file
+    #
+    # This method attempts to extract the CFBundleShortVersionString value from
+    # the parsed plist data and convert it into a Version object for proper
+    # semantic versioning comparison. If the version string is not a valid
+    # semantic version, it stores the raw string instead.
+    #
+    # @return [ Tins::StringVersion, String, nil ] the version object or string if found, nil otherwise
     def version
       unless @version
         if version = CFBundleShortVersionString()
@@ -37,6 +93,18 @@ module Hackmac
       @version
     end
 
+    # The remote_kext method retrieves or creates a remote source object for a
+    # kext
+    #
+    # This method attempts to return an existing cached remote kext source or
+    # constructs a new one based on the configuration source for this kext. It
+    # supports both GitHub-based sources and direct URL downloads, determining
+    # the appropriate source type from the configuration and creating the
+    # corresponding source object.
+    #
+    # @return [ Hackmac::GithubSource, Hackmac::URLDownload, nil ] returns the remote
+    #   source object if a configuration source exists, or nil if no source is
+    #   configured or the kext has no associated configuration
     def remote_kext
       return @remote_kext if @remote_kext
       if @config
@@ -58,14 +126,35 @@ module Hackmac
       end
     end
 
+    # The remote_version method retrieves the version identifier from the
+    # remote kext source
+    #
+    # This method accesses the cached remote kext source object and returns its
+    # version information if available. It uses the safe navigation operator to
+    # avoid errors when the remote kext source has not been initialized or does
+    # not have version data
+    #
+    # @return [ Tins::StringVersion, String, nil ] the version object or string from
+    #   the remote source, or nil if no remote source is available or has no version
+    #   information
     def remote_version
       remote_kext&.version
     end
 
+    # The inspect method returns a string representation of the object
+    # that includes its class name and string value
+    #
+    # @return [ String ] a formatted string containing the object's class name
+    #   and its string representation
     def inspect
       "#<#{self.class}: #{to_s}>"
     end
 
+    # The to_s method returns a string representation of the object by
+    # combining its name and version attributes into a single space-separated
+    # string.
+    #
+    # @return [ String ] a formatted string containing the name and version separated by a space
     def to_s
       "#{name} #{version}"
     end

data/lib/hackmac/kext_upgrader.rb

@@ -3,16 +3,54 @@ require 'find'
 require 'pathname'
 
 module Hackmac
+  # A class that handles the upgrade process for kernel extensions (kexts)
+  #
+  # The KextUpgrader class manages the workflow for upgrading macOS kernel extensions
+  # by checking remote version availability, downloading new versions, and performing
+  # file system operations to replace existing kext files after user confirmation
+  #
+  # @example
+  #   upgrader = Hackmac::KextUpgrader.new(path: '/path/to/kext', config: config_obj)
+  #   upgrader.perform
+  #   # Executes the kext upgrade process in a temporary directory context
   class KextUpgrader
     include FileUtils
     include Hackmac::AssetTools
 
+    # The initialize method sets up a KextUpgrader instance by storing the
+    # provided path, configuration, and force flag.
+    #
+    # This method takes the necessary parameters to configure the kext
+    # upgrader, including the filesystem path to the kext, the configuration
+    # object that defines source information, and a force flag that determines
+    # whether upgrades should be performed even when the remote version is not
+    # newer than the local version.
+    #
+    # @param path [ String ] the filesystem path to the kext directory that
+    #   needs upgrading
+    # @param config [ Object ] the configuration object containing source
+    #   information for the kext
+    # @param force [ TrueClass, FalseClass ] flag indicating whether to force
+    #   upgrade even if remote version is not newer
     def initialize(path:, config:, force: false)
       @path, @config, @force = path, config, force
     end
 
     public
 
+    # The perform method executes the kext upgrade process by isolating the
+    # operation in a temporary directory
+    #
+    # This method handles the complete workflow for upgrading a kernel
+    # extension, including checking for remote version availability,
+    # downloading and decompressing the new version, identifying target
+    # installation paths, and performing the actual file replacement after user
+    # confirmation
+    #
+    # @return [ void ] Returns nothing but performs file system operations and
+    #   user interaction
+    # @raise [ RuntimeError ] raised when a remote download fails or when no
+    #   source is defined for the kext
     def perform
       isolate do |dir|
         kext = Kext.new(path: @path, config: @config)