NAME

WFC - wire format compiler

SYNTAX

wfc [options] <file>

DESCRIPTION

WFC translates protocol descriptions to C++ source files. The generated header files provide class descriptions for serializing and deserializing data accoring to the protocol description.

WFC syntax has been derived from protocol buffers, but provides optimizations for embedded systems.

OPTIONS

-i <filename> Use filename as input instead of the standard input (needs to be given for multi volume support). If filename is -, input is read from standard input.
-m <message> Generate code starting with message message. Depending messages will be generated if necessary.
-t <target> Use option set target as specified in the source file to generate the code.
-o <out_name> Generate files named out_name.cpp and ut_name.h.
-l Genrate wfc library only. This is useful if you want to share the library among multiple source files.
-v Operate in verbose mode.
-s Generate subclasses instead of mangled class names.

OPTIONS AND DEFAULT VALUES

Following options with associated default values are available. Option names are case insensitive. for options can be overridden on the command line or in the .wfc source file.
Optimize: valid values are review, size, speed; default is review
wfclib: valid values are static, inline, extern. Static means generate shareable functions as static/module local functions. Inline generates the functions in the header file. Extern forces the use of externally defined functions. For extern usage, the library can be generated with option -l (see above). UnkownField: valid values are assert, skip; default is skip. This option defines the handling of unkonwn message field tags during parsing. Usually you want to skip unknown fields.
wfclib: valid values are static, inline, extern; default is static
endian: valid values are unknown, little, big; default is unknown. Use little endian optimization only for targets that are able to perform an unaligned access. Big endian and unknown endian are currently implemented without any difference.
withEqual: valid values are true, false; default is true. If this option is enabled the operator == will be generated.
withUnequal: valid values are true, false; default is true. If this option is enabled the operator != will be generated.
MutableType: return type of mutable_* member functions. This can be either a pointer or a reference. Accordingly, the agrument must be either "pointer" or "reference". Default is "pointer".
ErrorHandling: what to do in case of errors that are detected during reading data. Valid methods are: cancel (i.e. return with an error code), assert (i.e. call abort), throw (throw an exception).
VarIntBits: Number of bits to use for variable length integer types. Default is 64, set to 32 or 16 on machines with smaller native types, if the value range of all fields allows it.
IntSize: default number of bits for data-types unsigned, signed, and int.
header: include a header file in the generated code. This option can be used multiple times.
header: This option can be used multple times and tells wfc to add an include directive for the specific header file into the generated code. This is needed if you intend to use custem string types.
namespace: Set the namespace for which the code shall be generated. This might be necessary, if you want to integrate multiple WFC definitions with conflicting settings. See wfclib example.
toASCII: name of toASCII method. This is disabled per default, as linking with wfc_support.cpp is otherwise necessary.
BaseClass: base class for generated message classes.
streamtype: Set class name to use for output streams. Default is std::ostream.

MESSAGE OPTIONS

SortMembers: member variables are sorted according to the given sorting scheme. Valid arguments are: id (default), name, type, size, unsorted.
inline: Comma separated lists of methods to inline. Defaults depend on Optimization level. Valid arguments are get, set, has.
members (BETA): message members can be either 'regular' or 'virtual'. When members is set to virtual the member variables are accessed via 'virtual functions and no member variables will be included in the class definition.

FIELD OPTIONS

Options that are applicable to elements of messages.
used: valid values are true, false; default is true. If this option is set to false, no code will be generated for handling this field.
stringtype: Data type to use for strings. Default is std::string. Set to "C" to use C string (const char *).
arraysize: Integer value of number of elements to allocate for a repeated type. If set to 0 (default), a std::vector will be used instead. Use if maximum number of elements is known, if you want to avoid impact of std::vector.
unset: sets an in range value that will be interpreted as the value being not set. I.e. has_xx will return false if its value is the unset value. This eleminates the requirement for a dedicated bit to implement the related has_ methods. The clear methods also use the unset value to reset the field.
default: default value that will be assigned during object initialization and when clearing the field value. If the field is an optional field, the field is presented as unset nevertheless. Note also that if unset is set to a different value, the value after object construction and after calling clear() will differ.
to_ascii: specifies a function that will be used for generating an ASCII representation for its value. Like this you can produce readable outputs for binary coded words. E.g. the decimal dot representiation of an IPv4 address. See the examples directory, to see how it works.
to_json: specifies a function that will be used for generating a JSON representation for its value. It works like to_ascii, but is complementary available, because JSON output might require certain characters to be escaped differently when compared to ASCII output.
usage: usage can be regular, deprecated, and obsolete. Default is regular. If usage is set to deprecated, data will not be serialized, but existing serialzed data will be read into memory. This is for fading out use of a certain field. Once you set the usage to obsolte, the data will neither be written or read anymore. Then the field specification is just there for blocking against future use, and documenting the fact that it was once there.
SetByName: name of function that can be used to assign members by name with ASCII input. This does not work for repeated types and bytes types. Enum types are limited to parsing their integer value for now. Only individual message fields can be set; i.e. parsing of complete messages like the ASCII output is out of scope. The function performs no input validity checking. Subelements of message fields can be selected with dot notation as in C: e.g. msg_a.field_b.element
storage (BETA): like option members this option sets the instantiation style of the data for the relevant field. I.e. if set to true, all member functions will be pure virtual, and no data will be instantiated. This option is limited to the relevant field is set, while in contrast the option members at the message level will set the default for all the members of the message.

EXAMPLES

To generate header and c++ source files accoring to a wfc protocol description, just run:

wfc <sourcefile>.wfc

To generate the code fot a specific target option set, use: wfc -t target source.wfc

See the examples subdirectory for complete examples of protocol descriptions, and option usage.

AUTHORS

Thomas Maier-Komor <thomas@maier-komor.de>

DONATIONS

If you like this software, and use it for production purposes in your company, please consider making a donation to support this work. You can donate directly via PayPal to the author's e-mail address (thomas@maier-komor.de).

HOMEPAGE

http://www.maier-komor.de/wfc.html

LICENSE

This software is published under GNU General Public License V3. See file LICENSE for details.

SEE ALSO

protoc(1)