- -

NAME

- -

xsd - W3C XML Schema to C++ Compiler

- -

SYNOPSIS

- -

xsd command [options] file [file ...]
xsd help [command]
xsd version

- -

DESCRIPTION

- -

xsd 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-tree: Generate the C++/Tree mapping. For each input file in the form - name.xsd the following C++ files are generated: - name.hxx (header file), - name.ixx (inline file, generated only if the - --generate-inline option is specified), - name.cxx (source file), and - name-fwd.hxx (forward declaration file, generated - only if the --generate-forward option is - specified).
cxx-parser: Generate the 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-driver.cxx - test driver file is generated.
help: Print usage information and exit. Use -
xsd 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

- -

--char-type type

Generate code using the provided character type - instead of the default char. Valid values - are char and wchar_t.

--char-encoding enc

Specify the character encoding that should be used in the generated - code. Valid values for the char character type - are utf8 (default), iso8859-1, - lcp (Xerces-C++ local code page), and - custom. If you pass custom as - the value then you will need to include the transcoder implementation - header for your encoding at the beginning of the generated header - files (see the --hxx-prologue option). - -

For the wchar_t character type the only valid - value is auto and the encoding is automatically - selected between UTF-16 and UTF-32/UCS-4, depending on the - wchar_t type size.

--output-dir dir

Write generated files to dir instead of - the current directory.

--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 the 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, if you have file hello.xsd - with namespace http://example.com/hello and you run - xsd on this file, then the string in question - will be:

- -

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

- -

For the built-in XML Schema namespace the string is:

- -

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

- -

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

- -

The expression is applied and if the result is empty the - next expression is considered.
All / are replaced with - ::.
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.

- -

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

--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/. - Note that this expression is also used to construct names for - included/imported schemas. 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/. - 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/. - See also the REGEX AND SHELL QUOTING section below. -

--hxx-prologue text

Insert text at the beginning of the header file. -

--ixx-prologue text

Insert text at the beginning of the inline file. -

--cxx-prologue text

Insert text at the beginning of the source file. -

--prologue text

Insert text at the beginning of each generated - file for which there is no file-specific prologue. -

--hxx-epilogue text

Insert text at the end of the header file. -

--ixx-epilogue text

Insert text at the end of the inline file. -

--cxx-epilogue text

Insert text at the end of the source file. -

--epilogue text

Insert text at the end of each generated - file for which there is no file-specific epilogue. -

--hxx-prologue-file file

Insert the content of the file at the beginning - of the header file. -

--ixx-prologue-file file

Insert the content of the file at the beginning - of the inline file. -

--cxx-prologue-file file

Insert the content of the file at the beginning - of the source file. -

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

--hxx-epilogue-file file

Insert the content of the file at the end of the - header file. -

--ixx-epilogue-file file

Insert the content of the file at the end of the - inline file. -

--cxx-epilogue-file file

Insert the content of the file at the end of the - source file. -

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

--custom-literals file

Load custom XML string to C++ literal mappings from - file. This mechanism can be useful if you - are using a custom character encoding and some of the strings - in your schemas, for example element/attribute names or enumeration - values, contain non-ASCII characters. In this case you will need - to provide a custom mapping to C++ literals for such - strings. The format of this file is specified in the - custom-literals.xsd XML Schema file that - can be found in the documentation directory. -

--export-symbol symbol

Insert symbol in places where DLL - export/import control statements - (__declspec(dllexport/dllimport)) are necessary. -

--export-xml-schema

Export/import types in the XML Schema namespace using the export - symbol provided with the --export-symbol option. - The XSD_NO_EXPORT macro can be used to omit - this code during C++ compilation, which may be useful if you - would like to use the same generated code across multiple platforms. -

--export-maps

Export polymorphism support maps from a Win32 DLL into which this - generated code is linked. This is necessary when your type hierarchy - is split across several DLLs since otherwise each DLL will have its - own set of maps. In this situation the generated code for the DLL - which contains base types and/or substitution group heads should be - compiled with this option and the generated code for all other - DLLs should be compiled with --import-maps. - This option is only valid together with - --generate-polymorphic. - The XSD_NO_EXPORT macro can be used to omit - this code during C++ compilation, which may be useful if you - would like to use the same generated code across multiple platforms. -

--import-maps

Import polymorphism support maps to a Win32 DLL or executable into - which this generated code is linked. See the --export-maps - option documentation for details. This options is only valid together - with --generate-polymorphic. - The XSD_NO_EXPORT macro can be used to omit - this code during C++ compilation, which may be useful if you - would like to use the same generated code across multiple platforms. -

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

