corefoundation 0.2.0 → 0.3.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0643a8f8fa6e54707a3f01f8ee355d087dbd5c489a5421ce71ff99fb56efe02f
+  data.tar.gz: '0168e360dc7c45ea8523198fffd2b133d4de7965f764063a3806caa9ccd37cfb'
+SHA512:
+  metadata.gz: 72c31cff02be17a7864bdc57bc77c3cb8af9becad10fa33f0358d9b1765fb3edafce7de53ebfc9fc61c8e9125bca5e0f70e7b20674ad52c555bbeddae1d6c0a3
+  data.tar.gz: f70c46f8d528a0783486f0ab7615332bfe52d4fbe841171aefa289fb48675e92bfa48b3c8b164b5d49227bd55f7f8b170059d78dd696242939fe074f39bef9c9

data/lib/corefoundation/array.rb

@@ -49,7 +49,7 @@ module CF
       range[:location] = 0
       range[:length] = length
       callback = lambda do |value, _|
-        yield Base.typecast(value).retain.release_on_gc
+        yield Base.typecast(value).retain
       end
       CF.CFArrayApplyFunction(self, range, callback, nil)
       self
@@ -64,13 +64,13 @@ module CF
       end
       m = FFI::MemoryPointer.new(:pointer, array.length)
       m.write_array_of_pointer(array)
-      new(CF.CFArrayCreate(nil,m,array.length,CF::kCFTypeArrayCallBacks.to_ptr)).release_on_gc
+      new(CF.CFArrayCreate(nil,m,array.length,CF::kCFTypeArrayCallBacks.to_ptr))
     end
 
     # Creates a new, empty mutable CFArray
     # @return [CF::Array] A mutable CF::Array containing the objects, setup to release the array upon garbage collection
     def self.mutable
-      result = new(CF.CFArrayCreateMutable nil, 0, CF::kCFTypeArrayCallBacks.to_ptr).release_on_gc
+      result = new(CF.CFArrayCreateMutable nil, 0, CF::kCFTypeArrayCallBacks.to_ptr)
       result.instance_variable_set(:@mutable, true)
       result
     end
@@ -79,7 +79,7 @@ module CF
     # @param [Integer] index the 0 based index of the item to retrieve. Behaviour is undefined if it is not in the range 0...size
     # @return [CF::Base] a subclass of CF::Base
     def [](index)
-      Base.typecast(CF.CFArrayGetValueAtIndex(self, index)).retain.release_on_gc
+      Base.typecast(CF.CFArrayGetValueAtIndex(self, index)).retain
     end
 
     # Sets object at the index
@@ -92,7 +92,6 @@ module CF
       raise TypeError, "instance is not mutable" unless mutable?
       self.class.check_cftype(value)
       CF.CFArraySetValueAtIndex(self, index, value)
-      value
     end
 
     # Appends a value to the array

data/lib/corefoundation/base.rb

@@ -1,101 +1,43 @@
+# frozen_string_literal: true
 
 # The top level namespace for the corefoundation library. The raw FFI generated methods are attached here
-#
-#
 module CF
-  extend FFI::Library
-  ffi_lib '/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation'
+  # The base class for all of the wrapper classes in CF module.
+  class Base
+    using CF::Refinements
 
-  if FFI::Platform::ARCH == 'x86_64'
-    typedef :long_long, :cfindex
-    typedef :long_long, :cfcomparisonresult
-    typedef :ulong_long, :cfoptionflags
-    typedef :ulong_long, :cftypeid
-    typedef :ulong_long, :cfhashcode
-  else
-    typedef :long, :cfindex
-    typedef :long, :cfcomparisonresult
-    typedef :ulong, :cfoptionflags
-    typedef :ulong, :cftypeid
-    typedef :ulong, :cfhashcode
-  end
-
-
-  # @private
-  class Range < FFI::Struct
-    layout :location, :cfindex,
-           :length, :cfindex
-  end
-
-  typedef :pointer, :cftyperef
-
-  #general utility functions
-  attach_function :show, 'CFShow', [:cftyperef], :void
-  attach_function :release, 'CFRelease', [:cftyperef], :void
-  attach_function :retain, 'CFRetain', [:cftyperef], :cftyperef
-  attach_function 'CFEqual', [:cftyperef, :cftyperef], :char
-  attach_function 'CFHash', [:cftyperef], :cfhashcode
-  attach_function 'CFCopyDescription', [:cftyperef], :cftyperef
-  attach_function 'CFGetTypeID', [:cftyperef], :cftypeid
-
-  # The base class for all of the wrapper classes 
-  #
-  # @abstract
-  class Base  
     @@type_map = {}
