(rontolisp) docs
← Functions

objc Package Functions

The objc package binds the Objective-C runtime and AppKit through the foreign function API — no reflection, so unlike java: it works in the native binary as well as under java -jar. It is macOS only -- the interpreter, a compiled .class / .jar and a --native executable for macOS on Apple silicon, never a .wasm -- and not part of Common Lisp; reference its functions with the objc: qualifier, or use the package as LispWorks code does. Its vocabulary is LispWorks 8.1's Objective-C interface, plus blocks, conditions for what Objective-C reports itself and four verbs of its own. Each name below links to its own page; the macOS GUI guide covers conversion, threads, ownership and the native binary's shape table.

The LispWorks interface

The names of LispWorks 8.1's Objective-C interface, with its lambda lists, so code written against its manual runs here. The package also names the types: objc:objc-object-pointer (every object), objc:objc-class (a class, also an object pointer) and objc:sel (a selector) are the types of the values these functions answer, and objc:objc-bool, objc:objc-c++-bool, objc:objc-c-string, objc:objc-at-question-mark and objc:objc-unknown are the type designators a list-form method and objc:objc-class-method-signature use. The macro objc:with-autorelease-pool evaluates its body inside an autorelease pool. Classes are defined with the macros objc:define-objc-class, objc:define-objc-method, objc:define-objc-class-method, objc:current-super, objc:define-objc-struct, objc:define-objc-typedef and objc:define-objc-protocol; an instance of such a class is an objc:standard-objc-object.

FunctionExampleResult
objc:ensure-objc-initialized(objc:ensure-objc-initialized :modules '("/path/Framework"))nil; the modules are loaded
objc:invoke(objc:invoke "NSString" "stringWithUTF8String:" "hi")the method's value, converted by its declared types
objc:invoke-bool(objc:invoke-bool s "hasPrefix:" "h")t or nil
objc:invoke-into(objc:invoke-into 'string s "description")the value, converted or stored as the first argument says
objc:can-invoke-p(objc:can-invoke-p s "length")t or nil
objc:alloc-init-object(objc:alloc-init-object "NSObject")a new instance
objc:description(objc:description s)the description, a string
objc:trace-invoke(objc:trace-invoke "length")the name; later sends of it are traced
objc:untrace-invoke(objc:untrace-invoke "length")the name; the trace is removed
objc:coerce-to-objc-class(objc:coerce-to-objc-class "NSString")a class pointer
objc:objc-class-name(objc:objc-class-name c)the class's name
objc:coerce-to-selector(objc:coerce-to-selector "frame")a selector
objc:selector-name(objc:selector-name sel)the selector's name
objc:objc-class-method-signature(objc:objc-class-method-signature "NSString" "length")argument types, result type, encoding
objc:retain(objc:retain p)p, retained
objc:release(objc:release p)nil; one reference given up
objc:autorelease(objc:autorelease p)p; one reference handed to the pool
objc:retain-count(objc:retain-count p)the retainCount
objc:make-autorelease-pool(objc:make-autorelease-pool)a pool, current until released
objc:ns-string-to-string(objc:ns-string-to-string s)a Lisp string
objc:string-to-ns-string(objc:string-to-ns-string "hi")an NSString the program owns
objc:objc-object-pointer(objc:objc-object-pointer p)the object's pointer
objc:objc-object-from-pointer(objc:objc-object-from-pointer p)the associated Lisp object, or nil
objc:objc-object-var-value(objc:objc-object-var-value obj "count")an instance variable's value; setf-able
objc:objc-object-copied(defmethod objc:objc-object-copied :after ((old c) (new c)) ...)called when an instance is copied
objc:objc-object-destroyed(defmethod objc:objc-object-destroyed :after ((o c)) ...)called when an instance is deallocated

Blocks

Blocks made from Lisp functions, which LispWorks' OBJC has no interface for, under names of this package's own: an objc:objc-block passes wherever a method or a C function takes a block. The macros objc:define-objc-block-type and objc:with-objc-block name a signature and make a block for the extent of a body; C functions such as dispatch_async are declared with fli:define-foreign-function; the fli package also carries the foreign objects a method fills by reference.

FunctionExampleResult
objc:make-objc-block(objc:make-objc-block '(:int (:int :int)) #'+)an objc:objc-block calling the function
objc:free-objc-block(objc:free-objc-block b)nil; a copy a callee kept lives on
objc:call-objc-block(objc:call-objc-block '(:int (:int :int)) b 3 4)the block's value
objc:objc-block-pointer(objc:objc-block-pointer b)the literal's address, or nil once freed
objc:objc-block-live-p(objc:objc-block-live-p b)t until freed

Exceptions and NSError

What Objective-C reports itself, which LispWorks' OBJC does not turn into conditions: an exception raised inside a call signals objc:objc-exception (a subtype of error) from the innermost objc:invoke, C function or block call, and objc:invoke-with-error signals objc:ns-error for a method that fails through its NSError **.

FunctionExampleResult
objc:invoke-with-error(objc:invoke-with-error fm "removeItemAtPath:error:" path)the method's value; objc:ns-error when it failed
objc:objc-exception-name(objc:objc-exception-name e)"NSRangeException"
objc:objc-exception-reason(objc:objc-exception-reason e)the reason, or nil
objc:objc-exception-object(objc:objc-exception-object e)the thrown object
objc:ns-error-domain(objc:ns-error-domain e)"NSCocoaErrorDomain"
objc:ns-error-code(objc:ns-error-code e)the code, an integer
objc:ns-error-description(objc:ns-error-description e)the localized description
objc:ns-error-object(objc:ns-error-object e)the NSError

This package's own

Verbs LispWorks' OBJC does not have: running Lisp on the main thread, moving a block of memory across, and telling an Objective-C object from any other value.

FunctionExampleResult
objc:on-main(objc:on-main (lambda () ...))the function's value, computed on the main thread
objc:data(objc:data buffer)an NSMutableData holding the buffer's bytes
objc:bytes(objc:bytes data)an NSData's contents as a fresh (unsigned-byte 8) vector
objc:objectp(objc:objectp x)t for an object pointer, classes included