hackmac 1.8.2 → 1.8.3

data/lib/hackmac/disks.rb

@@ -1,26 +1,95 @@
 require 'hackmac/plist'
 
 module Hackmac
+  # A class that provides detailed information about a specific disk by
+  # querying the system's disk utility.
+  #
+  # The DiskInfo class interfaces with macOS's diskutil command to retrieve
+  # comprehensive details about a specified disk.
+  #
+  # @example
+  #   disk_info = Hackmac::DiskInfo.new(disk: '/dev/disk0')
+  #   # Provides access to disk information through method calls
   class DiskInfo
     include Hackmac::Plist
-
+    # The initialize method sets up a DiskInfo instance by retrieving detailed
+    # information about a specific disk.
+    #
+    # This method constructs and executes a system command to fetch
+    # comprehensive details about the specified disk using diskutil's info
+    # functionality with plist output format. The resulting plist data is
+    # parsed and made available for querying through dynamic method calls.
+    #
+    # @param disk [ String ] the disk identifier to retrieve information for
     def initialize(disk:)
       @disk = disk
-      plist *(%w[ diskutil info -plist ] << disk)
+      plist(**(%w[ diskutil info -plist ] << disk))
     end
 
+    # The disk reader method provides access to the disk identifier that was
+    # used when initializing the DiskInfo instance.
+    #
+    # @return [ String ] the disk identifier associated with this instance
     attr_reader :disk
   end
 
+  # A class that provides access to comprehensive disk information by querying
+  # macOS's diskutil command
+  #
+  # The Disks class interfaces with the diskutil utility to retrieve detailed
+  # information about all disks in the system. It executes system commands to
+  # gather plist-formatted data about disk configurations and makes this
+  # information available through dynamic method calls for easy access and
+  # manipulation.
+  #
+  # @example
+  #   disks = Hackmac::Disks.new
+  #   # Provides access to disk information through method calls
   class Disks
     include Hackmac::Plist
 
+    # The initialize method sets up a Disks instance by executing a system
+    # command to retrieve comprehensive disk information.
+    #
+    # This method constructs and runs a shell command using the diskutil
+    # utility to fetch detailed information about all disks in the system. 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 limiter [ String ] optional parameter to limit the output of diskutil list
+    # @param device [ String ] optional parameter to specify a particular device to query
     def initialize(limiter: nil, device: nil)
-      plist *(%w[ diskutil list -plist ] + [ limiter, device ].compact)
+      plist(*(%w[ diskutil list -plist ] + [ limiter, device ].compact))
     end
   end
 
+  # A class that provides access to APFS container disk information by querying
+  # macOS's diskutil command
+  #
+  # The ContainerDisk class extends the Disks class to specifically retrieve
+  # and process information about Apple File System (APFS) containers
+  #
+  # This class initializes by taking a disk identifier and searching for the
+  # corresponding Apple_APFS device within the diskutil list output
+  #
+  # It then uses the APFS device path to construct a Disks instance, allowing
+  # access to detailed APFS container information through dynamic method calls
+  #
+  # @example
+  #   container_disk = Hackmac::ContainerDisk.new(disk: '/dev/disk0')
+  #   # Provides access to APFS container information through method calls
   class ContainerDisk < Disks
+    # The initialize method sets up a ContainerDisk instance by identifying and
+    # initializing with the APFS device associated with a given disk.
+    #
+    # This method takes a disk identifier and searches for the corresponding
+    # Apple_APFS device within the diskutil list output. It extracts the device
+    # path and passes it along to the parent Disks class constructor, allowing
+    # for further processing of APFS container information.
+    #
+    # @param disk [ String ] the disk identifier to search for APFS container device
+    # @param limiter [ String ] optional parameter to limit the output of diskutil list
     def initialize(disk:, limiter: nil)
       @disk = disk
       device = `#{Shellwords.join(%w[ diskutil list ] << disk)}`.

