Clotho 0.2 API
February 16, 2004
copyright 2004 by mikel evins

[Note: This document is based on the similar document distributed with Alpaca 0.5 --me]

Acknowledgments

	Clotho is built on the work of other people. Without the tools and libraries those other people made and shared, Clotho would not exist. Clotho 0.2 is built on the following work:

	OpenMCL 0.14.1 by Gary Byers and contributors
		http://openmcl.clozure.com/
	The OpenMCL Cocoa Bridge by Randall Beer
		(distributed as part of OpenMCL 0.14.1)
	The Cocoa Inspector by Hamilton Link
		(distributed as part of OpenMCL 0.14.1)
	ASDF by Daniel Barlow and contributors
		http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf/
	Bosco 0.5 by mikel evins
		http://evins.net
	remote-repl by Sven Van Caekenberghe
		http://homepage.mac.com/svc/
	Mac OS X 10.3 "Panther"
		http://www.apple.com/macosx

Introduction

	Clotho 0.2 is an early-stage development version of an open-source, integrated development environment (IDE) for Common Lisp and Mac OS X. The Clotho project is open to people interested in contributing to its development, and is maintained at the Common-Lisp.net site:

	http://www.common-lisp.net/project/clotho/

	For more information about the project, see the above website, or see the mailing-list information at 

	http://common-lisp.net/mailman/listinfo/mac-lisp-ide

	NOTE: The Clotho.app bundle in the bin subdirectory of the source distribution iis not a fully-functional application. To build it and make it work, see the section below, "Building Clotho".

	For more about Clotho 0.2 features and other information, see the accompanying README file.

Clotho key-bindings

	Clotho uses key-bindings similar to those in Emacs, though Clotho's standard bindings are not nearly as extensive as those of Emacs. They are completely extensible and customizable, however; see the next section for details. Clotho's key-bindings and other aspects of its API are ported from Alpaca, a text-editor for authors also written in Common Lisp using the Bosco framework. Alpaca is available from http://alpaca.sourceforge.net. Bosco is available from http://evins.net.

	Pressing a key in Clotho runs a command. If no special command is bound to a key, the default command inserts the character associated with the key. Certain keys, though, have Clotho editing commands bound to them. The Following tables show the standard editing commands defined in Clotho editing windows and in Lisp listener windows.

Note: the notation S-<key> means that the Shift key is held down when pressing <key>. C-<key> means that the Control key is held down; M-<key> means the Meta key (also called the Option or Alt key) is held down. You can combine these modifier keys; for example, "S-M-C-c" means the "c" key is pressed while holding down the Shift, Meta, and Control keys.

Note: Clotho does not (yet) implement multiple-press sequences like those in Emacs, such as C-x or C-h sequences. It also does not (yet) support support M-x command-entry.

Editor bindings

C-g		cancel-operation
M-c		capitalize-word 
C-l		center-selection
DEL		delete-backward
C-d		delete-forward
C-k		kill
C-w		delete-to-mark
C-DEL 	delete-word-backward
M-DEL 	delete-word-forward
C-o 		insert-newline
TAB 		insert-tab
M-l 		lowercase-word
C-b 		backward-char
C-n 		next-line
C-f 		forward-char
S-M-< 	beginning-of-document
C-a 		beginning-of-line
S-M-{ 	beginning-of-paragraph
S-M-> 	end-of-document
C-e 		end-of-line
S-M-} 	end-of-paragraph
M-b 		backward-word
M-f 		forward-word
M-v 		page-up
C-v 		page-down
M-h 		select-paragraph
C-  		set-mark
C-m 		select-to-mark
C-t 		transpose
M-u 		uppercase-word
C-y 		yank

Listener bindings

M-p 		insert-previous-history-form
M-n 		insert-next-history-form

	The names given are the names of predefined editing functions written in Lisp. You can write your own editing functions and bind them to Clotho keys. For more information on how to do that, see the next section.

Customizing Clotho

	You can extend Clotho's behavior by writing Lisp code. When Clotho launches it looks for a file named "~/.clotho". If it finds such a file, Clotho assumes that the file contains Common Lisp code and loads it into its running image. You can therefore add Lisp forms to your ".clotho" file to extend and customize Clotho.

	If there is no "~/.clotho" file, then Clotho gets the value of the environment variable CLOTHO_INIT_FILE and looks for a file at the path stored in that variable.

	Common Lisp is both Clotho's implementation language and its extension language; in other words, you can extend Clotho to do anything that can be done in Common Lisp. Moreover, your compiled Lisp code becomes part of the running Clotho image, linked against the same classes and methods that define the application, so you have essentially unlimited power to change Clotho's behavior using code in your init file.

	Here are a few sample definitions that show how Clotho can be extended. These definitions are part of Clotho's source code, and define key-bindings in the standard editor and listener environments.

	Following is the Common Lisp definition of Clotho's capitalize-word function. This definition uses the Objective C bridge to send a message to the current key target:

