diff options
| -rw-r--r-- | Lisp/data-types.lisp | 96 | ||||
| -rw-r--r-- | Lisp/defpackage.lisp | 16 | ||||
| -rw-r--r-- | Lisp/parameters.lisp | 66 |
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__") |