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.