From 707cc94fe52463870a9c6c8e2e66eaaa389e601d Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Tue, 24 Feb 2009 15:16:26 +0200 Subject: Start tracking XSD/e with git after version 3.0.0 --- documentation/xsde.xhtml | 1578 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1578 insertions(+) create mode 100644 documentation/xsde.xhtml (limited to 'documentation/xsde.xhtml') diff --git a/documentation/xsde.xhtml b/documentation/xsde.xhtml new file mode 100644 index 0000000..ac01b91 --- /dev/null +++ b/documentation/xsde.xhtml @@ -0,0 +1,1578 @@ + + + + + + XSD/e 3.0.0 Compiler Command Line Manual + + + + + + + + + + + +
+
+ +

NAME

+ +

xsde - W3C XML Schema to C++ Compiler for Embedded Systems

+ +

SYNOPSIS

+ +
+
xsde command [options] file [file ...]
+
xsde help [command]
+
xsde version
+
+ +

DESCRIPTION

+ +

xsde generates vocabulary-specific, statically-typed + C++ mapping from W3C XML Schema definitions. Particular mapping to + produce is selected by a command. Each mapping has + a number of mapping-specific options that should + appear, if any, after the command. Input files should + be W3C XML Schema definitions. The exact set of the generated files + depends on the selected mapping and options.

+ +

COMMANDS

+ +
+
cxx-hybrid
+
Generate the Embedded C++/Hybrid mapping. For each input file in the + form name.xsd the following C++ files are generated: + name.hxx (object model header file), + name.ixx (object model inline file, generated only + if the --generate-inline option is specified), + name.cxx (object model source file), and + name-fwd.hxx (object model forward declaration + file, generated only if the --generate-forward + option is specified). + +

If the --generate-parser option is specified, + the Embedded C++/Parser mapping is invoked and the + name-pskel.hxx, + name-pskel.ixx, and + name-pskel.cxx parser skeleton files are + generated, as described below. Additionally, the following parser + implementation files are generated: + name-pimpl.hxx (parser implementation header + file) and + name-pimpl.cxx (parser implementation source + file).

+ +

If the --generate-serializer option is + specified, the Embedded C++/Serializer mapping is invoked and the + name-sskel.hxx, + name-sskel.ixx, and + name-sskel.cxx serializer skeleton files are + generated, as described below. Additionally, the following serializer + implementation files are generated: + name-simpl.hxx (serializer implementation header + file) and + name-simpl.cxx (serializer implementation source + file).

+
+ +
cxx-parser
+
Generate the Embedded C++/Parser mapping. For each input file in the + form name.xsd the following C++ files are generated: + name-pskel.hxx (parser skeleton header file), + name-pskel.ixx (parser skeleton inline file, + generated only if the --generate-inline + option is specified), and + name-pskel.cxx (parser skeleton source file). + If the --generate-noop-impl or + --generate-print-impl option is specified, + the following additional sample implementation files are generated: + name-pimpl.hxx (parser implementation header + file) and + name-pimpl.cxx (parser implementation source + file). If the --generate-test-driver option + is specified, the additional name-pdriver.cxx + test driver file is generated.
+ +
cxx-serializer
+
Generate the Embedded C++/Serializer mapping. For each input file + in the form name.xsd the following C++ files + are generated: name-sskel.hxx (serializer + skeleton header file), name-sskel.ixx (serializer + skeleton inline file, generated only if the + --generate-inline option is specified), and + name-sskel.cxx (serializer skeleton source file). + If the --generate-empty-impl option is specified, + the following additional sample implementation files are generated: + name-simpl.hxx (serializer implementation header + file) and name-simpl.cxx (serializer + implementation source file). If the --generate-test-driver + option is specified, the additional name-sdriver.cxx + test driver file is generated. +
+ +
help
+
Print usage information and exit. Use +

xsde help command

+ for command-specific help. +
+ +
version
+
Print version and exit.
+
+ +

OPTIONS

+ +

Command-specific options, if any, should appear + after the corresponding command.

+ +

COMMON OPTIONS

+ +
+
--output-dir dir
+
Write generated files to dir instead of + the current directory.
+ +
--no-stl
+
Generate code that does not use the Standard Template Library + (STL).
+ +
--no-iostream
+
Generate code that does not use the standard input/output + stream library (iostream).
+ +
--no-exceptions
+
Generate code that does not use C++ exceptions.
+ +
--no-long-long
+
Generate code that does not use the long long + and unsigned long long types. The + 64 bit long and unsignedLong + built-in XML Schema types are then mapped to long + and unsigned long.
+ +
--generate-inline
+
Generate simple functions inline. This option triggers creation + of the inline file.
+ +
--namespace-map xns=cns
+
Map XML Schema namespace xns to C++ namespace cns. + Repeat this option to specify mapping for more than one XML Schema + namespace. For example, the following option: + +

--namespace-map http://example.com/foo/bar=foo::bar

+ +

will map the http://example.com/foo/bar + XML Schema namespace to the foo::bar C++ + namespace.

+
+ +
--namespace-regex regex
+
Add regex to the list of regular expressions + used to translate XML Schema namespace names to C++ namespace + names. regex is a perl-like regular expression in + the form /pattern/replacement/. + Any character can be used as a delimiter instead of /. + Escaping of the delimiter character in pattern or + replacement is not supported. + +

All regular expressions are pushed into a stack with the last + specified expression considered first. The first match that + succeeds is used. Regular expressions are applied to a string + in the form

+ +

filename namespace

+ +

For example,

+ +

XMLSchema.xsd http://www.w3.org/2001/XMLSchema

+ +

The filename for the current translation unit + is empty. For example, if you have file hello.xsd + with namespace http://example.com/hello and you run + xsde on this file, then the string in question + would be:

+ +

 http://example.com/hello

+ +

Note the leading space.

+ +

The following three steps are performed for each regular expression + until the match is found:

+ +
    +
  1. The expression is applied and if the result is empty the + next expression is considered.
    2. + +
  2. All / are replaced with + ::.
    3. + +
  3. The result is verified to be a valid C++ scope name (e.g., + foo::bar). If this test succeeds, the + result is used as a C++ namespace name.
    4. +
+ +

As an example, the following expression maps XML Schema + namespaces in the form + http://example.com/foo/bar to C++ + namespaces in the form foo::bar:

+ +

%.* http://example.com/(.+)%$1%

+ +

See also the REGEX AND SHELL QUOTING section below.

+
+ +
--namespace-regex-trace
+
Trace the process of applying regular expressions specified with + the --namespace-regex option. Use this option + to find out why your regular expressions don't do what you expected + them to do. +
+ + + +
--reserved-name name[=rep]
+
Add name to the list of names that should not + be used as identifiers. The name can optionally be followed by + = and the replacement name that should be + used instead. All C++ keywords are already in this list. +
+ +
--include-with-brackets
+
Use angle brackets (<>) instead of quotes ("") in + generated #include directives. +
+ +
--include-prefix prefix
+
Add prefix to generated #include + directive paths. + +

For example, if you had the following import element in your + schema

+ +

<import namespace="..." schemaLocation="base.xsd"/>

+ +

and compiled this fragment with --include-prefix schemas/, + then the include directive in the generated code would be:

+ +

#include "schemas/base.hxx"

+
+ +
--include-regex regex
+
Add regex to the list of regular expressions + used to transform #include directive paths. + regex is a perl-like regular expression in + the form /pattern/replacement/. + Any character can be used as a delimiter instead of /. + Escaping of the delimiter character in pattern or + replacement is not supported. + +

All regular expressions are pushed into a stack with the last + specified expression considered first. The first match that + succeeds is used.

+ +

As an example, the following expression transforms paths + in the form schemas/foo/bar to paths + in the form generated/foo/bar:

+ +

%schemas/(.+)%generated/$1%

+ +

See also the REGEX AND SHELL QUOTING section below.

+
+ +
--include-regex-trace
+
Trace the process of applying regular expressions specified with + the --include-regex option. Use this option + to find out why your regular expressions don't do what you expected + them to do. +
+ +
--guard-prefix prefix
+
Add prefix to generated header inclusion guards. + The prefix is transformed to upper case and all characters that are + illegal in a preprocessor macro name are replaced with underscores. + If this option is not specified then the directory part of the + input schema file is used as a prefix. +
+ +
--hxx-suffix suffix
+
Use the provided suffix instead of the default + .hxx to construct the name of the header file. + Note that this suffix is also used to construct names for + included/imported schemas. +
+ +
--ixx-suffix suffix
+
Use the provided suffix instead of the default + .ixx to construct the name of the inline file. +
+ +
--cxx-suffix suffix
+
Use the provided suffix instead of the default + .cxx to construct the name of the source file. +
+ +
--fwd-suffix suffix
+
Use the provided suffix instead of the default + -fwd.hxx to construct the name of the forward + declaration file (C++/Hybrid mapping only). +
+ +
--hxx-regex regex
+
Use the provided expression to construct the name of the header + file. regex is a perl-like regular expression + in the form + /pattern/replacement/. + This expression is also used to construct names for included/imported + schemas. + +

+ For the C++/Hybrid mapping, the regex argument + can be optionally prefixed with a file key in the form + key=regex. The valid values for + key are pskel (parser + skeleton files), pimpl (parser implementation + files), sskel (serializer skeleton files), + simpl (serializer implementation files), + and * (all files). If key + is empty or not present then the expression is used for the + object model files only. +

+ +

See also the REGEX AND SHELL QUOTING section below.

+
+ +
--ixx-regex regex
+
Use the provided expression to construct the name of the inline + file. regex is a perl-like regular expression + in the form + /pattern/replacement/. + For the C++/Hybrid mapping, the regex argument + can be optionally prefixed with a file key. See the + --hxx-regex option for details. + See also the REGEX AND SHELL QUOTING section below. +
+ +
--cxx-regex regex
+
Use the provided expression to construct the name of the source + file. regex is a perl-like regular expression + in the form + /pattern/replacement/. + For the C++/Hybrid mapping, the regex argument + can be optionally prefixed with a file key. See the + --hxx-regex option for details. + See also the REGEX AND SHELL QUOTING section below. +
+ +
--fwd-regex regex
+
Use the provided expression to construct the name of the forward + declaration file (C++/Hybrid mapping only). regex + is a perl-like regular expression in the form + /pattern/replacement/. + See also the REGEX AND SHELL QUOTING section below. +
+ + + +
--hxx-prologue text
+
Insert text at the beginning of the header file. + +

