+ +

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

+ + + +

--std version

Specify the C++ standard that the generated code should conform to. Valid + values are c++98 (default) and + c++11. + +

The C++ standard affects various aspects of the generated code that are + discussed in more detail in various mapping-specific documentation. Overall, + when C++11 is selected, the generated code relies on the move semantics and + uses std::unique_ptr instead of deprecated + std::auto_ptr.

+ +

When the C++11 mode is selected, you normally don't need to perform any + extra steps other than enable C++11 in your C++ compiler, if required. The + XSD compiler will automatically add the necessary macro defines to the + generated header files that will switch the header-only XSD runtime library + (libxsd) to the C++11 mode. However, if you include any + of the XSD runtime headers directly in your application (normally you just + include the generated headers), then you will need to define the + XSD_CXX11 macro for your entire project.

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

--generate-inline

Generate simple functions inline. This option triggers creation of the + inline file.

--generate-xml-schema

Generate a C++ header file as if the schema being compiled defines the XML + Schema namespace. For the C++/Tree mapping, the resulting file will contain + definitions for all XML Schema built-in types. For the C++/Parser mapping, + the resulting file will contain definitions for all the 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.

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

+ +

1. The expression is applied and if the result is empty the next + expression is considered.

+ +

2. All / are replaced with + ::.

+ +

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.

+ +

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 n[=r]

Add name n to the list of names that should not be used as + identifiers. The name can optionally be followed by = + and the replacement name r 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 of header files corresponding to + 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.

--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 of header files + corresponding to 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.

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

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

--fwd-prologue text

Insert text at the beginning of the forward declaration 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.

--fwd-epilogue text

Insert text at the end of the forward declaration 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.

--fwd-prologue-file file

Insert the content of the file at the beginning of the forward + declaration 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.

--fwd-epilogue-file file

Insert the content of the file at the end of the forward declaration + 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.

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

--generate-dep

Generate make dependency information. This option + triggers the creation of the .d file containing the + dependencies of the generated files on the main schema file as well as all + the schema files that it includes/imports, transitively. This dependency + file is then normally included into the main makefile to + implement automatic dependency tracking. + +

Note also that automatic dependency generation is not supported in the + file-per-type mode (--file-per-type). In this case, all + the generated files are produced with a single compiler invocation and + depend on all the schemas. As a result, it is easier to establish such a + dependency manually, perhaps with the help of the + --file-list* options.

--generate-dep-only

Generate make dependency information only.

--dep-phony

Generate phony targets for included/imported schema files, causing each to + depend on nothing. Such dummy rules work around make + errors caused by the removal of schema files without also updating the + dependency file to match.

--dep-target target

Change the target of the dependency rule. By default it contains all the + generated C++ files as well as the dependency file itself, without any + directory prefixes. If you require multiple targets, then you can specify + them as a single, space-separated argument or you can repeat this option + multiple times.

--dep-suffix suffix

Use the provided suffix instead of the default .d + to construct the name of the dependency file.

--dep-regex regex

Use the provided expression to construct the name of the dependency file. + regex is a Perl-like regular expression in the form + /pattern/replacement/. See + also the REGEX AND SHELL QUOTING section below.

--disable-warning warn

Disable printing warning with id warn. If all is + specified for the warning id then all warnings are disabled.

--options-file file

Read additional options from file. Each option should appearing on a + separate line optionally followed by space and an option value. Empty lines + and lines starting with # are ignored. Option values can + be enclosed in double (") or single + (') quotes to preserve leading and trailing whitespaces + as well as to specify empty values. If the value itself contains trailing or + leading quotes, enclose it with an extra pair of quotes, for example + '"x"'. Non-leading and non-trailing quotes are + interpreted as being part of the option value. + +

The semantics of providing options in a file is equivalent to providing + the same set of options in the same order on the command line at the point + where the --options-file option is specified except that + the shell escaping and quoting is not required. You can repeat this option + to specify more than one options file.

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

--proprietary-license

Indicate that the generated code is licensed under a proprietary license + instead of the GPL.

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

--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, + --fat-type-file, 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 useful 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.
--polymorphic-plate num: Specify the polymorphic map plate the generated code should register on. + This functionality is primarily useful to segregate multiple schemas that + define the same polymorphic types.
--ordered-type type: Indicate that element order in type is significant. An example would + be a complex type with unbounded choice as a content model where the element + order in XML has application-specific semantics. For ordered types the + compiler generates a special container data member and a corresponding set + of accessors and modifiers that are used to capture the order of elements + and, for mixed content, of text. + +
The type argument is an XML Schema type name that can be + optionally qualified with a namespace in the + namespace#name form. Note also that you + will need to specify this option when compiling every schema file that has + other ordered types derived from this type.
--ordered-type-derived: Automatically treat types derived from ordered bases as also ordered. This + is primarily useful if you would like to be able to iterate over the + complete content using the content order container.
--ordered-type-mixed: Automatically treat complex types with mixed content as ordered.
--ordered-type-all: Indicate that element order in all types is significant.
--order-container type: Specify a custom class template that should be used as a container for the + content order in ordered types instead of the default + std::vector. See --ordered-type for + more information on ordered type. This option is primarily useful if you + need to perform more complex lookups in the content order container, for + example by element id. In this case, a container like Boost multi-index may + be more convenient. Note that if using a custom container, you will also + most likely need to include the relevant headers using the + --hxx-prologue* options.
--generate-serialization: Generate serialization functions. Serialization functions convert the object + model back to XML.
--generate-ostream: Generate ostream insertion operators (operator<<) + for generated types. This allows one 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 + member-wise.
--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-any-type: Extract and store content of the XML Schema anyType type + as a DOM fragment. 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.
--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) and later 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.
--const-regex regex: Add regex to the list of regular expressions used to translate XML + Schema-derived names to C++ constant 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 map: Use a custom C++ type instead of the generated class. The map + argument is in the form + name[=type[/base]], where + name is a type name as defined in XML Schema and type is a C++ + type name that should be used instead. 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 regex: Use custom C++ types instead of the generated classes. The regex + argument is in the form + /name-pat/[type-sub/[base-sub/]], + where name-pat is a regex pattern that will be matched against type + names as defined in XML Schema and type-sub is a C++ type name + substitution that should be used instead. 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 this substitution as its name. The pattern + and substitutions are in the Perl regular expression format. See also the + REGEX AND SHELL QUOTING section below.
--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-validation: Generate validation code. The validation code ("perfect parser") 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. 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 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 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.
--skel-type-suffix suffix: Use the provided suffix instead of the default + _pskel to construct the names of the generated parser + skeletons.
--skel-file-suffix suffix: Use the provided suffix instead of the default + -pskel to construct the names of the generated parser + skeleton files.
--impl-type-suffix suffix: Use the provided suffix instead of the default + _pimpl to construct the names of the parser + implementations for the built-in XML Schema types as well as sample parser + implementations.
--impl-file-suffix suffix: Use the provided suffix instead of the default + -pimpl to construct the names of the 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, + --const-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, + --const-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/

+ +

The const category is used to create C++ constant names for the + element/wildcard/text content ids in ordered types.

+ +

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.

+ +