summaryrefslogtreecommitdiff
path: root/Lisp
diff options
context:
space:
mode:
authorMatthias Benkard <code@mail.matthias.benkard.de>2007-08-06 03:46:23 +0200
committerMatthias Benkard <code@mail.matthias.benkard.de>2007-08-06 03:46:23 +0200
commit2ae7324b43a2a20c44af0cb283dba56061f7baeb (patch)
tree5674c761acfc8e549e5971d7546b3592be8c533b /Lisp
parentb30c4b8ce6d1ce2133c9f2edb47d5bf7e99e5544 (diff)
Document INITIALISE-RUNTIME, SHUTDOWN-RUNTIME and INSTALL-READER-SYNTAX.
darcs-hash:9b2b0d2e48753404b9423a826f3617d3a87c4df8
Diffstat (limited to 'Lisp')
-rw-r--r--Lisp/libobjcl.lisp45
-rw-r--r--Lisp/reader-syntax.lisp110
2 files changed, 154 insertions, 1 deletions
diff --git a/Lisp/libobjcl.lisp b/Lisp/libobjcl.lisp
index 82b9a8f..12a880c 100644
--- a/Lisp/libobjcl.lisp
+++ b/Lisp/libobjcl.lisp
@@ -20,9 +20,54 @@
;; FIXME: docs
(defcfun ("objcl_initialise_runtime" initialise-runtime) :void)
+(setf (documentation #'initialise-runtime 'function)
+ "Initialise the Objective C runtime.
+
+## Description:
+
+The function __initialise-runtime__ makes all the necessary arrangements
+for object instantiation and method calls to work. In particular, it
+creates an autorelease pool in order to make the use of Objective C's
+semiautomatic reference counting memory management possible, which is
+used internally by Objective CL.
+
+Note that, as the autorelease pool created by __initialise-runtime__ is
+currently only deallocated and its containees released when
+__shutdown-runtime__ is called, it is generally advisable to make use of
+AppKit's automatic creation and deletion auf autorelease pools, if
+possible. Naturally, AppKit-based applications need not worry about
+this, but be aware that they do need to call __initialise-runtime__
+before making any other Objective C calls.
+
+
+## See also:
+
+ __shutdown-runtime__")
+
;; FIXME: docs
(defcfun ("objcl_shutdown_runtime" shutdown-runtime) :void)
+(setf (documentation #'shutdown-runtime 'function)
+ "Shut the Objective C runtime down.
+
+## Description:
+
+The function __shutdown-runtime__ cleans the environment up. In
+particular, it tries to release all the objects retained in any
+autorelease pools created by __initialise-runtime__.
+
+Note that even if you make use of AppKit, which manages its own
+autorelease pools, you must call __initialise-runtime__ before making
+any Objective C calls, and you should call __shutdown-runtime__ when you
+are finished with Objective C, since Objective CL makes use of
+autoreleased objects internally before you are even able to retrieve any
+objects or classes, let alone send messages to them.
+
+
+## See also:
+
+ __initialise-runtime__")
+
(defcfun ("objcl_invoke_instance_method"
%objcl-invoke-instance-method) obj-data
diff --git a/Lisp/reader-syntax.lisp b/Lisp/reader-syntax.lisp
index ccb4ff0..497253e 100644
--- a/Lisp/reader-syntax.lisp
+++ b/Lisp/reader-syntax.lisp
@@ -2,7 +2,115 @@
(defun install-reader-syntax ()
- "FIXME"
+ "Install an Objective-C-like **reader macro** for Objective C method
+ calls.
+
+## Description:
+
+The **reader macro** installed by __install-reader-syntax__ closely
+resembles the conventional method call syntax of Objective C. In fact,
+any differences between standard Objective C method call syntax and this
+**reader macro** that are not documented here is probably a bug and
+should be reported to the maintainer.
+
+
+## Reader Macro:
+
+[\\{*receiver* | *class-name*\\} *message-name-part [[argument [[message-name-arg-pair]]*\\**]]*]
+
+message-name-arg-pair ::= *message-name-part argument*
+
+
+## Reader Macro Arguments and Values:
+
+*receiver* --- an **object**.
+
+*class-name* --- a **symbol** (not evaluated).
+
+*message-name-part* --- a **symbol** (not evaluated).
+
+*argument* -- an **object**.
+
+Returns: *result* --- the result of the method invocation.
+
+
+## Reader Macro Description:
+
+First, it is determined whether to regard the first element of the
+form as an object or as a class name according to the following rules:
+
+1. If the element is no **symbol**, it is regarded as an object.
+
+2. Otherwise, if it is a **symbol** whose **name** starts with a
+**lowercase** letter, it is regarded as an object.
+
+3. Otherwise, it is regarded as a class name.
+
+Next, the method call is parsed by alternately
+reading *message name parts* and *arguments* separated by
+whitespace. *Message name parts* are expected to consist of
+**alphanumeric** **character**s and **colon**s, while *arguments* may
+be arbitrary Lisp expressions. If any but the first *message name part*
+does not end with a **colon**, the effects are undefined. Likewise, the
+effects are undefined if any *message name part* contains a **colon** in
+a position other than the end.
+
+After the parsing is done, all *message name parts* are concatenated in
+order to form a single **string** that is used as if as the second
+**argument** to __invoke-by-name__, and all *arguments* are collected in
+order and the resulting **list** used as if as a **list** of additional
+arguments to __invoke-by-name__.
+
+
+## Reader Macro Examples:
+
+ [NSString stringWithCString: \"Mulk.\"]
+ ;=> #<GSCBufferString `Mulk.' {5B36087}>
+
+ [NSObject self]
+ ;=> #<NSObject `NSObject' {16ECF598}>
+
+ [NSObject name]
+ ;=> \"NSObject\"
+
+ [[[NSObject self] self] name]
+ ;=> \"NSObject\"
+
+ [NSString stringWithCString: \"Mulk.\" encoding: 4]
+ ;=> #<GSCBufferString `Mulk.' {5B36087}>
+
+
+
+## Rationale:
+
+Objective C method names tend to be relatively verbose and are
+frequently composed of many short words like \"of\" and \"by\". As a
+result, using __invoke__ can be quite cumbersome at times and waste
+screen real estate. One need only compare the example call
+
+ (invoke (find-objc-class 'ns-string)
+ :string-with-c-string \"Mulk.\"
+ :encoding 4)
+
+with its reader macro counterpart
+
+ [NSString stringWithCString: \"Mulk.\" encoding: 4]
+
+to be able to see an improvement in length as well as readability.
+
+In any case, it is a matter of taste whether to prefer __invoke__ or
+Objective C syntax as it is whether to prefer the standard Common Lisp
+__loop__ facility or a widespread and well-known alternative called
+\"Iterate\". In both cases, one can argue that one of the forms
+sacrifices an elusive quality of \"lispiness\" as well as text editor
+friendliness in favor of natural-language-style readability and
+conciseness.
+
+
+## See also:
+
+ __invoke__, __invoke-by-name__"
+
(set-macro-character #\] (get-macro-character #\)))
(set-macro-character #\[ #'(lambda (stream char)