Custom POO Editors

Introduction

POO provides a very simple built-in editor. This is the editor invoked by commands such as @edit or @newfunc, if your ".editor" property is undefined or cannot be executed as a custom editor.

However, if you set your ".editor" property to a properly written custom editing function, that function will be used instead of the built-in editor. Since it requires wiz privs to set a reference to a function you do not own, non-wizards will have to change their editor with a command such as the following:

@editor notvi This command (if installed on your POO) will set your editor to the function stored as $pub.editors.notvi -- to return to the default editor, use "@editor default".

Creating Custom Editors

WARNING: Creating custom POO editors is Big Magic. If you do doubt your skill or your courage, go no further, for frustration awaits you with big nasty pointy teeth!

An editor function has the form:

myEditor( self, buffer, msg, state )

self: the object on which the editor is being invoked
buffer: a list of strings -- the lines being edited
msg: the line typed by the user at the "edit>" prompt
state: editor-defined state variable; initially None

The editor function must examine the msg and state parameters to decide how to process the buffer. It must then return a new state, which will be passed back upon the next entry by the user. "state" may be any datatype, but two return values have special meaning to the POO engine:

"DONE": exit the editor and save changes
"ABORT": exit the editor, discard changes

You must return one of these two strings to end the editing session. Any other return value will be passed back to you as the state parameter.

Note: if msg is '.x' you must exit with "DONE", and if it is '.q' you must exit with "ABORT". These are enforced by the POO engine; if you don't interpret these messages, the normal save/abort behavior will be invoked regardless. This is to prevent users from getting "stuck" in a custom editor and unable to exit.

If your code raises an exception, it will be caught silently and the built-in editor will be invoked instead. This makes debugging difficult; the only way to debug is to manually invoke your editor, e.g.,

;me.myEditor(['line one','line two'], '.x', "OK")

Sample Editor

The code below can be executed by a wizard to create a minimal custom editor. To restore the default editor, use @delprop me.editor.

@newfunc me.testEditor( self, buffer, msg, state )
print "in " + str(self) + "'s editor, with ", \
	"buffer: ", buffer, "msg: ", msg, "state: ", state
# for this ultra-simple editor, the only command we recognize
# is "." to exit; anything else is text to append to the buffer.
if not state:
	print "[Cheezy line-entry editor -- enter a period when done.]"
	return "OK"		# we'll use "OK" to mean "ready to accept input"
if msg == ".":
	return "DONE"	# <-- special keyword, indicates we're done editing
else:
	buffer.append(msg)
	print "new buffer:", buffer
	return "OK"
.x

@set me.editor = me.testEditor

Cautions

Nonwizards cannot assign functions they do not own to properties. So to make an editor publicly available, something like $pub.editors should be used.

Python objects don't die as long as any references to them exist. So if you recreate your editor with @newfunc, and other players have references to it, they will continue to use the old code. To avoid this mess, always update an editor function with @edit rather than @newfunc.

Summary

Custom editors are a powerful feature of POO that allow the simple built-in editor to be replaced with a variety of more sophisticated ones, automatically invoked for each user according to his preference. Writing a custom editor is difficult, but once done, the functionality of POO can be significantly enhanced without modifying the engine code.

http://www.strout.net/python/poo/editors.html
Last Updated: 8/14/97 . . . . . . Joe Strout