xsdcxx (1) Linux Manual Page

NAME

xsdcxx – W3C XML Schema to C++ Compiler

SYNOPSIS

xsdcxx command [ options ] file [ file …] xsdcxx help [ command ] xsdcxx version

DESCRIPTION

xsdcxx 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

xsdcxx 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 XSDCXX compiler will automatically add the necessary macro defines to the generated header files that will switch the header-only XSDCXX runtime library (libxsd) to the C++11 mode. However, if you include any of the XSDCXX 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.

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

%.* .* (.+/)*(.+)%