data/lib/hackmac/github_source.rb

@@ -3,16 +3,43 @@ require 'json'
 require 'tins/string_version'
 
 module Hackmac
+  # A class that provides functionality for fetching and processing release
+  # information from GitHub repositories
+  #
+  # The GithubSource class enables interaction with GitHub's API to retrieve
+  # release data for a specified repository
+  #
+  # It parses release information to identify the latest version and provides
+  # methods for downloading associated assets
+  #
+  # @example
+  #   source = Hackmac::GithubSource.new('owner/repo', auth: ['user', 'token'])
+  #   # Fetches latest release information and allows asset downloads
   class GithubSource
     GITHUB_API_URL = 'https://api.github.com/repos/%s/releases'
 
     include Tins::StringVersion
 
+    # The initialize method sets up a GithubSource instance by fetching and
+    # parsing release information from the GitHub API.
+    #
+    # This method takes a GitHub repository identifier and optional
+    # authentication credentials, then retrieves all releases for that
+    # repository via the GitHub API. It processes the release data to find the
+    # highest version number, extracts relevant metadata about that release,
+    # and stores the release information for later use in downloading assets.
+    #
+    # @param github [ String ] the GitHub repository identifier in the format
+    #   "owner/repo"
+    # @param auth [ Array<String>, nil ] optional basic authentication
+    #   credentials [username, token]
+    # @param suffix [ String, nil ] optional suffix to filter asset names when
+    #   downloading
     def initialize(github, auth: nil, suffix: nil)
       @github  = github
       @auth    = auth
       @suffix  = (Regexp.quote(suffix) if suffix)
-      account, repo = github.split(?/)
+      _account, repo = github.split(?/)
       @name = repo
       releases = URI.open(
         GITHUB_API_URL % github,
@@ -32,14 +59,54 @@ module Hackmac
       end
     end
 
+    # The name reader method provides access to the name attribute that was set
+    # during object initialization.
+    #
+    # This method returns the value of the name instance variable, which
+    # typically represents the descriptive identifier or label associated with
+    # the object.
+    #
+    # @return [ String ] the name value stored in the instance variable
     attr_reader :name
 
+    # The version reader method provides access to the version attribute that
+    # was set during object initialization.
+    #
+    # This method returns the value of the version instance variable, which
+    # typically represents the semantic version number associated with the
+    # object's current state or configuration.
+    #
+    # @return [ String, nil ] the version value stored in the instance variable, or nil if not set
     attr_reader :version
 
+    # The github reader method provides access to the github attribute that was
+    # set during object initialization.
+    #
+    # This method returns the value of the github instance variable, which
+    # typically represents the GitHub repository identifier in the format
+    # "owner/repo" associated with the object.
+    #
+    # @return [ String ] the github value stored in the instance variable
     attr_reader :github
 
+    # The auth reader method provides access to the auth attribute that was set
+    # during object initialization.
+    #
+    # This method returns the value of the auth instance variable, which
+    # typically represents authentication credentials used for accessing
+    # protected resources or services.
+    #
+    # @return [ Array<String>, nil ] the auth value stored in the instance variable, or nil if not set
     attr_reader :auth
 
+    # The download_asset method retrieves a compressed asset file from a GitHub
+    # release by finding the appropriate asset based on a suffix filter and
+    # downloading its contents
+    # as binary data
+    #
+    # @return [ Array<String, String>, nil ] returns an array containing the asset filename
+    #   and downloaded data if successful, or nil if no suitable asset is found or
+    #   if there is no release information available
     def download_asset
       @release or return
       asset = @release.assets.find { |a| a.name =~ /#@suffix.*\.(zip|tar\.gz)\z/i } or return
@@ -52,14 +119,30 @@ module Hackmac
       return asset.name, data
     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 in the
+    # format "name version".
+    #
+    # @return [ String ] a formatted string containing the name and version
+    #   separated by a space
     def to_s
       "#{name} #{version}"
     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