- -

filename namespace xpath

- -

For instance:

- -

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

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

- -

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 the 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. Other options related - to this mode are: - --type-file-regex, - --schema-file-regex, and - --file-list. -

--type-file-regex regex

Add regex to the list of regular expressions - used to translate type names to file names when the - --file-per-type 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 the 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. -

--schema-file-regex regex

Add regex to the list of regular expressions - used to translate schema file names when the - --file-per-type 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 the 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 the absolute filesystem path - of a schema file and the result, including the directory part, - if any, is used to derive the #include directive - paths as well as the generated C++ file paths. This option, along - with --type-file-regex are primarily used to - place the generated files into subdirectories or to resolve file - name conflicts. - -

For example, the following expression maps schema files in the - foo/1.0.0/ subdirectory to the files in - the foo/ subdirectory. As a result, the - #include directive paths for such schemas - will be in the foo/schema.hxx form and - the generated C++ files will be placed into the - foo/ subdirectory:

- -

%.*/foo/1.0.0/(.+)%foo/$1%

- -

See also the REGEX AND SHELL QUOTING section below.

--schema-file-regex-trace

Trace the process of applying regular expressions specified with - the --schema-file-regex option. Use this option - to find out why your regular expressions don't do what you expected - them to do. -

--fat-type-file

Generate code corresponding to global elements into type files - instead of schema files when the --type-file-regex - option is specified. This option is primarily useful when trying - to minimize the amount of object code that is linked to an executable - by packaging compiled generated code into a static (archive) library. -

--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-TREE COMMAND OPTIONS

- -