+ For the C++/Hybrid mapping, the text argument + can be optionally prefixed with a file key in the form + key=text. The valid values for + key are pskel (parser + skeleton files), pimpl (parser implementation + files), sskel (serializer skeleton files), + simpl (serializer implementation files), + and * (all files). If key + is empty or not present then the text is used for the + object model files only. +

+ +
+ +
--ixx-prologue text
+
Insert text at the beginning of the inline file. + For the C++/Hybrid mapping, the text argument + can be optionally prefixed with a file key. See the + --hxx-prologue option for details. +
+ +
--cxx-prologue text
+
Insert text at the beginning of the source file. + For the C++/Hybrid mapping, the text argument + can be optionally prefixed with a file key. See the + --hxx-prologue option for details. +
+ +
--fwd-prologue text
+
Insert text at the beginning of the forward + declaration file (C++/Hybrid mapping only). +
+ +
--prologue text
+
Insert text at the beginning of each generated + file for which there is no file-specific prologue. + For the C++/Hybrid mapping, the text argument + can be optionally prefixed with a file key. See the + --hxx-prologue option for details. +
+ + + +
--hxx-epilogue text
+
Insert text at the end of the header file. + For the C++/Hybrid mapping, the text argument + can be optionally prefixed with a file key. See the + --hxx-prologue option for details. +
+ +
--ixx-epilogue text
+
Insert text at the end of the inline file. + For the C++/Hybrid mapping, the text argument + can be optionally prefixed with a file key. See the + --hxx-prologue option for details. +
+ +
--cxx-epilogue text
+
Insert text at the end of the source file. + For the C++/Hybrid mapping, the text argument + can be optionally prefixed with a file key. See the + --hxx-prologue option for details. +
+ +
--fwd-epilogue text
+
Insert text at the end of the forward + declaration file (C++/Hybrid mapping only). +
+ +
--epilogue text
+
Insert text at the end of each generated + file for which there is no file-specific epilogue. + For the C++/Hybrid mapping, the text argument + can be optionally prefixed with a file key. See the + --hxx-prologue option for details. +
+ + + +
--hxx-prologue-file file
+
Insert the content of the file at the beginning + of the header file. + +

+ For the C++/Hybrid mapping, the file argument + can be optionally prefixed with a file key in the form + key=file. The valid values for + key are pskel (parser + skeleton files), pimpl (parser implementation + files), sskel (serializer skeleton files), + simpl (serializer implementation files), + and * (all files). If key + is empty or not present then the file is used for the + object model files only. +

+
+ +
--ixx-prologue-file file
+
Insert the content of the file at the beginning + of the inline file. + For the C++/Hybrid mapping, the file argument + can be optionally prefixed with a file key. See the + --hxx-prologue-file option for details. +
+ +
--cxx-prologue-file file
+
Insert the content of the file at the beginning + of the source file. + For the C++/Hybrid mapping, the file argument + can be optionally prefixed with a file key. See the + --hxx-prologue-file option for details. +
+ +
--fwd-prologue-file file
+
Insert the content of the file at the beginning + of the forward declaration file (C++/Hybrid mapping only). +
+ +
--prologue-file file
+
Insert the content of the file at the beginning + of each generated file for which there is no file-specific prologue + file. + For the C++/Hybrid mapping, the file argument + can be optionally prefixed with a file key. See the + --hxx-prologue-file option for details. +
+ + + +
--hxx-epilogue-file file
+
Insert the content of the file at the end of the + header file. + For the C++/Hybrid mapping, the file argument + can be optionally prefixed with a file key. See the + --hxx-prologue-file option for details. +
+ +
--ixx-epilogue-file file
+
Insert the content of the file at the end of the + inline file. + For the C++/Hybrid mapping, the file argument + can be optionally prefixed with a file key. See the + --hxx-prologue-file option for details. +
+ +
--cxx-epilogue-file file
+
Insert the content of the file at the end of the + source file. + For the C++/Hybrid mapping, the file argument + can be optionally prefixed with a file key. See the + --hxx-prologue-file option for details. +
+ +
--fwd-epilogue-file file
+
Insert the content of the file at the end of the + forward declaration file (C++/Hybrid mapping only). +
+ +
--epilogue-file file
+
Insert the content of the file at the end of each + generated file for which there is no file-specific epilogue file. + For the C++/Hybrid mapping, the file argument + can be optionally prefixed with a file key. See the + --hxx-prologue-file option for details. +
+ + +
--disable-warning warn
+
Disable printing warning with id warn. If all + is specified for the warning id then all warnings are disabled. +
+ + + +
--show-sloc
+
Show the number of generated physical source lines of code (SLOC). +
+ +
--sloc-limit num
+
Check that the number of generated physical source lines of code + (SLOC) does not exceed num. +
+ +
--options-file file
+
Read additional options from file. Each option + should appear on a separate line optionally followed by space and + an argument. Empty lines and lines starting with # + are ignored. The semantics of providing options in a + file is equivalent to providing the same set of options in + the same order in the command line at the point where the + --options-file option is specified + except that shell escaping and quoting is not required. + Repeat this option to specify more than one options files. +
+ +
--proprietary-license
+
Indicate that the generated code is licensed under a proprietary + license instead of the GPL. +
+ + + +
--preserve-anonymous
+
Preserve anonymous types. By default anonymous types are + automatically named with names derived from the enclosing + elements/attributes. Because mappings implemented by this + compiler require all types to be named, this option is only + useful if you want to make sure your schemas don't have + anonymous types. +
+ +
--show-anonymous
+
Show elements and attributes that are of anonymous types. + This option only makes sense together with the + --preserve-anonymous option. +
+ +
--anonymous-regex regex
+
Add regex to the list of regular expressions + used to derive names for anonymous types from the enclosing + attributes/elements. regex is a perl-like regular + expression in the form + /pattern/replacement/. + Any character can be used as a delimiter instead of /. + Escaping of the delimiter character in pattern or + replacement is not supported. + +

