Lumas Lib Help

Lumas Library Licence Terms & Conditions

About the Lumas Library

The Lumas library consists of the file lumas-lib.c and its associated header file lumas-lib.h. There is also a C++ wrapper in the header file lumas-lib.hpp.

The library comes with some additional files that allow you to test the library and get an idea of how the library is used. These files are lumas-lib-test.c and lumas-cpp-lib-test.cpp.

The code has been developed on Visual C++ 6 and tested on GCC version 2.95.2, but should work with most compilers.

If you find any bugs, please report them to:

lumas-lib-bugs@tech-know-ware.com

Lumas Library Licence Terms & Conditions

Each of the files in this library contains and is subject to the following licence terms. If you do not agree to the licence terms you must delete all the files associated with the library immediately:

// Notice:      TERMS & CONDITIONS
//
//              Your use of this file implies agreement to the Terms & 
//              Conditions as presented in this notice.
//
//              Subject to the terms and conditions of this notice, 
//              TECH-KNOW-WARE LTD hereby grants YOU (the person accepting this 
//              agreement) a non-exclusive right to use this file.
//
//              THIS FILE AND THE SOFTWARE CONTAINED HEREIN IS PROVIDED 'AS IS' 
//              AND COMES WITH NO WARRENTY OF ANY KIND.  
//
//              TECH-KNOW-WARE LTD SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED 
//              BY ANYONE OR ANYTHING DUE TO THE USE OF THIS FILE HOWEVER THEY 
//              MAY BE CAUSED.
//
//              This file, or any derivative of it, is provided on the condition
//              that YOU may not supply it to a third party outside of the 
//              organisation to which you are affiliated in a form that 
//              allows the third party to compile or link the software into 
//              programs of their own making.  Other than the previous 
//              condition, this file, or any derivative of it, may be used for 
//              any purpose, including commercial purposes. 
//
//              Users are permitted to modify the contents of this file, as 
//              long this notice and the copyright notice remains and the 
//              modified file is given a name that can not be confused with 
//              the files provided by Tech-Know-Ware Ltd.
//
//              Users are permitted to extract elements of this file into
//              other files, subject to this notice and the copyright notice 
//              also being copied into the target files.
//
//              For more information on Lumas, visit:
//
//                  http://www.tech-know-ware.com/lumas
//
//              If you find a bug in this software, please report it to:
//
//                  lumas-lib-bugs@tech-know-ware.com
//
//              Copyright (c) 2002, 2003 Tech-Know-Ware Ltd.
//
//              End of Notice.

How to use the Lumas Library

Follow the steps below to use the library on an encoded message.

Check that you have a complete message. This can be done using some application specific technique, or using the Lumas standard method. If the Lumas standard method is used, then the completeness of the Lumas message can be checked by calling flml_is_message_complete.
Create an instance of the parse control structure slms_prse_ctrl.
Parse the message by calling the function flml_parse_message.
To navigate to various parts in the message, use the location setting functions flml_set_location, flml_restore_location.
Use the parameter reading functions to read the deisred parameters.
Once all parameters have been read, release the parsing information by calling flml_release

The parameter reading function generally return TRUE if the read is successful, and FALSE otherwise. This allows code to be structured using the form:

if( flml_read_integer( &parse_ctrl, "width", 0, &value_width ) &&
		flml_read_integer( &parse_ctrl, "height", 0, &value_height ) &&
		flml_read_integer( &parse_ctrl, "depth", 0, &value_depth ) ) {
	// Process dimensions
	// ...
}
else {
	elml_error error = flml_get_last_error( &parse_ctrl );
	// Process error
	// ...
}

Or:

for( i=0; flml_read_integer( &parse_ctrl, "scores", 0, &(value_scores[i]) ); i++ ) {
}

The functions contained in the library are documented in the reference guide.

You may wish to have a look at lumas-lib-test.c to get an idea of how the library can be used.

Specifying Tags

The functions for setting the position in the parsing tree, and for reading parameters address parameters in much the same why as specifying files in a hierarchical directory structure.

The main conceptual difference is that within a single construct there might be multiple parameters that have the same tag. It is therefore necessary to specify both the tag of the parameter sought, and the instance of that parameter. This is done using the two function parameters ac_tagging and a_instance.

The names at each level of the hierarchy are seprated by the '=' character. The specifications can be relative to the locations last set by the flml_set_location, and flml_restore_location functions, or the first character of the ac_tagging parameter can be set to '=' in which case the specification is relative to the root of the message.

Thus, for a message that has the form:

top = { middle = { 7 bottom = 5, 8 other = 'something' } more_other = Live } The hierarchical name for the bottom parameter may appear as follows:

top=middle=bottom or

=top=middle=bottom Each level in the hierarchy is made up of 3 separate and optional parts, the untagged count, the text tag and the instance. The untagged count specifies either 0 based count of the untagged parameter that is being sought, or the total number of untagged values if a text tag is specified. (Note: untagged count can be omitted from the specification if it is known that the parser can not confuse an untagged parameter with a sought text tagged parameter.) text tag specifies any text tag that is to be looked for. instance specifies the instance of the parameter that is to be looked for, starting at 0. For example, in there are 3 occurances of a particular value in a message, the 2nd instance can be referenced by setting the instance part of the specification to 1.

The parts are combined into a single string, using the format '[<untagged count>][<text tag>][,<instance>]'. For example, the '8' in the above example can be specified as:

0top=0middle=1bottom,1 as there are no untagged items before top or middle, there is 1 untagged parameter before bottom and the '8' is the 1th (as opposed to 0th) instance of bottom.

Similarly, the '7' in the above example message can be specified as:

0top=0middle=0 as the '7' is the 0th parameter in the middle struct.

As has just been explained, the ac_tagging parameter can specify the instance of the parameter that is being looked for. However, in a number of cases it may be easier to specify the required instance using the a_instance parameter. An example of such a case might be when using the reader functions in for or while loops that iterate through all instances of a parameter.

If the a_instance parameter has a value greater than or equal to 0, then that value will be used to specify the desired instance. If the value of a_instance is -1, the instance value will be taken from the ac_tagging parameter.

For the a_instance parameter, the first instance of the parameter is extracted by setting this value to 0, and the second instance extracted by setting the parameter to 1 and so on. This follows the C array indexing convention.

You can find further examples of the tag specification in the lumas-lib-test.c file.