XParam - General-Purpose Object Serialization Framework for C++

The XParam Library User's Guide

Usage Examples

Next: Frequently Asked Questions
Previous: Installing XParam
Up: Table of Contents

Contents:

  1. Introduction
  2. Simple Example
  3. Involved Example
  4. Calculator Example

Introduction

The following sections describe three examples of XParam programs in order of increasing sophistication. The full compileable sources and run-able binaries can be found in the "examples" directory of the XParam distribution. If you've installed the xparam-devel RPM, you will find these examples in a tar ball, in the same directory as this documentation.

The files referenced by this HTML have been abbreviated, for clarity, by omitting a large part of the license notice at the beginning of each. The code, however, is still protected by the same license as the rest of XParam. Other than this change, the files are identical to those used in the actual working code.

Simple Example

This little C++ program demonstrates a very simple usage of XParam. It asks for two inputs, an integer called "num" and a string called "name". "num" is a number you're guessing; "name" is your name. The program reads this input from the command line. Next it reads an integer from the file my_number.txt and sees whether you guessed too high or too low. Finally, the program outputs "my_number" as a ParamSet, in the format recognizeable by other XParam programs, which is also human-readable.

You can execute this program with no parameters, and will receive the reply that "num" is a required parameter. You can input "num" only, in which case the program will enter the default name: "John Doe", or you can enter both parameters. You can also execute this program with the help-request option:

~> simple !

for example, and this will give you all the parameter information.

One particularly amusing way to execute this program is by using

~> simple num=@my_number.txt

This will redirect "num" to be read from "my_number.txt", which, of course, will lead to your number being exactly correct.

The full code can be found in simple.cpp.

Involved Example

A more involved example is the example of initializing an entire drawing, using a polymorphic Shape pointer. This example is given in involved.cpp. The generic shape interface is given in shapes.h and its implementation is in shapes.cpp. The interface is registered in reg_shapes.cpp.

You can execute this program using

~> bin/involved @data/my_shape.txt

This will load the shape information from the file my_shape.txt. The shape information itself uses class "Circle", which has not been defined in "shapes.h". Consequently, XParam will dynamically load the dynamic link library that was compiled from the files circle.cpp and reg_circle.cpp (the command to do so is in circle.xpn). These files implement and register the circle class, whose interface appears in circle.h.

This program demonstrates parameter passing with user-defined classes and dynamic loading. For it to work, you must make sure that environment variable XPARAM_CLASSPATH is set, and that the path of circle.xpn appears in it.

Note: XParam does not currently support dynamic loading in Windows, so for the example to work in Windows you will have to link in the files circle.cpp and reg_circle.cpp statically.

Calculator Example

This program demonstrates an interactive usage of streams. The main program code appears in calculator.cpp. This is all the code you need to program a calculator in XParam, because all the parsing is done by XParam for you. However, you still need to program classes for the different arithmetic operations. These classes appear in functions.h and functions.cpp. They are registered into XParam in reg_functions.cpp. With these files alone, this is already a functioning calculator.

However, we also wanted to demonstrate that the calculator is easily extendable. By adding the files mathfunc.h, reg_mathfunc.cpp and mathfunc.xpn we managed to add two functions, "sqrt" and "ln", which are loaded dynamically when needed.

The program is a calculator, working on doubles, that supports the functions "add", "sub", "mul" and "div" (as well as "sqrt" and "ln"). It reads its input as an input object stream from the standard input and outputs its output as an output object stream to the standard output. Errors go to the standard error. The calculator supports commands that look like this: "mul(5,add(4,2))". This input will cause it to output "30.0", because 5*(4+2)=30. The calculator also supports variables. use "def(var1,13)" to define "var1" to be "13". Variable names are general strings. To use the variable, simply use its name: "sub(var1,8)" will output "5.0". To exit the calculator, simple truncate the input stream (^D in Unix or ^Z under Windows).

Another thing you can do is import an object, by using the redirection operator. A single object may contain many variable definitions. This is done by placing them between brackets. Use "@data/constants.dat" to import Pi and E from constants.dat, for example.

Calculator also demonstrates another use-case for paramsets. Though there is no command-line input needed for the calculator, it nevertheless uses a paramset to read the command line. This allows the calculator to give usage instructions with the "!" directive, as well as help on specific functions.

The main thing to note about the calculator is that no concessions had to be made regarding its interface (with the exception that it has to use functions instead of operators), because of the use of XParam. Correct design of the class hierarchy it uses makes it possible for you to write "15" and it to be accepted as a number, "max" and it to be accepted as a variable, "[ def(one,1), def(two,2) ]" and for that to be accepted as a list of definitions, a single redirection to import many variables, any format of double to be readable, usage of "div" and "sqrt", even though these are functions that already have a meaning in C++, and so on. On the output side, the interface provides output as soon as you finish writing an expression, it outputs a stream of XParam doubles, readable by other XParam-supporting programs, when you input a calculation, and nothing when you input a definition or a list of definitions - these were all design goals.

The class hierarchy in the calculator program makes XParam implicitly convert values to the type you need them in, in order for the user not to have to be at all aware of the existence of classes such as ArithValue, Expression and MultiDef. She will only ever encounter them in error messages.

Next: Frequently Asked Questions
Previous: Installing XParam
Up: Table of Contents