All regular expressions are pushed into a stack with the last + specified expression considered first. The first match that + succeeds is used. Regular expressions are applied to a string + in the form

+ +

filename namespace xpath

+ +

For example,

+ +

hello.xsd http://example.com/hello element

+

hello.xsd http://example.com/hello type/element

+ +

The filename for the current translation unit + is empty. For example, if you have file hello.xsd + with namespace http://example.com/hello and you run + xsde on this file, then the string in question + would be:

+ +

 http://example.com/hello element

+ +

Note the leading space.

+ +

As an example, the following expression makes all the derived + names start with capital letters. This could be useful when + your naming convention requires type names to start with + capital letters:

+ +

%.* .* (.+/)*(.+)%\u$2%

+ +

See also the REGEX AND SHELL QUOTING section below.

+
+ +
--anonymous-regex-trace
+
Trace the process of applying regular expressions specified with + the --anonymous-regex option. Use this option + to find out why your regular expressions don't do what you expected + them to do. +
+ + + +
--location-map ol=nl
+
Map the original schema location ol that is specified in + the XML Schema include or import elements to new schema + location nl. Repeat this option to map more than one + schema location. For example, the following option maps the + http://example.com/foo.xsd URL to the + foo.xsd local file. + +

--location-map http://example.com/foo.xsd=foo.xsd

+
+ +
--location-regex regex
+
Add regex to the list of regular expressions + used to map schema locations that are specified in the XML Schema + include or import elements. regex is a perl-like + regular expression in the form + /pattern/replacement/. + Any character can be used as a delimiter instead of /. + Escaping of the delimiter character in pattern or + replacement is not supported. All regular + expressions are pushed into a stack with the last specified + expression considered first. The first match that succeeds is used. + +

For example, the following expression maps URL locations in the form + http://example.com/foo/bar.xsd to local files + in the form bar.xsd:

+ +

%http://.+/(.+)%$1%

+ +

See also the REGEX AND SHELL QUOTING section below.

+
+ +
--location-regex-trace
+
Trace the process of applying regular expressions specified with + the --location-regex option. Use this option + to find out why your regular expressions don't do what you expected + them to do. +
+ + + +
--file-per-type
+
Generate a separate set of C++ files for each type defined in XML + Schema. Note that in this mode you only need to compile the root + schema(s) and the code will be generated for all included and + imported schemas. This compilation mode is primarily useful when + some of your schemas cannot be compiled separately or have cyclic + dependencies which involve type inheritance. +
+ + +
--type-file-regex regex
+
Add regex to the list of regular expressions + used to translate type names to file names when the + --type-per-file option is specified. + regex is a perl-like regular expression in the form + /pattern/replacement/. + Any character can be used as a delimiter instead of /. + Escaping of the delimiter character in pattern or + replacement is not supported. All regular + expressions are pushed into a stack with the last specified + expression considered first. The first match that succeeds is used. + Regular expressions are applied to a string in the form + +

namespace type-name

+ +

For example, the following expression maps type foo + that is defined in the http://example.com/bar + namespace to file name bar-foo:

+ +

%http://example.com/(.+) (.+)%$1-$2%

+ +

See also the REGEX AND SHELL QUOTING section below.

+
+ +
--type-file-regex-trace
+
Trace the process of applying regular expressions specified with + the --type-file-regex option. Use this option + to find out why your regular expressions don't do what you expected + them to do. +
+ + + +
--file-list file
+
Write a list of generated C++ files to file. + This option is primarily useful in the file-per-type compilation + mode (--file-per-type) to create a list of + generated C++ files, for example, as a makefile fragment. +
+ +
--file-list-prologue text
+
Insert text at the beginning of the file list. + As a convenience, all occurrences of the \n character sequence in + text are replaced with new lines. This option + can, for example, be used to assign the generated file list to a + makefile variable. +
+ +
--file-list-epilogue text
+
Insert text at the end of the file list. + As a convenience, all occurrences of the \n character sequence in + text are replaced with new lines. +
+ +
--file-list-delim text
+
Delimit file names written to the file list with + text instead of new lines. As a convenience, + all occurrences of the \n character sequence in + text are replaced with new lines. +
+ +
+ +

CXX-HYBRID COMMAND OPTIONS

