summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Lisp/data-types.lisp96
-rw-r--r--Lisp/defpackage.lisp16
-rw-r--r--Lisp/parameters.lisp66
3 files changed, 170 insertions, 8 deletions
diff --git a/Lisp/data-types.lisp b/Lisp/data-types.lisp
index 16d9147..606c0c4 100644
--- a/Lisp/data-types.lisp
+++ b/Lisp/data-types.lisp
@@ -45,16 +45,65 @@
:initform nil)))
-(defclass selector (c-pointer-wrapper) ())
-(defclass id (c-pointer-wrapper) ())
-(defclass objc-class (c-pointer-wrapper) ())
+(defclass selector (c-pointer-wrapper) ()
+ (:documentation "An Objective C method selector.
+
+## Description:
+
+Method selectors are Objective C's equivalent to what Common Lisp calls
+**symbols**. Their use is restricted to retrieving methods by name.
+
+__selector__ objects cannot be created by means of __make-instance__.
+Use __find-selector__ instead.
+
+
+## See also:
+
+ __find-selector__"))
+
+
+(defclass id (c-pointer-wrapper) ()
+ (:documentation "An instance of an Objective C class.
+
+## Description:
+
+The class __id__ serves as a general-purpose container for all kinds of
+Objective C objects that are instances of some Objective C class, that
+is, neither primitive C values nor __selector__, __class__ or
+__exception__ objects.
+
+__id__ objects cannot be created by means of __make-instance__. Use
+a suitable class method instead as you would in Objective C.
+
+
+## Examples:
+
+ (invoke (find-objc-class 'ns-object)
+ 'self)
+ ;=> #<NSObject `NSObject' {16ECF598}>
+
+ (invoke (find-objc-class 'ns-string)
+ :string-with-c-string \"Mulk.\")
+ ;=> #<GSCBufferString `Mulk.' {5B36087}>
+
+ (invoke (find-objc-class 'ns-string)
+ 'new)
+ ;=> #<GSCBufferString `' {FFFFFFE}>
+
+
+## See also:
+
+ __invoke__, __invoke-by-name__, __exception__"))
+
+
+(defclass objc-class (c-pointer-wrapper) ()
+ (:documentation ""))
(define-condition exception (error)
((pointer :type c-pointer
:accessor pointer-to
:initarg :pointer))
- (:documentation "The condition type for Objective C exceptions.")
(:report (lambda (condition stream)
(format stream
"The Objective C runtime has issued an exception of ~
@@ -65,7 +114,44 @@
"UTF8String")
(invoke-by-name
(invoke-by-name condition "reason")
- "UTF8String")))))
+ "UTF8String"))))
+ (:documentation "The condition type for Objective C exceptions.
+
+## Description:
+
+Whenever an Objective C call made by means of __invoke__ or
+__invoke-by-name__ raises an exception, the exception is propagated to
+the Lisp side by being encapsulated in an __exception__ object and
+signaled.
+
+Note that it is currently impossible to directly extract the original
+Objective C exception from an __exception__ object, although it might
+arguably be desirable to do so. As __exception__ objects behave just
+like __id__ objects in almost all circumstances, this is not much of a
+problem, though. If you really do need an __id__ instance rather than
+an __exception__, you can simply send it the `self' message.
+
+
+## Examples:
+
+\(With __install-reader-syntax__ enabled.)
+
+ (handler-case
+ [NSArray selph] ; oops, typo
+ (exception (e)
+ e))
+ ;=> #<MULK.OBJECTIVE-CL:EXCEPTION NSInvalidArgumentException {1048D63}>
+
+ (class-of *)
+ ;=> #<CONDITION-CLASS EXCEPTION>
+
+ (class-of [** self])
+ ;=> #<STANDARD-CLASS ID>
+
+
+## See also:
+
+ __id__"))
(defgeneric objcl-eql (obj1 obj2))
diff --git a/Lisp/defpackage.lisp b/Lisp/defpackage.lisp
index af51e52..c3fcc2e 100644
--- a/Lisp/defpackage.lisp
+++ b/Lisp/defpackage.lisp
@@ -1,6 +1,8 @@
(defpackage #:mulk.objective-cl
- (:nicknames #:objcl)
+ (:nicknames #:objcl #:objective-cl #:mulk.objcl)
(:use #:cl #:cffi #:split-sequence)
+
+ ;; Functions
(:export #:initialise-runtime
#:shutdown-runtime
#:install-reader-syntax
@@ -8,4 +10,14 @@
#:invoke
#:find-objc-class
#:find-selector
- #:*trace-method-calls*))
+
+ ;; Special variables
+ #:*trace-method-calls*
+
+ ;; Classes
+ #:id
+ #:selector
+ #:exception
+
+ ;; Metaclasses
+ #:objective-c-class))
diff --git a/Lisp/parameters.lisp b/Lisp/parameters.lisp
index 3974b89..e9e3057 100644
--- a/Lisp/parameters.lisp
+++ b/Lisp/parameters.lisp
@@ -5,4 +5,68 @@
(defvar *skip-retaining* nil)
(defvar *trace-method-calls* nil
- "FIXME")
+ "Whether to print trace messages of all Objective C method calls.
+
+## Value Type:
+
+a **generalized boolean**.
+
+
+## Initial Value:
+
+__nil__.
+
+
+## Description:
+
+Sometimes it is useful to find out exactly which message calls are done
+in a piece of code that is executed. If __*trace-method-calls*__ is
+**true**, Objective CL tries to print trace messages to
+__*terminal-io*__ that can be useful for understanding the behaviour
+both of application code and the internals of Objective CL itself.
+
+If __*trace-method-calls*__ is __nil__ (which is the default), no trace
+messages are printed.
+
+Note that there is currently no way of determining the receivers of
+messages. As this limitation severely limits the usefulness of the
+trace messages, it is expected to be lifted in a future version of
+Objective CL.
+
+
+## Examples:
+
+\(With __install-reader-syntax__ enabled.)
+
+ (defvar *tmp*)
+ (setq *trace-method-calls* t)
+
+ (setq *tmp* [NSString new])
+ ; Invoking [new].
+
+ (setq *tmp* [NSString string])
+ ; Invoking [string].
+ ; Invoking [retain].
+
+ (setq *tmp* nil)
+ (gc :full t)
+ ; Invoking [release].
+ ; Invoking [release].
+
+ (setq *trace-method-calls* nil)
+
+\(Note that objects created by a call to `new' are not retained, because
+it is the user's (that is, the Objective CL framework's) responsibility
+to release them, while convenience constructors such as `string' return
+objects that have already had `autorelease' called on them and must thus
+be retained not to be garbage-collected prematurely.)
+
+
+## Affected By:
+
+ __*terminal-io*__
+
+
+## See also:
+
+ __invoke__, __invoke-by-name__")