cocoas

0.0.0

A toolkit library to help deal with CoreFoundation, Cocoa, and objc

About Cocoas

This is a small toolkit library to help deal with Apple's CoreFoundation, Cocoa, and Objective C interfaces.

How To

The library exposes the additional cffi types nsstring, cfstring, cfnumber, cfset, cfarray, and cfdictionary to allow convenient translation between the respective Lisp representation of these types and the ObjC/CoreFoundation representation. You can use them like you would any other CFFI type.

You can also define convenient Lisp function wrappers for static methods and instance methods, using define-objcfun and define-objcmethod respectively, using similar syntax to cffi:defcfun:

(cocoas:define-objcfun "NSAlert" alloc :pointer)
; [NSAlert alloc] => (nsalert-alloc)

(cocoas:define-objcmethod init :pointer)
; [obj init] => (init obj)

(cocoas:define-objcmethod run-modal :uint)
; [obj runModal] => (run-modal obj)

(cocas:define-objcmethod ((setf informative-text) "setInformativeText:") NIL
  (text cocoas:nsstring))
; [obj setInformativeText: [NSString stringWithUTF8String: text]] => (setf (informative-text obj) text)

To handle object cleanup and initialisation, there's with-main-loop, with-objects, and with-foundation-objects.

(cocas:with-main-loop ()
  (cocoas:with-objects ((window (init (nsalert-alloc))))
    (setf (informative-text window) "Hello!")
    (prog1 (run-modal window)
      (loop while (cocoas:process-event)))))

The library also installs a standard uncaught exception handler that translates and re-signals any NSException as a foundation-error so the errors can be dealt with Lisp-side.

System Information

Version: 0.0.0

Dependencies:

Author: Yukari Hafner

License: zlib

Homepage: https://shinmera.github.io/cocoas/

Bug Tracker: https://github.com/shinmera/cocoas/issues

Sources: https://github.com/shinmera/cocoas.git

Definition Index

ORG.SHIRAKUMO.COCOAS

No documentation provided.

EXTERNAL CLASS

CFARRAY

Source

CFFI type for CFSet translation.

An optional argument may specify how to translate the individual
pointer values of the array. Defaults to just :pointer.

Will translate to a vector and from a list or vector.

EXTERNAL CLASS

CFDICTIONARY

Source

CFFI type for CFDictionary translation.

Two optional arguments may specify how to translate the individual
pointer values of the dictionary keys and values respectively. 
Defaults to just :pointer for both.

Will translate to a hash-table with an EQUAL test, and from a
hash-table or alist.

EXTERNAL CLASS

CFNUMBER

Source

CFFI type for CFNumber translation.

An optional argument may specify the raw number type to use, which may
be one of the following:

  :int8
  :int16
  :int32
  :int64
  :char
  :short
  :int
  :long
  :longlong
  :float
  :double
  org.shirakumo.cocoas.cffi:cfindex
  org.shirakumo.cocoas.cffi:nsinteger
  org.shirakumo.cocoas.cffi:cgfloat

The actual lisp value will be coerced (as possible) to conform to the
number type. If not specified, the default is
org.shirakumo.cocoas.cffi:cgfloat

EXTERNAL CLASS

CFSET

Source

CFFI type for CFSet translation.

An optional argument may specify how to translate the individual
pointer values of the set. Defaults to just :pointer.

Will translate to a list and from a list or vector.

EXTERNAL CLASS
CFSTRING
Source
```
CFFI type for CFString translation.
```
EXTERNAL CLASS
NSSTRING
Source
```
CFFI type for NSString translation.
```

EXTERNAL CONDITION

FOUNDATION-ERROR

Source

Representation of an NSException error.

Signalled for uncaught NSExceptions.

See NAME
See REASON

EXTERNAL FUNCTION
FOUNDATION-ERROR
- EXCEPTION
Source
No documentation provided.

EXTERNAL FUNCTION

INIT

&REST
LIBS

Source

Initialises the libraries.

LIBS can be a set containing:
  :FOUNDATION
  :COCOA
  :APPKIT

If LIBS is not specified, all libraries are loaded.

See SHUTDOWN

EXTERNAL FUNCTION

PROCESS-EVENT

&OPTIONAL
APP

Source

Process an event from the apps' queue.

Returns true if an event was processed and NIL otherwise.

EXTERNAL FUNCTION
SHUTDOWN
Source
```
Cleans up the libraries.

See INIT
```

EXTERNAL GENERIC-FUNCTION

NAME

CONDITION

Returns the name for the foundation-error.

See FOUNDATION-ERROR (type)

EXTERNAL GENERIC-FUNCTION

REASON

CONDITION

Returns the reason for the foundation-error, if any.

See FOUNDATION-ERROR (type)

EXTERNAL MACRO

DEFINE-OBJCFUN

CLASS
MNAME
RETTYPE
&BODY
ARGS

Source

Defines an ObjC static class method/function.

CLASS should be the class name the method is defined on.

NAME should be the name of the method. It can be a list of the
lisp-side function name and the method name. If the method name is not
explicitly given, it is translated from the lisp name. To specify
colons in the name, you may use a slash instead. For instance, the
lisp-name

   foo-bar/baz

is translated to

   fooBar:baz

If the NAME is not a list, the class is automatically prepended to the
name of the resulting lisp function name, meaning

   (define-objcfun "foo" bar ...)