--generate-polymorphic: Generate polymorphism-aware code. Specify this option if you use - substitution groups or xsi:type. Use the - --polymorphic-type or - --polymorphic-type-all option to specify - which type hierarchies are polymorphic.
--polymorphic-type type: Indicate that type is a root of a polymorphic - type hierarchy. The compiler can often automatically determine - which types are polymorphic based on the substitution group - declarations. However, you may need to use this option if you are - not using substitution groups or if substitution groups are defined - in another schema. You need to specify this option when compiling - every schema file that references type. The - type argument is an XML Schema type name that - can be optionally qualified with a namespace in the - namespace#name form.
--polymorphic-type-all: Indicate that all types should be treated as polymorphic.
--generate-serialization: Generate serialization functions. Serialization functions - convert the object model back to XML.
--generate-inline: Generate simple functions inline. This option triggers creation - of the inline file.
--generate-ostream: Generate ostream insertion operators - (operator<<) for generated types. This - allows to easily print a fragment or the whole object model - for debugging or logging.
--generate-doxygen: Generate documentation comments suitable for extraction by the - Doxygen documentation system. Documentation from annotations - is added to the comments if present in the schema.
--generate-comparison: Generate comparison operators - (operator== and operator!=) - for complex types. Comparison is performed memberwise.
--generate-default-ctor: Generate default constructors even for types that have required - members. Required members of an instance constructed using such a - constructor are not initialized and accessing them results in - undefined behavior.
--generate-from-base-ctor: Generate constructors that expect an instance of a base type - followed by all required members.
--suppress-assignment: Suppress the generation of copy assignment operators for complex - types. If this option is specified, the copy assignment operators - for such types are declared private and left unimplemented.
--generate-detach: Generate detach functions for required elements and attributes - (detach functions for optional and sequence cardinalities are - provided by the respective containers). These functions, for - example, allow you to move sub-trees in the object model either - within the same tree or between different trees.
--generate-wildcard: Generate accessors and modifiers as well as parsing and serialization - code for XML Schema wildcards (any and - anyAttribute). XML content matched by wildcards - is presented as DOM fragments. Note that you need to initialize the - Xerces-C++ runtime if you are using this option.
--generate-insertion os: Generate data representation stream insertion operators for - the os output stream type. Repeat this - option to specify more than one stream type. The ACE CDR stream - (ACE_OutputCDR) and RPC XDR are recognized - by the compiler and the necessary #include - directives are automatically generated. For custom stream - types use the --hxx-prologue* options - to provide the necessary declarations.
--generate-extraction is: Generate data representation stream extraction constructors for - the is input stream type. Repeat this - option to specify more than one stream type. The ACE CDR stream - (ACE_InputCDR) and RPC XDR are recognized by - the compiler and the necessary #include - directives are automatically generated. For custom stream - types use the --hxx-prologue* options - to provide the necessary declarations.
--generate-forward: Generate a separate header file with forward declarations for the - types being generated.
--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 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.
--suppress-parsing: Suppress the generation of the parsing functions and constructors. - Use this option to reduce the generated code size when parsing - from XML is not needed.
--generate-element-type: Generate types instead of parsing and serialization functions - for root elements. This is primarily useful to distinguish - object models with the same root type but with different root - elements.
--generate-element-map: Generate a root element map that allows uniform parsing and - serialization of multiple root elements. This option is only - valid together with --generate-element-type. -
--generate-intellisense: Generate workarounds for IntelliSense bugs in Visual Studio - 2005 (8.0). When this option is used, the resulting code is - slightly more verbose. IntelliSense in Visual Studio 2008 (9.0) - does not require these workarounds. Support for IntelliSense in - Visual Studio 2003 (7.1) is improved with this option but is - still incomplete.
--omit-default-attributes: Omit attributes with default and fixed values from serialized - XML documents.
--type-naming style: Specify the type naming convention that should be used in the - generated code. Valid styles are knr - (default), ucc, and java. - See the NAMING CONVENTION section below for more information. -
--function-naming style: Specify the function naming convention that should be used in the - generated code. Valid styles are knr - (default), lcc, and java. - See the NAMING CONVENTION section below for more information. -
--type-regex regex: Add regex to the list of regular expressions - used to translate XML Schema type names to C++ type names. See the - NAMING CONVENTION section below for more information. -
--accessor-regex regex: Add regex to the list of regular expressions - used to translate XML Schema names of elements/attributes to C++ - accessor function names. See the NAMING CONVENTION section below - for more information. -
--one-accessor-regex regex: Add regex to the list of regular expressions - used to translate XML Schema names of elements/attributes with - cardinality one to C++ accessor function names. See the NAMING - CONVENTION section below for more information. -
--opt-accessor-regex regex: Add regex to the list of regular expressions - used to translate XML Schema names of elements/attributes with - cardinality optional to C++ accessor function names. See the - NAMING CONVENTION section below for more information. -
--seq-accessor-regex regex: Add regex to the list of regular expressions - used to translate XML Schema names of elements/attributes with - cardinality sequence to C++ accessor function names. See the - NAMING CONVENTION section below for more information. -
--modifier-regex regex: Add regex to the list of regular expressions - used to translate XML Schema names of elements/attributes to C++ - modifier function names. See the NAMING CONVENTION section below - for more information. -
--one-modifier-regex regex: Add regex to the list of regular expressions - used to translate XML Schema names of elements/attributes with - cardinality one to C++ modifier function names. See the NAMING - CONVENTION section below for more information. -
--opt-modifier-regex regex: Add regex to the list of regular expressions - used to translate XML Schema names of elements/attributes with - cardinality optional to C++ modifier function names. See the - NAMING CONVENTION section below for more information. -
--seq-modifier-regex regex: Add regex to the list of regular expressions - used to translate XML Schema names of elements/attributes with - cardinality sequence to C++ modifier function names. See the - NAMING CONVENTION section below for more information. -
--parser-regex regex: Add regex to the list of regular expressions - used to translate XML Schema element names to C++ parsing function - names. See the NAMING CONVENTION section below for more information. -
--serializer-regex regex: Add regex to the list of regular expressions - used to translate XML Schema element names to C++ serialization - function names. See the NAMING CONVENTION section below for more - information. -
--enumerator-regex regex: Add regex to the list of regular expressions - used to translate XML Schema enumeration values to C++ enumerator - names. See the NAMING CONVENTION section below for more information. -
--element-type-regex regex: Add regex to the list of regular expressions - used to translate XML Schema element names to C++ element type - names. See the NAMING CONVENTION section below for more information. -
--name-regex-trace: Trace the process of applying regular expressions specified with - the name transformation options. Use this option to find out why - your regular expressions don't do what you expected them to do. -
--root-element-first: Treat only the first global element as a document root. By default - all global elements are considered document roots. -
--root-element-last: Treat only the last global element as a document root. By default - all global elements are considered document roots. -
--root-element-all: Treat all global elements as document roots. This is the default - behavior. By explicitly specifying this option you can suppress - the warning that is issued if more than one global element is defined. -
--root-element-none: Do not treat any global elements as document roots. By default - all global elements are considered document roots. -
--root-element element: Treat only element as a document root. Repeat this - option to specify more than one root element. -
--custom-type - name[=type[/base]]: Use a custom C++ type type instead of the generated class for - XML Schema type name. If type is not present - or empty then the custom type is assumed to have the same name and - be defined in the same namespace as the generated class would have. - If base is specified then the generated class is still - generated but with that name. -
--custom-type-regex - /name-pat/[type-sub/[base-sub/]]: For each type defined in XML Schema that matches the name-pat - pattern use a custom C++ type instead of the generated class. The - name of the custom type is obtained by substituting type-sub. - If type-sub is not present or its substitution results in an - empty string then the custom type is assumed to have the same name - and be defined in the same namespace as the generated class would - have. If base-sub is present and its substitution results - in a non-empty string then the generated class is still generated - but with the result of substitution as its name. The pattern and - substitutions are in the perl regular expression format. See also - the REGEX AND SHELL QUOTING section below. -
--fwd-suffix suffix: Use the provided suffix instead of the default - -fwd.hxx to construct the name of the forward - declaration file. -
--fwd-regex regex: Use the provided expression to construct the name of the forward - declaration file. regex is a perl-like regular - expression in the form - /pattern/replacement/. - See also the REGEX AND SHELL QUOTING section below. -
--fwd-prologue text: Insert text at the beginning of the forward - declaration file. -
--fwd-epilogue text: Insert text at the end of the forward - declaration file. -
--fwd-prologue-file file: Insert the content of the file at the beginning - of the forward declaration file. -
--fwd-epilogue-file file: Insert the content of the file at the end of the - forward declaration file. -
--parts num: Split generated source code into num parts. This - is useful when translating large, monolithic schemas and a C++ - compiler is not able to compile the resulting source code at once - (usually due to insufficient memory). -
--parts-suffix suffix: Use suffix instead of the default - '-' to separate the file name from the - part number. -

