diff options
Diffstat (limited to 'xsd/doc/xsd.1')
| -rw-r--r-- | xsd/doc/xsd.1 | 1648 |
1 files changed, 1648 insertions, 0 deletions
diff --git a/xsd/doc/xsd.1 b/xsd/doc/xsd.1 new file mode 100644 index 0000000..dc5b38a --- /dev/null +++ b/xsd/doc/xsd.1 @@ -0,0 +1,1648 @@ +.\" Process this file with +.\" groff -man -Tascii xsd.1 +.\" +.TH XSD 1 "July 2014" "XSD 4.0.0" +.SH NAME +xsd \- W3C XML Schema to C++ Compiler +.\" +.\" +.\" +.\"-------------------------------------------------------------------- +.SH SYNOPSIS +.\"-------------------------------------------------------------------- +.B xsd +.I command +.B [ +.I options +.B ] +.I file +.B [ +.I file +.B ...] +.in +.B xsd help +.B [ +.I command +.B ] +.in +.B xsd version +.\" +.\" +.\" +.\"-------------------------------------------------------------------- +.SH DESCRIPTION +.\"-------------------------------------------------------------------- +.B xsd +generates vocabulary-specific, statically-typed C++ mapping from W3C XML +Schema definitions. Particular mapping to produce is selected by a +.IR command . +Each mapping has a number of mapping-specific +.I options +that should appear, if any, after the +.IR command . +Input files should be W3C XML Schema definitions. The exact set of the +generated files depends on the selected mapping and options. +.\" +.\" +.\" +.\"-------------------------------------------------------------------- +.SH COMMANDS +.\"-------------------------------------------------------------------- +.IP \fBcxx-tree\fR +Generate the C++/Tree mapping. For each input file in the form +.B name.xsd +the following C++ files are generated: +.B name.hxx +(header file), +.B name.ixx +(inline file, generated only if the +.B --generate-inline +option is specified), +.B name.cxx +(source file), and +.B name-fwd.hxx +(forward declaration file, generated only if the +.B --generate-forward +option is specified). + +.IP \fBcxx-parser\fR +Generate the C++/Parser mapping. For each input file in the form +.B name.xsd +the following C++ files are generated: +.B name-pskel.hxx +(parser skeleton header file), +.B name-pskel.ixx +(parser skeleton inline file, generated only if the +.B --generate-inline +option is specified), and +.B name-pskel.cxx +(parser skeleton source file). If the +.B --generate-noop-impl +or +.B --generate-print-impl +option is specified, the following additional sample implementation files +are generated: +.B name-pimpl.hxx +(parser implementation header file) and +.B name-pimpl.cxx +(parser implementation source file). If the +.B --generate-test-driver +option is specified, the additional +.B name-driver.cxx +test driver file is generated. + +.IP \fBhelp\fR +Print usage information and exit. Use +.PP +.RS +.RS 3 +.B xsd help +.I command +.RE +.PP +for command-specific help. +.RE +.IP \fBversion\fR +Print version and exit. +.\"-------------------------------------------------------------------- +.SH OPTIONS +.\"-------------------------------------------------------------------- +Command-specific +.IR options , +if any, should appear after the corresponding +.IR command . + +.\" +.\" Common options. +.\" +.SS common options +. +.\" +.\" The following documentation was generated by CLI, a command +.\" line interface compiler for C++. +.\" +.IP "\fB--std\fP \fIversion\fP" +Specify the C++ standard that the generated code should conform to\. Valid +values are \fBc++98\fP (default) and \fBc++11\fP\. + +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 \fBstd::unique_ptr\fP instead of deprecated +\fBstd::auto_ptr\fP\. + +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 +(\fBlibxsd\fP) 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 \fBXSD_CXX11\fP macro +for your entire project\. + +.IP "\fB--char-type\fP \fItype\fP" +Generate code using the provided character \fItype\fP instead of the default +\fBchar\fP\. Valid values are \fBchar\fP and \fBwchar_t\fP\. + +.IP "\fB--char-encoding\fP \fIenc\fP" +Specify the character encoding that should be used in the generated code\. +Valid values for the \fBchar\fP character type are \fButf8\fP (default), +\fBiso8859-1\fP, \fBlcp\fP (Xerces-C++ local code page), and \fBcustom\fP\. +If you pass \fBcustom\fP 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 \fB--hxx-prologue\fP option)\. + +For the \fBwchar_t\fP character type the only valid value is \fBauto\fP and +the encoding is automatically selected between UTF-16 and UTF-32/UCS-4, +depending on the \fBwchar_t\fP type size\. + +.IP "\fB--output-dir\fP \fIdir\fP" +Write generated files to \fIdir\fP instead of the current directory\. + +.IP "\fB--generate-inline\fP" +Generate simple functions inline\. This option triggers creation of the +inline file\. + +.IP "\fB--generate-xml-schema\fP" +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 +\fB--extern-xml-schema\fP option to include this file in the generated files +for other schemas\. + +.IP "\fB--extern-xml-schema\fP \fIfile\fP" +Include a header file derived from \fIfile\fP 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 +\fB--generate-xml-schema\fP option to generate this header file\. + +.IP "\fB--namespace-map\fP \fIxns\fP=\fIcns\fP" +Map XML Schema namespace \fIxns\fP to C++ namespace \fIcns\fP\. Repeat this +option to specify mapping for more than one XML Schema namespace\. For +example, the following option: + +\fB--namespace-map http://example\.com/foo/bar=foo::bar\fP + +Will map the \fBhttp://example\.com/foo/bar\fP XML Schema namespace to the +\fBfoo::bar\fP C++ namespace\. + +.IP "\fB--namespace-regex\fP \fIregex\fP" +Add \fIregex\fP to the list of regular expressions used to translate XML +Schema namespace names to C++ namespace names\. \fIregex\fP is a Perl-like +regular expression in the form +\fB/\fP\fIpattern\fP\fB/\fP\fIreplacement\fP\fB/\fP\. Any character can be +used as a delimiter instead of \fB/\fP\. Escaping of the delimiter character +in \fIpattern\fP or \fIreplacement\fP 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 + +\fIfilename\fP \fInamespace\fP + +For example, if you have file \fBhello\.xsd\fP with namespace +\fBhttp://example\.com/hello\fP and you run \fBxsd\fP on this file, then the +string in question will be: + +\fBhello\.xsd\. http://example\.com/hello\fP + +For the built-in XML Schema namespace the string is: + +\fBXMLSchema\.xsd http://www\.w3\.org/2001/XMLSchema\fP + +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 \fB/\fP are replaced with \fB::\fP\. + +3\. The result is verified to be a valid C++ scope name (e\.g\., +\fBfoo::bar\fP)\. 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 \fBhttp://example\.com/foo/bar\fP to C++ namespaces in the form +\fBfoo::bar\fP: + +\fB%\.* http://example\.com/(\.+)%$1%\fP + +See also the REGEX AND SHELL QUOTING section below\. + +.IP "\fB--namespace-regex-trace\fP" +Trace the process of applying regular expressions specified with the +\fB--namespace-regex\fP option\. Use this option to find out why your +regular expressions don't do what you expected them to do\. + +.IP "\fB--reserved-name\fP \fIn\fP[=\fIr\fP]" +Add name \fIn\fP to the list of names that should not be used as +identifiers\. The name can optionally be followed by \fB=\fP and the +replacement name \fIr\fP that should be used instead\. All the C++ keywords +are already in this list\. + +.IP "\fB--include-with-brackets\fP" +Use angle brackets (<>) instead of quotes ("") in generated \fB#include\fP +directives\. + +.IP "\fB--include-prefix\fP \fIprefix\fP" +Add \fIprefix\fP to generated \fB#include\fP directive paths\. + +For example, if you had the following import element in your schema + +\fB<import namespace="\.\.\." schemaLocation="base\.xsd"/>\fP + +and compiled this fragment with \fB--include-prefix schemas/\fP, then the +include directive in the generated code would be: + +\fB#include "schemas/base\.hxx"\fP + +.IP "\fB--include-regex\fP \fIregex\fP" +Add \fIregex\fP to the list of regular expressions used to transform +\fB#include\fP directive paths\. \fIregex\fP is a Perl-like regular +expression in the form \fB/\fP\fIpattern\fP\fB/\fP\fIreplacement\fP\fB/\fP\. +Any character can be used as a delimiter instead of \fB/\fP\. Escaping of +the delimiter character in \fIpattern\fP or \fIreplacement\fP 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 +\fBschemas/foo/bar\fP to paths in the form \fBgenerated/foo/bar\fP: + +\fB%schemas/(\.+)%generated/$1%\fP + +See also the REGEX AND SHELL QUOTING section below\. + +.IP "\fB--include-regex-trace\fP" +Trace the process of applying regular expressions specified with the +\fB--include-regex\fP option\. Use this option to find out why your regular +expressions don't do what you expected them to do\. + +.IP "\fB--guard-prefix\fP \fIprefix\fP" +Add \fIprefix\fP 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\. + +.IP "\fB--hxx-suffix\fP \fIsuffix\fP" +Use the provided \fIsuffix\fP instead of the default \fB\.hxx\fP 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\. + +.IP "\fB--ixx-suffix\fP \fIsuffix\fP" +Use the provided \fIsuffix\fP instead of the default \fB\.ixx\fP to +construct the name of the inline file\. + +.IP "\fB--cxx-suffix\fP \fIsuffix\fP" +Use the provided \fIsuffix\fP instead of the default \fB\.cxx\fP to +construct the name of the source file\. + +.IP "\fB--fwd-suffix\fP \fIsuffix\fP" +Use the provided \fIsuffix\fP instead of the default \fB-fwd\.hxx\fP to +construct the name of the forward declaration file\. + +.IP "\fB--hxx-regex\fP \fIregex\fP" +Use the provided expression to construct the name of the header file\. +\fIregex\fP is a Perl-like regular expression in the form +\fB/\fP\fIpattern\fP\fB/\fP\fIreplacement\fP\fB/\fP\. 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\. + +.IP "\fB--ixx-regex\fP \fIregex\fP" +Use the provided expression to construct the name of the inline file\. +\fIregex\fP is a Perl-like regular expression in the form +\fB/\fP\fIpattern\fP\fB/\fP\fIreplacement\fP\fB/\fP\. See also the REGEX AND +SHELL QUOTING section below\. + +.IP "\fB--cxx-regex\fP \fIregex\fP" +Use the provided expression to construct the name of the source file\. +\fIregex\fP is a Perl-like regular expression in the form +\fB/\fP\fIpattern\fP\fB/\fP\fIreplacement\fP\fB/\fP\. See also the REGEX AND +SHELL QUOTING section below\. + +.IP "\fB--fwd-regex\fP \fIregex\fP" +Use the provided expression to construct the name of the forward declaration +file\. \fIregex\fP is a Perl-like regular expression in the form +\fB/\fP\fIpattern\fP\fB/\fP\fIreplacement\fP\fB/\fP\. See also the REGEX AND +SHELL QUOTING section below\. + +.IP "\fB--hxx-prologue\fP \fItext\fP" +Insert \fItext\fP at the beginning of the header file\. + +.IP "\fB--ixx-prologue\fP \fItext\fP" +Insert \fItext\fP at the beginning of the inline file\. + +.IP "\fB--cxx-prologue\fP \fItext\fP" +Insert \fItext\fP at the beginning of the source file\. + +.IP "\fB--fwd-prologue\fP \fItext\fP" +Insert \fItext\fP at the beginning of the forward declaration file\. + +.IP "\fB--prologue\fP \fItext\fP" +Insert \fItext\fP at the beginning of each generated file for which there is +no file-specific prologue\. + +.IP "\fB--hxx-epilogue\fP \fItext\fP" +Insert \fItext\fP at the end of the header file\. + +.IP "\fB--ixx-epilogue\fP \fItext\fP" +Insert \fItext\fP at the end of the inline file\. + +.IP "\fB--cxx-epilogue\fP \fItext\fP" +Insert \fItext\fP at the end of the source file\. + +.IP "\fB--fwd-epilogue\fP \fItext\fP" +Insert \fItext\fP at the end of the forward declaration file\. + +.IP "\fB--epilogue\fP \fItext\fP" +Insert \fItext\fP at the end of each generated file for which there is no +file-specific epilogue\. + +.IP "\fB--hxx-prologue-file\fP \fIfile\fP" +Insert the content of the \fIfile\fP at the beginning of the header file\. + +.IP "\fB--ixx-prologue-file\fP \fIfile\fP" +Insert the content of the \fIfile\fP at the beginning of the inline file\. + +.IP "\fB--cxx-prologue-file\fP \fIfile\fP" +Insert the content of the \fIfile\fP at the beginning of the source file\. + +.IP "\fB--fwd-prologue-file\fP \fIfile\fP" +Insert the content of the \fIfile\fP at the beginning of the forward +declaration file\. + +.IP "\fB--prologue-file\fP \fIfile\fP" +Insert the content of the \fIfile\fP at the beginning of each generated file +for which there is no file-specific prologue file\. + +.IP "\fB--hxx-epilogue-file\fP \fIfile\fP" +Insert the content of the \fIfile\fP at the end of the header file\. + +.IP "\fB--ixx-epilogue-file\fP \fIfile\fP" +Insert the content of the \fIfile\fP at the end of the inline file\. + +.IP "\fB--cxx-epilogue-file\fP \fIfile\fP" +Insert the content of the \fIfile\fP at the end of the source file\. + +.IP "\fB--fwd-epilogue-file\fP \fIfile\fP" +Insert the content of the \fIfile\fP at the end of the forward declaration +file\. + +.IP "\fB--epilogue-file\fP \fIfile\fP" +Insert the content of the \fIfile\fP at the end of each generated file for +which there is no file-specific epilogue file\. + +.IP "\fB--export-symbol\fP \fIsymbol\fP" +Insert \fIsymbol\fP in places where DLL export/import control statements +(\fB__declspec(dllexport/dllimport)\fP) are necessary\. + +.IP "\fB--export-xml-schema\fP" +Export/import types in the XML Schema namespace using the export symbol +provided with the \fB--export-symbol\fP option\. The \fBXSD_NO_EXPORT\fP +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\. + +.IP "\fB--export-maps\fP" +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 +\fB--import-maps\fP\. This option is only valid together with +\fB--generate-polymorphic\fP\. The \fBXSD_NO_EXPORT\fP 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\. + +.IP "\fB--import-maps\fP" +Import polymorphism support maps to a Win32 DLL or executable into which +this generated code is linked\. See the \fB--export-maps\fP option +documentation for details\. This options is only valid together with +\fB--generate-polymorphic\fP\. The \fBXSD_NO_EXPORT\fP 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\. + +.IP "\fB--generate-dep\fP" +Generate \fBmake\fP dependency information\. This option triggers the +creation of the \fB\.d\fP 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 \fBmakefile\fP to implement automatic dependency +tracking\. + +Note also that automatic dependency generation is not supported in the +file-per-type mode (\fB--file-per-type\fP)\. 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 \fB--file-list*\fP options\. + +.IP "\fB--generate-dep-only\fP" +Generate \fBmake\fP dependency information only\. + +.IP "\fB--dep-phony\fP" +Generate phony targets for included/imported schema files, causing each to +depend on nothing\. Such dummy rules work around \fBmake\fP errors caused by +the removal of schema files without also updating the dependency file to +match\. + +.IP "\fB--dep-target\fP \fItarget\fP" +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\. + +.IP "\fB--dep-suffix\fP \fIsuffix\fP" +Use the provided \fIsuffix\fP instead of the default \fB\.d\fP to construct +the name of the dependency file\. + +.IP "\fB--dep-regex\fP \fIregex\fP" +Use the provided expression to construct the name of the dependency file\. +\fIregex\fP is a Perl-like regular expression in the form +\fB/\fP\fIpattern\fP\fB/\fP\fIreplacement\fP\fB/\fP\. See also the REGEX AND +SHELL QUOTING section below\. + +.IP "\fB--disable-warning\fP \fIwarn\fP" +Disable printing warning with id \fIwarn\fP\. If \fBall\fP is specified for +the warning id then all warnings are disabled\. + +.IP "\fB--options-file\fP \fIfile\fP" +Read additional options from \fIfile\fP\. Each option should appearing on a +separate line optionally followed by space and an option value\. Empty lines +and lines starting with \fB#\fP are ignored\. Option values can be enclosed +in double (\fB"\fP) or single (\fB'\fP) 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 \fB'"x"'\fP\. 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 \fB--options-file\fP 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\. + +.IP "\fB--show-sloc\fP" +Show the number of generated physical source lines of code (SLOC)\. + +.IP "\fB--sloc-limit\fP \fInum\fP" +Check that the number of generated physical source lines of code (SLOC) does +not exceed \fInum\fP\. + +.IP "\fB--proprietary-license\fP" +Indicate that the generated code is licensed under a proprietary license +instead of the GPL\. + +.IP "\fB--custom-literals\fP \fIfile\fP" +Load custom XML string to C++ literal mappings from \fIfile\fP\. 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 \fBcustom-literals\.xsd\fP XML +Schema file that can be found in the documentation directory\. + +.IP "\fB--preserve-anonymous\fP" +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\. + +.IP "\fB--show-anonymous\fP" +Show elements and attributes that are of anonymous types\. This option only +makes sense together with the \fB--preserve-anonymous\fP option\. + +.IP "\fB--anonymous-regex\fP \fIregex\fP" +Add \fIregex\fP to the list of regular expressions used to derive names for +anonymous types from the enclosing attributes/elements\. \fIregex\fP is a +Perl-like regular expression in the form +\fB/\fP\fIpattern\fP\fB/\fP\fIreplacement\fP\fB/\fP\. Any character can be +used as a delimiter instead of \fB/\fP\. Escaping of the delimiter character +in \fIpattern\fP or \fIreplacement\fP 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 + +\fIfilename\fP \fInamespace\fP \fIxpath\fP + +For instance: + +\fBhello\.xsd http://example\.com/hello element\fP + +\fBhello\.xsd http://example\.com/hello type/element\fP + +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: + +\fB%\.* \.* (\.+/)*(\.+)%\eu$2%\fP + +See also the REGEX AND SHELL QUOTING section below\. + +.IP "\fB--anonymous-regex-trace\fP" +Trace the process of applying regular expressions specified with the +\fB--anonymous-regex\fP option\. Use this option to find out why your +regular expressions don't do what you expected them to do\. + +.IP "\fB--location-map\fP \fIol\fP=\fInl\fP" +Map the original schema location \fIol\fP that is specified in the XML +Schema include or import elements to new schema location \fInl\fP\. Repeat +this option to map more than one schema location\. For example, the +following option maps the \fBhttp://example\.com/foo\.xsd\fP URL to the +\fBfoo\.xsd\fP local file\. + +\fB--location-map http://example\.com/foo\.xsd=foo\.xsd\fP + +.IP "\fB--location-regex\fP \fIregex\fP" +Add \fIregex\fP to the list of regular expressions used to map schema +locations that are specified in the XML Schema include or import elements\. +\fIregex\fP is a Perl-like regular expression in the form +\fB/\fP\fIpattern\fP\fB/\fP\fIreplacement\fP\fB/\fP\. Any character can be +used as a delimiter instead of \fB/\fP\. Escaping of the delimiter character +in \fIpattern\fP or \fIreplacement\fP 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 +\fBhttp://example\.com/foo/bar\.xsd\fP to local files in the form +\fBbar\.xsd\fP: + +\fB%http://\.+/(\.+)%$1%\fP + +See also the REGEX AND SHELL QUOTING section below\. + +.IP "\fB--location-regex-trace\fP" +Trace the process of applying regular expressions specified with the +\fB--location-regex\fP option\. Use this option to find out why your regular +expressions don't do what you expected them to do\. + +.IP "\fB--file-per-type\fP" +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: +\fB--type-file-regex\fP, \fB--schema-file-regex\fP, \fB--fat-type-file\fP, +and \fB--file-list\fP\. + +.IP "\fB--type-file-regex\fP \fIregex\fP" +Add \fIregex\fP to the list of regular expressions used to translate type +names to file names when the \fB--file-per-type\fP option is specified\. +\fIregex\fP is a Perl-like regular expression in the form +\fB/\fP\fIpattern\fP\fB/\fP\fIreplacement\fP\fB/\fP\. Any character can be +used as a delimiter instead of \fB/\fP\. Escaping of the delimiter character +in \fIpattern\fP or \fIreplacement\fP 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 + +\fInamespace\fP \fItype-name\fP + +For example, the following expression maps type \fBfoo\fP that is defined in +the \fBhttp://example\.com/bar\fP namespace to file name \fBbar-foo\fP: + +\fB%http://example\.com/(\.+) (\.+)%$1-$2%\fP + +See also the REGEX AND SHELL QUOTING section below\. + +.IP "\fB--type-file-regex-trace\fP" +Trace the process of applying regular expressions specified with the +\fB--type-file-regex\fP option\. Use this option to find out why your +regular expressions don't do what you expected them to do\. + +.IP "\fB--schema-file-regex\fP \fIregex\fP" +Add \fIregex\fP to the list of regular expressions used to translate schema +file names when the \fB--file-per-type\fP option is specified\. \fIregex\fP +is a Perl-like regular expression in the form +\fB/\fP\fIpattern\fP\fB/\fP\fIreplacement\fP\fB/\fP\. Any character can be +used as a delimiter instead of \fB/\fP\. Escaping of the delimiter character +in \fIpattern\fP or \fIreplacement\fP 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 +\fB#include\fP directive paths as well as the generated C++ file paths\. +This option, along with \fB--type-file-regex\fP 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 +\fBfoo/1\.0\.0/\fP subdirectory to the files in the \fBfoo/\fP +subdirectory\. As a result, the \fB#include\fP directive paths for such +schemas will be in the \fBfoo/schema\.hxx\fP form and the generated C++ +files will be placed into the \fBfoo/\fP subdirectory: + +\fB%\.*/foo/1\.0\.0/(\.+)%foo/$1%\fP + +See also the REGEX AND SHELL QUOTING section below\. + +.IP "\fB--schema-file-regex-trace\fP" +Trace the process of applying regular expressions specified with the +\fB--schema-file-regex\fP option\. Use this option to find out why your +regular expressions don't do what you expected them to do\. + +.IP "\fB--fat-type-file\fP" +Generate code corresponding to global elements into type files instead of +schema files when the \fB--type-file-regex\fP 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\. + +.IP "\fB--file-list\fP \fIfile\fP" +Write a list of generated C++ files to \fIfile\fP\. This option is primarily +useful in the file-per-type compilation mode (\fB--file-per-type\fP) to +create a list of generated C++ files, for example, as a makefile fragment\. + +.IP "\fB--file-list-prologue\fP \fItext\fP" +Insert \fItext\fP at the beginning of the file list\. As a convenience, all +occurrences of the \fB\en\fP character sequence in \fItext\fP are replaced +with new lines\. This option can, for example, be used to assign the +generated file list to a makefile variable\. + +.IP "\fB--file-list-epilogue\fP \fItext\fP" +Insert \fItext\fP at the end of the file list\. As a convenience, all +occurrences of the \fB\en\fP character sequence in \fItext\fP are replaced +with new lines\. + +.IP "\fB--file-list-delim\fP \fItext\fP" +Delimit file names written to the file list with \fItext\fP instead of new +lines\. As a convenience, all occurrences of the \fB\en\fP character +sequence in \fItext\fP are replaced with new lines\. + +.\" +.\" C++/Tree options. +.\" +.SS cxx-tree command options +.\" +.\" The following documentation was generated by CLI, a command +.\" line interface compiler for C++. +.\" +.IP "\fB--generate-polymorphic\fP" +Generate polymorphism-aware code\. Specify this option if you use +substitution groups or \fBxsi:type\fP\. Use the \fB--polymorphic-type\fP or +\fB--polymorphic-type-all\fP option to specify which type hierarchies are +polymorphic\. + +.IP "\fB--polymorphic-type\fP \fItype\fP" +Indicate that \fItype\fP 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 \fItype\fP\. The \fItype\fP +argument is an XML Schema type name that can be optionally qualified with a +namespace in the \fInamespace\fP\fB#\fP\fIname\fP form\. + +.IP "\fB--polymorphic-type-all\fP" +Indicate that all types should be treated as polymorphic\. + +.IP "\fB--polymorphic-plate\fP \fInum\fP" +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\. + +.IP "\fB--ordered-type\fP \fItype\fP" +Indicate that element order in \fItype\fP 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 \fItype\fP argument is an XML Schema type name that can be optionally +qualified with a namespace in the \fInamespace\fP\fB#\fP\fIname\fP 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\. + +.IP "\fB--ordered-type-derived\fP" +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\. + +.IP "\fB--ordered-type-mixed\fP" +Automatically treat complex types with mixed content as ordered\. + +.IP "\fB--ordered-type-all\fP" +Indicate that element order in all types is significant\. + +.IP "\fB--order-container\fP \fItype\fP" +Specify a custom class template that should be used as a container for the +content order in ordered types instead of the default \fBstd::vector\fP\. +See \fB--ordered-type\fP 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 \fB--hxx-prologue*\fP options\. + +.IP "\fB--generate-serialization\fP" +Generate serialization functions\. Serialization functions convert the +object model back to XML\. + +.IP "\fB--generate-ostream\fP" +Generate ostream insertion operators (\fBoperator<<\fP) for generated +types\. This allows one to easily print a fragment or the whole object model +for debugging or logging\. + +.IP "\fB--generate-doxygen\fP" +Generate documentation comments suitable for extraction by the Doxygen +documentation system\. Documentation from annotations is added to the +comments if present in the schema\. + +.IP "\fB--generate-comparison\fP" +Generate comparison operators (\fBoperator==\fP and \fBoperator!=\fP) for +complex types\. Comparison is performed member-wise\. + +.IP "\fB--generate-default-ctor\fP" +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\. + +.IP "\fB--generate-from-base-ctor\fP" +Generate constructors that expect an instance of a base type followed by all +required members\. + +.IP "\fB--suppress-assignment\fP" +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\. + +.IP "\fB--generate-detach\fP" +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\. + +.IP "\fB--generate-wildcard\fP" +Generate accessors and modifiers as well as parsing and serialization code +for XML Schema wildcards (\fBany\fP and \fBanyAttribute\fP)\. 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\. + +.IP "\fB--generate-any-type\fP" +Extract and store content of the XML Schema \fBanyType\fP type as a DOM +fragment\. Note that you need to initialize the Xerces-C++ runtime if you +are using this option\. + +.IP "\fB--generate-insertion\fP \fIos\fP" +Generate data representation stream insertion operators for the \fIos\fP +output stream type\. Repeat this option to specify more than one stream +type\. The ACE CDR stream (\fBACE_OutputCDR\fP) and RPC XDR are recognized +by the compiler and the necessary \fB#include\fP directives are +automatically generated\. For custom stream types use the +\fB--hxx-prologue*\fP options to provide the necessary declarations\. + +.IP "\fB--generate-extraction\fP \fIis\fP" +Generate data representation stream extraction constructors for the \fIis\fP +input stream type\. Repeat this option to specify more than one stream +type\. The ACE CDR stream (\fBACE_InputCDR\fP) and RPC XDR are recognized by +the compiler and the necessary \fB#include\fP directives are automatically +generated\. For custom stream types use the \fB--hxx-prologue*\fP options to +provide the necessary declarations\. + +.IP "\fB--generate-forward\fP" +Generate a separate header file with forward declarations for the types +being generated\. + +.IP "\fB--suppress-parsing\fP" +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\. + +.IP "\fB--generate-element-type\fP" +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\. + +.IP "\fB--generate-element-map\fP" +Generate a root element map that allows uniform parsing and serialization of +multiple root elements\. This option is only valid together with +\fB--generate-element-type\fP\. + +.IP "\fB--generate-intellisense\fP" +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\. + +.IP "\fB--omit-default-attributes\fP" +Omit attributes with default and fixed values from serialized XML +documents\. + +.IP "\fB--type-naming\fP \fIstyle\fP" +Specify the type naming convention that should be used in the generated +code\. Valid styles are \fBknr\fP (default), \fBucc\fP, and \fBjava\fP\. See +the NAMING CONVENTION section below for more information\. + +.IP "\fB--function-naming\fP \fIstyle\fP" +Specify the function naming convention that should be used in the generated +code\. Valid styles are \fBknr\fP (default), \fBlcc\fP, and \fBjava\fP\. See +the NAMING CONVENTION section below for more information\. + +.IP "\fB--type-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--accessor-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--one-accessor-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--opt-accessor-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--seq-accessor-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--modifier-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--one-modifier-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--opt-modifier-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--seq-modifier-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--parser-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--serializer-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--const-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--enumerator-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--element-type-regex\fP \fIregex\fP" +Add \fIregex\fP 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\. + +.IP "\fB--name-regex-trace\fP" +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\. + +.IP "\fB--root-element-first\fP" +Treat only the first global element as a document root\. By default all +global elements are considered document roots\. + +.IP "\fB--root-element-last\fP" +Treat only the last global element as a document root\. By default all +global elements are considered document roots\. + +.IP "\fB--root-element-all\fP" +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\. + +.IP "\fB--root-element-none\fP" +Do not treat any global elements as document roots\. By default all global +elements are considered document roots\. + +.IP "\fB--root-element\fP \fIelement\fP" +Treat only \fIelement\fP as a document root\. Repeat this option to specify +more than one root element\. + +.IP "\fB--custom-type\fP \fImap\fP" +Use a custom C++ type instead of the generated class\. The \fImap\fP +argument is in the form \fIname\fP[\fB=\fP\fItype\fP[\fB/\fP\fIbase\fP]], +where \fIname\fP is a type name as defined in XML Schema and \fItype\fP is a +C++ type name that should be used instead\. If \fItype\fP 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 \fIbase\fP is +specified then the generated class is still generated but with that name\. + +.IP "\fB--custom-type-regex\fP \fIregex\fP" +Use custom C++ types instead of the generated classes\. The \fIregex\fP +argument is in the form +\fB/\fP\fIname-pat\fP\fB/\fP[\fItype-sub\fP\fB/\fP[\fIbase-sub\fP\fB/\fP]], +where \fIname-pat\fP is a regex pattern that will be matched against type +names as defined in XML Schema and \fItype-sub\fP is a C++ type name +substitution that should be used instead\. If \fItype-sub\fP 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 \fIbase-sub\fP 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\. + +.IP "\fB--parts\fP \fInum\fP" +Split generated source code into \fInum\fP 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)\. + +.IP "\fB--parts-suffix\fP \fIsuffix\fP" +Use \fIsuffix\fP instead of the default '\fB-\fP' to separate the file name +from the part number\. + +\" +\" C++/Parser +\" +.SS cxx-parser command options +.\" +.\" The following documentation was generated by CLI, a command +.\" line interface compiler for C++. +.\" +.IP "\fB--type-map\fP \fImapfile\fP" +Read XML Schema to C++ type mapping information from \fImapfile\fP\. 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 \fBvoid\fP\. See the TYPE MAP section below for more +information\. + +.IP "\fB--xml-parser\fP \fIparser\fP" +Use \fIparser\fP as the underlying XML parser\. Valid values are +\fBxerces\fP for Xerces-C++ (default) and \fBexpat\fP for Expat\. + +.IP "\fB--generate-validation\fP" +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 +(\fBexpat\fP)\. + +.IP "\fB--suppress-validation\fP" +Suppress the generation of validation code\. Validation is suppressed by +default when the selected underlying XML parser is validating +(\fBxerces\fP)\. + +.IP "\fB--generate-polymorphic\fP" +Generate polymorphism-aware code\. Specify this option if you use +substitution groups or \fBxsi:type\fP\. + +.IP "\fB--generate-noop-impl\fP" +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 \fBname\.xsd\fP this option triggers +the generation of two additional C++ files in the form: +\fBname-pimpl\.hxx\fP (parser implementation header file) and +\fBname-pimpl\.cxx\fP (parser implementation source file)\. + +.IP "\fB--generate-print-impl\fP" +Generate a sample parser implementation that prints the XML data to STDOUT\. +For an input file in the form \fBname\.xsd\fP this option triggers the +generation of two additional C++ files in the form: \fBname-pimpl\.hxx\fP +(parser implementation header file) and \fBname-pimpl\.cxx\fP (parser +implementation source file)\. + +.IP "\fB--generate-test-driver\fP" +Generate a test driver for the sample parser implementation\. For an input +file in the form \fBname\.xsd\fP this option triggers the generation of an +additional C++ file in the form \fBname-driver\.cxx\fP\. + +.IP "\fB--force-overwrite\fP" +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\. + +.IP "\fB--root-element-first\fP" +Indicate that the first global element is the document root\. This +information is used to generate the test driver for the sample +implementation\. + +.IP "\fB--root-element-last\fP" +Indicate that the last global element is the document root\. This +information is used to generate the test driver for the sample +implementation\. + +.IP "\fB--root-element\fP \fIelement\fP" +Indicate that \fIelement\fP is the document root\. This information is used +to generate the test driver for the sample implementation\. + +.IP "\fB--skel-type-suffix\fP \fIsuffix\fP" +Use the provided \fIsuffix\fP instead of the default \fB_pskel\fP to +construct the names of the generated parser skeletons\. + +.IP "\fB--skel-file-suffix\fP \fIsuffix\fP" +Use the provided \fIsuffix\fP instead of the default \fB-pskel\fP to +construct the names of the generated parser skeleton files\. + +.IP "\fB--impl-type-suffix\fP \fIsuffix\fP" +Use the provided \fIsuffix\fP instead of the default \fB_pimpl\fP to +construct the names of the parser implementations for the built-in XML +Schema types as well as sample parser implementations\. + +.IP "\fB--impl-file-suffix\fP \fIsuffix\fP" +Use the provided \fIsuffix\fP instead of the default \fB-pimpl\fP to +construct the names of the generated sample parser implementation files\. + +\" +\" NAMING CONVENTION +\" + +.SH 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 +.B --type-naming +and +.B --function-naming +options. A custom naming convention can be achieved using the +.BR --type-regex , +.BR --accessor-regex , +.BR --one-accessor-regex , +.BR --opt-accessor-regex , +.BR --seq-accessor-regex , +.BR --modifier-regex , +.BR --one-modifier-regex , +.BR --opt-modifier-regex , +.BR --seq-modifier-regex , +.BR --parser-regex , +.BR --serializer-regex , +.BR --const-regex , +.BR --enumerator-regex , +and +.B --element-type-regex +options. + +The +.B --type-naming +option specifies the convention that should be used for naming C++ types. +Possible values for this option are +.B knr +(default), +.BR ucc , +and +.BR java . +The +.B 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 +.B ucc +(stands for upper-camel-case) and +.B 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 +.B --function-naming +option specifies the convention that should be used for naming C++ functions. +Possible values for this option are +.B knr +(default), +.BR lcc , +and +.BR java . +The +.B 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 +.B 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 +.B 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 +.B --type-naming +and +.B --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 +.B --*-regex +options (discussed below) to perform further transformations on the names +that come from the schema. + +The +.BR --type-regex , +.BR --accessor-regex , +.BR --one-accessor-regex , +.BR --opt-accessor-regex , +.BR --seq-accessor-regex , +.BR --modifier-regex , +.BR --one-modifier-regex , +.BR --opt-modifier-regex , +.BR --seq-modifier-regex , +.BR --parser-regex , +.BR --serializer-regex , +.BR --const-regex , +.BR --enumerator-regex , +and +.B --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 +.B --type-naming +and +.B --function-naming +options. Expressions that are provided with the +.B --*-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 +.B --name-regex-trace +option allows you to trace the process of applying +regular expressions to names. + +The value for the +.B --*-regex +options should be a perl-like regular expression in the form +.BI / pattern / replacement /\fR. +Any character can be used as a delimiter instead of +.BR / . +Escaping of the delimiter character in +.I pattern +or +.I 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 +.B --one-accessor-regex +(accessors with cardinality one), +.B --opt-accessor-regex +(accessors with cardinality optional), and +.B --seq-accessor-regex +(accessors with cardinality sequence) categories the +.B --accessor-regex +expressions are used as a fallback. For the +.BR --one-modifier-regex , +.BR --opt-modifier-regex , +and +.B --seq-modifier-regex +categories the +.B --modifier-regex +expressions are used as a fallback. For the +.B --element-type-regex +category the +.B --type-regex +expressions are used as a fallback. + +The type name expressions +.RB ( --type-regex ) +are evaluated on the name string that has the following format: + +[\fInamespace \fR]\fIname\fR[\fB,\fIname\fR][\fB,\fIname\fR][\fB,\fIname\fR] + +The element type name expressions +.RB ( --element-type-regex ), +effective only when the +.B --generate-element-type +option is specified, are evaluated on the name string that has the following +format: + +.I namespace name + +In the type name format the +.I 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 +.I namespace +part is empty but the space is still present. In the type name format after +the initial +.I name +component, up to three additional +.I name +components can be present, separated by commas. For example: + +.B http://example.com/hello type + +.B foo + +.B foo,iterator + +.B 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: + +.B /(?:[^ ]* )?([^,]+)/\\\\u$1/ + +.B /(?:[^ ]* )?([^,]+),([^,]+)/\\\\u$1\\\\u$2/ + +.B /(?:[^ ]* )?([^,]+),([^,]+),([^,]+)/\\\\u$1\\\\u$2\\\\u$3/ + +.B /(?:[^ ]* )?([^,]+),([^,]+),([^,]+),([^,]+)/\\\\u$1\\\\u$2\\\\u$3\\\\u$4/ + +The accessor and modifier expressions +.RB ( --*accessor-regex +and +.BR --*modifier-regex ) +are evaluated on the name string that has the following format: + +\fIname\fR[\fB,\fIname\fR][\fB,\fIname\fR] + +After the initial +.I name +component, up to two additional +.I name +components can be present, separated by commas. For example: + +.B foo + +.B dom,document + +.B foo,default,value + +The following set of predefined regular expressions is used to transform +accessor names when the +.B java +naming convention is selected: + +.B /([^,]+)/get\\\\u$1/ + +.B /([^,]+),([^,]+)/get\\\\u$1\\\\u$2/ + +.B /([^,]+),([^,]+),([^,]+)/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 +.B java +naming convention is selected: + +.B /(.+)/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 +\" +.SH 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 +.B 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 +.BR void . +By providing your own type maps you can override these predefined rules. +The format of the type map file is presented below: + +.RS +.B namespace +.I schema-namespace +[ +.I cxx-namespace +] +.br +.B { +.br + ( +.B include +.IB file-name ; +)* +.br + ([ +.B type +] +.I schema-type cxx-ret-type +[ +.I cxx-arg-type +.RB ] ; +)* +.br +.B } +.br +.RE + +Both +.I schema-namespace +and +.I schema-type +are regex patterns while +.IR cxx-namespace , +.IR cxx-ret-type , +and +.I cxx-arg-type +are regex pattern substitutions. All names can be optionally enclosed +in \fR" "\fR, for example, to include white-spaces. + +.I schema-namespace +determines XML Schema namespace. Optional +.I cxx-namespace +is prefixed to every C++ type name in this namespace declaration. +.I cxx-ret-type +is a C++ type name that is used as a return type for the +.B post_* +functions. Optional +.I cxx-arg-type +is an argument type for callback functions corresponding to elements and +attributes of this type. If +.I cxx-arg-type +is not specified, it defaults to +.I cxx-ret-type +if +.I cxx-ret-type +ends with +.B * +or +.B & +(that is, it is a pointer or a reference) and +.B const +\fIcxx-ret-type\fB&\fR otherwise. +.I file-name +is a file name either in the \fR" "\fR or < > format and is added with the +.B #include +directive to the generated code. + +The \fB#\fR character starts a comment that ends with a new line or end of +file. To specify a name that contains \fB#\fR enclose it in \fR" "\fR. For +example: + +.RS +namespace http://www.example.com/xmlns/my my +.br +{ +.br + include "my.hxx"; +.br + + # Pass apples by value. + # + apple apple; +.br + + # Pass oranges as pointers. + # + orange orange_t*; +.br +} +.br +.RE + +In the example above, for the +.B http://www.example.com/xmlns/my#orange +XML Schema type, the +.B 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: + +.RS +include "my.hxx"; +.br +apple apple; +.br + +namespace http://www.example.com/xmlns/my +.br +{ +.br + orange "const orange_t*"; +.br +} +.br +.RE + + +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 +.B std::string +or +.B std::wstring +depending on the character type selected with the +.B --char-type +option +.RB ( char +by default). + +.RS +namespace http://www.w3.org/2001/XMLSchema +.br +{ +.br + boolean bool bool; +.br + + byte "signed char" "signed char"; +.br + unsignedByte "unsigned char" "unsigned char"; +.br + + short short short; +.br + unsignedShort "unsigned short" "unsigned short"; +.br + + int int int; +.br + unsignedInt "unsigned int" "unsigned int"; +.br + + long "long long" "long long"; +.br + unsignedLong "unsigned long long" "unsigned long long"; +.br + + integer "long long" "long long"; +.br + + negativeInteger "long long" "long long"; +.br + nonPositiveInteger "long long" "long long"; +.br + + positiveInteger "unsigned long long" "unsigned long long"; +.br + nonNegativeInteger "unsigned long long" "unsigned long long"; +.br + + float float float; +.br + double double double; +.br + decimal double double; +.br + + string std::string; +.br + normalizedString std::string; +.br + token std::string; +.br + Name std::string; +.br + NMTOKEN std::string; +.br + NCName std::string; +.br + ID std::string; +.br + IDREF std::string; +.br + language std::string; +.br + anyURI std::string; +.br + + NMTOKENS xml_schema::string_sequence; +.br + IDREFS xml_schema::string_sequence; +.br + + QName xml_schema::qname; +.br + + base64Binary std::auto_ptr<xml_schema::buffer> +.br + std::auto_ptr<xml_schema::buffer>; +.br + hexBinary std::auto_ptr<xml_schema::buffer> +.br + std::auto_ptr<xml_schema::buffer>; +.br + + date xml_schema::date; +.br + dateTime xml_schema::date_time; +.br + duration xml_schema::duration; +.br + gDay xml_schema::gday; +.br + gMonth xml_schema::gmonth; +.br + gMonthDay xml_schema::gmonth_day; +.br + gYear xml_schema::gyear; +.br + gYearMonth xml_schema::gyear_month; +.br + time xml_schema::time; +.br +} +.br +.RE + + +The last predefined rule maps anything that wasn't mapped by previous +rules to +.BR void : + +.RS +namespace .* +.br +{ +.br + .* void void; +.br +} +.br +.RE + +When you provide your own type maps with the +.B --type-map +option, they are evaluated first. This allows you to selectively override +predefined rules. + +.\" +.\" REGEX AND SHELL QUOTING +.\" +.SH 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 +.B --options-file +option. With this approach you don't need to worry about shell quoting. + +.\" +.\" DIAGNOSTICS +.\" +.SH DIAGNOSTICS +If the input file is not a valid W3C XML Schema definition, +.B xsd +will issue diagnostic messages to +.B STDERR +and exit with non-zero exit code. +.SH BUGS +Send bug reports to the xsd-users@codesynthesis.com mailing list. +.SH COPYRIGHT +Copyright (c) 2005-2014 Code Synthesis Tools CC. + +Permission is granted to copy, distribute and/or modify this +document under the terms of the GNU Free Documentation License, +version 1.2; with no Invariant Sections, no Front-Cover Texts and +no Back-Cover Texts. Copy of the license can be obtained from +http://codesynthesis.com/licenses/fdl-1.2.txt |