1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Plugin Lifestyle</title>
<meta name="generator" content="BBEdit 6.5">
</head>
<body>
<h1><a id="intro">Introduction</a></h1>
<h2>Or: The worlds of MUXing are varied, so why shouldn't my viewer be?</h2>
<p>
Most MUXes are built off very similar codebases and design patters, but
within those similar roots are an infinite and varied number of worlds.
</p>
<p>
In order to cope with the almost maddening variety in MUXing,
programmatically, you have to develop some kind of programming language.
For instance, TinyFugue's trigger's are a simple programming language.
</p>
<p>
So, to allow for the largest amount of flexibility in Moxie, Moxie
includes a full programming language. While inventing one specifically
for Moxie would certainly be the norm, it is not something that should
be valued highly. In fact, by using a standard language, you get a lot
of benefits of useably free code-base.
</p>
<p>
So, Moxie includes an <a href="http://clisp.cons.org/">embedded lisp
interpreter</a>. This gives you the full power of the Lisp language from
within your plugin code. What kind of things you write, and how you want to
interact with Moxie and your MUX are limited only by your imagination.
</p>
<p>
This does mean you'll have to learn Lisp - at least a little - in order
to write any plugins for Moxie, although I will endeavour to keep things
as simple as possible throughout this document.
</p>
<h1><a id="quickstart">Quick Start</a></h1>
<h2>Or: Just Gimme the Code, and I'll Come Back When I Need You.</h2>
<p>
The simplest plugins are keyword expansions: when you type
"/foobar baz" into Moxie, it will try to trigger keyword expansion for
the keyword "foobar".
</p>
<p>
To register a keyword expander, you first have to write the code
for the expander, then register it with the keyword expansion hook.
all the functions referenced here are exported from the MOXIE
<a href="lisp-glossary.html#package">package</a>.
</p>
<p>
First, we'll create a package for our test plugin, and use the moxie
<a href="lisp-glossary.html#package">package</a>, as well as the
<a href="lisp-glossary.html#bjc-utils">bjc-utils</a> package.
</p>
<pre>
(defpackage test-plugin
(:use :cl :cl-user :moxie :bjc-utils))
(in-package :test-plugin)
</pre>
<p>
Then we define our expander function. We just want to take a name off
of the argument line, and page them with "hello!". For the sake of
debugging, we also want to print out what we got as the argument
to the lisp <a href="lisp-glossary.html#repl">REPL</a>:
</p>
<pre>
(defun foobar-handler (string)
(format t "foobar-handler got: ~A~%" string)
(map-variables "page $1$ = hello!"
(split string #\Space)))
</pre>
<p>
The function we've defined returns the string from the map-variables
command. This return value is what's sent to the MUX. If we don't want
to send anything to the MUX you can return an empty string ("") or
nil.
</p>
<p>
Now that we have the function defined, we want to register it with
the keyword expansion hook:
</p>
<pre>
(add-keyword 'foobar-handler "foobar")
</pre>
<p>
To test this, first bring up the REPL window so we can see what's
being printed out by the function as it runs. To do this, select
"Lisp REPL" from the "Window" menu.
</p>
<p>
Now, in Moxie, type "/foobar me", and, assuming you're connected
to a MUX, you should get a page from yourself saying, "hello!".
In the REPL window, however, you'll see:
</p>
<pre>
foobar-handler got: me
</pre>
<p>
Which means the handler received the string "me" as the argument
string.
</p>
<p>
If you're curious how the functions map-variables and split work,
in the REPL, type "(documentation 'map-variables 'function)" to view
their documentation.
</p>
<p>
There are other pre-defined triggers that work in a similar fashion.
There is a list of them in the moxie.lisp file in the
<a href="#app-source">resources directory</a>.
</p>
<h1><a id="app-predefs">Appendix: Pre-defined variables and triggers</a></h1>
<p>
Moxie uses a set of pre-defined symbols to communicate with the lisp
sub-system. Below is a table of symbols, what type they are, and what
they do.
</p>
<table border=1>
<tr>
<td>Name</td>
<td>Type</td>
<td>Description</td>
</tr>
<tr>
<td>moxie::*moxie-result-stream*</td>
<td>stream</td>
<td>The stream for communicating with Moxie.</td>
</tr>
<tr>
<td>moxie::*world*</td>
<td>object</td>
<td>The currently active world-id. This may be 0, if a world hasn't called into
the plugin system.</td>
</tr>
<tr>
<td>moxie::eval-hook</td>
<td>function</td>
<td>Used by Moxie to send data from the REPL window to the
lisp plugin system.</td>
</tr>
<tr>
<td>moxie::input-to-server-hook</td>
<td>function</td>
<td>Used by Moxie to send data to the lisp plugins after receiving
something from the input line.</td>
</tr>
<tr>
<td>moxie::output-from-server-hook</td>
<td>function</td>
<td>Used by Moxie when data is received from the MUX for display
on the screen.</td>
</tr>
<tr>
<td>moxie::keystroke-hook</td>
<td>function</td>
<td>Used by Moxie when a registered keystroke is pressed to call into its
function</td>
</tr>
<tr>
<td>moxie::world-opened-hook</td>
<td>function</td>
<td>Used by Moxie to tell the plugin system a new world has opened.</td>
</tr>
<tr>
<td>moxie::world-closed-hook</td>
<td>function</td>
<td>Used by Moxie to tell the plugin system a world has closed.</td>
</tr>
<tr>
<td>moxie::start-logging-hook</td>
<td>function</td>
<td>Used by Moxie to tell the plugin system it wishes to log transcripts.</td>
</tr>
<tr>
<td>moxie::stop-logging-hook</td>
<td>function</td>
<td>Used by Moxie to tell the plugin system it no longer wishes to log.</td>
</tr>
</table>
<h1><a id="app-source">Appendix: Sample source code</a></h1>
<p>
You can find definitions for all the built in functions in the Application
bundle: <code>Contents/Resources/*.lisp</code>. The file <code>startlisp</code>
parses the file <code>init-template.lisp</code> and starts the lisp with the parsed
file, loading the rest of the plug in system with it.
</p>
<p>
There are certain hooks in <code>tpl.lisp</code> which the application calls. You
can have a look at them, and even change them if you want, but don't
rename them or Moxie won't work anymore.
</p>
<p>
Also included in the Application Plug-Ins directory are a few pre-supplied plug ins
which you can use as an example. This includes the default logger, numpad movement macros,
and ANSI color support.
</p>
</body>
</html
|
