Sofud
Tutorial

Sofud tutorial

Sofud allows you to parse Sofu 0.2 files from D programs. You should be familiar with the D programming language to use Sofud.

You should also read the generic Sofu tutorial before continuing.

Modules

You can conveniently import the complete Sofud user interface with the module Sofu.Sofu. It contains everything you will need to use Sofud.

Loading

Loading a file is easy: Simply call the function loadFile, which returns the file's root object (a Map).

Map loadFile(char[] fileName)

Returns the map that is at the root of the specified file.

fileName: The name of the file to be loaded. The file can be in any Unicode 4.0 encoding form - i.e. one of UTF-8, UTF-16 and UTF-32. Both the big endian and little endian schemes of UTF-16 and UTF-32 are supported; however, a byte order mark is required for these.

Getting at the Data

The three types of object Sofu offers - Map, List and Value - are all derived from SofuObject. Since it's the type returned by loadFile(), let's first look at the Map type.

Map

Maps offer two major ways to access their attributes:

  1. Direct access by attribute name
  2. Iterating over all attributes with foreach

The first way is very straightforward. The Map class provides a set of functions that, given an attribute name, return the corresponding attribute.

SofuObject Map.object(wchar[] attribName)

Returns the attribute of the map which has the specified name. If there is no such attribute, throws AttributeDoesNotExistException.

Value Map.value(wchar[] attribName)

Returns the attribute of the map which has the specified name. If the attribute isn't a Value, throws TypeException.

List Map.list(wchar[] attribName)

Returns the attribute of the map which has the specified name. If the attribute isn't a List, throws TypeException.

Map Map.map(wchar[] attribName)

Returns the attribute of the map which has the specified name. If the attribute isn't a Map, throws TypeException.

The other way to access attributes is to use foreach. You can use foreach on a Map in two ways:

int opApply(int delegate(inout wchar[] attribName, inout SofuObject attrib) dg)

Iterates over all attributes of the map, storing the attribute name in attribName and the attribute in attrib. An example of using this is:

foreach(wchar[] attribName, SofuObject attrib; myMap) {
    writefln("%s = %s", attribName, attrib.outputString());
}

int opApply(int delegate(inout SofuObject attrib) dg)

Iterates over all attributes of the map, storing the attribute in attrib. There is no way to get an attribute's name - if you need it, use the above version instead.

foreach(SofuObject attrib; myMap) {
    writef("%s, ", attrib.outputString());
}

List

Accessing a List's elements is very similar to accessing a Map's attributes. Similarly to Maps, List elements can be accessed one at a time, or they can be iterated with foreach.

SofuObject List.object(int index)

Returns the element of the list which has the specified index. Indexes are counted in the order of appearance in the file, starting from zero. If the index is outside the range of the list (either below zero or larger than the last element's index), throws ListIndexOutOfRangeException.

Value List.value(int index)

Returns the element of the list which has the specified index. If the element isn't a Value, throws TypeException.

List List.list(int index)

Returns the element of the list which has the specified index. If the element isn't a List, throws TypeException.

Map List.map(int index)

Returns the element of the list which has the specified index. If the element isn't a Map, throws TypeException.

You can also access all list elements in order using foreach:

int opApply(int delegate(inout SofuObject elem) dg)

An example of using this is:

foreach(SofuObject elem, myList) {
    writefln("%s", elem.outputString());
}

Value

While List and Map are more or less structural types, Values contain the actual data we're interested in. This means that they provide a bunch of functions for getting the value's contents in various data types.

char[] toString()

Returns the value's contents as an UTF-8 string.

char[] toUTF8()

wchar[] toUTF16()

dchar[] toUTF32()

Return the value's contents as strings of the respective encodings.

int toInt()

Returns the value's contents interpreted as an integer. If conversion to an integer failed (e.g. because the value contains characters that aren't meaningful in an integer), throws ValueConversionException.

long toLong()

Returns the value's contents interpreted as a long integer. If conversion to a long failed (e.g. because the value contains characters that aren't meaningful in an integer), throws ValueConversionException.

float toFloat()

Returns the value's contents interpreted as a floating point number. If conversion to a float failed (e.g. because the value contains characters that aren't meaningful in a floating point number), throws ValueConversionException.

double toDouble()

Returns the value's contents interpreted as a floating point number. If conversion to a double failed (e.g. because the value contains characters that aren't meaningful in a floating point number), throws ValueConversionException.

There's a bit more functionality in Sofud than this tutorial showed, so it may be continued some time. Until that happens, you may find the source code a valuable source for information.