From ab10720260e2c184b319026da89f4dfd338500bb Mon Sep 17 00:00:00 2001 From: Brian Cully Date: Wed, 2 Apr 2008 19:20:20 -0400 Subject: Initial commit --- English.lproj/Moxie Help/pages/lisp-functions.html | 947 +++++++++++++++++++++ 1 file changed, 947 insertions(+) create mode 100644 English.lproj/Moxie Help/pages/lisp-functions.html (limited to 'English.lproj/Moxie Help/pages/lisp-functions.html') diff --git a/English.lproj/Moxie Help/pages/lisp-functions.html b/English.lproj/Moxie Help/pages/lisp-functions.html new file mode 100644 index 0000000..a6091c7 --- /dev/null +++ b/English.lproj/Moxie Help/pages/lisp-functions.html @@ -0,0 +1,947 @@ + + + + + + Lisp Functions + + + + +

Moxie plugin functions

These functions are all exported from the MOXIE + package. +

+ Contents: +

world-var
add-hook
remove-hook
run-hook
add-keyword
remove-keyword
add-keystroke-macro
remove-keystroke-macro
send-to-mux
print-to-world
set-status-buffer
enable-logging
disable-logging
make-attributed-string
escape-mux-string
map-variables

+ +

Function WORLD-VAR

Syntax:

+ world-var name &optional (world-id *world*) => result +

+ (setf (world-var name &optional (world-id *world*)) new-value) +

+ +

Arguments and Values:

name---an object.

world-id---an object.

result---an object.

+ +

Description:

+ world-var is used to associate values, which are persistent throughout the application's lifetime, with name for a particular Moxie world, which has the unique identifier, world-id. +

+ setf may be used with world-var to modify the values associated with a given name, or to add a new entry. +

+ +

