hackmac 1.8.2 → 1.8.3

data/lib/hackmac/oc.rb

@@ -1,9 +1,43 @@
 module Hackmac
+  # A class that represents an OpenCore configuration and provides access to
+  # its remote version information
+  #
+  # The OC class encapsulates the functionality for working with OpenCore
+  # bootloader configurations, including retrieving remote release information
+  # from GitHub sources and providing access to version metadata for comparison
+  # and upgrade operations
+  #
+  # @example
+  #   oc = Hackmac::OC.new(config: config_obj)
+  #   # Provides access to OpenCore version information through method calls
   class OC
+    # The initialize method sets up an OC instance by storing the provided
+    # configuration object.
+    #
+    # This method takes a configuration object and assigns it to an instance
+    # variable for later use in accessing OC-related settings and source
+    # information.
+    #
+    # @param config [ Object ] the configuration object containing OC-specific
+    #   settings and source definitions
     def initialize(config:)
       @config = config
     end
 
+    # The remote method retrieves or creates a remote source object for
+    # OpenCore
+    #
+    # This method manages the initialization and caching of a remote source
+    # object that provides access to OpenCore release information from GitHub.
+    # It constructs the appropriate source configuration including
+    # authentication credentials and version suffix based on debug settings,
+    # then creates a GithubSource instance to handle communication with the
+    # GitHub API for retrieving release data
+    #
+    # @return [ Hackmac::GithubSource ] the cached remote source object for
+    #   OpenCore releases
+    # @return [ nil ] returns nil if no OpenCore source is configured in the
+    #   configuration
     def remote
       @remote and return @remote
       source = @config.oc.source
@@ -19,21 +53,50 @@ module Hackmac
       @remote = Hackmac::GithubSource.new(github, auth: auth, suffix: suffix)
     end
 
+    # The name method retrieves the name attribute from the remote source
+    # object
+    #
+    # This method accesses the cached remote source object and returns its name
+    # information if available. It uses the safe navigation operator to avoid
+    # errors when the remote source has not been initialized
+    #
+    # @return [ String, nil ] the name value from the remote source, or nil if no remote source is available
     def name
       remote.name
     end
 
+    # The 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 serves as a delegate to the
+    # remote_kext's version attribute, providing convenient access to the
+    # latest version data for the kext
+    #
+    # @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 version
       remote.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
   end
 end
-

data/lib/hackmac/oc_upgrader.rb

@@ -1,16 +1,54 @@
 require 'fileutils'
 
 module Hackmac
+  # A class that handles the upgrade process for OpenCore bootloader files
+  #
+  # The OCUpgrader class manages the workflow for upgrading OpenCore bootloader
+  # installations by retrieving remote release information, downloading and
+  # decompressing new versions, and performing file system operations to replace
+  # existing EFI files after ensuring the installation directory is properly
+  # configured
+  #
+  # @example
+  #   upgrader = Hackmac::OCUpgrader.new(mdev: '/dev/disk1', config: config_obj)
+  #   upgrader.perform
+  #   # Executes the OpenCore upgrade process in a temporary directory context
   class OCUpgrader
     include FileUtils::Verbose
     include Hackmac::AssetTools
 
+    # The initialize method sets up an OCUpgrader instance by configuring the
+    # installation directory based on the provided mount point and
+    # configuration.
+    #
+    # This method takes a mount device identifier and configuration object,
+    # then constructs the full path to the EFI installation directory by
+    # joining the mount path with the OpenCore EFI path specified in the
+    # configuration.
+    #
+    # @param mdev [ String ] the mount device identifier for the EFI partition
+    # @param config [ Object ] the configuration object containing OpenCore settings including the EFI path
+    #
+    # @return [ void ] Returns nothing but initializes instance variables for the upgrade process
     def initialize(mdev:, config:)
       @config      = config
       mount_path   = Pathname.new('/Volumes').join(mdev)
       @install_dir = Pathname.new(mount_path).join(@config.oc.efi_path)
     end
 
+    # The perform method executes the OpenCore upgrade process by isolating the
+    # operation in a temporary directory
+    #
+    # This method handles the complete workflow for upgrading OpenCore
+    # bootloader files, including retrieving remote release information,
+    # downloading and decompressing the new version, and performing file system
+    # operations to replace existing EFI files after ensuring
+    # the installation directory is properly configured
+    #
+    # @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 OpenCore upgrade
     def perform
       isolate do |dir|
         oc = OC.new(config: @config)
@@ -28,6 +66,12 @@ module Hackmac
       end
     end
 
+    # The to_s method returns a string representation of the object by
+    # formatting the installation directory path into a descriptive string
+    # that indicates where the OpenCore files will be installed
+    #
+    # @return [ String ] a formatted string containing the installation path
+    #   in the format "Installation into /path/to/installation/directory"
     def to_s
       'Installation into %s' % @install_dir
     end

data/lib/hackmac/oc_validator.rb

@@ -1,7 +1,27 @@
 module Hackmac
   include Hackmac::AssetTools
-
+  # A class that handles validation of OpenCore bootloader configurations
+  #
+  # The OCValidator class provides functionality for verifying the correctness
+  # and compatibility of OpenCore EFI configuration files. It retrieves the
+  # latest OpenCore release, downloads the necessary validation utilities, and
+  # executes validation checks against a specified configuration plist file to
+  # ensure it meets the required standards for OpenCore bootloaders.
+  #
+  # @example
+  #   validator = Hackmac::OCValidator.new(mdev: '/dev/disk1', config: config_obj)
+  #   # Configures validation for an OpenCore installation on a specific disk
   class OCValidator
+    # The initialize method sets up an OCValidator instance by configuring the
+    # path to the OpenCore configuration plist file
+    #
+    # This method takes a mount device identifier and configuration object,
+    # then constructs the full path to the OpenCore configuration plist file by
+    # joining the mount path with the EFI path and OC subdirectory specified in
+    # the configuration
+    #
+    # @param mdev [ String ] the mount device identifier for the EFI partition
+    # @param config [ Object ] the configuration object containing OpenCore settings including the EFI path
     def initialize(mdev:, config:)
       @config = config
       mount_path   = Pathname.new('/Volumes').join(mdev)
@@ -9,6 +29,16 @@ module Hackmac
         Pathname.new(mount_path).join(@config.oc.efi_path).join('OC/config.plist')
     end
 
+    # The perform method executes the OpenCore configuration validation process
+    #
+    # This method handles the complete workflow for validating an OpenCore
+    # configuration file by retrieving the latest OpenCore release, downloading
+    # the validation utilities, and running the ocvalidate tool against the
+    # specified configuration plist file
+    #
+    # @return [ Boolean ] returns true if validation succeeds, false if validation fails
+    # @raise [ RuntimeError ] raised when the OpenCore download fails or when no
+    #                         remote source is defined for the OpenCore upgrade
     def perform
       isolate do |dir|
         oc = OC.new(config: @config)

data/lib/hackmac/plist.rb

@@ -2,23 +2,86 @@ require 'plist'
 require 'shellwords'
 
 module Hackmac
+  # A module that provides methods for parsing and interacting with Property
+  # List (plist) data
+  #
+  # The Plist module offers functionality to parse XML-formatted plist data
+  # from shell commands and provides convenient access to the resulting hash
+  # structure. It includes methods for executing commands, parsing their XML
+  # output, and accessing plist values through dynamic method calls.
+  #
+  # @example
+  #   class MyClass
+  #     include Hackmac::Plist
+  #   end
+  #
+  #   obj = MyClass.new
+  #   obj.plist('diskutil', 'info', '-plist', '/dev/disk0')
+  #   # Access parsed data through method_missing or as_hash
   module Plist
+    # Parses XML output from a command into a plist hash
+    #
+    # This method executes a shell command and parses its XML output into a
+    # Ruby hash using the Plist library. The resulting hash is stored in the
+    # @plist instance variable for later access through other methods.
+    #
+    # @param cmd [Array<String>] command and arguments to execute
+    #
+    # @return [void] Returns nothing, but sets the @plist instance variable
     def plist(*cmd)
       @plist = ::Plist.parse_xml(`#{Shellwords.join(cmd)}`)
     end
 
-    def as_hash(*)
+    # Returns a duplicate of the internal plist hash
+    #
+    # This method provides access to the parsed plist data by returning a shallow copy
+    # of the internal @plist instance variable. This allows external code to read
+    # the plist contents without directly modifying the original data structure.
+    #
+    # @return [ Hash ] a duplicate of the plist hash containing the parsed XML data
+    def as_hash(*a)
       @plist.dup
     end
 
+    # The each method iterates over the parsed plist data
+    #
+    # This method provides an iterator interface for the plist hash by
+    # delegating to the as_hash method's each implementation. It allows callers
+    # to enumerate over the key-value pairs in the parsed plist structure.
+    #
+    # @yield [ key, value ] yields each key-value pair from the plist
+    #
+    # @return [ Hash ] returns the hash representation of the plist.
     def each(&block)
       as_hash.each(&block)
     end
 
+    # The to_json method converts the parsed plist data to a JSON string
+    #
+    # This method takes the internal plist hash and serializes it into a JSON
+    # format using the standard to_json method from the Hash class. It provides
+    # a convenient way to output the plist data in JSON representation.
+    #
+    # @param a [ Array ] additional arguments to pass to the underlying to_json method
+    #
+    # @return [ String ] a JSON string representation of the plist data
     def to_json(*a)
       as_hash.to_json(*a)
     end
 
