Skip to content

Taml Guide

Jump to bottom
MelvMay-GG edited this page Feb 18, 2013 · 14 revisions

Introduction

TAML is an acronym of Torque Application Mark-up Language. It decribes a method of persisting type instances in various output formats. TAML is designed to be extremely easy to use and provides a nice consistent method of persisting information.

Prerequisite Knowledge

This document assumes knowledge of the TorqueScript Syntax only.

TorqueScript Bindings

Starting Out

TAML was designed to be easy to use and in that sense, the following code should be easy to understand:

// Create a sprite.
%obj = new Sprite();

// Write it out.
TamlWrite( %obj, "stuff.taml" );

This will write the following XML file:

<Sprite/>

That's pretty simple and shows a basic principle when the output format is XML in that an XML element denotes a type to be created, in this case it's the "Sprite" type. It should also be clear that nothing else related to the "Sprite" has been written. This is another feature that TAML provides in that it allows type designers to specify whether additional state like fields are written or not, typically based upon whether they are at their default values or not.

To read this back in we would use:

%obj = TamlRead( "stuff.taml" );

Again, pretty simple. Given the two global functions shown you have nearly everything you need to know to actually use the TAML system because you can both write and read objects.

This document however breaks down TAML into more detail beyond what you may need on a day-to-day basis but also includes information on the structure of its XML format which is an easily editable format to work with.

TAML instance

The global functions shown above are simplified ways of writing and reading objects. They are simplified because they hide the fact that TAML is actually a type you can create.

For instance, the previous write and read examples could've been done using the following:

// Create a sprite.
%obj = new Sprite();

// Create an instance of TAML.
%taml = new Taml();

// Write it out.
%taml.write( %obj, "stuff.taml" );

// Read it in using the same TAML instance.
%readObj = %taml.read( "stuff.taml" );

// Delete the instance of Taml.
%taml.delete();

The "TamlWrite()" and "TamlRead()" essentially remove the need to generate a TAML instance and delete if afterwards. Whilst this is convenient in many cases, these functions don't expose all the other features that TAML provides therefore it becomes necesssary to use a TAML instance when you wish to use them.

There is an exception to this, both the "TamlWrite()" and "TamlRead()" support additional arguments to specify the formats to use however that will be covered below.

TAML instance features

TAML provides several features as listed here:

  • Multiple input/ouput formats, per-format options and auto-format detection
  • Write defaults on/off
  • Progenitor updating
  • Direct write and read

The following goes into more detail on each of these features.

Multiple formats

TAML currently supports two named formats of:

  • XML
  • Binary

The XML format offers an easily edited format which is useful during game construction to edit outside of any editor. XML however is more verbose and typically produces larger file sizes however this disadvantage is greatly outweighed by the fact that it is easily editable.

The Binary format is not easily edited but produces smaller file sizes, especially when compression is used.

TAML can easily be extended to support more format types as long as the the format can encapsulate the state that TAML compiles when it analyses an object. Also, all formats must obviously be lossless and produce identical results in that if you were to read from one format and save to another then read that back and save back to the original format, the output should be identical. Currently both the XML and Binary formats strictly adhere to this principle.

There are two ways to select which format to use for writing and reading, one explicit and the other implicit.

Here's a couple of explicit method examples:

// Create a sprite.
%obj = new Sprite();

// Create an instance of TAML.
%taml = new Taml();

// Set the XML format.
%taml.Format = Xml;

// Write it out.
%taml.write( %obj, "stuff.taml" );

// Read it in.
%readObj = %taml.read( "stuff.taml" );

// Delete the instance of Taml.
%taml.delete();
// Create a sprite.
%obj = new Sprite();

// Create an instance of TAML.
%taml = new Taml();

// Set the Binary format.
%taml.Format = Binary;

// Write it out.
%taml.write( %obj, "stuff.baml" );

// Read it in.
%readObj = %taml.read( "stuff.baml" );

// Delete the instance of Taml.
%taml.delete();

As you can see, the format was set using the field "Format" but an alternate is using the method "setFormat()". You can currently specify either "xml" or "binary" for the format. The TAML instance will then use that format for all subsequent write and read operations.

In the examples the extensions ".taml" and ".baml" were used to denote an XML file and a Binary file respectively however these extensions and filenames can be whatever you choose.

Explicit formatting provides very fine control over write and read operations however it's common to not actually know the format but instead establish an extension to denote a format type just like you would expect for other file types.

Implicit formatting also known as "auto format" works without you having to select the format mode. Auto format does this by looking at the specified filename in the write or read operation and uses its extension to determine which format to use.

Taml comes with defaults for the filename extensions for both XML and Binary, these being "taml" and "baml" respectively but you are free to change those easily.

Here's an example auto-format:

// Create a sprite.
%obj = new Sprite();

// Create an instance of TAML.
%taml = new Taml();

// Write it out in XML.
%taml.write( %obj, "stuff.taml" );

// Write it out in Binary.
%taml.write( %obj, "stuff.baml" );

// Read it in.
%readObj1 = %taml.read( "stuff.taml" );
%readObj2 = %taml.read( "stuff.baml" );

// Delete the instance of Taml.
%taml.delete();

As you can see, there's no format specification anywhere. Again, this is because TAML determined that the "taml" extension is associated with XML and the "baml" extension with Binary.

You can change these meanings and reuse a TAML instance if you so desire like so:

// Create a sprite.
%obj = new Sprite();

// Create an instance of TAML.
%taml = new Taml()

%taml.AutoFormatXmlExtension = "xml";
%taml.AutoFormatBinaryExtension = "bin";

// Write it out in XML.
%taml.write( %obj, "stuff.xml" );

// Write it out in Binary.
%taml.write( %obj, "stuff.bin" );

// Read it in.
%readObj1 = %taml.read( "stuff.xml" );
%readObj2 = %taml.read( "stuff.bin" );

// Delete the instance of Taml.
%taml.delete();

Currently, TAML only supports a single file extension specification but it's a trivial matter to change this to support multiple extensions should it be required.

Clone this wiki locally