Results in the defined lisp function being named FOO-BAR, but

   (define-objcfun "foo" (bar) ...)

Results in the defined lisp function being named BAR.

RETTYPE should be the return type of the function. It can also be NIL,
in which case it is automatically replaced with OBJC:ID.

ARGS should be a body of list specifying the function arguments, with
the argument name first and the type second, same as CFFI:DEFCFUN.

See CFFI:DEFCFUN
See DEFINE-OBJCMETHOD

EXTERNAL MACRO

DEFINE-OBJCMETHOD

NAME
RETTYPE
&BODY
ARGS

Source

Defines an ObjC instance method/function.

NAME should be the name of the method. It can be a list of the
lisp-side function name and the method name. If the method name is not
explicitly given, it is translated from the lisp name. To specify
colons in the name, you may use a slash instead. For instance, the
lisp-name

   foo-bar/baz

is translated to

   fooBar:baz

RETTYPE should be the return type of the function. It can also be NIL,
in which case it is automatically replaced with OBJC:ID.

ARGS should be a body of list specifying the function arguments, with
the argument name first and the type second, same as CFFI:DEFCFUN.

See CFFI:DEFCFUN
See DEFINE-OBJCFUN

EXTERNAL MACRO

WITH-FOUNDATION-OBJECTS

BINDINGS
&BODY
BODY

Source

Bind a bunch of CoreFramework objects.

Automatically calls OBJC:RELEASE to deallocate the objects on exit. If an
object is bound to a null pointer, its failure form is returned.

Each binding may be a list of the variable name, initialiser form, and
an optional failure form. If the failure form is not specified, an
ERROR form is generated for you.

EXTERNAL MACRO

WITH-MAIN-LOOP

&BODY
INIT

Source

Runs BODY in the main thread.

MacOS requires GUI things to run on the main thread. Additionally,
system API calls frequently generate floating point traps which your
Lisp implementation will likely intercept. This also disables those to
ensure your application can run properly.

See FLOAT-FEATURES:WITH-FLOAT-TRAPS-MASKED
See TRIVIAL-MAIN-THREAD:WITH-BODY-IN-MAIN-THREAD

EXTERNAL MACRO

WITH-OBJECTS

BINDINGS
&BODY
BODY

Source

Bind a bunch of ObjC objects.

Automatically calls OBJC:FREE to deallocate the objects on exit. If an
object is bound to a null pointer, its failure form is returned.

Each binding may be a list of the variable name, initialiser form, and
an optional failure form. If the failure form is not specified, an
ERROR form is generated for you.

ORG.SHIRAKUMO.COCOAS.CFFI
No documentation provided.
- EXTERNAL CONSTANT
  CFINDEX
  
  Source
  No documentation provided.
- EXTERNAL CONSTANT
  CGFLOAT
  
  Source
  No documentation provided.
- EXTERNAL CONSTANT
  NSINTEGER
  
  Source
  No documentation provided.
- EXTERNAL SYMBOL-MACRO
  APP
  
  Source
  No documentation provided.
- EXTERNAL SYMBOL-MACRO
  DEFAULT-RUN-LOOP-MODE
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  ARRAY-GET-COUNT
  
  ARRAY
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  ARRAY-GET-VALUE-AT-INDEX
  
  ARRAY
  
  INDEX
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  CREATE-ARRAY
  
  ALLOCATOR
  
  VALUES
  
  NUM-VALUES
  
  CALLBACKS
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  CREATE-DICTIONARY
  
  ALLOCATOR
  
  KEYS
  
  VALUES
  
  NUM-VALUES
  
  KEY-CALLBACKS
  
  VALUE-CALLBACKS
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  CREATE-NUMBER
  
  ALLOCATOR
  
  TYPE
  
  VALUE
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  CREATE-SET
  
  ALLOCATOR
  
  VALUES
  
  NUM-VALUES
  
  CALLBACKS
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  CREATE-STRING-WITH-CSTRING
  
  ALLOCATOR
  
  BYTES
  
  ENCODING
  
  IS-EXTERNAL-REPRESENTATION
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  DICTIONARY-CONTAINS-KEY
  
  DICTIONARY
  
  KEY
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  DICTIONARY-GET-COUNT
  
  DICTIONARY
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  DICTIONARY-GET-KEYS-AND-VALUES
  
  DICTIONARY
  
  KEYS
  
  VALUES
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  DICTIONARY-GET-VALUE
  
  DICTIONARY
  
  KEY
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  FREE
  
  ID
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  GET-CLASS
  
  NAME
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  NUMBER-GET-VALUE
  
  NUMBER
  
  TYPE
  
  VALUE
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  REGISTER-NAME
  
  NAME
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  RELEASE
  
  OBJECT
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  SET-GET-COUNT
  
  SET
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  SET-GET-VALUES
  
  SET
  
  VALUES
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  SET-UNCAUGHT-EXCEPTION-HANDLER
  
  HANDLER
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  STRING-GET-CSTRING
  
  STRING
  
  BUFFER
  
  LENGTH
  
  ENCODING
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  STRING-GET-CSTRING-PTR
  
  STRING
  
  ENCODING
  
  Source
  No documentation provided.
- EXTERNAL FUNCTION
  STRING-GET-LENGTH
  
  STRING
  
  Source
  No documentation provided.
- EXTERNAL MACRO
  CALL
  
  SELF
  
  METHOD
  
  &REST
  
  ARGS
  
  Source
  No documentation provided.