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.
| Function | Example | Result |
|---|---|---|
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.
| Function | Example | Result |
|---|---|---|
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 **.
| Function | Example | Result |
|---|---|---|
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.
| Function | Example | Result |
|---|---|---|
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 |