+ +
+
--generate-parser
+
Generate XML parsing code.
+ +
--generate-serializer
+
Generate XML serialization code.
+ +
--generate-aggregate
+
Generate parser/serializer aggregates for root elements and/or + types. See also the --root-element-* and + --root-type options.
+ +
--suppress-validation
+
Suppress the generation of validation code in parser and serializer.
+ +
--suppress-parser-val
+
Suppress the generation of validation code in parser.
+ +
--suppress-serializer-val
+
Suppress the generation of validation code in serializer.
+ +
--generate-forward
+
Generate forward declaration file.
+ +
--generate-xml-schema
+
Generate C++ header files as if the schema being compiled defines + the XML Schema namespace. In particular, the resulting files will + have definitions for all object model types, parser skeletons and + implementations, as well as serializer skeletons and implementations + corresponding to the XML Schema built-in types. The schema file + provided to the compiler need not exist and is only used to derive + the names of the resulting header files. Use the + --extern-xml-schema option to include these file + in the generated files for other schemas.
+ +
--extern-xml-schema file
+
Include header files derived from file instead of + generating the XML Schema namespace mapping inline. The provided + file need not exist and is only used to derive the names of the + included header files. Use the --generate-xml-schema + option to generate these header files.
+ +
--suppress-reset
+
Suppress the generation of parser and serializer reset code. + Reset support allows you to reuse parsers and serializers + after an error.
+ +
--reuse-style-mixin
+
Generate code that supports the mixin base parser/serializer + implementation reuse style. Note that this reuse style + relies on virtual inheritance and may result in a substantial + object code size increase for large vocabularies. By default + the tiein reuse style is used.
+ + +
--custom-data type
+
Add the ability to store custom data to the C++ class generated + for XML Schema type type. To add custom + data to a nested compositor class use the qualified name + starting from the XML Schema type containing the compositor, + for example, foo::sequence::choise1.
+ +
--custom-parser + type[=base[/include]]
+
Use a custom parser implementation instead of the generated version. + The type component is the XML Schema type name + being customized. Optional base is a C++ name + that should be given to the generated version. It is normally used + as a base for the custom implementation. Optional + include is the header file that defines the + custom implementation. It is #include'ed + into the generated code immediately after (if base + is specified) or instead of the generated version.
+ +
--custom-serializer + type[=base[/include]]
+
Use a custom serializer implementation instead of the generated version. + The type component is the XML Schema type name + being customized. Optional base is a C++ name + that should be given to the generated version. It is normally used + as a base for the custom implementation. Optional + include is the header file that defines the + custom implementation. It is #include'ed + into the generated code immediately after (if base + is specified) or instead of the generated version.
+ + + +
--root-element-first
+
Treat only the first global element as a document root. This + determines for which elements parser and serializer aggregates + are generated. By default all global elements are considered + document roots. See also the --generate-aggregate + option. +
+ +
--root-element-last
+
Treat only the last global element as a document root. This + determines for which elements parser and serializer aggregates + are generated. By default all global elements are considered + document roots. See also the --generate-aggregate + option. +
+ +
--root-element-all
+
Treat all global elements as document roots (the default + behavior). This determines for which elements parser and + serializer aggregates are generated. By explicitly specifying + this option you can suppress the warning that is issued if + more than one global element is defined. See also the + --generate-aggregate option. +
+ +
--root-element-none
+
Do not treat any global elements as document roots. This + determines for which elements parser and serializer aggregates + are generated. By default all global elements are considered + document roots. See also the --generate-aggregate + option. +
+ +
--root-element element
+
Treat only element as a document root. This + determines for which elements parser and serializer aggregates + are generated. Repeat this option to specify more than one root + element. See also the --generate-aggregate option. +
+ +
--root-type type
+
Generate parser/serializer aggregate for type. + Repeat this option to specify more than one type. See also the + --generate-aggregate option.
+ +
--pskel-type-suffix suffix
+
Use suffix instead of the default + _pskel to construct the names of generated parser + skeletons.
+ +
--sskel-type-suffix suffix
+
Use suffix instead of the default + _sskel to construct the names of generated + serializer skeletons.
+ +
--pskel-file-suffix suffix
+
Use suffix instead of the default + -pskel to construct the names of generated + parser skeleton files.
+ +
--sskel-file-suffix suffix
+
Use suffix instead of the default + -sskel to construct the names of generated + serializer skeleton files.
+ +
--pimpl-type-suffix suffix
+
Use suffix instead of the default + _pimpl to construct the names of generated + parser implementations.
+ +
--simpl-type-suffix suffix
+
Use suffix instead of the default + _simpl to construct the names of generated + serializer implementations.
+ +
--pimpl-file-suffix suffix
+
Use suffix instead of the default + -pimpl to construct the names of generated + parser implementation files.
+ +
--simpl-file-suffix suffix
+
Use suffix instead of the default + -simpl to construct the names of generated + serializer implementation files.
+ +
--paggr-type-suffix suffix
+
Use suffix instead of the default + _paggs to construct the names of generated + parser aggregates.
+ +
--saggr-type-suffix suffix
+
Use suffix instead of the default + _saggr to construct the names of generated + serializer aggregates.
+
+ +

CXX-PARSER COMMAND OPTIONS