- -

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.
--xml-parser parser: Use parser as the underlying XML parser. - Valid values are xerces for Xerces-C++ (default) - and expat for Expat.
--generate-inline: Generate simple functions inline. This option triggers creation - of the inline file.
--generate-validation: Generate validation code ("perfect" parser) which ensures that - instance documents conform to the schema. Validation code is - generated by default when the selected underlying XML parser - is non-validating (expat).
--suppress-validation: Suppress the generation of validation code ("perfect" parser). - Validation is suppressed by default when the selected underlying - XML parser is validating (xerces).
--generate-polymorphic: Generate polymorphism-aware code. Specify this option if you use - substitution groups or xsi:type.
--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-driver.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.

- -

NAMING CONVENTION

- -

The compiler can be instructed to use a particular naming - convention in the generated code. A number of widely-used - conventions can be selected using the --type-naming - and --function-naming options. A custom - naming convention can be achieved using the - --type-regex, - --accessor-regex, - --one-accessor-regex, - --opt-accessor-regex, - --seq-accessor-regex, - --modifier-regex, - --one-modifier-regex, - --opt-modifier-regex, - --seq-modifier-regex, - --parser-regex, - --serializer-regex, - --enumerator-regex, and - --element-type-regex options. -

- -

The --type-naming option specifies the - convention that should be used for naming C++ types. Possible - values for this option are knr (default), - ucc, and java. The - knr value (stands for K&R) signifies - the standard, lower-case naming convention with the underscore - used as a word delimiter, for example: foo, - foo_bar. The ucc (stands - for upper-camel-case) and - java values a synonyms for the same - naming convention where the first letter of each word in the - name is capitalized, for example: Foo, - FooBar.

- -

Similarly, the --function-naming option - specifies the convention that should be used for naming C++ - functions. Possible values for this option are knr - (default), lcc, and java. The - knr value (stands for K&R) signifies - the standard, lower-case naming convention with the underscore - used as a word delimiter, for example: foo(), - foo_bar(). The lcc value - (stands for lower-camel-case) signifies a naming convention - where the first letter of each word except the first is - capitalized, for example: foo(), fooBar(). - The java naming convention is similar to - the lower-camel-case one except that accessor functions are prefixed - with get, modifier functions are prefixed - with set, parsing functions are prefixed - with parse, and serialization functions are - prefixed with serialize, for example: - getFoo(), setFooBar(), - parseRoot(), serializeRoot().

- -

Note that the naming conventions specified with the - --type-naming and - --function-naming options perform only limited - transformations on the names that come from the schema in the - form of type, attribute, and element names. In other words, to - get consistent results, your schemas should follow a similar - naming convention as the one you would like to have in the - generated code. Alternatively, you can use the - --*-regex options (discussed below) - to perform further transformations on the names that come from - the schema.

- -