+    # The method_missing method provides dynamic access to plist data by
+    # handling attribute reads and writes through method calls
+    #
+    # This method intercepts undefined method calls on objects that include the
+    # Plist module, allowing convenient access to plist values using
+    # method-style syntax. When a method name ends with an equals sign, it sets
+    # the corresponding plist key to the provided value. Otherwise, if the
+    # method name matches an existing plist key, it returns the value.
+    #
+    # @param name [ Symbol ] the method name being called
+    # @param a [ Array ] the arguments passed to the method
+    #
+    # @return [ Object ] the value of the plist key when reading, or nil when setting
     def method_missing(name, *a)
       n = name.to_s
       if n =~ /(.+)=\z/

data/lib/hackmac/url_download.rb

@@ -2,19 +2,65 @@ require 'open-uri'
 require 'tins/string_version'
 
 module Hackmac
+  # A class that provides functionality for downloading assets from URLs with
+  # version tracking
+  #
+  # The URLDownload class encapsulates the logic for managing downloadable
+  # assets by storing their name, version, and download URL. It provides
+  # methods to retrieve the asset data and metadata, making it suitable for use
+  # in systems that need to track and download software components from web
+  # sources.
+  #
+  # @example
+  #   downloader = Hackmac::URLDownload.new('Foo', '1.0.0', 'https://example.com/foo.zip')
+  #   # Configures a download source with name, version, and URL for later retrieval
   class URLDownload
     include Tins::StringVersion
 
+    # The initialize method sets up a URLDownload instance by storing the
+    # provided name, URL, and version information.
+    #
+    # This method takes the necessary parameters to configure the download
+    # source and converts the version string into a Version object for later
+    # comparison.
+    #
+    # @param name [ String ] the descriptive name of the downloadable asset
+    # @param version [ String ] the version identifier to be parsed and stored
+    # @param url [ String ] the web address where the asset can be retrieved
     def initialize(name, version, url)
       @name    = name
       @url     = url
       @version = Version.new(version)
     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 download_asset method retrieves binary data from a configured URL
+    #
+    # This method performs an HTTP GET request to the stored URL to download
+    # the associated asset file. It returns both the filename derived from
+    # the URL and the raw binary data content.
+    #
+    # @return [ Array<String, String> ] an array containing the filename and downloaded data
+    # @return [ nil ] returns nil if no URL is configured for this instance
     def download_asset
       data = URI.open(
         @url,
@@ -24,14 +70,30 @@ module Hackmac
       return File.basename(@url), 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 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
 
+    # 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/utils.rb

@@ -8,9 +8,22 @@ require 'tmpdir'
 require 'shellwords'
 
 module Hackmac
+  # A module that provides utility methods for executing shell commands and
+  # interacting with users.
+  #
+  # The Utils module includes methods for running system commands with colored
+  # output, prompting users for input, and handling common file operations in a
+  # Hackmac context.
   module Utils
     include FileUtils
 
+    # The x method executes a shell command and displays its output with
+    # colorized prompts.
+    #
+    # @param cmd [ String ] the shell command to execute
+    # @param verbose [ TrueClass, FalseClass ] whether to show command output in verbose mode
+    #
+    # @return [ String ] the captured output of the command execution
     def x(cmd, verbose: true)
       prompt = cmd =~ /\A\s*sudo/ ? ?# : ?$
       cmd_output = "#{prompt} #{cmd}".color(27) + (verbose ? "" : " >/dev/null".yellow)
@@ -27,6 +40,10 @@ module Hackmac
       output
     end
 
+    # The ask method prompts the user for a yes/no response.
+    #
+    # @param prompt [ String ] the message to display to the user
+    # @return [ Boolean ] true if the user answered 'y' or 'Y', false otherwise
     def ask(prompt)
       print prompt.bold.yellow
       gets =~ /\Ay/i

data/lib/hackmac/version.rb

@@ -1,6 +1,6 @@
 module Hackmac
   # Hackmac version
-  VERSION         = '1.8.2'
+  VERSION         = '1.8.3'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hackmac
 version: !ruby/object:Gem::Version
-  version: 1.8.2
+  version: 1.8.3
 platform: ruby
 authors:
 - Florian Frank
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.20'
+        version: '2.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.20'
+        version: '2.6'
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -176,7 +176,7 @@ extra_rdoc_files:
 - lib/hackmac/utils.rb
 - lib/hackmac/version.rb
 files:
-- ".gitignore"
+- ".context/code_comment.rb"
 - CHANGES.md
 - Gemfile
 - LICENSE
@@ -207,7 +207,8 @@ files:
 - lib/hackmac/utils.rb
 - lib/hackmac/version.rb
 homepage: http://github.com/flori/hackmac
-licenses: []
+licenses:
+- MIT
 metadata: {}
 rdoc_options:
 - "--title"

data/.gitignore

@@ -1,9 +0,0 @@
-.*.sw[pon]
-.AppleDouble
-.DS_Store
-.bundle
-.byebug_history
-.rvmrc
-Gemfile.lock
-pkg
-tags