# NAME

xsd - W3C XML Schema Definition Compiler

# SYNOPSIS

`xsd command [options] 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), and `name.cxx` (source 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.
`--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 for included and imported schema definitions.
`--include-prefix prefix`
  Add `prefix` to generated `#include` directive paths for included and imported schema definitions.

  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/`, the include directive in the generated code would be:

  `#include "schemas/base.hxx"`

`--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.
`--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.
`--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/`.
`--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.
`--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.
`--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.
`--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.
`--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-sloc`
  Show the number of generated physical source lines of code (SLOC).
`--show-classification`
  Show anonymous types that are use to classify more than one attribute/element.
`--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 for included and imported schema definitions.
`--include-prefix prefix`
  Add `prefix` to generated `#include` directive paths for included and imported schema definitions.

  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/`, the include directive in the generated code would be:

  `#include "schemas/base.hxx"`

`--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-sloc`
  Show the number of generated physical source lines of code (SLOC).
`--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.