+ +
+
--type-map mapfile
+
Read XML Schema to C++ type mapping information from + mapfile. Repeat this option to specify + several type maps. Type maps are considered in order of + appearance and the first match is used. By default all + user-defined types are mapped to void. + See the TYPE MAP section below for more information.
+ +
--reuse-style-mixin
+
Generate code that supports the mixin base parser + implementation reuse style. Note that this reuse style + relies on virtual inheritance and may result in a substantial + object code size increase for large vocabularies. By default + support for the tiein style is generated.
+ +
--reuse-style-none
+
Do not generate any support for base parser implementation + reuse. By default support for the tiein style is generated.
+ +
--suppress-validation
+
Suppress the generation of validation code.
+ +
--generate-polymorphic
+
Generate polymorphism-aware code. Specify this option if you use + substitution groups or xsi:type.
+ +
--runtime-polymorphic
+
Generate non-polymorphic code that uses the runtime library + configured with polymorphism support.
+ +
--suppress-reset
+
Suppress the generation of parser reset code. Reset + support allows you to reuse parsers after an error.
+ +
--generate-noop-impl
+
Generate a sample parser implementation that does nothing (no + operation). The sample implementation can then be filled with + the application-specific code. For an input file in the form + name.xsd this option triggers the generation + of the two additional C++ files in the form: + name-pimpl.hxx (parser implementation header + file) and name-pimpl.cxx (parser implementation + source file).
+ +
--generate-print-impl
+
Generate a sample parser implementation that prints the XML data + to STDOUT. For an input file in the form name.xsd + this option triggers the generation of the two additional C++ files + in the form: name-pimpl.hxx (parser implementation + header file) and name-pimpl.cxx (parser + implementation source file).
+ +
--generate-test-driver
+
Generate a test driver for the sample parser implementation. For an + input file in the form name.xsd this option + triggers the generation of an additional C++ file in the form + name-pdriver.cxx.
+ +
--force-overwrite
+
Force overwriting of the existing implementation and test driver + files. Use this option only if you do not mind loosing the changes + you have made in the sample implementation or test driver files.
+ +
--root-element-first
+
Indicate that the first global element is the document root. This + information is used to generate the test driver for the sample + implementation.
+ +
--root-element-last
+
Indicate that the last global element is the document root. This + information is used to generate the test driver for the sample + implementation.
+ +
--root-element element
+
Indicate that element is the document root. + This information is used to generate the test driver for the + sample implementation.
+ +
--generate-xml-schema
+
Generate a C++ header file as if the schema being compiled defines + the XML Schema namespace. In particular, the resulting file will + have definitions for all parser skeletons and implementations + corresponding to the XML Schema built-in types. The schema file + provided to the compiler need not exist and is only used to derive + the name of the resulting header file. Use the + --extern-xml-schema option to include this file + in the generated files for other schemas.
+ +
--extern-xml-schema file
+
Include a header file derived from file instead of + generating the XML Schema namespace mapping inline. The provided + file need not exist and is only used to derive the name of the + included header file. Use the --generate-xml-schema + option to generate this header file.
+ +
--skel-type-suffix suffix
+
Use the provided suffix instead of the + default _pskel to construct the names + of generated parser skeletons.
+ +
--skel-file-suffix suffix
+
Use the provided suffix instead of the + default -pskel to construct the names of + generated parser skeleton files.
+ +
--impl-type-suffix suffix
+
Use the provided suffix instead of the + default _pimpl to construct the names of + parser implementations for the built-in XML Schema types + and sample parser implementations.
+ +
--impl-file-suffix suffix
+
Use the provided suffix instead of the + default -pimpl to construct the names of + generated sample parser implementation files.
+
+ +

CXX-SERIALIZER COMMAND OPTIONS

+ +
+
--type-map mapfile
+
Read XML Schema to C++ type mapping information from + mapfile. Repeat this option to specify + several type maps. Type maps are considered in order of + appearance and the first match is used. By default all + user-defined types are mapped to void. + See the TYPE MAP section below for more information.
+ +
--reuse-style-mixin
+
Generate code that supports the mixin base serializer + implementation reuse style. Note that this reuse style + relies on virtual inheritance and may result in a substantial + object code size increase for large vocabularies. By default + support for the tiein style is generated.
+ +
--reuse-style-none
+
Do not generate any support for base serializer implementation + reuse. By default support for the tiein style is generated.
+ +
--suppress-validation
+
Suppress the generation of validation code.
+ +
--generate-polymorphic
+
Generate polymorphism-aware code. Specify this option if you use + substitution groups or xsi:type.
+ +
--runtime-polymorphic
+
Generate non-polymorphic code that uses the runtime library + configured with polymorphism support.
+ +
--suppress-reset
+
Suppress the generation of serializer reset code. Reset + support allows you to reuse serializers after an error.
+ +
--generate-empty-impl
+
Generate a sample serializer implementation with empty function + bodies which can then be filled with the application-specific code. + For an input file in the form name.xsd this + option triggers the generation of the two additional C++ files in the + form: name-simpl.hxx (serializer implementation + header file) and name-simpl.cxx (serializer + implementation source file).
+ +
--generate-test-driver
+
Generate a test driver for the sample serializer implementation. For + an input file in the form name.xsd this option + triggers the generation of an additional C++ file in the form + name-sdriver.cxx.
+ +
--force-overwrite
+
Force overwriting of the existing implementation and test driver + files. Use this option only if you do not mind loosing the changes + you have made in the sample implementation or test driver files.
+ +
--root-element-first
+
Indicate that the first global element is the document root. This + information is used to generate the test driver for the sample + implementation.
+ +
--root-element-last
+
Indicate that the last global element is the document root. This + information is used to generate the test driver for the sample + implementation.
+ +
--root-element element
+
Indicate that element is the document root. + This information is used to generate the test driver for the + sample implementation.
+ +
--generate-xml-schema
+
Generate a C++ header file as if the schema being compiled defines + the XML Schema namespace. In particular, the resulting file will + have definitions for all serializer skeletons and implementations + corresponding to the XML Schema built-in types. The schema file + provided to the compiler need not exist and is only used to derive + the name of the resulting header file. Use the + --extern-xml-schema option to include this file + in the generated files for other schemas.
+ +
--extern-xml-schema file
+
Include a header file derived from file instead of + generating the XML Schema namespace mapping inline. The provided + file need not exist and is only used to derive the name of the + included header file. Use the --generate-xml-schema + option to generate this header file.
+ +
--skel-type-suffix suffix
+
Use the provided suffix instead of the + default _sskel to construct the names + of generated serializer skeletons.
+ +
--skel-file-suffix suffix
+
Use the provided suffix instead of the + default -sskel to construct the names of + generated serializer skeleton files.
+ +
--impl-type-suffix suffix
+
Use the provided suffix instead of the + default _simpl to construct the names of + serializer implementations for the built-in XML Schema types + and sample serializer implementations.
+ +
--impl-file-suffix suffix
+
Use the provided suffix instead of the + default -simpl to construct the names of + generated sample serializer implementation files.
+
+ + +

