Coca

About

Cocoa in Common Lisp

NOTE: currently, only tested on SBCL (2.5.10) on macOS (m1 air Sequoia 15.5 and m2 air Tahoe 26.2). cannot ensure and won’t provide support for other implementation or other platform (right now). But contributions are welcomed.

Documentations

Coca is (or SHOULD BE) self-documented. Load the system and use sly-describe-symbol or SLIME functions to read the documentation of each symbol.

Examples

A few examples could be found under =examples= directory.

Subsystems

Coca/ObjC

Loads coca/objc and use package :coca.objc (see objc/readme for details).

Coca/Frameworks

Load coca/frameworks will only loads coca/frameworks/foundation and coca/frameworks/appkit.

Coca/Frameworks/Foundation

ObjC bindings of Foundation Framework

Access essential data types, collections, and operating-system services to
define the base layer of functionality for your app.

The Foundation framework provides a base layer of functionality for apps and
frameworks, including data storage and persistence, text processing, date and
time calculations, sorting and filtering, and networking. The classes, protocols,
and data types defined by Foundation are used throughout the macOS, iOS,
watchOS, and tvOS SDKs.

see https://developer.apple.com/documentation/Foundation?language=objc

Coca/Frameworks/Appkit

ObjC bindings of AppKit Framework

Construct and manage a graphical, event-driven user interface for your macOS app.

AppKit contains the objects you need to build the user interface for a macOS app.
In addition to drawing windows, buttons, panels, and text fields, it handles all the
event management and interaction between your app, people, and macOS.

see https://developer.apple.com/documentation/AppKit?language=objc

Coca/Frameworks/Webkit

ObjC bindings of Webkit Framework

Integrate web content seamlessly into your app,
and customize content interactions to meet your app's needs.

Use the WebKit framework to integrate richly styled web content into your
app's native content. WebKit offers a full browsing experience for your content,
offering a platform-native view and supporting classes to:

+ Display rich web content using HTML, CSS, and JavaScript
+ Handle the incremental loading of page content
+ Display multiple MIME types and compound frame elements
+ Navigate between pages of content
+ Manage a forward-back list of recently visited pages

For more information about WebKit, go to https://webkit.org.

see https://developer.apple.com/documentation/WebKit?language=objc

Dev Note

License

Coca is distributed under the LLGPL (Lisp Lesser General Public License). You are free to use Coca as a library within your commercial Cocoa applications. However, I kindly ask that any improvements or modifications to Coca itself remain open-sourced, so that the entire community can benefit and Coca can continue to evolve through your contributions.

Road Map

• [ ] Cocoa examples (github:gammasoft71/Examples_Cocoa), see examples/basic/readme.org

  by the time it’s finished, Coca could be thought as mostly finished and ready for real productition codes

• [ ] Deploy, expected to be examples/deploy/readme.org

  currently it’s possible to save-lisp-and-die (with coca-init to reset ObjC environment), but may not able to deliver to end user

• [ ] Applications, expected to be under application

  those applications should only be experimental, not meant to be performance for actual productivity (just to proof that Coca could do so)

  • [ ] Lem Coca Backend, expected to be under application/lem as coca/lem subsystem
  • [ ] Nyxt Coca Backend, expected to be under application/nyxt as coca/nyxt subsystem
  • [ ] CLIM Coca Backend, expected to be under application/clim as coca/clim subsystem

How to Contribute

ObjC frameworks

No wrapping, just use Coca/ObjC

If you just want to do some rapid prototyping or you need something that are not provided with Coca currently, you can use functions provided in Coca/ObjC to call ObjC methods directly:

For example:

• [object SEL ...] could be written as (invoke object SEL ...)

Note that it’s also recommanded to load Coca/Frameworks system (or at least Coca/Frameworks/Foundation) since it wrapps a lot of ObjC method in the lispy style.

Trivial wrapping with devtools/parse-apple-docs.js

I wrote a helper script in devtools/parse-apple-docs.js, which could be used to extract definitions from Apple’s documentation website. It maynot always generate correct code so use it with caution.

Lispy wrapper codes

Style Guide:

• define-objc-const: the const should be named like +const-name+

  Example:

  • +ns-foundation-version-number+

Values converting:

• as-xxx: convert lisp values into ObjC form

  Example:

  • as-boolean: convert values as ObjC :bool
  • as-ns-font:
• decode-xxx: convert ObjC values into lisp value

  by default, define-objc-enum will automatically generate decoder for enum numbers

Methods:

• use lisp methods rather than ObjC methods

Generic functions:

• init: implement init to set the logic of creating an ObjC object
• xxxp and xxx-xxx-p: boolean test slots should have accessor function with p (lisp style) testing names

Optimization of Coca/ObjC

I cannot say that current Coca/ObjC is perfectly working. The code and the performance should be more robust.

Reference

• Apple’s Documentation
• Cocoa examples (github:gammasoft71/Examples_Cocoa)

  some of the examples are learnt from this repo

• Silicon.h (github:EimaKve/Silicon)

  some of the examples are learnt from this repo

Below is the developping notes on my blog (mostly Chinese):

• ObjC (00): ObjC Runtime Inspector
• ObjC (1.5) NSException (EN)
• ObjC (1.75) libffi, cffi, cffi-grovel, and C