psyctext template format

PSYC has a template syntax by the MIME type text/x-psyc also known as psyctext. It allows for errors, warnings and other automatically generated messages to be both readable for humans and automatons. The variable names in brackets SHOULD be replaced by the actual content of the variable, when presented to the user.

     Example:
     	:_method        i
       _error_unsupported_method
       No such method '[_method]' defined here.
       |

This should display as

       No such method 'i' defined here.

When no match is found, like in the case of a template containing array[i++] where a variable called i++ does not exist, the string remains unchanged. This is not an error.

For a likely future extension, see Talk:Entity.

API

This is the current definition of the psyctext implementation in psyced.

string psyctext(string template, mapping vars, string data)

You feed it with a protocol template like

"[_nick] [_action]: [_data]"

and it will replace the variables from the variables mapping and the _data from the message body.

Simple and straightforward.

Rationale

This allows the protocol to provide both technical information for automatic processing in well-defined storage elements and practical end-user messages for simple implementations which don't want to do complicated things. Thus enabling extremely slim clients that know close to nothing: As long as you can issue a command and read the results, you can use close to any protocol feature.

This invites innovation. Imagine you want to implement a chatroom that remote controls an SQL database (just a stupid example). You could create slash commands for all SQL statements and invent new _status, _error etc for all of the results SQL may return. This allows for a full scale integration of SQL into PSYC, but at the same time any existing PSYC client enables you to use your brand new interface.

This is actually a pretty unique strength of PSYC. In comparison, IRC has clumsy messages which do not really help, like

ERR_USERONCHANNEL
 "<user> <channel> :is already on channel"

ERR_USERNOTINCHANNEL
 "<nick> <channel> :They aren't on that channel"

which requires IRC clients to ignore those messages and create its own ones, thus implementing every little detail of the protocol, which by consequence makes the introduction of new features harder. When new numeric messages are added to an IRC server, you can't even be all sure IRC clients will display them. If they do, they will be in whatever language the programmer used – and they will look strange because of the prepended arguments.

Jabber/XMPP does not even attempt to provide many end-user messages, and if we introduced that we'd have a problem specifying which elements of the XML tree are to be used in the template, probably leading to duplication of the content, as it is probably easier than implementing an XPath-like strategy. At least, when it comes to introducing new messages, you can just do a namespace extension of an existing message and the client will treat it like it didn't have that extension. Or at least that's the theory. Clients hardly ever encounter extensions they haven't negotiated first, so in the end when introducing new features you typically also have to upgrade all clients.

Notes

• Note on compact vars: don't assume that all psyctext keywords will always begin with _

PSYCText Templates are of the form [ ] with any valid keyword name inside the brackets. once we have compact vars, [_action] becomes [a]

JavaScript Implementation

See PsycZilla for a JavaScript Implementation of this feature. The psyctext function is provided through the prototype of PsycPacket. See psyc/packet.js in the PsycZilla archive.

Helpful pieces:

Regular Expression to find the variable placeholders:

 /* RegExp to find psyc tags like: [_varName] */
 var tagsExp = /\[_\w+\]/g;

Especially interesting is the psychtml() function further low.

psycTiVE uses a simplified variant instead, that goes like..

       public static function psyctext(message : String, vars : Object) : String {
               for( var k:String in vars ) {
                       message = message.split("["+ k + "]").join(vars[k]);
               }
               return message;
       }

This is a very nice to read approach, but with so many splits going on, not exactly easy on the processing. With this approach, to do an HTML version you can clone the vars and htmlize them before you enter psyctext, but PsycZilla's way of doing it is certainly more efficient.