TYPE MAP

+ +

Type map files are used to define a mapping between XML Schema + and C++ types. For C++/Parser, the compiler uses + this information to determine the return types of + post_* functions in parser skeletons + corresponding to XML Schema types as well as argument types + for callbacks corresponding to elements and attributes of these + types. For C++/Serializer, type maps are used to determine + the argument type of pre functions in + serializer skeletons corresponding to XML Schema types as + well as return types for callbacks corresponding to elements + and attributes of these types.

+ +

The compiler has a set of predefined mapping rules that map + the built-in XML Schema types to suitable C++ types (discussed + in the following sub-sections) and all other types to + void. By providing your own type maps you + can override these predefined rules. The format of the type map + file is presented below: +

+ + 
+namespace <schema-namespace> [<cxx-namespace>]
+{
+  (include <file-name>;)*
+  ([type] <schema-type> <cxx-ret-type> [<cxx-arg-type>];)*
+}
+
+ +

Both <schema-namespace> and + <schema-type> are regex patterns while + <cxx-namespace>, + <cxx-ret-type>, and + <cxx-arg-type> are regex pattern + substitutions. All names can be optionally enclosed in + " ", for example, to include white-spaces.

+ +

<schema-namespace> determines XML + Schema namespace. Optional <cxx-namespace> + is prefixed to every C++ type name in this namespace declaration. + <cxx-ret-type> is a C++ type name that is + used as a return type for the post_* function + in C++/Parser or for element/attribute callbacks in C++/Serializer. + Optional <cxx-arg-type> is an argument type + for element/attribute callbacks in C++/Parser or for the + pre function in C++/Serializer. If + <cxx-arg-type> is not specified, it defaults + to <cxx-ret-type> if <cxx-ret-type> + ends with * or & (that is, + it is a pointer or a reference) and + const <cxx-ret-type>& + otherwise. + <file-name> is a file name either in the + " " or < > format + and is added with the #include directive to + the generated code.

+ +

The # character starts a comment that ends + with a new line or end of file. To specify a name that contains + # enclose it in " ". + For example:

+ + 
+namespace http://www.example.com/xmlns/my my
+{
+  include "my.hxx";
+
+  # Pass apples by value.
+  #
+  apple apple;
+
+  # Pass oranges as pointers.
+  #
+  orange orange_t*;
+}
+
+ +

In the example above, for the + http://www.example.com/xmlns/my#orange + XML Schema type, the my::orange_t* C++ type will + be used as both return and argument types.

+ +

Several namespace declarations can be specified in a single + file. The namespace declaration can also be completely + omitted to map types in a schema without a namespace. For + instance:

+ + 
+include "my.hxx";
+apple apple;
+
+namespace http://www.example.com/xmlns/my
+{
+  orange "const orange_t*";
+}
+
+ +

The compiler has a number of predefined mapping rules + for the built-in XML Schema types that vary depending on + the mapping used. They are described in the following + subsections. The last predefined rule for all mappings + maps anything that wasn't mapped by previous rules to + void:

+ + 
+namespace .*
+{
+  .* void void;
+}
+
+ +

When you provide your own type maps with the + --type-map option, they are evaluated first. + This allows you to selectively override predefined rules.

+ + +

Predefined C++/Parser Type Maps

+ +

The C++/Parser mapping provides a number of predefined type + map rules for the built-in XML Schema types. They can be + presented as the following map files:

+ + 
+namespace http://www.w3.org/2001/XMLSchema
+{
+  boolean bool bool;
+
+  byte "signed char" "signed char";
+  unsignedByte "unsigned char" "unsigned char";
+
+  short short short;
+  unsignedShort "unsigned short" "unsigned short";
+
+  int int int;
+  unsignedInt "unsigned int" "unsigned int";
+
+  long "long long" "long long";
+  unsignedLong "unsigned long long" "unsigned long long";
+
+  integer long long;
+
+  negativeInteger long long;
+  nonPositiveInteger long long;
+
+  positiveInteger "unsigned long" "unsigned long";
+  nonNegativeInteger "unsigned long" "unsigned long";
+
+  float float float;
+  double double double;
+  decimal double double;
+
+  NMTOKENS xml_schema::string_sequence*;
+  IDREFS xml_schema::string_sequence*;
+
+  base64Binary xml_schema::buffer*;
+  hexBinary xml_schema::buffer*;
+
+  date xml_schema::date;
+  dateTime xml_schema::date_time;
+  duration xml_schema::duration;
+  gDay xml_schema::gday;
+  gMonth xml_schema::gmonth;
+  gMonthDay xml_schema::gmonth_day;
+  gYear xml_schema::gyear;
+  gYearMonth xml_schema::gyear_month;
+  time xml_schema::time;
+}
+
+ +