(defun capitalize-word (&optional target)
  (let ((target (or target (key-target))))
	(send target :capitalize-word (%null-ptr))
	t))

The capitalize-word function is bound in the *clotho-keymap* to the key-combination Meta-C. Following is the Lisp form that sets up that binding:

(define-key *clotho-keymap* "M-c" 'capitalize-word)

	Editing functions can be more involved than this. In fact, they can do anything you can write in Common Lisp. Consider the definition for the Listener window's insert-previous-history-form command:

(defun insert-previous-history-form (&optional target)
  (let* ((target (or target (key-target)))
		 (max (1- (length ccl::*read-history*))))
	(when (> ccl::*last-read-history-access-index* max)
	  (setq ccl::*last-read-history-access-index* max))
	(let* ((form (elt ccl::*read-history* ccl::*last-read-history-access-index*))
		   (form-string (%make-nsstring (format nil "~S" form)))
		   (has-marked-text? (send target 'has-marked-text)))
	  (if has-marked-text?
		  (slet ((marked-range (send target 'marked-range)))
				(send target
					  :set-marked-text form-string
					  :selected-range marked-range))
		(slet ((selected-range (send target 'selected-range)))
				(send target
					  :set-marked-text form-string
					  :selected-range selected-range))))
	(incf ccl::*last-read-history-access-index*)
	t))

	This command is bound in *clotho-listener-keymap*, but not in *clotho-keymap*, which means that it works in Listener windows but not in text-editing windows. Here is the form that defines this binding:

(define-key *clotho-listener-keymap* "M-p" 
  'insert-previous-history-form)

Clotho Key-names

	When binding functions to key-sequences you need to know the name of the key-sequence you want to bind. This section lists the names of Clotho keys and explains how modifier keys are named.

	Key-sequences are named by strings. The most common keys, those that enter letters, digits, and other ordinary characters, are named by the characters they enter. For example, the name of the "a" key is "a".

	Other keys don't have such conveniently obvious names; for these keys we use conventions documented in this section. For example, holding down the Control key and hitting "c" generates the keystroke named "C-c".

	The names of the modifier keys in Clotho are:

	"S-"	Shift
	"C-"	Control
	"M-"	Meta (or Alt, or Option)

	The name of the Space key is " " (a literal space). It combines with modifiers in the same way as other literal keys; for example, you can bind a command to Control-Space by writing "C- " for the key name.

	When naming a key with modifiers, always put the modifier names in the order "Shift-Control-Meta". For example, you can write "S-M-b", but don't write "M-S-b"; Clotho will not recognize it.

	Finally, there are a number of keys that fit neither of the previous categories, and are just assigned conventional names. Those names are listed below.

DEL 
<UP> <DOWN> <LEFT> <RIGHT>
<F1> ... <F35>

Clotho's API

	Because Clotho is implemented in Lisp, and because you can easily add function definitions of your own and evaluate Lisp forms in its Listener window, you can, with a little effort, reprogram Clotho to do whatever you want. That doesn't necessarily mean that it's easy to make it do exactly what you want, though.

	In version 0.2 Clotho has just the beginnings of an API designed to make it easier to customize. Clotho provides a few variables, classes, and functions designed to make it easy to get and change the states of Clotho objects. This section describes that API.

	Astute Cocoa programmers will notice that the majority of the functions are simply Lisp wrappers for NSResponder messages that are designed to emulate Emacs features, but there are also features unique to Clotho.

*clotho-keymap*
	VARIABLE
	This variable stores a reference to the keymap that Clotho uses to map key events to editing functions. You can use the define-key function to add bindings to the keymap. Don't store anything but a keymap in this variable; doing so will make Clotho misbehave.

backward-char (&optional target)
	KEY FUNCTION
	Moves the insertion point backward one character in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is thee value of (key-target).

backward-word (&optional target)
	KEY FUNCTION
	Moves the insertion point backward one word in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

beginning-of-document (&optional target)
	KEY FUNCTION
	Moves the insertion point to the beginning of the document in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

beginning-of-line (&optional target)
	KEY FUNCTION
	Moves the insertion point to the beginning of the current line in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

beginning-of-paragraph (&optional target)
	KEY FUNCTION
	Moves the insertion point to the beginning of the current paragraph in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

cancel-operation (&optional target)
	KEY FUNCTION
	Cancels a time-consuming operation in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

capitalize-word (&optional target)
	KEY FUNCTION
	Capitalizes the current word in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

center-selection (&optional target)
	KEY FUNCTION
	Scrolls the target text so that the selection is centered in the view. Works more reliably with plain-text than with RTF windows. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

character-count (document)
	FUNCTION
	Returns the number of characters in the document.

copy-keymap (keymap)
	FUNCTION
	Returns a new keymap, a copy of the supplied keymap. The new keymap has the same defined key-bindings as the old keymap. Useful for creating a new keymap for purposes of customization, when you want the new keymap to start with the same bindings as an existing keymap.

define-key (keymap string function)
define-key (keymap string symbol)
	FUNCTION
	Defines a new key-binding in the supplied keymap. The supplied function is bound to the key-sequence named in the string. If the third argument is a symbol then the value of its SYMBOL-FUNCTION is bound to the key-sequence. See the section "Clotho Key Names" for more about the names of keys used in key-bindings.

delete-backward (&optional target)
	KEY FUNCTION
	Deletes one character before the insertion point in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

delete-forward (&optional target)
	KEY FUNCTION
	Deletes one character after the insertion point in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

delete-to-mark (&optional target)
	KEY FUNCTION
	Deletes all text between the current insertion point and the mark in the target. See set-mark for more about the mark. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

delete-word-backward (&optional target)
	KEY FUNCTION
	Deletes one word before the insertion point in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

delete-word-forward (&optional target)
	KEY FUNCTION
	Deletes one word after the insertion point in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

end-of-document (&optional target)
	KEY FUNCTION
	Moves the insertion point to the end of the document in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

end-of-line (&optional target)
	KEY FUNCTION
	Moves the insertion point to the end of the current line in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

end-of-paragraph (&optional target)
	KEY FUNCTION
	Moves the insertion point to the end of the current paragraph in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

filename (document)
	FUNCTION
	Returns the file pathname of the document, or NIL if the document has not been saved to disk.

find-document (tagnum)
	FUNCTION
	Returns the document with the supplied tag number. Each document is assigned a tag number when it is created. The first document's tag is 1; each tag number after that increases by one.

forward-char (&optional target)
	KEY FUNCTION
	Moves the insertion point forward one character in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

forward-word (&optional target)
	KEY FUNCTION
	Moves the insertion point forward one word in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

get-key-function (keymap string)
	FUNCTION
	Returns the key function bound to the key named by the string. The key name follows the conventions described in the section "Clotho Key Names".

insert-previous-history-form (&optional target)
	KEY FUNCTION
	Inserts the last form read by the Lisp read-eval-print loop in the target. Pressing this key-combination repeatedly moves backward through the reader's history. Listener windows bind this function to "M-p". The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

insert-newline (&optional target)
	KEY FUNCTION
	Inserts a newline character, opening a line in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

insert-next-history-form (&optional target)
	KEY FUNCTION
	Inserts the last form read by the Lisp read-eval-print loop in the target. Pressing this key-combination repeatedly moves forward through the reader's history. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

insert-tab (&optional target)
	KEY FUNCTION
	Inserts a tab character in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

insert-text (string &optional target)
	KEY FUNCTION
	Inserts the supplied string in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

keymap
	CLOS CLASS
	The class of keymaps.

kill (&optional target)
	KEY FUNCTION
	Deletes text from the insertion point to the end of the current line in the target, adding the killed text to Clotho's kill buffer. Subsequent yank commands insert the killed text in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

key-target ()
	FUNCTION
	key-target returns the application's current key target—that is, the object that receives and processes key events. This function is especially useful in defining editing commands, because you can use it to fetch the key target and then send messages to the target to effect editing changes.

lowercase-word (&optional target)
	KEY FUNCTION
	Converts the selected text or current word to lowercase in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

next-line (&optional target)
	KEY FUNCTION
	Moves the insertion point down one line in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

page-down (&optional target)
	KEY FUNCTION
	Scrolls the view down one page in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

page-up (&optional target)
	KEY FUNCTION
	Scrolls the view up one page in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

select-all (&optional target)
	KEY FUNCTION
	Selects all the text in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

select-line (&optional target)
	KEY FUNCTION
	Selects the current line in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

select-paragraph (&optional target)
	KEY FUNCTION
	Selects the current paragraph in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

select-to-mark (&optional target)
	KEY FUNCTION
	Selects all the text between thee insertion point and the mark in the target. See set-mark for more about the mark. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

select-word (&optional target)
	KEY FUNCTION
	Selects the current word in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

set-mark (&optional target)
	KEY FUNCTION
	Sets the mark at the current location of the insertion point in the target. The mark can be used in combination with the insertion point to select and operate on ranges of text. For example, you can set the mark, move the insertion point, and then use select-to-mark to select all the text in between for cutting, replacement, or other operations. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

swap-with-mark (&optional target)
	KEY FUNCTION
	Swaps the locations of the insertion point and the mark in the target. See set-mark for more about the mark. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

transpose (&optional target)
	KEY FUNCTION
	Switches the characters before and after the insertion point in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

uppercase-word (&optional target)
	KEY FUNCTION
	Changes thee current word to upper case in the target. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).

word-count (document)
	FUNCTION
	Returns the total number of words in the document.

yank (&optional target)
	KEY FUNCTION
	Inserts a block of text from the kill buffer in the target. Commands that delete ranges of text add text to the kill buffer. The target argument must be an NSResponder subclass, such as NSTextView, that implements key-event handling. In normal event-handling the target passed to this function is the value of (key-target).