macos.rb 0.50.0

data/README.md

@@ -0,0 +1,129 @@
+# macos.rb
+
+Work with macOS from Ruby: network interfaces and hardware ports, the system's version, defaults, disks and disk images, USB flash drives, applications, users, voices, the keychain and launchd.
+
+Each part wraps the command macOS provides for it, such as `ifconfig`, `networksetup`, `system_profiler`, `defaults` or `diskutil`, and gives back Ruby objects rather than text.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'macos.rb'
+```
+
+And then execute:
+
+```
+$ bundle install
+```
+
+Or install it yourself as:
+
+```
+$ gem install macos.rb
+```
+
+## Usage
+
+```ruby
+require 'MacOS'
+```
+
+loads every part, or require only the parts you want, such as `require 'MacOS/IfConfig'`.
+
+### Network interfaces and hardware ports
+
+```ruby
+MacOS::IfConfig.interface_names            # => ["lo0", "en0", "utun4", ...]
+MacOS::IfConfig.up_interfaces_names        # those active, or flagged UP, and with an address
+en0 = MacOS::IfConfig.find_by_interface('en0')
+en0.ipv4_address                           # => "192.0.2.114"
+en0.mac_address                            # => "00:00:5e:00:53:02"
+MacOS::IfConfig.all_matching(/\Autun/)     # a Regexp, or a String matched literally
+
+MacOS::HardwarePort.find_by_name('Wi-Fi').interface    # => "en0"
+
+MacOS::VPN.up?                             # the first tunnel interface which is up, if any
+
+MacOS::Apple80211.channel                  # the Wi-Fi connection's; also .ssid, .link_auth and .attributes
+```
+
+Apple80211 reads `airport -I`, and from macOS 14.4 on, where `airport` reports nothing, `system_profiler SPAirPortDataType`. That gives the channel and security in its own form, `"36 (5GHz, 80MHz)"` and `"WPA2 Personal"`, rather than airport's, and no SSID: macOS redacts the network's name from programs without location access.
+
+### The system
+
+```ruby
+MacOS.version                              # a Version, which compares with strings: MacOS.version >= '14.0'
+MacOS.version.major                        # => "15"
+MacOS::SystemProfiler.kernel_version.to_s  # => "24.6.0"
+MacOS::SystemProfiler.boot_mode            # => "Normal"
+MacOS::SystemProfiler.time_since_boot      # => "6 days, 2 hours, 34 minutes"
+```
+
+### Defaults
+
+```ruby
+MacOS::Defaults.domains                    # every domain defaults knows
+MacOS::Defaults.new(domain: 'com.apple.dock').export     # to a plist file, which #to_h then reads
+
+MacOS::Defaults::ComAppleDock.read('autohide', 'tilesize')   # => {"autohide" => "yes", "tilesize" => 48}
+MacOS::Defaults::ComAppleDock.load('persistent-apps' => ['/Applications/Safari.app'], 'autohide' => true)
+
+keys = MacOS::Defaults::NSGlobalDomain::NSUserKeyEquivalents
+keys.assign_keys(%w{cmd alt left}, 'Previous Tab')       # a keyboard shortcut for a menu item
+keys.read_keys                             # => [{keys: [:cmd, :alt, :left], menu_items: ["Previous Tab"]}, ...]
+```
+
+### Disks, disk images and USB flash drives
+
+```ruby
+MacOS::DiskUtil.volumes                    # => [{device_id: "disk4s1", mount_point: "/Volumes/EXAMPLE", name: "EXAMPLE", size: ...}, ...]
+MacOS::DiskUtil.free_bytes_for_volume_name('EXAMPLE')
+
+MacOS::Dmg.new(path_to_dmg: 'Example-1.0.dmg', disk_image_name: 'Example-1.0.dmg', package: 'Example').install
+
+MacOS::USBFlashDrive.all_mount_points      # => ["/Volumes/EXAMPLE", ...]
+```
+
+### Applications, users, voices, the keychain and launchd
+
+```ruby
+MacOS::Applications.installed?('Safari')   # in /System/Applications, /Applications or ~/Applications
+MacOS::Applications.start('Safari')
+
+MacOS::Users.all                           # the real users, without the system and service accounts
+
+MacOS::Voice.list.map(&:name)              # every voice say knows
+MacOS::Voice.random_voice
+
+MacOS::Keychain.wifi_password('ExampleNet')            # nil where the keychain has none
+
+MacOS::LaunchControl.new('/Library/LaunchAgents/com.example.agent.plist').load
+```
+
+Some of these change the system, and some ask for `sudo`: bringing interfaces down, installing from a disk image, writing defaults and loading launchd plists. Reading never does.
+
+## Versions
+
+Versions before 0.49.0 were reckoned when the library was put together, from its components' own versions; 0.50.0 is the first released as a gem. Each version carries the libraries it requires, at the versions current at its date.
+
+## Tests
+
+```
+$ bundle exec rake test
+```
+
+The tests never run the commands macOS provides. Each is given output captured from them, in `test/fixtures`, with its MAC addresses, IP addresses and names made anonymous.
+
+## Contributing
+
+1. Fork it (https://github.com/thoran/macos.rb/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new pull request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,9 @@
+# Rakefile
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/lib/Array/all_but_last.rb

@@ -0,0 +1,7 @@
+# Array/all_but_last.rb
+# Array#all_but_last
+
+# 20180804
+# 0.1.0 (The same version number as the current version of Thoran/Array/AllButLast.)
+
+require 'Thoran/Array/AllButLast/all_but_last'

data/lib/MacOS/Apple80211.rb

@@ -0,0 +1,68 @@
+# MacOS/Apple80211.rb
+# MacOS::Apple80211
+
+module MacOS
+  class Apple80211
+    class << self
+
+      def airport_i
+        `/System/Library/PrivateFrameworks/Apple80211.framework/Resources/airport -I`
+      rescue Errno::ENOENT
+        ''
+      end
+
+      def system_profiler_airport
+        `system_profiler SPAirPortDataType`
+      end
+
+      # airport -I's attributes, or, where it gives none, as from macOS 14.4 on, system_profiler's.
+      def attributes
+        from_airport = airport_attributes
+        from_airport.empty? ? system_profiler_attributes : from_airport
+      end
+
+      def channel
+        attributes['channel']
+      end
+
+      def ssid
+        attributes['SSID']
+      end
+
+      def link_auth
+        attributes['link auth']
+      end
+
+      private
+
+      # The deprecation warning macOS 14.4 and later print, in place of the attributes, left out.
+      def airport_attributes
+        airport_i.split("\n").inject({}) do |a, line|
+          if line && line.match(/: .+/)
+            k, v = line.split(': ')
+            a[k.strip] = v.gsub('"', '')
+          end
+          a
+        end.reject{|k, _| k == 'WARNING'}
+      end
+
+      # The current network's fields, with its name as SSID where macOS doesn't redact it, and its Channel and Security as
+      # channel and link auth.
+      def system_profiler_attributes
+        lines = system_profiler_airport.lines
+        start = lines.index{|line| line.strip == 'Current Network Information:'} or return {}
+        name_line = lines[start + 1].to_s
+        return {} unless name_line.strip.end_with?(':')
+        depth = name_line[/\A */].size
+        fields = lines[(start + 2)..].take_while{|line| line[/\A */].size > depth && !line.strip.empty?}
+        attributes = fields.to_h{|line| line.strip.split(': ', 2)}
+        name = name_line.strip.chomp(':')
+        attributes['SSID'] = name unless name == '<redacted>'
+        attributes['channel'] = attributes['Channel'] if attributes['Channel']
+        attributes['link auth'] = attributes['Security'] if attributes['Security']
+        attributes
+      end
+
+    end # class << self
+  end
+end

data/lib/MacOS/Applications.rb

@@ -0,0 +1,73 @@
+# MacOS/Applications.rb
+# MacOS::Applications
+
+# Description: Locates and detects installed .app application bundles across the system, local, and user
+# file-system domains, in the manner of `which` for command-line executables.
+
+require 'MacOS/Users'
+
+module MacOS
+  module Applications
+    module_function
+
+    def paths(username = ENV['USER'])
+      system_paths +
+        system_utility_paths +
+        local_paths +
+        local_utility_paths +
+        user_paths(username)
+    end
+
+    def system_paths
+      in_directory('/System/Applications')
+    end
+
+    def system_utility_paths
+      in_directory('/System/Applications/Utilities')
+    end
+
+    def local_paths
+      in_directory('/Applications')
+    end
+
+    def local_utility_paths
+      in_directory('/Applications/Utilities')
+    end
+
+    def user_paths(username = ENV['USER'])
+      under_directory("/Users/#{username}/Applications")
+    end
+
+    def all_user_paths
+      MacOS::Users.all.collect{|username| user_paths(username)}.flatten
+    end
+
+    def in_directory(directory)
+      Dir["#{directory}/*.app"]
+    end
+
+    def under_directory(directory)
+      Dir["#{directory}/**/*.app"].reject{|path| path.sub(/\.app$/, '').match?(/\.app\//)}
+    end
+
+    def path_for(application_name)
+      paths.detect do |path|
+        File.basename(path) == application_name ||
+          File.basename(path, '.app') == application_name
+      end
+    end
+
+    def installed?(application_name)
+      path_for(application_name) ? true : false
+    end
+
+    def start(application_name)
+      return unless path = path_for(application_name)
+      system('open', path, exception: true)
+    end
+    alias_method :launch, :start
+    alias_method :open, :start
+    alias_method :run, :start
+    module_function :launch, :open, :run
+  end
+end

data/lib/MacOS/Defaults/ComAppleDock.rb

@@ -0,0 +1,153 @@
+# MacOS/Defaults/ComAppleDock.rb
+# MacOS::Defaults::ComAppleDock
+
+require 'plist'
+require 'yaml'
+
+module MacOS
+  class Defaults
+    module ComAppleDock
+      ARRAY_ATTRIBUTES = %w{
+        persistent-apps
+        persistent-others
+        recent-apps
+      }
+      BOOLEAN_ATTRIBUTES = %w{
+        autohide
+        expose-group-apps
+        launchanim
+        magnification
+        minimize-to-application
+        show-process-indicators
+        single-app
+        trash-full
+      }
+      INTEGER_ATTRIBUTES = %w{
+        tilesize
+      }
+      STRING_ATTRIBUTES = %w{
+        mineffect
+        orientation
+      }
+      ALL_ATTRIBUTES = (ARRAY_ATTRIBUTES + BOOLEAN_ATTRIBUTES + INTEGER_ATTRIBUTES + STRING_ATTRIBUTES).sort
+
+      class << self
+        def app_plist_data(urlified_app_string)
+          <<~APP_PLIST
+            <dict>
+              <key>tile-data</key>
+              <dict>
+                <key>file-data</key>
+                <dict>
+                  <key>_CFURLString</key>
+                  <string>#{urlified_app_string}</string>
+                  <key>_CFURLStringType</key>
+                  <integer>15</integer>
+                </dict>
+              </dict>
+            </dict>
+          APP_PLIST
+        end
+
+        def urlified_app_string(item)
+          "file://#{File.expand_path(item)}"
+        end
+
+        def persistent_app_write_command(app_plist_data)
+          "defaults write com.apple.dock persistent-apps -array-add '#{app_plist_data}'"
+        end
+
+        def add_persistent_app(persistent_app_path)
+          system(
+            persistent_app_write_command(
+              app_plist_data(
+                urlified_app_string(
+                  persistent_app_path
+                )
+              )
+            )
+          )
+        end
+
+        def load_persistent_apps(persistent_app_paths)
+          persistent_app_paths.each do |persistent_app_path|
+            add_persistent_app(persistent_app_path)
+          end
+        end
+
+        def delete_all_items
+          delete_item('persistent-apps')
+          delete_item('persistent-others')
+          delete_item('recent-apps')
+        end
+
+        def delete_item(scope)
+          system("defaults delete com.apple.dock #{scope}")
+        end
+
+        def attribute_write_command(attr, value)
+          value = (
+            if BOOLEAN_ATTRIBUTES.include?(attr) # Without adding -bool it doesn't work.
+              "-bool #{value}"
+            elsif INTEGER_ATTRIBUTES.include?(attr) # Adding -int isn't strictly necessary for it to work, but is correct syntax.
+              "-int #{value}"
+            else
+              value
+            end
+          )
+          "defaults write com.apple.dock #{attr} #{value}"
+        end
+
+        def load_attribute(attr, value)
+          system(attribute_write_command(attr, value))
+        end
+
+        def load(dock_config)
+          dock_config.each do |attr, value|
+            if attr == 'persistent-apps'
+              load_persistent_apps(value)
+            else
+              load_attribute(attr, value)
+            end
+          end
+        end
+
+        def peristent_app_paths(plist)
+          plist['persistent-apps'].map do |persistent_app|
+            file_url = persistent_app['tile-data']['file-data']['_CFURLString']
+            file_url.sub(/file:\/\//, '').gsub(/%20/, ' ').sub(/\/Users\/.+?(\/.+)\//, '~\1')
+          end
+        end
+
+        def boolean_to_yes_no(boolean_string)
+          case boolean_string
+          when true; 'yes'
+          when false; 'no'
+          end
+        end
+
+        def read(*attributes)
+          return_value = {}
+          plist = Plist.parse_xml(`defaults export com.apple.dock -`)
+          attribute_list = (attributes.empty? ? ALL_ATTRIBUTES : attributes)
+          attribute_list.each do |attribute|
+            next if %w{persistent-others recent-apps}.include?(attribute)
+            if attribute == 'persistent-apps'
+              return_value[attribute] = peristent_app_paths(plist)
+            elsif BOOLEAN_ATTRIBUTES.include?(attribute)
+              return_value[attribute] = boolean_to_yes_no(plist[attribute])
+            else
+              return_value[attribute] = plist[attribute]
+            end
+          end
+          return_value
+        end
+
+        def to_yaml
+          YAML.dump(read).gsub(/['"]/, '')
+        end
+        alias_method :dump, :to_yaml
+      end
+    end
+  end
+end

data/lib/MacOS/Defaults/NSGlobalDomain/NSUserKeyEquivalents.rb

@@ -0,0 +1,109 @@
+# MacOS/Defaults/NSGlobalDomain/NSUserKeyEquivalents.rb
+# MacOS::Defaults::NSGlobalDomain::NSUserKeyEquivalents
+
+require 'set'
+require 'yaml'
+
+module MacOS
+  class Defaults
+    module NSGlobalDomain
+      class NSUserKeyEquivalents
+        KEY_MAP = {
+          [:cmd, :command, :command_key] => '@',
+          [:alt, :alt_key, :option, :option_key] => '~',
+          [:ctrl, :control, :control_key] => '^',
+          [:shift, :shift_key] => '$',
+          [:left, :left_key, :left_arrow, :left_arrow_key] => '\UF702', # Also '\U2190'?
+          [:right, :right_key, :right_arrow, :right_arrow_key] => '\UF703', # Also '\U2192'?
+        }
+
+        class << self
+          def key_code(*keys)
+            return_value = []
+            keys.flatten.each do |key|
+              if ('a'..'z').include?(key.to_s.downcase)
+                return_value << key.downcase
+              elsif matching_pair = KEY_MAP.find{|key_mapping| key_mapping.first.map(&:to_s).map(&:downcase).include?(key.to_s.downcase)}
+                return_value << matching_pair.last
+              else
+                raise "No key #{key} found."
+              end
+            end
+            return_value.join
+          end
+
+          def assign_key_code_command_string(key_code, menu_item)
+            "defaults write NSGlobalDomain NSUserKeyEquivalents -dict-add '#{menu_item}' '#{key_code}'"
+          end
+
+          def assign_key_code_command_strings(key_code, menu_item_or_items)
+            return_value = []
+            [menu_item_or_items].flatten.each do |menu_item|
+              return_value << assign_key_code_command_string(key_code, menu_item)
+            end
+            return_value
+          end
+
+          def assign_key_code(key_code, menu_item_or_items)
+            return_value = true
+            assign_key_code_command_strings(key_code, menu_item_or_items).each do |assign_key_code_command_string|
+              system(assign_key_code_command_string)
+              return_value = return_value && $?.success?
+            end
+            return_value
+          end
+
+          def assign_keys(key_or_keys, menu_item_or_items)
+            assign_key_code(key_code(key_or_keys), menu_item_or_items)
+          end
+
+          def load(shortcuts)
+            shortcuts.map do |shortcut|
+              assign_keys(shortcut[:keys], shortcut[:menu_items])
+            end
+          end
+
+          def parse_key_code(key_code)
+            key_code.split('\U')
+          end
+
+          def read_keys
+            return_value = []
+            plist_dict = `defaults read .GlobalPreferences NSUserKeyEquivalents -`
+            menu_item_to_keys_map = plist_dict.lines.grep(/=/).map{|e| e.split('=')}.map{|k,v| [k.strip, v.strip]}.map{|k,v| [k.tr('"',''), v.tr('"','')]}
+            menu_item_to_keys_map.each do |shortcut|
+              menu_item, key_code = shortcut.first, shortcut.last
+              md = key_code.match(/([\@~\^\$]+)(.+);/)
+              modifier_key_codes, key_code = md[1], md[2]
+              modifier_key_names = modifier_key_codes.split('').map{|e| KEY_MAP.find{|km| km.last == e}.first.first}
+              key_code = key_code.sub(/\\/, '')
+              key_name = (
+                if ('a'..'z').include?(key_code)
+                  key_code
+                else
+                  KEY_MAP.find do |km|
+                    km.last == key_code.upcase
+                  end.first.first
+                end
+              )
+              keys = [modifier_key_names, key_name].flatten
+              found_shortcut = return_value.find{|e| Set.new(e[:keys]) == Set.new(keys)}
+              if found_shortcut = return_value.find{|e| Set.new(e[:keys]) == Set.new(keys)}
+                index = return_value.index(found_shortcut)
+                return_value[index][:menu_items] << menu_item
+              else
+                return_value << {keys: keys, menu_items: [menu_item]}
+              end
+            end
+            return_value.reverse
+          end
+
+          def to_yaml
+            YAML.dump(read_keys)
+          end
+          alias_method :dump, :to_yaml
+        end
+      end
+    end
+  end
+end

data/lib/MacOS/Defaults.rb

@@ -0,0 +1,126 @@
+# MacOS/Defaults.rb
+# MacOS::Defaults
+
+# Todo:
+# 1. Handle compound/vector values in to_yaml().  Currently dumping hashes when it should be creating another level or more levels of hierarchy.
+
+# Transformations:
+# 1. database <--> plist
+# 2. plist <--> hash
+# 3. yaml <--> database
+
+
+require 'cfpropertylist'
+require 'yaml'
+
+module MacOS
+  class Defaults
+
+    DEFAULT_PLIST_DIRECTORY = '/tmp'
+    DEFAULT_YAML_FILENAME = File.expand_path(File.join('~', '.config', 'osx_defaults.yml'))
+
+    class << self
+
+      def domains
+        `defaults domains`.chomp.split(', ')
+      end
+      alias_method :all_domains, :domains
+
+      def all
+        domains.collect do |domain|
+          self.new(domain: domain)
+        end
+      end
+
+      def bulk_export_to_plist_files
+        domains.each do |domain|
+          self.new(domain: domain).export
+        end
+      end
+
+      def bulk_import_from_plist_files
+        domains.each do |domain|
+          self.new(domain: domain).import
+        end
+      end
+
+      def from_yaml(yaml_filename = nil)
+        yaml_filename ||= DEFAULT_YAML_FILENAME
+        yaml_defaults = YAML.load_file(yaml_filename)
+        yaml_defaults.each do |domain, attributes|
+          self.new(domain: domain).from_yaml(attributes)
+        end
+      end
+
+    end # class << self
+
+    def initialize(**args)
+      @domain = args[:domain]
+    end
+
+    def export
+      if domain_valid?
+        `defaults export #{@domain} #{DEFAULT_PLIST_DIRECTORY}/#{@domain}.plist`
+      else
+        raise "Domain: #{@domain} was not found in the defaults database."
+      end
+      true
+    end
+
+    def import
+      if File.exist?("#{DEFAULT_PLIST_DIRECTORY}/#{@domain}.plist")
+        `defaults import #{@domain} #{DEFAULT_PLIST_DIRECTORY}/#{@domain}.plist`
+      else
+        raise "File: #{DEFAULT_PLIST_DIRECTORY}/#{@domain}.plist was not found in the filesystem."
+      end
+      true
+    end
+
+    def to_h
+      plist = CFPropertyList::List.new(file: "#{DEFAULT_PLIST_DIRECTORY}/#{@domain}.plist")
+      CFPropertyList.native_types(plist.value)
+    end
+
+    def to_yaml(yaml_parts = [], hash = to_h, recursion_depth = 1)
+      yaml_parts << "#{@domain}:" if recursion_depth == 1
+      hash.each do |k,v|
+        to_yaml(yaml_parts, v, recursion_depth += 1) if v.is_a?(Hash)
+        indent = ' ' * recursion_depth * 2
+        yaml_parts << "#{indent}- #{k}: #{v}"
+      end
+      yaml_parts.join("\n")
+    end
+    alias_method :to_yml, :to_yaml
+
+    # Writes each attribute, as to_yaml writes them, a list of single key: value pairs, true where every write succeeds.
+    def from_yaml(attributes)
+      attributes.map do |attribute|
+        key, value = attribute.to_a.first
+        system('defaults', 'write', @domain, key.to_s, *defaults_arguments(value))
+      end.all?
+    end
+
+    def domain_valid?
+      self.class.domains.include?(@domain) || global_domain?
+    end
+
+    def global_domain?
+      @domain == '-globalDomain'
+    end
+
+    private
+
+    # A value as defaults write takes it, its type given first.
+    def defaults_arguments(value)
+      case value
+      when true, false then ['-bool', value.to_s]
+      when Integer then ['-int', value.to_s]
+      when Float then ['-float', value.to_s]
+      when Array then ['-array', *value.map(&:to_s)]
+      when Hash then ['-dict', *value.flat_map{|k, v| [k.to_s, v.to_s]}]
+      else ['-string', value.to_s]
+      end
+    end
+
+  end
+end