If the --no-stl option is not specified, + the following mapping is used for the string-based XML Schema + built-in types:

+ + 
+namespace http://www.w3.org/2001/XMLSchema
+{
+  include <string>;
+
+  string std::string;
+  normalizedString std::string;
+  token std::string;
+  Name std::string;
+  NMTOKEN std::string;
+  NCName std::string;
+  ID std::string;
+  IDREF std::string;
+  language std::string;
+  anyURI std::string;
+
+  QName xml_schema::qname;
+}
+
+ +

Otherwise, a C string-based mapping is used:

+ + 
+namespace http://www.w3.org/2001/XMLSchema
+{
+  string char*;
+  normalizedString char*;
+  token char*;
+  Name char*;
+  NMTOKEN char*;
+  NCName char*;
+  ID char*;
+  IDREF char*;
+  language char*;
+  anyURI char*;
+
+  QName xml_schema::qname*;
+}
+
+ +

Predefined C++/Serializer Type Maps

+ +

The C++/Serializer mapping provides a number of predefined type + map rules for the built-in XML Schema types. They can be + presented as the following map files:

+ + 
+namespace http://www.w3.org/2001/XMLSchema
+{
+  boolean bool bool;
+
+  byte "signed char" "signed char";
+  unsignedByte "unsigned char" "unsigned char";
+
+  short short short;
+  unsignedShort "unsigned short" "unsigned short";
+
+  int int int;
+  unsignedInt "unsigned int" "unsigned int";
+
+  long "long long" "long long";
+  unsignedLong "unsigned long long" "unsigned long long";
+
+  integer long long;
+
+  negativeInteger long long;
+  nonPositiveInteger long long;
+
+  positiveInteger "unsigned long" "unsigned long";
+  nonNegativeInteger "unsigned long" "unsigned long";
+
+  float float float;
+  double double double;
+  decimal double double;
+
+  NMTOKENS "const xml_schema::string_sequence*";
+  IDREFS "const xml_schema::string_sequence*";
+
+  base64Binary "const xml_schema::buffer*";
+  hexBinary "const xml_schema::buffer*";
+
+  date xml_schema::date;
+  dateTime xml_schema::date_time;
+  duration xml_schema::duration;
+  gDay xml_schema::gday;
+  gMonth xml_schema::gmonth;
+  gMonthDay xml_schema::gmonth_day;
+  gYear xml_schema::gyear;
+  gYearMonth xml_schema::gyear_month;
+  time xml_schema::time;
+}
+
+ +

If the --no-stl option is not specified, + the following mapping is used for the string-based XML Schema + built-in types:

+ + 
+namespace http://www.w3.org/2001/XMLSchema
+{
+  include <string>;
+
+  string std::string;
+  normalizedString std::string;
+  token std::string;
+  Name std::string;
+  NMTOKEN std::string;
+  NCName std::string;
+  ID std::string;
+  IDREF std::string;
+  language std::string;
+  anyURI std::string;
+
+  QName xml_schema::qname;
+}
+
+ +

Otherwise, a C string-based mapping is used:

+ + 
+namespace http://www.w3.org/2001/XMLSchema
+{
+  string "const char*";
+  normalizedString "const char*";
+  token "const char*";
+  Name "const char*";
+  NMTOKEN "const char*";
+  NCName "const char*";
+  ID "const char*";
+  IDREF "const char*";
+  language "const char*";
+  anyURI "const char*";
+
+  QName "const xml_schema::qname*";
+}
+
+ +

REGEX AND SHELL QUOTING

+ +

When entering a regular expression argument in the shell + command line it is often necessary to use quoting (enclosing + the argument in " " or + ' ') in order to prevent the shell + from interpreting certain characters, for example, spaces as + argument separators and $ as variable + expansions.

+ +

Unfortunately it is hard to achieve this in a manner that is + portable across POSIX shells, such as those found on + GNU/Linux and UNIX, and Windows shell. For example, if you + use " " for quoting you will get a + wrong result with POSIX shells if your expression contains + $. The standard way of dealing with this + on POSIX systems is to use ' ' instead. + Unfortunately, Windows shell does not remove ' ' + from arguments when they are passed to applications. As a result you + may have to use ' ' for POSIX and + " " for Windows ($ is + not treated as a special character on Windows).

+ +

Alternatively, you can save regular expression options into + a file, one option per line, and use this file with the + --options-file option. With this approach + you don't need to worry about shell quoting.

+ +

DIAGNOSTICS

+ +

If the input file is not a valid W3C XML Schema definition, + xsde will issue diagnostic messages to STDERR + and exit with non-zero exit code.

+ +

BUGS

+ +

Send bug reports to the + xsde-users@codesynthesis.com mailing list.

+ +
+ +
+ + -- cgit v1.1