Phantasmal Site > Phantasmal Operation > UNQ DTDs

UNQ DTDs: What Are They?

Like XML, UNQ can be used to store structured data. Like XML, UNQ uses files called Document Type Definitions to define the document's structure. "Document Type Definition" is usually abbreviated as DTD, both for UNQ and XML.

UNQ DTDs are stored in DTD files. They can't currently be embedded in the actual UNQ file they refer to. Since we normally use a single DTD for a much larger batch of UNQ data, that's currently considered a reasonable restriction. If you need it changed, the code is all public, and the entire UNQ system is relatively easy to extract from Phantasmal.

An UNQ DTD file defines the DTD with an UNQ structure. Here's an example:

~DTD{
  ~object{name,number?,location?,bdesc,gdesc,ldesc,edesc?,location,nouns,
           adjectives?}
  ~name{string}
  ~location{string}
  ~number{integer}
  ~bdesc{phrase}
  ~gdesc{phrase}
  ~ldesc{phrase}
  ~edesc{phrase}
  ~nouns{phrase+}
  ~adjectives{phrase*}
}
  

The outside label must be "DTD", as above. The inner labels describe the fields of the structure defined by the DTD. There are built-in data types called "phrase", "string" and "integer" that are fairly self-explanatory (a "phrase" is a localized string type used by Phantasmal — it can just be a string, which is assumed to be English, or can contain translations to zero or more other languages).

Inside the curly braces after each inner label there are zero or more data types, possibly followed by characters like "*" and "?". If there are more than one, they are separated by commas. The entry above would match UNQ text like what follows:

~object{
  ~name{snowglobe}
  ~bdesc{a snowglobe}
  ~gdesc{a snowglobe with a snowman inside}
  ~ldesc{~enUS{The snowglobe has a ~i{snowman} inside, and tiny white flakes
               swirl around inside.}}
  ~edesc{The snowman has a carrot nose!  How cute!}
  ~nouns{{~enUS{snowman}~esUS{hombre de nieve}}
         {snowglobe}
         {globe}{flakes}{snow}}
  ~adjectives{{snowy}{snow-filled}}
}
  

The trailing characters tell the parser how many instances of the data type to match. For instance, if there are no trailing characters and the type is integer (such as in the "number" entry, above) then inside the curly braces should be a single whole number. You could add the line ~number{374} to the data above and it would parse just fine. The UNQ data would fit the DTD.

A trailing question mark means that zero or one instances are allowed. In the definition of "object", you'll see "number?" in between the commas. That means that you can include it or not, but you can have no more than one.

A plus sign means that you can have one or more of something. So in the definition of "nouns", where it says "phrase+", that means that you can have several nouns, or just one. However, if you have the "nouns" entry, you must have at least one phrase there. The "*" symbol is similar, but you can have none at all. The "adjectives" field uses that because you don't need to have any adjectives for an object.

The "integer" built-in type means a whole number, which can be positive or negative. The "string" type is any normal text. The "unq" built-in type is like a string, except that you can include UNQ tags (as long as they're balanced and the UNQ is valid!) inside. The "float" built-in type means a floating-point number, which is to say a number that can have a decimal fraction with it like "3.743". Floating-point numbers can also be either positive or negative.