+    include CF::Register
+    include CF::Memory
 
-    # @private
-    class Releaser
-      def initialize(ptr)
-        @address  = ptr.address
-      end
+    attr_reader :ptr
 
-      def call *ignored
-        if @address != 0
-          CF.release(@address)
-          @address = 0
-        end
-      end
+    # Raises an exception if the argument does not inherit from CF::Base
+    #
+    # @param cftyperef object to check
+    def self.check_cftype(cftyperef)
+      raise TypeError, "#{cftyperef.inspect} is not a cftype" unless cftyperef.is_a?(CF::Base)
     end
 
-    class << self
-      # Raises an exception if the argument does not inherit from CF::Base
-      #
-      # @param cftyperef object to check
-      def check_cftype(cftyperef)
-        raise TypeError, "#{cftyperef.inspect} is not a cftype" unless cftyperef.is_a?(CF::Base)
-      end
-
-      # Wraps an FFI::Pointer with the appropriate subclass of CF::Base
-      # If the pointer is not a CFTypeRef behaviour is undefined
-      # @param [FFI::Pointer] cftyperef Object to wrap
-      # @return A wrapper object inheriting from CF::Base
-      def typecast(cftyperef)
-        klass = klass_from_cf_type cftyperef
-        klass.new(cftyperef)
-      end
-
-      private
-      def klass_from_cf_type cftyperef
-        klass = @@type_map[CF.CFGetTypeID(cftyperef)]
-        if !klass
-          raise TypeError, "No class registered for cf type #{cftyperef.inspect}"
-        end
-        klass
-      end
-
-      def register_type(type_name)
-        CF.attach_function "#{type_name}GetTypeID", [], :cftypeid
-        @@type_map[CF.send("#{type_name}GetTypeID")] = self
-      end
+    # Wraps an FFI::Pointer with the appropriate subclass of CF::Base
+    # If the pointer is not a CFTypeRef behaviour is undefined
+    #
+    # @param [FFI::Pointer] cftyperef Object to wrap
+    # @return A wrapper object inheriting from CF::Base
+    def self.typecast(cftyperef)
+      klass = klass_from_cf_type cftyperef
+      klass.new(cftyperef)
+    end
 
+    # @param [FFI::Pointer] pointer The pointer to wrap
+    def initialize(pointer)
+      @ptr = FFI::Pointer.new(pointer)
+      ObjectSpace.define_finalizer(self, self.class.finalize(ptr))
     end
 
-    # 
-    #
-    # @param [FFI::Pointer] ptr The pointer to wrap
-    def initialize(ptr)
-      @ptr = FFI::Pointer.new(ptr)
+    # @param [FFI::Pointer] pointer to the address of the object
+    def self.finalize(pointer)
+      proc { CF.release(pointer) unless pointer.address.zero }
     end
 
     # Whether the instance is the CFNull singleton
@@ -105,49 +47,6 @@ module CF
       equals?(CF::NULL)
     end
 
-    # Returns the wrapped pointer
-    # @return [FFI::Pointer]
-    def to_ptr
-      @ptr
-    end
-
-    # Sets the wrapper pointer. You should only do this rarely. If you have used release_on_gc then that
-    # finalizer will still be called on the original pointer value
-    #
-    def ptr= ptr
-      @ptr = ptr
-    end
-
-    # Calls CFRetain on the wrapped pointer
-    # @return Returns self
-    def retain
-      CF.retain(self)
-      self
-    end
-
-    # Calls CFRelease on the wrapped pointer
-    # @return Returns self
-    def release
-      CF.release(self)
-      self
-    end
-
-    # Installs a finalizer on the wrapper object that will cause it to call CFRelease on the pointer
-    # when the wrapper is garbage collected
-    # @return Returns self
-    def release_on_gc
-      ObjectSpace.define_finalizer(@ptr, Releaser.new(@ptr))
-      self
-    end
-
-    # Returns a ruby string containing the output of CFCopyDescription for the wrapped object
-    #
-    # @return [String]
-    def inspect
-      cf = CF::String.new(CF.CFCopyDescription(self))
-      cf.to_s.tap {cf.release}
-    end
-
     # Uses CFHash to  return a hash code
     #
     # @return [Integer]
@@ -156,8 +55,6 @@ module CF
     end
 
     # eql? (and ==) are implemented using CFEqual
-    #
-    #
     def eql?(other)
       if other.is_a?(CF::Base)
         CF.CFEqual(self, other) != 0
