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

Introduction

Or: The worlds of MUXing are varied, so why shouldn't my viewer be?

+ Most MUXes are built off very similar codebases and design patters, but + within those similar roots are an infinite and varied number of worlds. +

+ 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. +

+ 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. +

+ So, Moxie includes an embedded lisp + interpreter. 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. +

+ 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. +

+ +

Quick Start

Or: Just Gimme the Code, and I'll Come Back When I Need You.

+ The simplest plugins are keyword expansions: when you type + "/foobar baz" into Moxie, it will try to trigger keyword expansion for + the keyword "foobar". +

+ 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 + package. +

+ First, we'll create a package for our test plugin, and use the moxie + package, as well as the + bjc-utils package. +

+      (defpackage test-plugin
+        (:use :cl :cl-user :moxie :bjc-utils))
+      (in-package :test-plugin)
+

+ 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 REPL: +

+      (defun foobar-handler (string)
+        (format t "foobar-handler got: ~A~%" string)
+        (map-variables "page $1$ = hello!"
+                       (split string #\Space)))
+

+ 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. +

+ Now that we have the function defined, we want to register it with + the keyword expansion hook: +

+      (add-keyword 'foobar-handler "foobar")
+

+ 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. +

+ 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: +

+      foobar-handler got: me
+

+ Which means the handler received the string "me" as the argument + string. +

+ If you're curious how the functions map-variables and split work, + in the REPL, type "(documentation 'map-variables 'function)" to view + their documentation. +

+ 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 + resources directory. +

+ +

Appendix: Pre-defined variables and triggers

+ 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. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Name	Type	Description
moxie::moxie-result-stream	stream	The stream for communicating with Moxie.
moxie::world	object	The currently active world-id. This may be 0, if a world hasn't called into + the plugin system.
moxie::eval-hook	function	Used by Moxie to send data from the REPL window to the + lisp plugin system.
moxie::input-to-server-hook	function	Used by Moxie to send data to the lisp plugins after receiving + something from the input line.
moxie::output-from-server-hook	function	Used by Moxie when data is received from the MUX for display + on the screen.
moxie::keystroke-hook	function	Used by Moxie when a registered keystroke is pressed to call into its + function
moxie::world-opened-hook	function	Used by Moxie to tell the plugin system a new world has opened.
moxie::world-closed-hook	function	Used by Moxie to tell the plugin system a world has closed.
moxie::start-logging-hook	function	Used by Moxie to tell the plugin system it wishes to log transcripts.
moxie::stop-logging-hook	function	Used by Moxie to tell the plugin system it no longer wishes to log.

+ +

Appendix: Sample source code

+ You can find definitions for all the built in functions in the Application + bundle: Contents/Resources/*.lisp. The file startlisp + parses the file init-template.lisp and starts the lisp with the parsed + file, loading the rest of the plug in system with it. +

+ There are certain hooks in tpl.lisp 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. +

+ 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. +

+ +