# NAME

xsd - W3C XML Schema Definition 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. For each input file in the form `name.xsd` some of the following C++ files are generated: `name.hxx` (header file), `name.ixx` (inline file), `name.txx` (template file), `name.cxx` (source file), and `name-fwd.hxx` (forward declaration file). The exact set of the generated files depends on the selected mapping and options.

# COMMANDS

`cxx-tree`
  Generate C++ tree mapping.
`cxx-parser`
  Generate C++ parser mapping.
`cxx-parser-e`
  Generate embedded C++ parser mapping.
`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`.

## cxx-tree command options

`--char-type type`
  Generate code using the provided character `type` instead of the default `char`. Valid values are `char` and `wchar_t`.
`--output-dir dir`
  Write generated files to `dir` instead of the current directory.
`--generate-polymorphic`
  Generate polymorphism-aware code. Specify this option if you use substitution groups or `xsi:type`.
`--generate-serialization`
  Generate serialization functions. Serialization functions convert an in-memory representation 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 representation of the document for debugging or logging.
`--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.
`--generate-insertion`
  Generate generic data representation stream insertion operators. Support for ACE CDR streams is provided as part of the runtime. Support for other stream types can be easily added.
`--generate-extraction`
  Generate generic data representation stream extraction constructors. Support for ACE CDR streams is provided as part of the runtime. Support for other stream types can be easily added.
`--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 generation of the parsing functions and constructors. Use this option to reduce the generated code size when parsing from XML is not needed.
`--namespace-map xns=cns`
  Map W3C 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-regex 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 W3C XML Schema namespace names to C++ namespace names. `regex` is a perl-like regular expression in the form `/pattern/replacement/`. Any character can be used as a delimiter instead of `/`. Escaping of the delimiter character in `pattern` or `replacement` is not supported.

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

  `filename namespace`

  For example,

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

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

  `http://example.com/hello`

  Note the leading space.

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

  1. The expression is applied and if the result is empty the next expression is considered.
  2. 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%`

`--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.
`--include-with-brackets`
  Use angle brackets (<>) instead of quotes ("") in generated `#include` directives.
`--include-prefix prefix`
  Add `prefix` to generated `#include` directive paths.

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

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

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

  `#include "schemas/base.hxx"`

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

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

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

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

`--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.
`--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.
`--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.
`--txx-suffix suffix`
  Use the provided `suffix` instead of the default `.txx` to construct the name of the template 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 for included/imported schemas.
`--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/`.
`--txx-regex regex`
  Use the provided expression to construct the name of the template file. `regex` is a perl-like regular expression in the form `/pattern/replacement/`.
`--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/`.
`--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/`.
`--hxx-prologue text`
  Insert `text` at the beginning of the header file.
`--ixx-prologue text`
  Insert `text` at the beginning of the inline file.
`--txx-prologue text`
  Insert `text` at the beginning of the template 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.
`--txx-epilogue text`
  Insert `text` at the end of the template 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.
`--txx-prologue-file file`
  Insert the content of the `file` at the beginning of the template 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.
`--txx-epilogue-file file`
  Insert the content of the `file` at the end of the template 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.
`--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.
`--export-symbol symbol`
  Insert `symbol` in places where Win32 DLL export/import control statements (`__declspec(dllexport/dllimport)`) are necessary.
`--show-classification`
  Show anonymous types that are use to classify more than one attribute/element.
`--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.
`--morph-anonymous`
  Morph anonymous types to explicitly named ones. The name is derived from the name of the enclosing element or attribute.
`--anonymous-regex regex`
  Add `regex` to the list of regular expressions used to derive names for anonymous types from the enclosing attributes/elements. `regex` is a perl-like regular expression in the form `/pattern/replacement/`. Any character can be used as a delimiter instead of `/`. Escaping of the delimiter character in `pattern` or `replacement` is not supported.

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

  `filename namespace xpath`

  For example,

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

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

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

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

  Note the leading space.

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

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

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

## cxx-parser and cxx-parser-e command options

`--char-type type`
  Generate code using the provided character `type` instead of the default `char`. Valid values are `char` and `wchar_t`.
`--output-dir dir`
  Write generated files to `dir` instead of the current directory.
`--xml-parser parser`
  Use `parser` as the underlying XML parser. Valid values are `xerces` for Xerces-C++ (default for the `cxx-parser` command) and `expat` for Expat (default for the `cxx-parser-e` command).
`--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 generation of validation code ("perfect" parser).
`--generate-inline`
  Generate simple functions inline. This option triggers creation of the inline file.
`--namespace-map xns=cns`
  Map W3C 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-regex 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 W3C XML Schema namespace names to C++ namespace names. `regex` is a perl-like regular expression in the form `/pattern/replacement/`. Any character can be used as a delimiter instead of `/`. Escaping of the delimiter character in `pattern` or `replacement` is not supported.

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

  `filename namespace`

  For example,

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

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

  `http://example.com/hello`

  Note the leading space.

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

  1. The expression is applied and if the result is empty the next expression is considered.
  2. 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%`

`--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.
`--include-with-brackets`
  Use angle brackets (<>) instead of quotes ("") in generated `#include` directives.
`--include-prefix prefix`
  Add `prefix` to generated `#include` directive paths.

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

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

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

  `#include "schemas/base.hxx"`

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

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

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

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

`--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.
`--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.
`--txx-suffix suffix`
  Use the provided `suffix` instead of the default `.txx` to construct the name of the template 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.
`--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/`.
`--txx-regex regex`
  Use the provided expression to construct the name of the template file. `regex` is a perl-like regular expression in the form `/pattern/replacement/`.
`--hxx-prologue text`
  Insert `text` at the beginning of the header file.
`--ixx-prologue text`
  Insert `text` at the beginning of the inline file.
`--txx-prologue text`
  Insert `text` at the beginning of the template 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.
`--txx-epilogue text`
  Insert `text` at the end of the template 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.
`--txx-prologue-file file`
  Insert the content of the `file` at the beginning of the template 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.
`--txx-epilogue-file file`
  Insert the content of the `file` at the end of the template 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 Win32 DLL export/import control statements (`__declspec(dllexport/dllimport)`) are necessary.
`--show-anonymous`
  Show elements and attributes that are of anonymous types.
`--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.
`--morph-anonymous`
  Morph anonymous types to explicitly named ones. The name is derived from the name of the enclosing element or attribute.
`--anonymous-regex regex`
  Add `regex` to the list of regular expressions used to derive names for anonymous types from the enclosing attributes/elements. `regex` is a perl-like regular expression in the form `/pattern/replacement/`. Any character can be used as a delimiter instead of `/`. Escaping of the delimiter character in `pattern` or `replacement` is not supported.

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

  `filename namespace xpath`

  For example,

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

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

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

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

  Note the leading space.

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

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

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

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