Contents

the PSYC text template database

This is a mechanism deployed with psyced, but in similar way also used by ppp and maybe other PSYC applications. It is a way to keep psyctext templates in an external file rather than having them scattered all over the source code.

This is similar to the PO files used by GNU's gettext, however we needed a way to map from mc to each template rather than to map from an english language template to other templates. So the PSYC textdb is actually more generic than gettext.

Additionally, textdb supports not only multiple languages, but also multiple protocol formats and design variations of each of these.

Text database API

The API for textdb typically looks like this:

#include <text.h>
localize(language, scheme);
template = T("_notice_whatever", "An optional default template");

but in most cases you don't need to use it as both sendmsg and castmsg automatically use the textdb where appropriate (see API).

Text database file format

This is a description of the .textdb file syntax.

Header

The file starts out with a totally arbitrarily chosen recognition string:

<PSYC:TEXTDB>

For pragmatic reasons any text following on the same line is ignored, this is useful to specify a syntax mode for vim. We like to use the following for regular textdb

<PSYC:TEXTDB> ## vim:syntax=mail

and the following for html.textdb which contains mostly mark-up:

<PSYC:TEXTDB> ## vim:syntax=html

That statement may be followed by further comment lines which start with the double hash sign, but may not leave an empty line in between. As in

<PSYC:TEXTDB> ## vim:syntax=html
## Hello, this is my first textdb!

Entries

The empty line is considered the entry seperator. Each entry starts with the uncompressed message code (see Method Naming) followed by a series of text lines preceded by the pipe symbol. For instance

_status_person_amount
|#251 [_nick_me] :There are [_amount] users on this server

makes it such, that the template for the _status_person_amount message code is going to contain the string "#251 [_nick_me] :There are [_amount] users on this server" which will later be converted to an IRC numeric by the IRC emulation of psyced after processing the template with psyctext.

Pseudo Message Codes

A textdb doesn't just contain official message codes, it also contains local extensions of them and several internal pseudo families of message codes. Some examples:

_MISC_character_command
|/

The default command character for this server.

_MISC_color_private
|#ff6666

The color for private messages, used by the applet.

_MISC_fonts
|arial,helvetica

Font list used by both web pages and applet.

textdb Inheritance

Well in fact the applet usually uses a different entry which looks like this:

_MISC_fonts_applet
|helvetica

but if that entry weren't available, the textdb mc inheritance feature would make it use _MISC_fonts instead.

textdb Language & Scheme Inheritance

In fact, before using the higher level family, textdb first tries out the other textdb instances in its inheritance chain, which is english after specific language and plain database after protocol specific database. Only if no entry for _MISC_fonts_applet is found in any of these databases, _MISC_fonts is used instead. So if your textdb file does not contain a certain method, you will probably find it in the basic system textdbs. A recursive grep in your copy of the psyced world/default directory shall help finding them.

Include Syntax

Textdb also provides for a form of server-side include, allowing for parts of a template to be modularized. We use it primarily to keep translations of typical phrases in their own entry, so that several templates can refer to them. Here's an example:

_status_person_present
|{_TEXT_present}: [_nick]

This one refers to the _TEXT_present entry for the current translation. Here's that entry from the german plain.textdb:

_TEXT_present
|Anwesend

whereas in the english one it reads Present.

Multiline & Comments

Did I mention the entries are multiline? Just look at html.textdb for entire web pages embedded into textdb.

The current syntax for comments is intentionally clumsy. You need to have both the entry prefix '|' and additionally the double hash '##' comment sign. As in:

_failure_exceeded_limit_users
|## This is just a comment.
|Extremely sorry, the maximum possible amount of people on this
|server has just been reached. But do try again soon, please!

The double hash is a consequence of some messages needing to start with a single hash character.

By the way, for hysterical reasons the comments are not removed at textdb parsing time, but later at application time. This allows for saving the comments back, should we regenerate textdb out of memory. So consider them a little expensive.

Builtin Macros

These are the builtin { } expansions defined in psyced's text.c. The names aren't brilliantly chosen or even logical according to the inheritance rules, thus subject to change.

_URL_img HTTP prefix string for images
_URL_applet HTTP prefix string for applets (java or flash)
_VAR_charset System charset, usually UTF-8
_VAR_host Nickname of the entire chatserver
_VAR_method Current mc being retrieved from textdb
_VAR_server Hostname or IP number of the server
_VAR_server_uniform Uniform of the root entity of the server
_VAR_server_XMPP XMPP uniform of the server
_VAR_server_version Version string of the application
_VAR_server_version_minor Just the minor version number

Application

The .textdb files are kept in http://www.psyced.org/dist/world/default/ and parsed by http://www.psyced.org/dist/world/net/text.c which isn't exactly an easy read to get started with LPC. Just mentioned for completeness.

psyced also supports fetching textdb files from remote webservers.

Implementations: text.c | Text.pmod