@@ -165,10 +62,10 @@ module CF
         false
       end
     end
-    
+
+    alias == :eql?
+
     # equals? is defined as returning true if the wrapped pointer is the same
-    #
-    #
     def equals?(other)
       if other.is_a?(CF::Base)
         @ptr.address == other.to_ptr.address
@@ -176,22 +73,21 @@ module CF
         false
       end
     end
-    
-    alias_method :==, :eql?
 
-    # Converts the CF object into a ruby object. Subclasses typically override this to return
-    # an appropriate object (for example CF::String returns a String)
-    #
     def to_ruby
-      self
+      raise CF::Exceptions::MethodNotImplemented, "#{self.class} should implement the to_ruby method."
     end
 
-    # to_cf is a no-op on CF::Base and its descendants - it always returns self
-    #
+    # This is a no-op on CF::Base and its subclasses. Always returns self.
     #
+    # @return Returns self
     def to_cf
       self
     end
-  end
 
+    private
+    def self.type_map
+      @@type_map
+    end
+  end
 end

data/lib/corefoundation/data.rb

@@ -15,7 +15,7 @@ module CF
     # @param [String] s the string to use
     # @return [CF::Data]
     def self.from_string(s)
-      new(CF.CFDataCreate(nil, s, s.bytesize)).release_on_gc
+      new(CF.CFDataCreate(nil, s, s.bytesize))
     end
 
     # Creates a ruby string from the wrapped data. The encoding will always be ASCII_8BIT
@@ -23,11 +23,7 @@ module CF
     # @return [String]
     def to_s
       ptr = CF.CFDataGetBytePtr(self)
-      if CF::String::HAS_ENCODING
-        ptr.read_string(CF.CFDataGetLength(self)).force_encoding(Encoding::ASCII_8BIT)
-      else
-        ptr.read_string(CF.CFDataGetLength(self))
-      end
+      ptr.read_string(CF.CFDataGetLength(self)).force_encoding(Encoding::ASCII_8BIT)
     end
 
     # The size in bytes of the CFData

data/lib/corefoundation/date.rb

@@ -17,7 +17,7 @@ module CF
     # @param [Time] time
     # @return [CF::Date] a CF::Date instance that will be released on garbage collection
     def self.from_time(time)
-      new(CF.CFDateCreate(nil, time.to_f - CF.kCFAbsoluteTimeIntervalSince1970)).release_on_gc
+      new(CF.CFDateCreate(nil, time.to_f - CF.kCFAbsoluteTimeIntervalSince1970))
     end
 
     # returns a ruby Time instance corresponding to the same point in time

data/lib/corefoundation/dictionary.rb

@@ -46,7 +46,7 @@ module CF
     #
     # @return [CF::Dictionary]
     def self.mutable
-      new(CF.CFDictionaryCreateMutable nil, 0, CF.kCFTypeDictionaryKeyCallBacks.to_ptr, CF.kCFTypeDictionaryValueCallBacks.to_ptr).release_on_gc
+      new(CF.CFDictionaryCreateMutable nil, 0, CF.kCFTypeDictionaryKeyCallBacks.to_ptr, CF.kCFTypeDictionaryValueCallBacks.to_ptr)
     end
 
     # Iterates over the array yielding the value to the block
@@ -55,7 +55,7 @@ module CF
 
     def each
       callback = lambda do |key, value, _|
-        yield [Base.typecast(key).retain.release_on_gc, Base.typecast(value).retain.release_on_gc]
+        yield [Base.typecast(key).retain, Base.typecast(value).retain]
       end
       CF.CFDictionaryApplyFunction(self, callback, nil)
       self
@@ -70,7 +70,7 @@ module CF
       key = CF::String.from_string(key) if key.is_a?(::String)
       self.class.check_cftype(key)
       raw = CF.CFDictionaryGetValue(self, key)
-      raw.null? ? nil : self.class.typecast(raw).retain.release_on_gc
+      raw.null? ? nil : self.class.typecast(raw).retain
     end
 
     # Sets the value associated with the key, or nil
@@ -83,7 +83,6 @@ module CF
       self.class.check_cftype(key)
       self.class.check_cftype(value)
       CF.CFDictionarySetValue(self, key, value)
-      value
     end
 
     # Adds the key value pairs from the argument to self

data/lib/corefoundation/exceptions.rb

