1XSDCXX(1) General Commands Manual XSDCXX(1)
2
6 xsdcxx - W3C XML Schema to C++ Compiler
7
9 xsdcxx command [ options ] file [ file ...]
10 xsdcxx help [ command ]
11 xsdcxx version
12
14 xsdcxx generates vocabulary-specific, statically-typed C++ mapping from
15 W3C XML Schema definitions. Particular mapping to produce is selected
16 by a command. Each mapping has a number of mapping-specific options
17 that should appear, if any, after the command. Input files should be
18 W3C XML Schema definitions. The exact set of the generated files
19 depends on the selected mapping and options.
20
22 cxx-tree
23 Generate the C++/Tree mapping. For each input file in the form
24 name.xsd the following C++ files are generated: name.hxx (header
25 file), name.ixx (inline file, generated only if the --generate-
26 inline option is specified), name.cxx (source file), and name-
27 fwd.hxx (forward declaration file, generated only if the --gen‐
28 erate-forward option is specified).
29 cxx-parser
32 Generate the C++/Parser mapping. For each input file in the form
33 name.xsd the following C++ files are generated: name-pskel.hxx
34 (parser skeleton header file), name-pskel.ixx (parser skeleton
35 inline file, generated only if the --generate-inline option is
36 specified), and name-pskel.cxx (parser skeleton source file). If
37 the --generate-noop-impl or --generate-print-impl option is
38 specified, the following additional sample implementation files
39 are generated: name-pimpl.hxx (parser implementation header
40 file) and name-pimpl.cxx (parser implementation source file). If
41 the --generate-test-driver option is specified, the additional
42 name-driver.cxx test driver file is generated.
43 help Print usage information and exit. Use
46 xsdcxx help command
48 for command-specific help.
50 version
52 Print version and exit.
53
55 Command-specific options, if any, should appear after the corresponding
56 command.
57 common options
60 --std version
61 Specify the C++ standard that the generated code should conform
62 to. Valid values are c++98 (default) and c++11.
63 The C++ standard affects various aspects of the generated code
65 that are discussed in more detail in various mapping-specific
66 documentation. Overall, when C++11 is selected, the generated
67 code relies on the move semantics and uses std::unique_ptr
68 instead of deprecated std::auto_ptr.
69 When the C++11 mode is selected, you normally don't need to per‐
71 form any extra steps other than enable C++11 in your C++ com‐
72 piler, if required. The XSDCXX compiler will automatically add
73 the necessary macro defines to the generated header files that
74 will switch the header-only XSDCXX runtime library (libxsd) to
75 the C++11 mode. However, if you include any of the XSDCXX run‐
76 time headers directly in your application (normally you just
77 include the generated headers), then you will need to define the
78 XSD_CXX11 macro for your entire project.
79 --char-type type
82 Generate code using the provided character type instead of the
83 default char. Valid values are char and wchar_t.
84 --char-encoding enc
87 Specify the character encoding that should be used in the gener‐
88 ated code. Valid values for the char character type are utf8
89 (default), iso8859-1, lcp (Xerces-C++ local code page), and cus‐
90 tom. If you pass custom as the value then you will need to
91 include the transcoder implementation header for your encoding
92 at the beginning of the generated header files (see the --hxx-
93 prologue option).
94 For the wchar_t character type the only valid value is auto and
96 the encoding is automatically selected between UTF-16 and
97 UTF-32/UCS-4, depending on the wchar_t type size.
98 --output-dir dir
101 Write generated files to dir instead of the current directory.
102 --generate-inline
105 Generate simple functions inline. This option triggers creation
106 of the inline file.
107 --generate-xml-schema
110 Generate a C++ header file as if the schema being compiled
111 defines the XML Schema namespace. For the C++/Tree mapping, the
112 resulting file will contain definitions for all XML Schema
113 built-in types. For the C++/Parser mapping, the resulting file
114 will contain definitions for all the parser skeletons and imple‐
115 mentations corresponding to the XML Schema built-in types.
116 The schema file provided to the compiler need not exist and is
118 only used to derive the name of the resulting header file. Use
119 the --extern-xml-schema option to include this file in the gen‐
120 erated files for other schemas.
121 --extern-xml-schema file
124 Include a header file derived from file instead of generating
125 the XML Schema namespace mapping inline. The provided file need
126 not exist and is only used to derive the name of the included
127 header file. Use the --generate-xml-schema option to generate
128 this header file.
129 --namespace-map xns=cns
132 Map XML Schema namespace xns to C++ namespace cns. Repeat this
133 option to specify mapping for more than one XML Schema names‐
134 pace. For example, the following option:
135 --namespace-map http://example.com/foo/bar=foo::bar
137 Will map the http://example.com/foo/bar XML Schema namespace to
139 the foo::bar C++ namespace.
140 --namespace-regex regex
143 Add regex to the list of regular expressions used to translate
144 XML Schema namespace names to C++ namespace names. regex is a
145 Perl-like regular expression in the form /pattern/replacement/.
146 Any character can be used as a delimiter instead of /. Escaping
147 of the delimiter character in pattern or replacement is not sup‐
148 ported.
149 All the regular expressions are pushed into a stack with the
151 last specified expression considered first. The first match that
152 succeeds is used. Regular expressions are applied to a string
153 in the form
154 filename namespace
156 For example, if you have file hello.xsd with namespace
158 http://example.com/hello and you run xsd on this file, then the
159 string in question will be:
160 hello.xsd. http://example.com/hello
162 For the built-in XML Schema namespace the string is:
164 XMLSchema.xsd http://www.w3.org/2001/XMLSchema
166 The following three steps are performed for each regular expres‐
168 sion until the match is found:
169 1. The expression is applied and if the result is empty the next
171 expression is considered.
172 2. All / are replaced with ::.
174 3. The result is verified to be a valid C++ scope name (e.g.,
176 foo::bar). If this test succeeds, the result is used as a C++
177 namespace name.
178 As an example, the following expression maps XML Schema names‐
180 paces in the form http://example.com/foo/bar to C++ namespaces
181 in the form foo::bar:
182 %.* http://example.com/(.+)%$1%
184 See also the REGEX AND SHELL QUOTING section below.
186 --namespace-regex-trace
189 Trace the process of applying regular expressions specified with
190 the --namespace-regex option. Use this option to find out why
191 your regular expressions don't do what you expected them to do.
192 --reserved-name n[=r]
195 Add name n to the list of names that should not be used as iden‐
196 tifiers. The name can optionally be followed by = and the
197 replacement name r that should be used instead. All the C++ key‐
198 words are already in this list.
199 --include-with-brackets
202 Use angle brackets (<>) instead of quotes ("") in generated
203 #include directives.
204 --include-prefix prefix
207 Add prefix to generated #include directive paths.
208 For example, if you had the following import element in your
210 schema
211 <import namespace="..." schemaLocation="base.xsd"/>
213 and compiled this fragment with --include-prefix schemas/, then
215 the include directive in the generated code would be:
216 #include "schemas/base.hxx"
218 --include-regex regex
221 Add regex to the list of regular expressions used to transform
222 #include directive paths. regex is a Perl-like regular expres‐
223 sion in the form /pattern/replacement/. Any character can be
224 used as a delimiter instead of /. Escaping of the delimiter
225 character in pattern or replacement is not supported.
226 All the regular expressions are pushed into a stack with the
228 last specified expression considered first. The first match that
229 succeeds is used.
230 As an example, the following expression transforms paths in the
232 form schemas/foo/bar to paths in the form generated/foo/bar:
233 %schemas/(.+)%generated/$1%
235 See also the REGEX AND SHELL QUOTING section below.
237 --include-regex-trace
240 Trace the process of applying regular expressions specified with
241 the --include-regex option. Use this option to find out why your
242 regular expressions don't do what you expected them to do.
243 --guard-prefix prefix
246 Add prefix to generated header inclusion guards. The prefix is
247 transformed to upper case and characters that are illegal in a
248 preprocessor macro name are replaced with underscores. If this
249 option is not specified then the directory part of the input
250 schema file is used as a prefix.
251 --hxx-suffix suffix
254 Use the provided suffix instead of the default .hxx to construct
255 the name of the header file. Note that this suffix is also used
256 to construct names of header files corresponding to
257 included/imported schemas.
258 --ixx-suffix suffix
261 Use the provided suffix instead of the default .ixx to construct
262 the name of the inline file.
263 --cxx-suffix suffix
266 Use the provided suffix instead of the default .cxx to construct
267 the name of the source file.
268 --fwd-suffix suffix
271 Use the provided suffix instead of the default -fwd.hxx to con‐
272 struct the name of the forward declaration file.
273 --hxx-regex regex
276 Use the provided expression to construct the name of the header
277 file. regex is a Perl-like regular expression in the form /pat‐
278 tern/replacement/. Note that this expression is also used to
279 construct names of header files corresponding to
280 included/imported schemas. See also the REGEX AND SHELL QUOTING
281 section below.
282 --ixx-regex regex
285 Use the provided expression to construct the name of the inline
286 file. regex is a Perl-like regular expression in the form /pat‐
287 tern/replacement/. See also the REGEX AND SHELL QUOTING section
288 below.
289 --cxx-regex regex
292 Use the provided expression to construct the name of the source
293 file. regex is a Perl-like regular expression in the form /pat‐
294 tern/replacement/. See also the REGEX AND SHELL QUOTING section
295 below.
296 --fwd-regex regex
299 Use the provided expression to construct the name of the forward
300 declaration file. regex is a Perl-like regular expression in the
301 form /pattern/replacement/. See also the REGEX AND SHELL QUOTING
302 section below.
303 --hxx-prologue text
306 Insert text at the beginning of the header file.
307 --ixx-prologue text
310 Insert text at the beginning of the inline file.
311 --cxx-prologue text
314 Insert text at the beginning of the source file.
315 --fwd-prologue text
318 Insert text at the beginning of the forward declaration file.
319 --prologue text
322 Insert text at the beginning of each generated file for which
323 there is no file-specific prologue.
324 --hxx-epilogue text
327 Insert text at the end of the header file.
328 --ixx-epilogue text
331 Insert text at the end of the inline file.
332 --cxx-epilogue text
335 Insert text at the end of the source file.
336 --fwd-epilogue text
339 Insert text at the end of the forward declaration file.
340 --epilogue text
343 Insert text at the end of each generated file for which there is
344 no file-specific epilogue.
345 --hxx-prologue-file file
348 Insert the content of the file at the beginning of the header
349 file.
350 --ixx-prologue-file file
353 Insert the content of the file at the beginning of the inline
354 file.
355 --cxx-prologue-file file
358 Insert the content of the file at the beginning of the source
359 file.
360 --fwd-prologue-file file
363 Insert the content of the file at the beginning of the forward
364 declaration file.
365 --prologue-file file
368 Insert the content of the file at the beginning of each gener‐
369 ated file for which there is no file-specific prologue file.
370 --hxx-epilogue-file file
373 Insert the content of the file at the end of the header file.
374 --ixx-epilogue-file file
377 Insert the content of the file at the end of the inline file.
378 --cxx-epilogue-file file
381 Insert the content of the file at the end of the source file.
382 --fwd-epilogue-file file
385 Insert the content of the file at the end of the forward decla‐
386 ration file.
387 --epilogue-file file
390 Insert the content of the file at the end of each generated file
391 for which there is no file-specific epilogue file.
392 --export-symbol symbol
395 Insert symbol in places where DLL export/import control state‐
396 ments (__declspec(dllexport/dllimport)) are necessary.
397 --export-xml-schema
400 Export/import types in the XML Schema namespace using the export
401 symbol provided with the --export-symbol option. The
402 XSD_NO_EXPORT macro can be used to omit this code during C++
403 compilation, which may be useful if you would like to use the
404 same generated code across multiple platforms.
405 --export-maps
408 Export polymorphism support maps from a Win32 DLL into which
409 this generated code is placed. This is necessary when your type
410 hierarchy is split across several DLLs since otherwise each DLL
411 will have its own set of maps. In this situation the generated
412 code for the DLL which contains base types and/or substitution
413 group heads should be compiled with this option and the gener‐
414 ated code for all other DLLs should be compiled with --import-
415 maps. This option is only valid together with --generate-poly‐
416 morphic. The XSD_NO_EXPORT macro can be used to omit this code
417 during C++ compilation, which may be useful if you would like to
418 use the same generated code across multiple platforms.
419 --import-maps
422 Import polymorphism support maps to a Win32 DLL or executable
423 into which this generated code is linked. See the --export-maps
424 option documentation for details. This options is only valid
425 together with --generate-polymorphic. The XSD_NO_EXPORT macro
426 can be used to omit this code during C++ compilation, which may
427 be useful if you would like to use the same generated code
428 across multiple platforms.
429 --generate-dep
432 Generate make dependency information. This option triggers the
433 creation of the .d file containing the dependencies of the gen‐
434 erated files on the main schema file as well as all the schema
435 files that it includes/imports, transitively. This dependency
436 file is then normally included into the main makefile to imple‐
437 ment automatic dependency tracking.
438 Note also that automatic dependency generation is not supported
440 in the file-per-type mode (--file-per-type). In this case, all
441 the generated files are produced with a single compiler invoca‐
442 tion and depend on all the schemas. As a result, it is easier to
443 establish such a dependency manually, perhaps with the help of
444 the --file-list* options.
445 --generate-dep-only
448 Generate make dependency information only.
449 --dep-phony
452 Generate phony targets for included/imported schema files, caus‐
453 ing each to depend on nothing. Such dummy rules work around make
454 errors caused by the removal of schema files without also updat‐
455 ing the dependency file to match.
456 --dep-target target
459 Change the target of the dependency rule. By default it contains
460 all the generated C++ files as well as the dependency file
461 itself, without any directory prefixes. If you require multiple
462 targets, then you can specify them as a single, space-separated
463 argument or you can repeat this option multiple times.
464 --dep-suffix suffix
467 Use the provided suffix instead of the default .d to construct
468 the name of the dependency file.
469 --dep-regex regex
472 Use the provided expression to construct the name of the depen‐
473 dency file. regex is a Perl-like regular expression in the form
474 /pattern/replacement/. See also the REGEX AND SHELL QUOTING sec‐
475 tion below.
476 --disable-warning warn
479 Disable printing warning with id warn. If all is specified for
480 the warning id then all warnings are disabled.
481 --options-file file
484 Read additional options from file. Each option should appearing
485 on a separate line optionally followed by space and an option
486 value. Empty lines and lines starting with # are ignored. Option
487 values can be enclosed in double (") or single (') quotes to
488 preserve leading and trailing whitespaces as well as to specify
489 empty values. If the value itself contains trailing or leading
490 quotes, enclose it with an extra pair of quotes, for example
491 '"x"'. Non-leading and non-trailing quotes are interpreted as
492 being part of the option value.
493 The semantics of providing options in a file is equivalent to
495 providing the same set of options in the same order on the com‐
496 mand line at the point where the --options-file option is speci‐
497 fied except that the shell escaping and quoting is not required.
498 You can repeat this option to specify more than one options
499 file.
500 --show-sloc
503 Show the number of generated physical source lines of code
504 (SLOC).
505 --sloc-limit num
508 Check that the number of generated physical source lines of code
509 (SLOC) does not exceed num.
510 --proprietary-license
513 Indicate that the generated code is licensed under a proprietary
514 license instead of the GPL.
515 --custom-literals file
518 Load custom XML string to C++ literal mappings from file. This
519 mechanism can be useful if you are using a custom character
520 encoding and some of the strings in your schemas, for example
521 element/attribute names or enumeration values, contain non-ASCII
522 characters. In this case you will need to provide a custom map‐
523 ping to C++ literals for such strings. The format of this file
524 is specified in the custom-literals.xsd XML Schema file that can
525 be found in the documentation directory.
526 --preserve-anonymous
529 Preserve anonymous types. By default anonymous types are auto‐
530 matically named with names derived from the enclosing ele‐
531 ments/attributes. Because mappings implemented by this compiler
532 require all types to be named, this option is only useful if you
533 want to make sure your schemas don't have anonymous types.
534 --show-anonymous
537 Show elements and attributes that are of anonymous types. This
538 option only makes sense together with the --preserve-anonymous
539 option.
540 --anonymous-regex regex
543 Add regex to the list of regular expressions used to derive
544 names for anonymous types from the enclosing attributes/ele‐
545 ments. regex is a Perl-like regular expression in the form /pat‐
546 tern/replacement/. Any character can be used as a delimiter
547 instead of /. Escaping of the delimiter character in pattern or
548 replacement is not supported.
549 All the regular expressions are pushed into a stack with the
551 last specified expression considered first. The first match that
552 succeeds is used. Regular expressions are applied to a string
553 in the form
554 filename namespace xpath
556 For instance:
558 hello.xsd http://example.com/hello element
560 hello.xsd http://example.com/hello type/element
562 As an example, the following expression makes all the derived
564 names start with capital letters. This could be useful when your
565 naming convention requires type names to start with capital let‐
566 ters:
567 %.* .* (.+/)*(.+)%\u$2%
569 See also the REGEX AND SHELL QUOTING section below.
571 --anonymous-regex-trace
574 Trace the process of applying regular expressions specified with
575 the --anonymous-regex option. Use this option to find out why
576 your regular expressions don't do what you expected them to do.
577 --location-map ol=nl
580 Map the original schema location ol that is specified in the XML
581 Schema include or import elements to new schema location nl.
582 Repeat this option to map more than one schema location. For
583 example, the following option maps the http://exam‐
584 ple.com/foo.xsd URL to the foo.xsd local file.
585 --location-map http://example.com/foo.xsd=foo.xsd
587 --location-regex regex
590 Add regex to the list of regular expressions used to map schema
591 locations that are specified in the XML Schema include or import
592 elements. regex is a Perl-like regular expression in the form
593 /pattern/replacement/. Any character can be used as a delimiter
594 instead of /. Escaping of the delimiter character in pattern or
595 replacement is not supported. All the regular expressions are
596 pushed into a stack with the last specified expression consid‐
597 ered first. The first match that succeeds is used.
598 For example, the following expression maps URL locations in the
600 form http://example.com/foo/bar.xsd to local files in the form
601 bar.xsd:
602 %http://.+/(.+)%$1%
604 See also the REGEX AND SHELL QUOTING section below.
606 --location-regex-trace
609 Trace the process of applying regular expressions specified with
610 the --location-regex option. Use this option to find out why
611 your regular expressions don't do what you expected them to do.
612 --file-per-type
615 Generate a separate set of C++ files for each type defined in
616 XML Schema. Note that in this mode you only need to compile the
617 root schema(s) and the code will be generated for all included
618 and imported schemas. This compilation mode is primarily useful
619 when some of your schemas cannot be compiled separately or have
620 cyclic dependencies which involve type inheritance. Other
621 options related to this mode are: --type-file-regex, --schema-
622 file-regex, --fat-type-file, and --file-list.
623 --type-file-regex regex
626 Add regex to the list of regular expressions used to translate
627 type names to file names when the --file-per-type option is
628 specified. regex is a Perl-like regular expression in the form
629 /pattern/replacement/. Any character can be used as a delimiter
630 instead of /. Escaping of the delimiter character in pattern or
631 replacement is not supported. All the regular expressions are
632 pushed into a stack with the last specified expression consid‐
633 ered first. The first match that succeeds is used. Regular
634 expressions are applied to a string in the form
635 namespace type-name
637 For example, the following expression maps type foo that is
639 defined in the http://example.com/bar namespace to file name
640 bar-foo:
641 %http://example.com/(.+) (.+)%$1-$2%
643 See also the REGEX AND SHELL QUOTING section below.
645 --type-file-regex-trace
648 Trace the process of applying regular expressions specified with
649 the --type-file-regex option. Use this option to find out why
650 your regular expressions don't do what you expected them to do.
651 --schema-file-regex regex
654 Add regex to the list of regular expressions used to translate
655 schema file names when the --file-per-type option is specified.
656 regex is a Perl-like regular expression in the form /pat‐
657 tern/replacement/. Any character can be used as a delimiter
658 instead of /. Escaping of the delimiter character in pattern or
659 replacement is not supported. All the regular expressions are
660 pushed into a stack with the last specified expression consid‐
661 ered first. The first match that succeeds is used. Regular
662 Expressions are applied to the absolute filesystem path of a
663 schema file and the result, including the directory part, if
664 any, is used to derive the #include directive paths as well as
665 the generated C++ file paths. This option, along with --type-
666 file-regex are primarily useful to place the generated files
667 into subdirectories or to resolve file name conflicts.
668 For example, the following expression maps schema files in the
670 foo/1.0.0/ subdirectory to the files in the foo/ subdirectory.
671 As a result, the #include directive paths for such schemas will
672 be in the foo/schema.hxx form and the generated C++ files will
673 be placed into the foo/ subdirectory:
674 %.*/foo/1.0.0/(.+)%foo/$1%
676 See also the REGEX AND SHELL QUOTING section below.
678 --schema-file-regex-trace
681 Trace the process of applying regular expressions specified with
682 the --schema-file-regex option. Use this option to find out why
683 your regular expressions don't do what you expected them to do.
684 --fat-type-file
687 Generate code corresponding to global elements into type files
688 instead of schema files when the --type-file-regex option is
689 specified. This option is primarily useful when trying to mini‐
690 mize the amount of object code that is linked to an executable
691 by packaging compiled generated code into a static (archive)
692 library.
693 --file-list file
696 Write a list of generated C++ files to file. This option is pri‐
697 marily useful in the file-per-type compilation mode (--file-per-
698 type) to create a list of generated C++ files, for example, as a
699 makefile fragment.
700 --file-list-prologue text
703 Insert text at the beginning of the file list. As a convenience,
704 all occurrences of the \n character sequence in text are
705 replaced with new lines. This option can, for example, be used
706 to assign the generated file list to a makefile variable.
707 --file-list-epilogue text
710 Insert text at the end of the file list. As a convenience, all
711 occurrences of the \n character sequence in text are replaced
712 with new lines.
713 --file-list-delim text
716 Delimit file names written to the file list with text instead of
717 new lines. As a convenience, all occurrences of the \n character
718 sequence in text are replaced with new lines.
719 cxx-tree command options
722 --generate-polymorphic
723 Generate polymorphism-aware code. Specify this option if you use
724 substitution groups or xsi:type. Use the --polymorphic-type or
725 --polymorphic-type-all option to specify which type hierarchies
726 are polymorphic.
727 --polymorphic-type type
730 Indicate that type is a root of a polymorphic type hierarchy.
731 The compiler can often automatically determine which types are
732 polymorphic based on the substitution group declarations. How‐
733 ever, you may need to use this option if you are not using sub‐
734 stitution groups or if substitution groups are defined in
735 another schema. You need to specify this option when compiling
736 every schema file that references type. The type argument is an
737 XML Schema type name that can be optionally qualified with a
738 namespace in the namespace#name form.
739 --polymorphic-type-all
742 Indicate that all types should be treated as polymorphic.
743 --polymorphic-plate num
746 Specify the polymorphic map plate the generated code should reg‐
747 ister on. This functionality is primarily useful to segregate
748 multiple schemas that define the same polymorphic types.
749 --ordered-type type
752 Indicate that element order in type is significant. An example
753 would be a complex type with unbounded choice as a content model
754 where the element order in XML has application-specific seman‐
755 tics. For ordered types the compiler generates a special con‐
756 tainer data member and a corresponding set of accessors and mod‐
757 ifiers that are used to capture the order of elements and, for
758 mixed content, of text.
759 The type argument is an XML Schema type name that can be option‐
761 ally qualified with a namespace in the namespace#name form.
762 Note also that you will need to specify this option when compil‐
763 ing every schema file that has other ordered types derived from
764 this type.
765 --ordered-type-derived
768 Automatically treat types derived from ordered bases as also
769 ordered. This is primarily useful if you would like to be able
770 to iterate over the complete content using the content order
771 container.
772 --ordered-type-mixed
775 Automatically treat complex types with mixed content as ordered.
776 --ordered-type-all
779 Indicate that element order in all types is significant.
780 --order-container type
783 Specify a custom class template that should be used as a con‐
784 tainer for the content order in ordered types instead of the
785 default std::vector. See --ordered-type for more information on
786 ordered type. This option is primarily useful if you need to
787 perform more complex lookups in the content order container, for
788 example by element id. In this case, a container like Boost
789 multi-index may be more convenient. Note that if using a custom
790 container, you will also most likely need to include the rele‐
791 vant headers using the --hxx-prologue* options.
792 --generate-serialization
795 Generate serialization functions. Serialization functions con‐
796 vert the object model back to XML.
797 --generate-ostream
800 Generate ostream insertion operators (operator<<) for generated
801 types. This allows one to easily print a fragment or the whole
802 object model for debugging or logging.
803 --generate-doxygen
806 Generate documentation comments suitable for extraction by the
807 Doxygen documentation system. Documentation from annotations is
808 added to the comments if present in the schema.
809 --generate-comparison
812 Generate comparison operators (operator== and operator!=) for
813 complex types. Comparison is performed member-wise.
814 --generate-default-ctor
817 Generate default constructors even for types that have required
818 members. Required members of an instance constructed using such
819 a constructor are not initialized and accessing them results in
820 undefined behavior.
821 --generate-from-base-ctor
824 Generate constructors that expect an instance of a base type
825 followed by all required members.
826 --suppress-assignment
829 Suppress the generation of copy assignment operators for complex
830 types. If this option is specified, the copy assignment opera‐
831 tors for such types are declared private and left unimplemented.
832 --generate-detach
835 Generate detach functions for required elements and attributes.
836 Detach functions for optional and sequence cardinalities are
837 provided by the respective containers. These functions, for
838 example, allow you to move sub-trees in the object model either
839 within the same tree or between different trees.
840 --generate-wildcard
843 Generate accessors and modifiers as well as parsing and serial‐
844 ization code for XML Schema wildcards (any and anyAttribute).
845 XML content matched by wildcards is presented as DOM fragments.
846 Note that you need to initialize the Xerces-C++ runtime if you
847 are using this option.
848 --generate-any-type
851 Extract and store content of the XML Schema anyType type as a
852 DOM fragment. Note that you need to initialize the Xerces-C++
853 runtime if you are using this option.
854 --generate-insertion os
857 Generate data representation stream insertion operators for the
858 os output stream type. Repeat this option to specify more than
859 one stream type. The ACE CDR stream (ACE_OutputCDR) and RPC XDR
860 are recognized by the compiler and the necessary #include direc‐
861 tives are automatically generated. For custom stream types use
862 the --hxx-prologue* options to provide the necessary declara‐
863 tions.
864 --generate-extraction is
867 Generate data representation stream extraction constructors for
868 the is input stream type. Repeat this option to specify more
869 than one stream type. The ACE CDR stream (ACE_InputCDR) and RPC
870 XDR are recognized by the compiler and the necessary #include
871 directives are automatically generated. For custom stream types
872 use the --hxx-prologue* options to provide the necessary decla‐
873 rations.
874 --generate-forward
877 Generate a separate header file with forward declarations for
878 the types being generated.
879 --suppress-parsing
882 Suppress the generation of the parsing functions and construc‐
883 tors. Use this option to reduce the generated code size when
884 parsing from XML is not needed.
885 --generate-element-type
888 Generate types instead of parsing and serialization functions
889 for root elements. This is primarily useful to distinguish
890 object models with the same root type but with different root
891 elements.
892 --generate-element-map
895 Generate a root element map that allows uniform parsing and
896 serialization of multiple root elements. This option is only
897 valid together with --generate-element-type.
898 --generate-intellisense
901 Generate workarounds for IntelliSense bugs in Visual Studio 2005
902 (8.0). When this option is used, the resulting code is slightly
903 more verbose. IntelliSense in Visual Studio 2008 (9.0) and
904 later does not require these workarounds. Support for Intel‐
905 liSense in Visual Studio 2003 (7.1) is improved with this option
906 but is still incomplete.
907 --omit-default-attributes
910 Omit attributes with default and fixed values from serialized
911 XML documents.
912 --type-naming style
915 Specify the type naming convention that should be used in the
916 generated code. Valid styles are knr (default), ucc, and java.
917 See the NAMING CONVENTION section below for more information.
918 --function-naming style
921 Specify the function naming convention that should be used in
922 the generated code. Valid styles are knr (default), lcc, and
923 java. See the NAMING CONVENTION section below for more informa‐
924 tion.
925 --type-regex regex
928 Add regex to the list of regular expressions used to translate
929 XML Schema type names to C++ type names. See the NAMING CONVEN‐
930 TION section below for more information.
931 --accessor-regex regex
934 Add regex to the list of regular expressions used to translate
935 XML Schema names of elements/attributes to C++ accessor function
936 names. See the NAMING CONVENTION section below for more informa‐
937 tion.
938 --one-accessor-regex regex
941 Add regex to the list of regular expressions used to translate
942 XML Schema names of elements/attributes with cardinality one to
943 C++ accessor function names. See the NAMING CONVENTION section
944 below for more information.
945 --opt-accessor-regex regex
948 Add regex to the list of regular expressions used to translate
949 XML Schema names of elements/attributes with cardinality
950 optional to C++ accessor function names. See the NAMING CONVEN‐
951 TION section below for more information.
952 --seq-accessor-regex regex
955 Add regex to the list of regular expressions used to translate
956 XML Schema names of elements/attributes with cardinality
957 sequence to C++ accessor function names. See the NAMING CONVEN‐
958 TION section below for more information.
959 --modifier-regex regex
962 Add regex to the list of regular expressions used to translate
963 XML Schema names of elements/attributes to C++ modifier function
964 names. See the NAMING CONVENTION section below for more informa‐
965 tion.
966 --one-modifier-regex regex
969 Add regex to the list of regular expressions used to translate
970 XML Schema names of elements/attributes with cardinality one to
971 C++ modifier function names. See the NAMING CONVENTION section
972 below for more information.
973 --opt-modifier-regex regex
976 Add regex to the list of regular expressions used to translate
977 XML Schema names of elements/attributes with cardinality
978 optional to C++ modifier function names. See the NAMING CONVEN‐
979 TION section below for more information.
980 --seq-modifier-regex regex
983 Add regex to the list of regular expressions used to translate
984 XML Schema names of elements/attributes with cardinality
985 sequence to C++ modifier function names. See the NAMING CONVEN‐
986 TION section below for more information.
987 --parser-regex regex
990 Add regex to the list of regular expressions used to translate
991 XML Schema element names to C++ parsing function names. See the
992 NAMING CONVENTION section below for more information.
993 --serializer-regex regex
996 Add regex to the list of regular expressions used to translate
997 XML Schema element names to C++ serialization function names.
998 See the NAMING CONVENTION section below for more information.
999 --const-regex regex
1002 Add regex to the list of regular expressions used to translate
1003 XML Schema-derived names to C++ constant names. See the NAMING
1004 CONVENTION section below for more information.
1005 --enumerator-regex regex
1008 Add regex to the list of regular expressions used to translate
1009 XML Schema enumeration values to C++ enumerator names. See the
1010 NAMING CONVENTION section below for more information.
1011 --element-type-regex regex
1014 Add regex to the list of regular expressions used to translate
1015 XML Schema element names to C++ element type names. See the NAM‐
1016 ING CONVENTION section below for more information.
1017 --name-regex-trace
1020 Trace the process of applying regular expressions specified with
1021 the name transformation options. Use this option to find out why
1022 your regular expressions don't do what you expected them to do.
1023 --root-element-first
1026 Treat only the first global element as a document root. By
1027 default all global elements are considered document roots.
1028 --root-element-last
1031 Treat only the last global element as a document root. By
1032 default all global elements are considered document roots.
1033 --root-element-all
1036 Treat all global elements as document roots. This is the default
1037 behavior. By explicitly specifying this option you can suppress
1038 the warning that is issued if more than one global element is
1039 defined.
1040 --root-element-none
1043 Do not treat any global elements as document roots. By default
1044 all global elements are considered document roots.
1045 --root-element element
1048 Treat only element as a document root. Repeat this option to
1049 specify more than one root element.
1050 --custom-type map
1053 Use a custom C++ type instead of the generated class. The map
1054 argument is in the form name[=type[/base]], where name is a type
1055 name as defined in XML Schema and type is a C++ type name that
1056 should be used instead. If type is not present or empty then the
1057 custom type is assumed to have the same name and be defined in
1058 the same namespace as the generated class would have. If base is
1059 specified then the generated class is still generated but with
1060 that name.
1061 --custom-type-regex regex
1064 Use custom C++ types instead of the generated classes. The regex
1065 argument is in the form /name-pat/[type-sub/[base-sub/]], where
1066 name-pat is a regex pattern that will be matched against type
1067 names as defined in XML Schema and type-sub is a C++ type name
1068 substitution that should be used instead. If type-sub is not
1069 present or its substitution results in an empty string then the
1070 custom type is assumed to have the same name and be defined in
1071 the same namespace as the generated class would have. If base-
1072 sub is present and its substitution results in a non-empty
1073 string then the generated class is still generated but with the
1074 result of this substitution as its name. The pattern and substi‐
1075 tutions are in the Perl regular expression format. See also the
1076 REGEX AND SHELL QUOTING section below.
1077 --parts num
1080 Split generated source code into num parts. This is useful when
1081 translating large, monolithic schemas and a C++ compiler is not
1082 able to compile the resulting source code at once (usually due
1083 to insufficient memory).
1084 --parts-suffix suffix
1087 Use suffix instead of the default '-' to separate the file name
1088 from the part number.
1089 cxx-parser command options
1095 --type-map mapfile
1096 Read XML Schema to C++ type mapping information from mapfile.
1097 Repeat this option to specify several type maps. Type maps are
1098 considered in order of appearance and the first match is used.
1099 By default all user-defined types are mapped to void. See the
1100 TYPE MAP section below for more information.
1101 --xml-parser parser
1104 Use parser as the underlying XML parser. Valid values are xerces
1105 for Xerces-C++ (default) and expat for Expat.
1106 --generate-validation
1109 Generate validation code. The validation code ("perfect parser")
1110 ensures that instance documents conform to the schema. Valida‐
1111 tion code is generated by default when the selected underlying
1112 XML parser is non-validating (expat).
1113 --suppress-validation
1116 Suppress the generation of validation code. Validation is sup‐
1117 pressed by default when the selected underlying XML parser is
1118 validating (xerces).
1119 --generate-polymorphic
1122 Generate polymorphism-aware code. Specify this option if you use
1123 substitution groups or xsi:type.
1124 --generate-noop-impl
1127 Generate a sample parser implementation that does nothing (no
1128 operation). The sample implementation can then be filled with
1129 the application-specific code. For an input file in the form
1130 name.xsd this option triggers the generation of two additional
1131 C++ files in the form: name-pimpl.hxx (parser implementation
1132 header file) and name-pimpl.cxx (parser implementation source
1133 file).
1134 --generate-print-impl
1137 Generate a sample parser implementation that prints the XML data
1138 to STDOUT. For an input file in the form name.xsd this option
1139 triggers the generation of two additional C++ files in the form:
1140 name-pimpl.hxx (parser implementation header file) and name-
1141 pimpl.cxx (parser implementation source file).
1142 --generate-test-driver
1145 Generate a test driver for the sample parser implementation. For
1146 an input file in the form name.xsd this option triggers the gen‐
1147 eration of an additional C++ file in the form name-driver.cxx.
1148 --force-overwrite
1151 Force overwriting of the existing implementation and test driver
1152 files. Use this option only if you do not mind loosing the
1153 changes you have made in the sample implementation or test
1154 driver files.
1155 --root-element-first
1158 Indicate that the first global element is the document root.
1159 This information is used to generate the test driver for the
1160 sample implementation.
1161 --root-element-last
1164 Indicate that the last global element is the document root. This
1165 information is used to generate the test driver for the sample
1166 implementation.
1167 --root-element element
1170 Indicate that element is the document root. This information is
1171 used to generate the test driver for the sample implementation.
1172 --skel-type-suffix suffix
1175 Use the provided suffix instead of the default _pskel to con‐
1176 struct the names of the generated parser skeletons.
1177 --skel-file-suffix suffix
1180 Use the provided suffix instead of the default -pskel to con‐
1181 struct the names of the generated parser skeleton files.
1182 --impl-type-suffix suffix
1185 Use the provided suffix instead of the default _pimpl to con‐
1186 struct the names of the parser implementations for the built-in
1187 XML Schema types as well as sample parser implementations.
1188 --impl-file-suffix suffix
1191 Use the provided suffix instead of the default -pimpl to con‐
1192 struct the names of the generated sample parser implementation
1193 files.
1194
1201 The compiler can be instructed to use a particular naming convention in
1202 the generated code. A number of widely-used conventions can be selected
1203 using the --type-naming and --function-naming options. A custom naming
1204 convention can be achieved using the --type-regex, --accessor-regex,
1205 --one-accessor-regex, --opt-accessor-regex, --seq-accessor-regex,
1206 --modifier-regex, --one-modifier-regex, --opt-modifier-regex, --seq-
1207 modifier-regex, --parser-regex, --serializer-regex, --const-regex,
1208 --enumerator-regex, and --element-type-regex options.
1209 The --type-naming option specifies the convention that should be used
1211 for naming C++ types. Possible values for this option are knr
1212 (default), ucc, and java. The knr value (stands for K&R) signifies the
1213 standard, lower-case naming convention with the underscore used as a
1214 word delimiter, for example: foo, foo_bar. The ucc (stands for upper-
1215 camel-case) and java values a synonyms for the same naming convention
1216 where the first letter of each word in the name is capitalized, for
1217 example: Foo, FooBar.
1218 Similarly, the --function-naming option specifies the convention that
1220 should be used for naming C++ functions. Possible values for this
1221 option are knr (default), lcc, and java. The knr value (stands for
1222 K&R) signifies the standard, lower-case naming convention with the
1223 underscore used as a word delimiter, for example: foo(), foo_bar().
1224 The lcc value (stands for lower-camel-case) signifies a naming conven‐
1225 tion where the first letter of each word except the first is capital‐
1226 ized, for example: foo(), fooBar(). The java naming convention is simi‐
1227 lar to the lower-camel-case one except that accessor functions are pre‐
1228 fixed with get, modifier functions are prefixed with set, parsing func‐
1229 tions are prefixed with parse, and serialization functions are prefixed
1230 with serialize, for example: getFoo(), setFooBar(), parseRoot(), seri‐
1231 alizeRoot().
1232 Note that the naming conventions specified with the --type-naming and
1234 --function-naming options perform only limited transformations on the
1235 names that come from the schema in the form of type, attribute, and
1236 element names. In other words, to get consistent results, your schemas
1237 should follow a similar naming convention as the one you would like to
1238 have in the generated code. Alternatively, you can use the --*-regex
1239 options (discussed below) to perform further transformations on the
1240 names that come from the schema.
1241 The --type-regex, --accessor-regex, --one-accessor-regex, --opt-acces‐
1243 sor-regex, --seq-accessor-regex, --modifier-regex, --one-modifier-
1244 regex, --opt-modifier-regex, --seq-modifier-regex, --parser-regex,
1245 --serializer-regex, --const-regex, --enumerator-regex, and --element-
1246 type-regex options allow you to specify extra regular expressions for
1247 each name category in addition to the predefined set that is added
1248 depending on the --type-naming and --function-naming options. Expres‐
1249 sions that are provided with the --*-regex options are evaluated prior
1250 to any predefined expressions. This allows you to selectively override
1251 some or all of the predefined transformations. When debugging your own
1252 expressions, it is often useful to see which expressions match which
1253 names. The --name-regex-trace option allows you to trace the process of
1254 applying regular expressions to names.
1255 The value for the --*-regex options should be a perl-like regular
1257 expression in the form /pattern/replacement/. Any character can be
1258 used as a delimiter instead of /. Escaping of the delimiter character
1259 in pattern or replacement is not supported. All the regular expressions
1260 for each category are pushed into a category-specific stack with the
1261 last specified expression considered first. The first match that suc‐
1262 ceeds is used. For the --one-accessor-regex (accessors with cardinality
1263 one), --opt-accessor-regex (accessors with cardinality optional), and
1264 --seq-accessor-regex (accessors with cardinality sequence) categories
1265 the --accessor-regex expressions are used as a fallback. For the --one-
1266 modifier-regex, --opt-modifier-regex, and --seq-modifier-regex cate‐
1267 gories the --modifier-regex expressions are used as a fallback. For the
1268 --element-type-regex category the --type-regex expressions are used as
1269 a fallback.
1270 The type name expressions (--type-regex) are evaluated on the name
1272 string that has the following format:
1273 [namespace ]name[,name][,name][,name]
1275 The element type name expressions (--element-type-regex), effective
1277 only when the --generate-element-type option is specified, are evalu‐
1278 ated on the name string that has the following format:
1279 namespace name
1281 In the type name format the namespace part followed by a space is only
1283 present for global type names. For global types and elements defined in
1284 schemas without a target namespace, the namespace part is empty but the
1285 space is still present. In the type name format after the initial name
1286 component, up to three additional name components can be present, sepa‐
1287 rated by commas. For example:
1288 http://example.com/hello type
1290 foo
1292 foo,iterator
1294 foo,const,iterator
1296 The following set of predefined regular expressions is used to trans‐
1298 form type names when the upper-camel-case naming convention is
1299 selected:
1300 /(?:[^ ]* )?([^,]+)/\u$1/
1302 /(?:[^ ]* )?([^,]+),([^,]+)/\u$1\u$2/
1304 /(?:[^ ]* )?([^,]+),([^,]+),([^,]+)/\u$1\u$2\u$3/
1306 /(?:[^ ]* )?([^,]+),([^,]+),([^,]+),([^,]+)/\u$1\u$2\u$3\u$4/
1308 The accessor and modifier expressions (--*accessor-regex and --*modi‐
1310 fier-regex) are evaluated on the name string that has the following
1311 format:
1312 name[,name][,name]
1314 After the initial name component, up to two additional name components
1316 can be present, separated by commas. For example:
1317 foo
1319 dom,document
1321 foo,default,value
1323 The following set of predefined regular expressions is used to trans‐
1325 form accessor names when the java naming convention is selected:
1326 /([^,]+)/get\u$1/
1328 /([^,]+),([^,]+)/get\u$1\u$2/
1330 /([^,]+),([^,]+),([^,]+)/get\u$1\u$2\u$3/
1332 For the parser, serializer, and enumerator categories, the correspond‐
1334 ing regular expressions are evaluated on local names of elements and on
1335 enumeration values, respectively. For example, the following predefined
1336 regular expression is used to transform parsing function names when the
1337 java naming convention is selected:
1338 /(.+)/parse\u$1/
1340 The const category is used to create C++ constant names for the ele‐
1342 ment/wildcard/text content ids in ordered types.
1343 See also the REGEX AND SHELL QUOTING section below.
1345
1351 Type map files are used in C++/Parser to define a mapping between XML
1352 Schema and C++ types. The compiler uses this information to determine
1353 the return types of post_* functions in parser skeletons corresponding
1354 to XML Schema types as well as argument types for callbacks correspond‐
1355 ing to elements and attributes of these types.
1356 The compiler has a set of predefined mapping rules that map built-in
1358 XML Schema types to suitable C++ types (discussed below) and all other
1359 types to void. By providing your own type maps you can override these
1360 predefined rules. The format of the type map file is presented below:
1361 namespace schema-namespace [ cxx-namespace ]
1363 {
1364 ( include file-name; )*
1365 ([ type ] schema-type cxx-ret-type [ cxx-arg-type ]; )*
1366 }
1367 Both schema-namespace and schema-type are regex patterns while cxx-
1369 namespace, cxx-ret-type, and cxx-arg-type are regex pattern substitu‐
1370 tions. All names can be optionally enclosed in " ", for example, to
1371 include white-spaces.
1372 schema-namespace determines XML Schema namespace. Optional cxx-names‐
1374 pace is prefixed to every C++ type name in this namespace declaration.
1375 cxx-ret-type is a C++ type name that is used as a return type for the
1376 post_* functions. Optional cxx-arg-type is an argument type for call‐
1377 back functions corresponding to elements and attributes of this type.
1378 If cxx-arg-type is not specified, it defaults to cxx-ret-type if cxx-
1379 ret-type ends with * or & (that is, it is a pointer or a reference) and
1380 const cxx-ret-type& otherwise. file-name is a file name either in the
1381 " " or < > format and is added with the #include directive to the gen‐
1382 erated code.
1383 The # character starts a comment that ends with a new line or end of
1385 file. To specify a name that contains # enclose it in " ". For example:
1386 namespace http://www.example.com/xmlns/my my
1388 {
1389 include "my.hxx";
1390 # Pass apples by value.
1392 #
1393 apple apple;
1394 # Pass oranges as pointers.
1396 #
1397 orange orange_t*;
1398 }
1399 In the example above, for the http://www.example.com/xmlns/my#orange
1401 XML Schema type, the my::orange_t* C++ type will be used as both return
1402 and argument types.
1403 Several namespace declarations can be specified in a single file. The
1405 namespace declaration can also be completely omitted to map types in a
1406 schema without a namespace. For instance:
1407 include "my.hxx";
1409 apple apple;
1410 namespace http://www.example.com/xmlns/my
1412 {
1413 orange "const orange_t*";
1414 }
1415 The compiler has a number of predefined mapping rules that can be pre‐
1418 sented as the following map files. The string-based XML Schema built-in
1419 types are mapped to either std::string or std::wstring depending on the
1420 character type selected with the --char-type option (char by default).
1421 namespace http://www.w3.org/2001/XMLSchema
1423 {
1424 boolean bool bool;
1425 byte "signed char" "signed char";
1427 unsignedByte "unsigned char" "unsigned char";
1428 short short short;
1430 unsignedShort "unsigned short" "unsigned short";
1431 int int int;
1433 unsignedInt "unsigned int" "unsigned int";
1434 long "long long" "long long";
1436 unsignedLong "unsigned long long" "unsigned long long";
1437 integer "long long" "long long";
1439 negativeInteger "long long" "long long";
1441 nonPositiveInteger "long long" "long long";
1442 positiveInteger "unsigned long long" "unsigned long long";
1444 nonNegativeInteger "unsigned long long" "unsigned long long";
1445 float float float;
1447 double double double;
1448 decimal double double;
1449 string std::string;
1451 normalizedString std::string;
1452 token std::string;
1453 Name std::string;
1454 NMTOKEN std::string;
1455 NCName std::string;
1456 ID std::string;
1457 IDREF std::string;
1458 language std::string;
1459 anyURI std::string;
1460 NMTOKENS xml_schema::string_sequence;
1462 IDREFS xml_schema::string_sequence;
1463 QName xml_schema::qname;
1465 base64Binary std::auto_ptr<xml_schema::buffer>
1467 std::auto_ptr<xml_schema::buffer>;
1468 hexBinary std::auto_ptr<xml_schema::buffer>
1469 std::auto_ptr<xml_schema::buffer>;
1470 date xml_schema::date;
1472 dateTime xml_schema::date_time;
1473 duration xml_schema::duration;
1474 gDay xml_schema::gday;
1475 gMonth xml_schema::gmonth;
1476 gMonthDay xml_schema::gmonth_day;
1477 gYear xml_schema::gyear;
1478 gYearMonth xml_schema::gyear_month;
1479 time xml_schema::time;
1480 }
1481 The last predefined rule maps anything that wasn't mapped by previous
1484 rules to void:
1485 namespace .*
1487 {
1488 .* void void;
1489 }
1490 When you provide your own type maps with the --type-map option, they
1492 are evaluated first. This allows you to selectively override predefined
1493 rules.
1494
1497 When entering a regular expression argument in the shell command line
1498 it is often necessary to use quoting (enclosing the argument in " " or
1499 ' ') in order to prevent the shell from interpreting certain charac‐
1500 ters, for example, spaces as argument separators and $ as variable
1501 expansions.
1502 Unfortunately it is hard to achieve this in a manner that is portable
1504 across POSIX shells, such as those found on GNU/Linux and UNIX, and
1505 Windows shell. For example, if you use " " for quoting you will get a
1506 wrong result with POSIX shells if your expression contains $. The stan‐
1507 dard way of dealing with this on POSIX systems is to use ' ' instead.
1508 Unfortunately, Windows shell does not remove ' ' from arguments when
1509 they are passed to applications. As a result you may have to use ' '
1510 for POSIX and " " for Windows ($ is not treated as a special character
1511 on Windows).
1512 Alternatively, you can save regular expression options into a file, one
1514 option per line, and use this file with the --options-file option. With
1515 this approach you don't need to worry about shell quoting.
1516
1519 If the input file is not a valid W3C XML Schema definition, xsdcxx will
1520 issue diagnostic messages to STDERR and exit with non-zero exit code.
1521
1523 Send bug reports to the xsd-users@codesynthesis.com mailing list.
1524
1526 Copyright (c) 2005-2014 Code Synthesis Tools CC.
1527 Permission is granted to copy, distribute and/or modify this document
1529 under the terms of the GNU Free Documentation License, version 1.2;
1530 with no Invariant Sections, no Front-Cover Texts and no Back-Cover
1531 Texts. Copy of the license can be obtained from http://codesynthe‐
1532 sis.com/licenses/fdl-1.2.txt
1533XSDCXX 4.0.0 July 2014 XSDCXX(1)