From 2ae7324b43a2a20c44af0cb283dba56061f7baeb Mon Sep 17 00:00:00 2001 From: Matthias Benkard Date: Mon, 6 Aug 2007 03:46:23 +0200 Subject: Document INITIALISE-RUNTIME, SHUTDOWN-RUNTIME and INSTALL-READER-SYNTAX. darcs-hash:9b2b0d2e48753404b9423a826f3617d3a87c4df8 --- Lisp/libobjcl.lisp | 45 ++++++++++++++++++++ Lisp/reader-syntax.lisp | 110 +++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 154 insertions(+), 1 deletion(-) (limited to 'Lisp') 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.\"] + ;=> # + + [NSObject self] + ;=> # + + [NSObject name] + ;=> \"NSObject\" + + [[[NSObject self] self] name] + ;=> \"NSObject\" + + [NSString stringWithCString: \"Mulk.\" encoding: 4] + ;=> # + + + +## 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) -- cgit v1.2.3