Faudes object serialization.

Detailed Description

Objects of a class derived from the universal base faudes::Type provide a uniform interface for serialization, which are to be implemented for derived classes.

This is supported by

• the faudes::Token class to model atomic data units like integers, sections tags and strings.
• 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

A token hast value types attached, e.g., type string, number, and/or tag. Tags indicate the beginning or end of a section, must balance, and must be XML compliant. The character data inbetween the 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 individual 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"
• "ab cd" the same string containing a blank
• 'ad"cd'; the same string containing a double quote
• abc\d the same string containing a backslash
• "123" the string 123
• 123 the non-negative integer 123
• 0xFF the non-negative integer 255 (hexadecimal notation)
• 1.5 the float 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 name="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>

Note that the special characters <, > and & must be quoted as entities, i.e., represented as &xxx; where the xxx refers to the character. This style of quoting is also required when the respective character appears within a quoted string or a faudes-style comment. This restriction is required for XML compliance.

Technical Note: alternative file format

libFAUDES token formats are intended to be human editable. However, the specific interpretation of the character data between the begin and end elements can not be covered a formal XML document model. The design objective here was a balance between a formal model and human editable data input.

Since the initial design, however, a number of faudes types where inroduced to configure the run-time behaviour of tools like the simulator or hardware access. Theese kind of objects are seldomly edited and we feel that a more rigoruos XML format is required to make use of professional XML editors/tools. Therefore we started in libFAUDES 2.16f to implement an alternative serialization format. Recent versions of libFAUDES still read the old format and provide the utility libfaudes/bin/fts2ftx 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 original file format for token output. However, for applications that require the more rigoruos XML format, the base class Type provides the additional interface XWrite().

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...