corefoundation 0.1.4

data/LICENSE

@@ -0,0 +1,8 @@
+The MIT License
+Copyright (c) 2012 Frederick Cheung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,39 @@
+
+CoreFoundation
+==============
+
+FFI based wrappers for a subset of core foundation: various bits of CFString, CFData, CFArray, CFDictionary are available. Not that useful on its own but a useful building block for writing ffi wrappers of other OS X libraries.
+
+Although the CF collection classes can store arbitrary pointer sized values this wrapper only supports storing CFTypes.
+
+The CF namespace has the raw FFI generated method calls but it's usually easier to use the wrapper classes: `CF::String`, `CF::Date`, `CF::Array`, `CF::Dictionary`, `CF::Boolean` which try to present a rubyish view of the world (for example `CF::Array` implements `Enumerable`)
+
+These implement methods for creating new instances from ruby objects (eg `CF::String.from_string("hello world")`) but you can also pass build them from an `FFI::Pointer`).
+
+Converting
+===========
+
+`CF::Base` objects has a `to_ruby` that creates a ruby object of the most approprite type (`String` for `CF::String`, `Time` for `CF::Date`, `Integer` or `Float` for `CF::Number` etc). The collection classes call `to_ruby` on their contents too.
+
+In addition to the methods on the wrapper classes themselves, the ruby classes are extended with a `to_cf` method. Because CoreFoundation strings aren't arbitrary collections of bytes, `String#to_cf` will return a `CF::Data` if the string has the ASCII-8BIT encoding and a `CF::String` if not.
+
+If you have an `FFI::Pointer` or a raw address then you can create a wrapper by passing it to `new`, for example `CF::String.new(some_pointer)`. This does *not* check that the pointer is actually a `CFString`. You can use `CF::Base.typecast` to construct an instance of the appropriate subclass, for example `CF::Base.typecast(some_pointer)` would return a `CF::String` if `some_pointer` was in fact a `CFStringRef`.
+
+Memory Management
+=================
+
+The convenience methods for creating CF objects will release the cf object when they are garbage collected. Methods on the convenience classes will usually retain the result and mark it for releasing when they are garbage collected (for example `CF::Dictionary#[]` retains the returned value). You don't need to do any extra memory management on these.
+
+If you pass an `FFI::Pointer` to `new` or `typecast` no assumptions are made for you. You should call `retain` or `release` to manage it manually. As an alternative to calling `release` manually,  the `release_on_gc` method adds a finalizer to the wrapper that will call `CFRelease` on the Core Foundation object when the wrapper is garbage collected. You will almost certainly crash your ruby interpreter if you overrelease an object and you will leak memory if you overretain one.
+
+If you use the raw api (eg `CF.CFArrayCreate`) then you're on your own.
+
+
+Compatibility
+=============
+Requires ruby 1.9 due to use of encoding related methods. Should work in MRI and jruby. Not compatible with rubinius due to rubinius' ffi implemenation not supporting certain features.
+
+License
+=======
+
+Released under the MIT license. See LICENSE

data/lib/corefoundation.rb

@@ -0,0 +1,11 @@
+require 'ffi'
+require 'corefoundation/base'
+require 'corefoundation/null'
+require 'corefoundation/string'
+require 'corefoundation/array'
+require 'corefoundation/boolean'
+require 'corefoundation/data'
+require 'corefoundation/dictionary'
+require 'corefoundation/number'
+require 'corefoundation/date'
+require 'corefoundation/extensions'

data/lib/corefoundation/array.rb

@@ -0,0 +1,123 @@
+module CF
+  typedef :pointer, :cfarrayref
+
+  # @private
+  class ArrayCallbacks < FFI::Struct
+    layout :version, :cfindex, #cfindex
+           :retain, :pointer,
+           :release, :pointer,
+           :copyDescription, :pointer,
+           :equal, :pointer
+  end
+
+  attach_variable :kCFTypeArrayCallBacks,  ArrayCallbacks
+  attach_function :CFArrayCreate, [:pointer, :pointer, :cfindex, :pointer], :cfarrayref
+  attach_function :CFArrayCreateMutable, [:pointer, :cfindex, :pointer], :cfarrayref
+  attach_function :CFArrayGetValueAtIndex, [:pointer, :cfindex], :pointer
+  attach_function :CFArraySetValueAtIndex, [:pointer, :cfindex, :pointer], :void
+  attach_function :CFArrayAppendValue, [:pointer, :pointer], :void
+  attach_function :CFArrayGetCount, [:pointer], :cfindex
+  
+  callback :each_applier, [:pointer, :pointer], :void
+
+  attach_function :CFArrayApplyFunction, [:cfarrayref, CF::Range.by_value, :each_applier, :pointer], :void
+
+
+  # Wrapper class for CFArrayRef. It implements enumberable so you can use a lot of your favourite ruby methods on it.
+  #
+  # Values returned by the accessor methods or yielded by the block are retained and marked as releasable on garbage collection
+  # This means you can safely use the returned values even if the CFArray itself has been destroyed
+  #
+  # Unlike ruby arrays you cannot set arbitary array indexes - You can only set indexes in the range 0..length
+  class Array < Base
+    include Enumerable
+    register_type("CFArray")
+   
+    # Whether the array is mutable
+    #
+    # WARNING: this only works for arrays created by CF::Array, there is no public api for telling whether an arbitrary
+    # CFTypeRef is a mutable array or not
+    def mutable?
+      @mutable
+    end
+
+    # Iterates over the array yielding the value to the block
+    # The value is wrapped in the appropriate CF::Base subclass and retained (but marked for releasing upon garbage collection)
+    # @return self
+    def each
+      range = CF::Range.new
+      range[:location] = 0
+      range[:length] = length
+      callback = lambda do |value, _|
+        yield Base.typecast(value).retain.release_on_gc
+      end
+      CF.CFArrayApplyFunction(self, range, callback, nil)
+      self
+    end
+
+    # Creates a new, immutable CFArray from a ruby array of cf objects
+    # @param [Array<CF::Base>] array The objects to place in the array. They must inherit from CF::Base
+    # @return [CF::Array] A CF::Array containing the objects, setup to release the array upon garbage collection
+    def self.immutable(array)
+      if bad_element = array.detect {|value| !value.is_a?(CF::Base)}
+        raise TypeError, "Array contains non cftype #{bad_element.inspect}" 
+      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
+    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.instance_variable_set(:@mutable, true)
+      result
+    end
+
+    # Returns the object at the index
+    # @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
+    end
+
+    # Sets object at the index
+    # @param [Integer] index the 0 based index of the item to retrieve. Behaviour is undefined if it is not in the range 0..size
+    #   It is legal to set the value at index n of a n item array - this is equivalent to appending the object
+    #
+    # @param [CF::Base] value the value to store
+    # @return [CF::Base] the store value
+    def []=(index, value)
+      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
+    #
+    # @return [CF::Array] self
+    def <<(value)
+      raise TypeError, "instance is not mutable" unless mutable?
+      self.class.check_cftype(value)
+      CF.CFArrayAppendValue(self, value)
+      self
+    end
+
+    # Returns a ruby array containing the result of calling to_ruby on each of the array's elements
+    #
+    def to_ruby
+      collect(&:to_ruby)
+    end
+
+    alias_method :push, :<<
+
+    # Returns the number of elements the array contains
+    # @return [Integer]
+    def length
+      CF.CFArrayGetCount(self)
+    end
+    alias_method :size, :length
+  end
+end

data/lib/corefoundation/base.rb

@@ -0,0 +1,197 @@
+
+# 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'
+
+  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 = {}
+
+    # @private
+    class Releaser
+      def initialize(ptr)
+        @address  = ptr.address
+      end
+
+      def call *ignored
+        if @address != 0
+          CF.release(@address)
+          @address = 0
+        end
+      end
+    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
+
+    end
+
+    # 
+    #
+    # @param [FFI::Pointer] ptr The pointer to wrap
+    def initialize(ptr)
+      @ptr = FFI::Pointer.new(ptr)
+    end
+
+    # Whether the instance is the CFNull singleton
+    #
+    # @return [Boolean]
+    def null?
+      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]
+    def hash
+      CF.CFHash(self)
+    end
+
+    # eql? (and ==) are implemented using CFEqual
+    #
+    #
+    def eql?(other)
+      if other.is_a?(CF::Base)
+        CF.CFEqual(self, other) != 0
+      else
+        false
+      end
+    end
+    
+    # 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
+      else
+        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
+    end
+
+    # to_cf is a no-op on CF::Base and its descendants - it always returns self
+    #
+    #
+    def to_cf
+      self
+    end
+  end
+
+end

data/lib/corefoundation/boolean.rb

@@ -0,0 +1,25 @@
+module CF
+  attach_variable 'kCFBooleanTrue', :pointer
+  attach_variable 'kCFBooleanFalse', :pointer
+  attach_function 'CFBooleanGetValue', [:pointer], :uchar
+
+  # Wrapper for CFBooleanRef.
+  # Typically you use the CF::Boolean::TRUE and CF::Boolean::FALSE constants
+  #
+  class Boolean < Base
+    register_type("CFBoolean")
+    # A constant containing kCFBooleanTrue
+    TRUE = new(CF.kCFBooleanTrue)
+    # A constant containing kCFBooleanFalse
+    FALSE = new(CF.kCFBooleanFalse)
+
+    # returns a ruby true/false value
+    #
+    # @return [Boolean]
+    def value
+      CF.CFBooleanGetValue(self) != 0
+    end
+
+    alias_method :to_ruby, :value
+  end
+end

data/lib/corefoundation/data.rb

@@ -0,0 +1,38 @@
+module CF
+  typedef :pointer, :cfdataref
+
+  attach_function 'CFDataCreate', [:pointer, :buffer_in, :cfindex], :cfdataref  
+  attach_function 'CFDataGetLength', [:cfdataref], :cfindex  
+  attach_function 'CFDataGetBytePtr', [:cfdataref], :pointer
+
+  # Wrapper for CFData
+  #
+  #
+  class Data < Base
+    register_type("CFData")
+
+    # Creates a CFData from a ruby string
+    # @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
+    end
+
+    # Creates a ruby string from the wrapped data. The encoding will always be ASCII_8BIT
+    #
+    # @return [String]
+    def to_s
+      ptr = CF.CFDataGetBytePtr(self)
+      ptr.read_string(CF.CFDataGetLength(self)).force_encoding(Encoding::ASCII_8BIT)
+    end
+
+    # The size in bytes of the CFData
+    # @return [Integer]
+    def size
+      CF.CFDataGetLength(self)
+    end
+
+    alias_method :to_ruby, :to_s
+  end
+end
+