The text node, predictably, is used to store text. This text is not interpreted or "understood" in any way defined by this specification; it is purely intended for application-specific use (hopefully conforming to an auxiliary standard or set of guidelines).
The intended use for text nodes is to store programs in source code format, that can be linked to objects in order to provide them with scripted "behaviors" through the use of object methods.
Each text node has a language field, which is simply a text string that names the language used for the content of that node.
There is no default or "native" language specified in Verse; you are free to write clients to support any language you chose, or to invent new languages. Such a client would typically implement a way for scripts to access Verse by sending and receiving node commands, but need not mimic the reference implementation when doing so.
The language name "text" is reserved for text in natural languages. To specify a single language, use a slash followed by an ISO 639:1988 standard code. Text in English would then be "text/en".
For programming language names, it is advised that the name is chosen to include a version number and a part that identifies the kind of Verse application programming interface used. This is because there may be multiple APIs defined for a single language, and interpreter clients need to determine if they should attempt to interpret a buffer or not. For instance, a file written in C and using the reference API might have a language string of "C/std". Text in XML as used by the "Purple" plug-in scripting engine is given a language starting with "XML/purple".
Data in a text node is arranged into buffers. A buffer can be thought of as simply a named text file; it consists of a linear sequence of characters. The sequence can be indexed, beginning from 0 which is the first character (if present).
Changing the content if a text buffer is done through a single command, called t_text_set. This command is fairly powerful, it combines two operations into one:
Deleting a range of text.
Inserting new text.
Here is an example showing the contents of a text buffer during the execution of a sequence of t_text_set commands:
Example 2-3. The t_text_set Command
Initially, the buffer is empty. We will show the text between square brackets, in an attempt to indicate the start and end clearly:
[]At this point, we execute the command t_text_set with range [0,0) [1] and new text equal to "foorag". Since the range is empty, this ends up being a straight insert, leaving the new state as simply the new text:
[foorag]The next command to execute has range [3,3), i.e. an empty range, and the text "ba". We get:
[foobarag]Finally, execute a command with range [6,8) and en empty new text, to delete the last two characters. Result:
[foobar]
It is important to realize that a single command is generally not enough to send the entire contents of a text buffer. There is an inherent limit on the amount of data in a single command, for network efficiency reasons. For such buffers, a sequence of commands will be required to send over the full content. For typical purposes, sending more than ~1,000 bytes of text per command should be avoided.
| [1] | Ranges are given in [start,end) notation. The interpretation is "all characters from index start up to, but not including, index end". This means that the number of deleted characters is computed by end - start, and this that a range where start and end are the same, is empty. |