Back in the days of yore, machines had limited memory, and life was hard. Compiled messages were originally designed to allow offline storage of large amounts of text for retrieval at runtime. These messages allow variable expansions and limited formatting capabilities. In Rapture, they are present mainly for compatibility with the existing projects which use this system. Offline storage is simulated (no sense slowing things down if there’s plenty of memory) and thus much faster. However, due to the inherent problems in the readability of source code and poor maintenance practices, general use of messages is frowned upon.
Messages are simply a string of text (with optional variable expansions embedded in it) associated with an ID. This ID can then be used to lookup and expand to the string value stored in an internal table. The messages are in a plain text file with a basic format:
<message1 ID>
<message1 text>\e
<message2 ID>
<message2 text>\e
...
That’s it. A message ID (an integer) on a line by itself. Followed by one or more lines of text that should be the message body. Note that the text will not retain whitespace formatting, and is terminated by the \e character sequence. The message IDs must be unique in the entire project and are used to identify the text stored within the executable. Once the message file has been compiled, it turns into a normal linkable object file. Message files have special escape sequences available for message text:
Sequence Meanings
\n Insert a newline character
\t[<n>] Insert <n> spaces.
\p[<x>] Position cursor <x> characters from the left edge of user's terminal.
\f[<color>] Change foreground color to <color>
\b[<color>] Change background color to <color>
\e Terminating sequence
\\ A literal '\' character.
Variable expansions are also available within the body of a message. To expand a variable, simply enclose its name within a $[<mod>](<variable>) sequence. (Use $$ to place an actual dollar sign character.) The <mod>, if present, is one of the following:
= Leave it as is (this is for compatibility)
++ Make the entire expansion uppercase
- Make the entire expansion lowercase
+ Make only the first character uppercase
These are used only to change the capitalization of the value expanded from the variable. The <variable> part is just the variable as it would appear in a RPL procedure (or a global). The name is expanded using the scoping rules (locals before globals) and its current value is retrieved.
All of this is facilitated by the use of the valid_message() and msg$() internal routines. The first returns true if the ID given is that of a valid (i.e. defined) message. And the second will lookup the message body, perform any expansions, and return the resultant string. It should be noted, however, that use of this indirect system of expansions is slightly slower than hard coding the expansions in RPL source code. Also, there is now an internal routine called expand$() which does a similar task of variable expansions with an arbitrary string parameter (useful, but slow).