The purpose of this document is to talk through the objectives of the existing formatting system, then talk about how it works, and finally to show examples of usage from an in-game coder's perspective.
The formatting system has to be able to handle the following things:
Additionally, it needed to be readable by coders--so it had to be a markup language. The formatting system had to be capable of adding and removing formatting information from text so that we could parse it without having to deal with the formatting markup.
The mudlib.formatter module encapsulates all the formatting code and abstracts the rest of the mud from the underlying markup language used and the semantics of how formatted text gets converted.
The mudlib.formatter module has:
The other module that's important is the mudlib.constants module which holds all the color constants.
The formatting system uses markup that's similar in style to HTML but it uses different tags than HTML so players can talk about HTML in-game without having their conversations suddenly turn funny colors.
The formatting markup looks like this:
<color v=...>some text</color> for colors <indent v=...>some text</color> for indenting
The value of the color tag can be any of the color constants in the mudlib.constants module. It can also be an ansi variable.
Ansi variables are how we allow players to personalize the color settings of their account. For example, Fred likes to have everything that's said to him in yellow so he can easily read it on his screen. But Barney hates yellow and prefers dark blue.
The ansi variable that the say command uses for color markup is 'say'. So, when Fred goes to set up his ansi preferences, he would type:
> #ansi on Ansi colors turned ON. > #ansiset say yellow Ansiset var 'say' -> yellow added.
Now whenever someone says something to Fred using the say command, the beginning part will be yellow.
The code for the say command is as follows:
from formatter import *
...
thisPlayer.getEnvironment().tellRoom([thisPlayer],
precolor("say"),
stdlib.VBFC(language.addDefiniteArticle,
thisPlayer.getShortDescription),
" says: " + postcolor(),
indent(5, arguments))
The precolor function uses the string "say". If Joe were to say "hi fred" to Fred, then the text that goes to Fred would be:
<color v=say>Joe says:</color> hi fred
And if Fred had ansi turned on, then the color tags would be replaced with the appropriate ANSI color codes and then sent over the network connection to Fred's mud client.
Here's an example of formatting used in in-game code:
from mudlib.constants import *
import mudlib.formatter
...
pl.write( mudlib.formatter.color(BLUE, "This text is blue") )
In the mudlib.constants module are all the color constants.
This fragment of code shows the use of the color function which colors the text "This text is blue" the color blue. It's pretty straightforward.
In a more complicated example, we use VBFCs in a list which breaks up the color string. color cannot handle VBFCs. So what we do is this:
from formatter import *
...
thisPlayer.getEnvironment().tellRoom([thisPlayer],
precolor("say"),
stdlib.VBFC(language.addDefiniteArticle,
thisPlayer.getShortDescription),
" says: " + postcolor(),
indent(5, arguments))
Here, because the text we want to color is not a string, but the result of a list of VBFCs and text, we use the precolor and postcolor functions to deal with the markup.
Tags that the formatter doesn't recognize will continue with the text. For example, Bluemud doesn't use the <b> ... </b> tag so it ignores it.
This does a couple of things. It allows people to talk about XML and HTML while online (I tend to log in when I have HTML issues and ask for help on the mud) and it also allows us to use < ... > syntax in command help files where we specify required arguments. It also allows coders to see where they screwed up the formatting text in descriptions rather than have the formatting mistakes dissappear.
For more details and specifics, read through the mudlib.formatter and mudlib.constants modules. Examples of formatting usage are all over the mudlib and world code. You'd be hard-pressed to not be able to find any.