Examples:

  (setf (world-var :foo 0) 'bar) => BAR
+  (world-var :foo 0) => BAR
+  (world-var :foo 1) => NIL
+  (setf (world-var :foo 1) 'YOW) => YOW
+  (world-var :foo 1) => YOW
+  (world-var :foo 0) => BAR

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

Notes:

+ world-id is available as the *world* special variable. +

+ +

Function ADD-HOOK

Syntax:

+ add-hook function mode => hook-list +

+ +

Arguments and Values:

function--a function designator. +

mode---A keyword.

hook-list---A list containing the active functions for mode.

+ +

Description:

add-hook adds function to the list of functions to be run when + the hook mode is executed via run-hook.

+ +

Examples:

+  (defun my-printer (string)
+    (let ((string (if (stringp string) string (car string))))
+      (concatenate 'string "TEST: " string))) => MY-PRINTER
+  (add-hook 'my-printer :output-from-server-hook) => (MY-PRINTER)
+  (run-hook :output-from-server-hook "foo") => "TEST: foo"
+  (defun 'do-nothing (&rest args) nil) => DO-NOTHING
+  (add-hook 'do-nothing :output-from-server-hook) => (MY-PRINTER DO-NOTHING)
+  (run-hook :output-from-server-hook "foo") => "TEST: foo"

+ +

Side Effects:

function will be run by run-hook for mode.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ remove-hook + run-hook +

+ +

Notes: +

If function is already on the hook list for mode, it will + not be added again.

+ +

Function REMOVE-HOOK

Syntax:

+ remove-hook function mode => hook-list +

+ +

Arguments and Values:

function--a function designator. +

mode---A keyword.

hook-list---A list containing the active functions for mode.

+ +

Description: None.

+ +

Examples:

+  (remove-hook 'my-printer :output-from-server-hook) => NIL

+ +

Side Effects:

function is no longer called by run-hook.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ add-hook + run-hook +

+ +

Notes:

+ If function is not on the hook list for mode, the hook list is + returned without change. You can use this facility to get the current list + of functions for mode by removing NIL from the hook list. +

+ +

Function RUN-HOOK

Syntax:

+ run-hook mode &optional arg + => result* +

+ +

Arguments and Values:

mode---a keyword.

arg---an object.

results---the values returned by the last non-NIL terminating function.

+ +

Description:

+ Applies the + functions for mode to the args. +

+ A hook-list acts as a filter, passing the output of one filter into the input of + the next. If a function on the hook-list returns NIL, it is treated in this iteration + as if it hadn't been on the hook-list in the first place. Thus, the only time + run-hook returns NIL is when every function on the hook-list returns + NIL. +

+ +

Examples:

+  (run-hook :output-from-server-hook "Foobar!") => "TEST: Foobar!"

+ +

Side Effects: None.

+ +

Affected By:

+ The hook list for mode. All the functions on the list are called, in + order. The last function which returns a non-nil value is used as the result + function. +

+ +

Exceptional Situations:

+ If a function on the hook list for mode is not a function + designator, an error will be raised. +

+ +

See Also:

+ add-hook + remove-hook +

+ +

Notes: None.

+ +

Function ADD-KEYWORD

Syntax:

+ add-keyword function keyword => result +

+ +

Arguments and Values:

function--a function designator. +

keyword---a string.

result---the function designator for keyword.

+ +

Description: None.

+ +

Examples:

  (defun my-keyword (args)
+    (format t "Keyword expander: ~S~%" args)) => MY-KEYWORD
+  (add-keyword 'my-keyword "foo") => MY-KEYWORD

+ +

Side Effects:

+ keyword is registered for keyword expansion. +

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ remove-keyword +

+ +

Notes:

+ The keyword expander compares keywords in a case insensitive fashion. So "FOO" and + "foo" are equivalent. +

+ +

Function REMOVE-KEYWORD

Syntax:

+ remove-keyword keyword => result +

+ +

Arguments and Values:

keyword---a string.

result---the T on successful removal. NIL otherwise. +

+ +

Description: None.

+ +

Examples:

  (remove-keyword "foo") => T
+  (remove-keyword "foo") => NIL

+ +

Side Effects:

+ keyword is no longer expanded by the keyword expander. +

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ add-keyword +

+ +

Notes:

+ The keyword expander compares keywords in a case insensitive fashion. So "FOO" and + "foo" are equivalent. +

+ +

Function ADD-KEYSTROKE-MACRO

Syntax:

+ add-keystroke-macro function keystroke => result +

+ +

Arguments and Values:

function--a function designator. +

keystroke---a keyword.

result---the function designator for keyword.

+ +

Description: None.

+ +

Examples:

  (defun my-keystroke-macro (keystroke)
+    (format t "Should expand keystroke ~S here.~%" keystroke)) => MY-KEYSTROKE-MACRO
+  (add-keystroke-macro 'my-keystroke-macro :f1) => MY-KEYSTROKE-MACRO

+ +

Side Effects:

+ function is called when keystroke is pressed. +

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ remove-keystroke-macro +

+ +

Notes:

+ Unlike most other functions defined here, keystrokes don't do anything by default. + This means that in order to achieve some user-visible result, you'll have to use + the lower level functions print-to-world, or send-to-mux.. +

This format is likely to change very soon!

+ Keystrokes, currently, are keywords with the following format: +

+  keystroke := :[<modifier>-]*<keycode>
+  modifier := cmd|opt|ctrl|shift|numpad
+  keycode := <fkey>|character
+  fkey := f1 .. fn .. f35

+ So, hitting 8 on the number pad, while the command key is down yields the keyword: :cmd-numpad-8 +

+ +

Function REMOVE-KEYSTROKE-MACRO

Syntax:

+ remove-keystroke-macro keystroke => result +

+ +

Arguments and Values:

keystroke---a keyword.

result---T, if the keystroke was previously registered, NIL otherwise.

+ +

Description: None.

+ +

Examples:

  (remove-keystroke-macro :f1) => T
+  (remove-keystroke-macro :f1) => NIL

+ +

Side Effects:

+ keystroke no longer triggers a function call. +

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ add-keystroke-macro +

+ +

Notes:

This format is likely to change very soon!

+ Keystrokes, currently, are keywords with the following format: +

+  keystroke := :[<modifier>-]*<keycode>
+  modifier := cmd|opt|ctrl|shift|numpad
+  keycode := <fkey>|character
+  fkey := f1 .. fn .. f35

+ So, hitting 8 on the number pad, while the command key is down yields the keyword: :cmd-numpad-8 +

+ +

Function SEND-TO-MUX

Syntax:

+ send-to-mux world-id string +

+ +

Arguments and Values:

world-id---an object.

string---a string.

+ +

Description:

+ This is the low-level function to send data to the MUX server associated with + world-id. Currently, you can only send a string command, which will be + interpreted by the MUX directly. This may change in the future to allow for + attributed strings. +

+ +

Examples:

  (send-to-mux *world* (format nil "Wauug!~%"))

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ print-to-world + set-status-buffer +

+ +

Notes:

+ world-id is available as the *world* special variable. +

+ +

Function PRINT-TO-WORLD

Syntax:

+ print-to-world world-id arg +

+ +

Arguments and Values:

world-id---an object.

string---a string.

+ +

Description:

+ This is the low-level function to send data to the Moxie's world output view + associated with world-id. You can send either a normal string or an + attributed string for printing. +

+ +

Examples:

  (print-to-world *world* (format nil "Wauug!~%"))

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ send-to-mux + set-status-buffer + make-attributed-string +

+ +

Notes:

+ world-id is available as the *world* special variable. +

+ +

Function SET-STATUS-BUFFER

Syntax:

+ set-status-buffer world-id string +

+ +

Arguments and Values:

world-id---an object.

string---a string.

+ +

Description:

+ Sets the status buffer of the window associated with world-id to string. +

+ +

Examples:

  (set-status-buffer *world* "Hello, world!")

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ send-to-mux + print-to-world +

+ +

Notes:

+ world-id is available as the *world* special variable. +

+ +

Function ENABLE-LOGGING

Syntax:

+ enable-logging world-id +

+ +

Arguments and Values:

world-id---an object.

+ +

Description:

+ Enables logging for the world associated with world-id. +

+ +

Examples:

  (enable-logging *world*)

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ disable-logging +

+ +

Notes:

+ world-id is available as the *world* special variable. +

+ +

Function DISABLE-LOGGING

Syntax:

+ disable-logging world-id +

+ +

Arguments and Values:

world-id---an object.

+ +

Description:

+ Disables logging for the world associated with world-id. +

+ +

Examples:

  (disable-logging *world*)

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ enable-logging +

+ +

Notes:

+ world-id is available as the *world* special variable. +

+ +

Function MAKE-ATTRIBUTED-STRING

Syntax:

+ make-attributed-string string &rest attribute* => result +

+ +

Arguments and Values:

string---a string.

attributes---a list.

result---a list.

+ +

Description:

+ Creates a string with attributes applied to it. This allows you to change various display properties of the string, such as the color, font, and style. +

+ +

Examples:

+  (make-attributed-string "Wauug!" (make-range 0 (length "Wauug!"))
+                                   (make-color 100 100 100)
+                                   (make-underline 1)) => ("Wauug!" ((:RANGE 0 6)
+							             (:COLOR 100 100 100)
+							             (:UNDERLINE 1)))

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ make-range + make-font + make-color + make-super + make-underline + make-link +

+ +

Notes:

+ The only hook, currently, which can use attributed strings is :output-from-server-hook, which calls on print-to-world to display results. Those are the only places within Moxie to which you should be sending attributed strings. +

+ +

Function MAKE-RANGE

Syntax:

+ make-range index length => result +

+ +

Arguments and Values:

index---a bounding index designator. +

length---a non-negative integer. +

result---a list.

+ +

Description:

+ Creates a range object from index for a length. +

+ +

Examples:

  (make-range 0 (length "Wauug!")) => (:RANGE 0 6)

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ make-attributed-string + make-font + make-color + make-super + make-underline + make-link +

+ +

Notes:

+ This function is likely to go away in the future as the attributed string mechansism gets cleaned up. +

+ +

Function MAKE-FONT

Syntax:

+ make-font name size => result +

+ +

Arguments and Values:

name---a string.

size---a real. +

result---a list.

+ +

Description:

+ Creates a font object. The font is located by name and is size points high. +

+ +

Examples:

  (make-font "apple-monaco" 12.0) => (:FONT "apple-monaco" 12.0)

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ make-attributed-string + make-range + make-color + make-super + make-underline + make-link +

+ +

Function MAKE-COLOR

Syntax:

+ make-color red-value green-value blue-value => result +

+ +

Arguments and Values:

red-value---an integer between 0 and 255. +

green-value---an integer between 0 and 255. +

blue-value---an integer between 0 and 255. +

result---a list.

+ +

Description:

+ Creates a color object with the specified values for red, green, and blue. +

+ +

Examples:

  (make-color 100 100 100) => (:COLOR 100 100 100)

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ make-attributed-string + make-range + make-font + make-super + make-underline + make-link +

+ +

Function MAKE-SUPER

Syntax:

+ make-super level => result +

+ +

Arguments and Values:

level---a non-negative integer. +

result---a list.

+ +

Description:

+ Creates a superscript attribute at the specified level. At level 0, the text is inline with normally attributed text, at each level above 0, the text moves higher and becomes smaller, denoting a superscript. +

+ +

Examples:

  (make-super 1) => (:SUPER 1)

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ make-attributed-string + make-range + make-font + make-color + make-underline + make-link +

+ +

Function MAKE-UNDERLINE

Syntax:

+ make-underline level => result +

+ +

Arguments and Values:

level---a non-negative integer. +

result---a list.

+ +

Description:

+ Creates an underline attribute with level number of underline strokes. +

+ +

Examples:

  (make-underline 1) => (:UNDERLINE 1)

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ make-attributed-string + make-range + make-font + make-color + make-super + make-link +

+ +

Function MAKE-LINK

Syntax:

+ make-link url => result +

+ +

Arguments and Values:

url---a string.

result---a list.

+ +

Description:

+ Creates a link attribute, pointing to url. +

+ +

Examples:

  (make-link "http://www.spork.org/") => (:LINK "http://www.spork.org/")

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

See Also:

+ make-attributed-string + make-range + make-font + make-color + make-super + make-underline +

+ +

Function ESCAPE-MUX-STRING

Syntax:

+ escape-mux-string string => result +

+ +

Arguments and Values:

string---a string.

result---a string.

+ +

Description:

+ This function is used to create pre-formatted strings for a MUX. MUXes normally ignore sequences of white space, and error on newlines, ignoring tab markins except as their capacity for white space. You can get around this by injecting %r, %t, and %b for newlines, tab characters, and white space, respectively. This function does that for you. +

+ +

Examples:

  (escape-mux-string "xyzzy plugh") => "xyzzy%bplugh"

+ +

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ +

Notes:

+ This function may only be useful for MUSHes. If your MUX escapes strings differently than a MUSH, then you will need a new function. +

+ +

Function MAP-VARIABLES

Syntax:

+ map-variables string variable-list=> result-string +

+ +

Arguments and Values:

string---a string.

variable-list---a list containing the variable substitutions for string. +

result-string---a string.

+ +

Description:

+ map-variables returns a string composed by substituting patterns of + the form $number$ from string with those places in variable-list. + So, $1$ refers to the first position (i.e., car) of the list + variable-list. +

+ +

Examples:

+  (map-variables "one: $1$ two: $2$ three: $3$" '(1 2 3)) => "one: 1 two: 2 three: 3"

Side Effects: None.

+ +

Affected By: None.

+ +

Exceptional Situations: None

+ + -- cgit v1.3