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.