XMLLOC-CPP

Documentation

Overview · Quick Start · XML Resource File · Compiler Syntax · XLEngine

Overview

XML Localisation for C++ (xmlloc-cpp), is designed to be a relatively simple way of handling locale-specific resource strings in C++ programming.

The standard way of creating 'resource strings' in C++ is typically:

#define CONSTANT_STRING "A constant string"

static char g_strConstantString[] = "A constant string";

Which is fine as long as you're developing for a single language, but what happens when you require resource strings in multiple languages?
Xmlloc helps you control your resource strings more easily by allowing you to store your resource strings in a structured external xml file. This file is compiled into a .h header file that you include in your project to provide shortcut tokens to select the current language group and retrieve strings.

So where you once used:

string strTest = CONSTANT_STRING;

printf(CONSTANT_STRING);

You can now use:

string strTest = CONSTANT_STRING;

printf(CONSTANT_STRING);

Which is exactly the same, except now CONSTANT_STRING links to a intelligent resource handler and any locale-specific resource strings will be taken into account.

Quick Start

Download

Download xmlloc-cpp (see download page).
Download TinyXML (see links page).

Unpack

Unpack the xmlloc-cpp source into its directory structure.
Unpack the TinyXML source into the src-tinyxml sub-directory of the xmlloc-cpp root.

Compile

Only a Visual C++ 7 project file is currently provided with the source. A makefile will be created in the very near future.

Visual C++ 7 - Load the ./xmlloc-cpp.sln solution file into Visual C++ 7/VS.NET and choose 'Build Solution'.
All output files will be placed in ./bin/debug and ./bin/release.

Usage

Generate your xml string resource file.
Run the file through the compiler (xl_cl.exe) to generate your .h resource header file.
Add the header file to your project, along with the XLEngine source files - xlengine.cpp & xlengine.h - in the same directory.

XML Resource File

The format of the xml resource file is very simple.

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE xmlloc SYSTEM "./xmlloc.dtd">
<xmlloc varname="_g_xle">
	<define id="CONSTANT_STRING" default="A Test String" />
	<define id="CONSTANT_STRING_2" default="Another Test String" />
	<define id="CONSTANT_STRING_TEST" default="Test String, III" />
	
	<language name="english"></language>
	<language name="french">
		<text id="CONSTANT_STRING_TEST">je ne comprends pas...</text>
	</language>
</xmlloc>

xmlloc
This is the root element of resource file and has the following attributes:

varname - Specifies the name for the main XLEngine class. Defaults to _g_xle.

define
Specifies the resource string definitions and has the following attributes:

id - The constant identifier to be associated with this string (must be a valid C/C++ name).
default - The default contents of the string. This will be used if the id is not re-defined in a text within a given language element.

language
Contains the language-specific versions of the resource strings. Has the following attributes:

name - Free-text name of the language (e.g. english, french, etc.).

text
Specifies the language-specific version of a resource string. Has the following attributes:

id - Specifies the resource id this string will override.

The data in the above xml example can be tabulated as such:

ID	English string	French string
CONSTANT_STRING	A Test String	A Test String
CONSTANT_STRING_2	Another Test String	Another Test String
CONSTANT_STRING_TEST	Test String, III	je ne comprends pas...

No strings have been redefines in the English language element, so all strings carry their default values.
Only CONSTANT_STRING_TEST has been redefined in the French language element, so all the other strings have their default values.

Note: Although TinyXML does not support DTD validation, a DTD file is supplied should you wish to validate your xml resource file in another parser.

Compiler Syntax

xl_cl /I:<filename> /O:<filename> [/V] [/?]

/?	Displays usage information, ignoring all other flags.
/I:<filename>	Specifies the input xml resource filename.
/O:<filename>	Specifies the ouput filename. If this file already exists, it will be overwritten.
/V	Specifies version information, ignoring all other flags.

Note: a dash (minus-sign) can be used in place of the forward-slash.

XLEngine

Your compiled header file will declare a global variable of type XLEngine, the main class that handles your constant string requests. Whatever the name of the global variable may be, there will always be a #define XLE_VAR for it (e.g. #define XLE_VAR _g_xle).

There are two types of #define's used to provide shortcuts to the strings. In the examples below, we'll assume that you've added the following line in your xml file:

<define id="CONSTANT_STRING_1" default="Test string" />

After compiling your xml file, CONSTANT_STRING_1 will be defined as...

#define CONSTANT_STRING_1 XLE_VAR.GetString(_XLE_VAL_CONSTANT_STRING_1)

...with _XLE_VAL_CONSTANT_STRING_1 being defined as an integer index value used by the XLEngine class to identify the string. Because the GetString function returns a char*, you can now use CONSTANT_STRING_1 in most places where you'd use a normal resource string declaration.

Selecting a language at run-time

When the global XLEngine object is constructed, it defaults to the first language that was specified in the xml file. You can change this by calling...

XLE_VAR.SetLanguage(int nLanguageIndex);

...where nLanguageIndex is the index of the language and is in the range...

0 <= nLanguageIndex < XLE_VAR.GetLanguageCount()

Retrieving language names

const char * XLE_VAR.GetLanguageName(int nLanguageIndex)