@@ -0,0 +1,16 @@
+module CF
+  module Exceptions
+    # Raised when the preference value couldn't be found for a domain.
+    class PreferenceDoesNotExist < StandardError
+      def initialize(key, domain, hostname = nil)
+        super("Returned NULL value for \"#{key}\" in \"#{domain}\"#{", hostname: #{hostname}" if hostname}")
+      end
+    end
+    # Raised when the preference value failed to write.
+    class PreferenceSyncFailed < StandardError
+      def initialize(key, domain, hostname = nil)
+        super("Couldn't write preference value for \"#{key}\" in \"#{domain}\"#{", hostname: #{hostname}" if hostname}")
+      end
+    end
+  end
+end

data/lib/corefoundation/memory.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# The top level namespace for the corefoundation library. The raw FFI generated methods are attached here
+module CF
+  attach_function :show, 'CFShow', [:cftyperef], :void
+  attach_function :release, 'CFRelease', [:cftyperef], :void
+  attach_function :retain, 'CFRetain', [:cftyperef], :cftyperef
+  attach_function 'CFEqual', [:cftyperef, :cftyperef], :char
+  attach_function 'CFHash', [:cftyperef], :cfhashcode
+  attach_function 'CFCopyDescription', [:cftyperef], :cftyperef
+  attach_function 'CFGetTypeID', [:cftyperef], :cftypeid
+
+  # Provides a more declarative way to define all required abstract methods.
+  # This gets included in the CF::Base class whose subclasses then need to define those methods.
+  module Memory
+
+    # Returns a ruby string containing the output of CFCopyDescription for the wrapped object
+    #
+    # @return [String]
+    def inspect
+      CF::String.new(CF.CFCopyDescription(self)).to_s
+    end
+
+    # Calls CFRelease on the wrapped pointer
+    #
+    # @return Returns self
+    def release
+      CF.release(self)
+      self
+    end
+
+    # Calls CFRetain on the wrapped pointer
+    #
+    # @return Returns self
+    def retain
+      CF.retain(self)
+      self
+    end
+
+    # Returns the wrapped pointer
+    #
+    # @return [FFI::Pointer]
+    def to_ptr
+      ptr
+    end
+  end
+end

data/lib/corefoundation/number.rb

@@ -39,7 +39,7 @@ module CF
     def self.from_f(float)
       p = FFI::MemoryPointer.new(:double)
       p.write_double(float.to_f)
-      new(CF.CFNumberCreate(nil, :kCFNumberDoubleType, p)).release_on_gc
+      new(CF.CFNumberCreate(nil, :kCFNumberDoubleType, p))
     end
 
     # Constructs a CF::Number from an integer
@@ -48,7 +48,7 @@ module CF
     def self.from_i(int)
       p = FFI::MemoryPointer.new(:int64)
       p.put_int64(0,int.to_i)
-      new(CF.CFNumberCreate(nil, :kCFNumberSInt64Type, p)).release_on_gc
+      new(CF.CFNumberCreate(nil, :kCFNumberSInt64Type, p))
     end
 
     # Compares the receiver with the argument

data/lib/corefoundation/preferences.rb

@@ -0,0 +1,134 @@
+module CF
+  typedef :pointer, :cfpropertylistref
+  typedef :cfstringref, :key
+  typedef :cfstringref, :application_id
+  typedef :cfstringref, :username
+  typedef :cfstringref, :hostname
+  typedef :cfpropertylistref, :value
+
+  attach_variable 'kCFPreferencesCurrentUser', :cfstringref
+  attach_variable 'kCFPreferencesAnyUser', :cfstringref
+  attach_variable 'kCFPreferencesCurrentHost', :cfstringref
+  attach_variable 'kCFPreferencesAnyHost', :cfstringref
+
+  attach_function 'CFPreferencesCopyAppValue', [:key, :application_id], :cfpropertylistref
+  attach_function 'CFPreferencesCopyValue', [:key, :application_id, :username, :hostname], :cfpropertylistref
+
+  attach_function 'CFPreferencesSetAppValue', [:key, :value, :application_id], :void
+  attach_function 'CFPreferencesSetValue', [:key, :value, :application_id, :username, :hostname], :void
+
+  attach_function 'CFPreferencesAppSynchronize', [:application_id], :bool
+
+  # Interface to the preference utilities from Corefoundation.framework.
+  # Documentation at https://developer.apple.com/documentation/corefoundation/preferences_utilities
+  #
+  class Preferences
+    using CF::Refinements
+
+    CURRENT_USER = CF.kCFPreferencesCurrentUser
+    ALL_USERS = CF.kCFPreferencesAnyUser
+    CURRENT_HOST = CF.kCFPreferencesCurrentHost
+    ALL_HOSTS = CF.kCFPreferencesAnyHost
+
+    class << self
+      # Returns the output from `CFPreferencesCopyValue` call after converting it to ruby type.
+      #
+      # @param [String] key Preference key to read
+      # @param [String] application_id Preference domain for the key
+      # @param [String, Symbol] username Domain user (current, any or a specific user)
+      # @param [String, Symbol] hostname Hostname (current, all hosts or a specific host)
+      #
+      # @return [VALUE] Preference value returned from the `CFPreferencesCopyValue` call.
+      #
+      def get(key, application_id, username = nil, hostname = nil)
+        plist_ref = if username && hostname
+                      CF.CFPreferencesCopyValue(
+                        key.to_cf,
+                        application_id.to_cf,
+                        arg_to_cf(username),
+                        arg_to_cf(hostname)
+                      )
+                    else
+                      CF.CFPreferencesCopyAppValue(key.to_cf, application_id.to_cf)
+                    end
+        CF::Base.typecast(plist_ref).to_ruby unless plist_ref.null?
+      end
+
+      # Calls the {#self.get} method and raise a `PreferenceDoesNotExist` error if `nil` is returned.
+      #
+      # @param [String] key Preference key to read
+      # @param [String] application_id Preference domain for the key
+      # @param [String, Symbol] username Domain user (current, any or a specific user)
+      # @param [String, Symbol] hostname Hostname (current, all hosts or a specific host)
+      #
+      # @raise [PreferenceDoesNotExist] If returned value is nil.
+      #
+      # @return [VALUE] Preference value returned from the {#self.get} method call.
+      #
+      def get!(key, application_id, username = nil, hostname = nil)
+        value = get(key, application_id, username, hostname)
+        if value.nil?
+          raise(CF::Exceptions::PreferenceDoesNotExist.new(key, application_id, hostname))
+        else
+          value
+        end
+      end
+
+      # Set the value for preference domain using `CFPreferencesSetValue`.
+      #
+      # @param [String] key Preference key
+      # @param [Integer, Float, String, TrueClass, FalseClass, Hash, Array] value Preference value
+      # @param [String] application_id Preference domain
+      # @param [String, Symbol] username Domain user (current, any or a specific user)
+      # @param [String, Symbol] hostname Hostname (current, all hosts or a specific host)
+      #
+      # @return [TrueClass, FalseClass] Returns true if preference was successfully written to storage, otherwise false.
+      #
+      def set(key, value, application_id, username = nil, hostname = nil)
+        if username && hostname
+          CF.CFPreferencesSetValue(
+            key.to_cf,
+            arg_to_cf(value),
+            application_id.to_cf,
+            arg_to_cf(username),
+            arg_to_cf(hostname)
+          )
+        else
+          CF.CFPreferencesSetAppValue(
+            key.to_cf,
+            arg_to_cf(value),
+            application_id.to_cf
+          )
+        end
+        CF.CFPreferencesAppSynchronize(application_id.to_cf)
+      end
+
+      # Calls the {#self.set} method and raise a `PreferenceSyncFailed` error if `false` is returned.
+      #
+      # @param [String] key Preference key to write
+      # @param [String] application_id Preference domain for the key
+      # @param [String, Symbol] username Domain user (current, any or a specific user)
+      # @param [String, Symbol] hostname Hostname (current, all hosts or a specific host)
+      #
+      # @raise [PreferenceSyncFailed] If {#self.set} call returned false.
+      #
+      # @return [VALUE] Returns nil if preference value is successfully written.
+      #
+      def set!(key, value, application_id, username = nil, hostname = nil)
+        raise(CF::Exceptions::PreferenceSyncFailed.new(key, application_id, hostname)) unless set(key, value, application_id, username, hostname)
+      end
+
+      private
+      # Convert an object from ruby to cf type.
+      #
+      # @param [VALUE, CFType] arg A ruby or corefoundation object.
+      #
+      # @return [CFType] A wrapped CF object.
+      #
+      # @visiblity private
+      def arg_to_cf(arg)
+        arg.respond_to?(:to_cf) ? arg.to_cf : arg
+      end
+    end
+  end
+end

data/lib/corefoundation/range.rb

@@ -0,0 +1,10 @@
+module CF
+  #
+  # Maps to the corefoundation structure CFRange.
+  # See usage in CF::Array and CF::String.
+  #
+  class Range < FFI::Struct
+    layout :location, :cfindex,
+           :length, :cfindex
+  end
+end