The - --type-regex, - --accessor-regex, - --one-accessor-regex, - --opt-accessor-regex, - --seq-accessor-regex, - --modifier-regex, - --one-modifier-regex, - --opt-modifier-regex, - --seq-modifier-regex, - --parser-regex, - --serializer-regex, - --enumerator-regex, and - --element-type-regex options allow you to - specify extra regular expressions for each name category in - addition to the predefined set that is added depending on - the --type-naming and - --function-naming options. Expressions - that are provided with the --*-regex - options are evaluated prior to any predefined expressions. - This allows you to selectively override some or all of the - predefined transformations. When debugging your own expressions, - it is often useful to see which expressions match which names. - The --name-regex-trace option allows you - to trace the process of applying regular expressions to - names.

- -

The value for the --*-regex options should be - 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 the regular expressions for each category are pushed into a - category-specific stack with the last specified expression - considered first. The first match that succeeds is used. For the - --one-accessor-regex (accessors with cardinality one), - --opt-accessor-regex (accessors with cardinality optional), and - --seq-accessor-regex (accessors with cardinality sequence) - categories the --accessor-regex expressions are - used as a fallback. For the - --one-modifier-regex, - --opt-modifier-regex, and - --seq-modifier-regex - categories the --modifier-regex expressions are - used as a fallback. For the --element-type-regex - category the --type-regex expressions are - used as a fallback.

- -

The type name expressions (--type-regex) - are evaluated on the name string that has the following - format:

- -

[namespace ]name[,name][,name][,name]

- -

The element type name expressions - (--element-type-regex), effective only when - the --generate-element-type option is specified, - are evaluated on the name string that has the following - format:

- -

namespace name

- -

In the type name format the namespace part - followed by a space is only present for global type names. For - global types and elements defined in schemas without a target - namespace, the namespace part is empty but - the space is still present. In the type name format after the - initial name component, up to three additional - name components can be present, separated - by commas. For example:

- -

http://example.com/hello type

foo

foo,iterator

foo,const,iterator

- -

The following set of predefined regular expressions is used to - transform type names when the upper-camel-case naming convention - is selected:

- -

/(?:[^ ]* )?([^,]+)/\u$1/

/(?:[^ ]* )?([^,]+),([^,]+)/\u$1\u$2/

/(?:[^ ]* )?([^,]+),([^,]+),([^,]+)/\u$1\u$2\u$3/

/(?:[^ ]* )?([^,]+),([^,]+),([^,]+),([^,]+)/\u$1\u$2\u$3\u$4/

- -

The accessor and modifier expressions - (--*accessor-regex and - --*modifier-regex) are evaluated on the name string - that has the following format:

- -

name[,name][,name]

- -

After the initial name component, up to two - additional name components can be present, - separated by commas. For example:

- -

foo

dom,document

foo,default,value

- -

The following set of predefined regular expressions is used to - transform accessor names when the java naming - convention is selected:

- -

/([^,]+)/get\u$1/

/([^,]+),([^,]+)/get\u$1\u$2/

/([^,]+),([^,]+),([^,]+)/get\u$1\u$2\u$3/

- -

For the parser, serializer, and enumerator categories, the - corresponding regular expressions are evaluated on local names of - elements and on enumeration values, respectively. For example, the - following predefined regular expression is used to transform parsing - function names when the java naming convention - is selected:

- -

/(.+)/parse\u$1/

- -

See also the REGEX AND SHELL QUOTING section below.

- -

TYPE MAP

- -

Type map files are used in C++/Parser to define a mapping between - XML Schema and C++ types. 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.

- -

The compiler has a set of predefined mapping rules that map - built-in XML Schema types to suitable C++ types (discussed - below) 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_* functions. - Optional <cxx-arg-type> is an argument - type for callback functions corresponding to elements and attributes - of this type. 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 that can be - presented as the following map files. The string-based XML Schema - built-in types are mapped to either std::string - or std::wstring depending on the character type - selected with the --char-type option - (char by default).

- -

-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" "long long";
-
-  negativeInteger "long long" "long long";
-  nonPositiveInteger "long long" "long long";
-
-  positiveInteger "unsigned long long" "unsigned long long";
-  nonNegativeInteger "unsigned long long" "unsigned long long";
-
-  float float float;
-  double double double;
-  decimal double double;
-
-  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;
-
-  NMTOKENS xml_schema::string_sequence;
-  IDREFS xml_schema::string_sequence;
-
-  QName xml_schema::qname;
-
-  base64Binary std::auto_ptr<xml_schema::buffer>
-               std::auto_ptr<xml_schema::buffer>;
-  hexBinary std::auto_ptr<xml_schema::buffer>
-            std::auto_ptr<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;
-}
-

- -

The last predefined rule 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.

- -

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, - xsd will issue diagnostic messages to STDERR - and exit with non-zero exit code.

- -

BUGS

- -

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

- -