Faudes object serialization.

Objects of a class derived from the universal base faudes::Type provide a uniform interface for serialization. More...

Classes

class  faudes::Token
 Tokens model atomic data for stream IO. More...
class  faudes::TokenReader
 A TokenReader reads sequential tokens from a file or string. More...
class  faudes::TokenWriter
 A TokenWriter writes sequential tokens to a file, a string or stdout. More...

Detailed Description

Objects of a class derived from the universal base faudes::Type provide a uniform interface for serialization.

It includes reading and writing the objects configuration data from/to a file or a std::string; see faudes::Type for the actual interface.

Serialization is implemented by three classes

  • the faudes::TokenReader class to read a tokenized character stream from file or string
  • the faudes::TokenWriter class to write a tokenized character stream to file or string
  • the faudes::Token class to model atomic data units like integers, sections tags and strings.

A token is of type string, number, or tag. Tags indicate the beginning or end of a section, must balance, and must be XML compliant. The character data inbeween tags is interpreted as a sequence of strings and numbers, to e.g. conveniently represent a list of events, transition or states. While the Token class implements reading and writing tokens from a C++ stream, the TokenReader and TokenWriter classes keep track of nested sections. Thus, opening a file via a TokenReader allows to scan for a particular section or to loop over all tokens from a particular section.

Tokens by example

  • abcd the string "abcd"
  • "abcd ef" the string "abcd ef"
  • "abc\"d" the string containing a double quote
  • "abc\\d" the string containing a backslash
  • "123" the string 123
  • 123 the integer 123
  • 0xFF the integer 255 (hexadecimal notation)
  • 1.5 the rational number 1.5
  • <Start> tag to indicate begin of section Start (so called XML element)
  • <Start/> tag to indicate end of section Start (so called XML element)
  • <Start value="x12"> begin tag with XML attribute

Faudes serialisation example

<Generator>

"simple machine"                   

<Alphabet>                         
"alpha" +C+ "beta" "mue" "lambda"      
</Alphabet>

<States>                           
"idle" "busy" "down"
</States>

<TransRel>
"idle" "alpha" "busy"
"busy" "beta" "idle"
"busy" "mue" "down"
"down" "lambda" "idle"
</TransRel>

<InitStates>
"idle"
</InitStates>

<MarkedStates>
"idle"
</MarkedStates>

% this is a comment: it will be ignored by TokenReader

<!-- another comment, will be ignored by TokenReader and other XML parsers -->

</Generator>



Technical Note: alternative file format

libFAUDES token formats are intended to be human editable. While XML compliant, the format does not allow for a strict document model within XML. E.g., from the XML perpective, transitions are just text between the <TransRel> and </TransRel> tags. Additional syntactical restrictions are implicitly imposed by the TokenReader and the respective class to serialized.

We feel that the trade-offs for our first design are well balanced, as long as typical user input (generators, alphabets etc) are considered. However, since the initial design of libFAUDES, a number of faudes types where inroduced, mainly to configure the run-time behaviour of tools like the simulator or hardware access. The latter kind of objects are seldomly edited and we feel that a more rigoruos XML format is required. This will enable the use of professional XML editors/tools for configuration and data maintenance. Therefore we started in libFAUDES 2.16f to implement an alternative serialization format. During the transition phase, both formats will be read while the new format will be written. The utility libfaudes/bin/fts2ftx is supplied for file conversion. Please let us know if you experience problems with data in the old format.

Typical user data like generators and alphabets by default continue to use the old file format for token output. However, for applications that require the more rigoruos XML format, the base class Type provides the additional interface XWrite().

libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen