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
81 Generate code using the provided character type instead of the
82 default char. Valid values are char and wchar_t.
83 --char-encoding enc
85 Specify the character encoding that should be used in the gener‐
86 ated code. Valid values for the char character type are utf8
87 (default), iso8859-1, lcp (Xerces-C++ local code page), and cus‐
88 tom. If you pass custom as the value then you will need to
89 include the transcoder implementation header for your encoding
90 at the beginning of the generated header files (see the --hxx-
91 prologue option).
92 For the wchar_t character type the only valid value is auto and
94 the encoding is automatically selected between UTF-16 and
95 UTF-32/UCS-4, depending on the wchar_t type size.
96 --output-dir dir
98 Write generated files to dir instead of the current directory.
99 --generate-inline
101 Generate simple functions inline. This option triggers creation
102 of the inline file.
103 --generate-xml-schema
105 Generate a C++ header file as if the schema being compiled
106 defines the XML Schema namespace. For the C++/Tree mapping, the
107 resulting file will contain definitions for all XML Schema
108 built-in types. For the C++/Parser mapping, the resulting file
109 will contain definitions for all the parser skeletons and imple‐
110 mentations corresponding to the XML Schema built-in types.
111 The schema file provided to the compiler need not exist and is
113 only used to derive the name of the resulting header file. Use
114 the --extern-xml-schema option to include this file in the gen‐
115 erated files for other schemas.
116 --extern-xml-schema file
118 Include a header file derived from file instead of generating
119 the XML Schema namespace mapping inline. The provided file need
120 not exist and is only used to derive the name of the included
121 header file. Use the --generate-xml-schema option to generate
122 this header file.
123 --namespace-map xns=cns
125 Map XML Schema namespace xns to C++ namespace cns. Repeat this
126 option to specify mapping for more than one XML Schema names‐
127 pace. For example, the following option:
128 --namespace-map http://example.com/foo/bar=foo::bar
130 Will map the http://example.com/foo/bar XML Schema namespace to
132 the foo::bar C++ namespace.
133 --namespace-regex regex
135 Add regex to the list of regular expressions used to translate
136 XML Schema namespace names to C++ namespace names. regex is a
137 Perl-like regular expression in the form /pattern/replacement/.
138 Any character can be used as a delimiter instead of '/'. Escap‐
139 ing of the delimiter character in pattern or replacement is not
140 supported.
141 All the regular expressions are pushed into a stack with the
143 last specified expression considered first. The first match that
144 succeeds is used. Regular expressions are applied to a string in
145 the form
146 filename namespace
148 For example, if you have file hello.xsd with namespace
150 http://example.com/hello and you run xsd on this file, then the
151 string in question will be:
152 hello.xsd. http://example.com/hello
154 For the built-in XML Schema namespace the string is:
156 XMLSchema.xsd http://www.w3.org/2001/XMLSchema
158 The following three steps are performed for each regular expres‐
160 sion until the match is found:
161 1. The expression is applied and if the result is empty the next
163 expression is considered.
164 2. All '/' are replaced with '::'.
166 3. The result is verified to be a valid C++ scope name (e.g.,
168 foo::bar). If this test succeeds, the result is used as a C++
169 namespace name.
170 As an example, the following expression maps XML Schema names‐
172 paces in the form http://example.com/foo/bar to C++ namespaces
173 in the form foo::bar:
174 %.* http://example.com/(.+)%$1%
176 See also the REGEX AND SHELL QUOTING section below.
178 --namespace-regex-trace
180 Trace the process of applying regular expressions specified with
181 the --namespace-regex option. Use this option to find out why
182 your regular expressions don't do what you expected them to do.
183 --reserved-name n[=r]
185 Add name n to the list of names that should not be used as iden‐
186 tifiers. The name can optionally be followed by = and the
187 replacement name r that should be used instead. All the C++ key‐
188 words are already in this list.
189 --include-with-brackets
191 Use angle brackets (<>) instead of quotes ("") in generated
192 #include directives.
193 --include-prefix prefix
195 Add prefix to generated #include directive paths.
196 For example, if you had the following import element in your
198 schema
199 <import namespace="..." schemaLocation="base.xsd"/>
201 and compiled this fragment with --include-prefix schemas/, then
203 the include directive in the generated code would be:
204 #include "schemas/base.hxx"
206 --include-regex regex
208 Add regex to the list of regular expressions used to transform
209 #include directive paths. regex is a Perl-like regular expres‐
210 sion in the form /pattern/replacement/. Any character can be
211 used as a delimiter instead of '/'. Escaping of the delimiter
212 character in pattern or replacement is not supported.
213 All the regular expressions are pushed into a stack with the
215 last specified expression considered first. The first match that
216 succeeds is used.
217 As an example, the following expression transforms paths in the
219 form schemas/foo/bar to paths in the form generated/foo/bar:
220 %schemas/(.+)%generated/$1%
222 See also the REGEX AND SHELL QUOTING section below.
224 --include-regex-trace
226 Trace the process of applying regular expressions specified with
227 the --include-regex option. Use this option to find out why your
228 regular expressions don't do what you expected them to do.
229 --guard-prefix prefix
231 Add prefix to generated header inclusion guards. The prefix is
232 transformed to upper case and characters that are illegal in a
233 preprocessor macro name are replaced with underscores. If this
234 option is not specified then the directory part of the input
235 schema file is used as a prefix.
236 --hxx-suffix suffix
238 Use the provided suffix instead of the default .hxx to construct
239 the name of the header file. Note that this suffix is also used
240 to construct names of header files corresponding to
241 included/imported schemas.
242 --ixx-suffix suffix
244 Use the provided suffix instead of the default .ixx to construct
245 the name of the inline file.
246 --cxx-suffix suffix
248 Use the provided suffix instead of the default .cxx to construct
249 the name of the source file.
250 --fwd-suffix suffix
252 Use the provided suffix instead of the default -fwd.hxx to con‐
253 struct the name of the forward declaration file.
254 --hxx-regex regex
256 Use the provided expression to construct the name of the header
257 file. regex is a Perl-like regular expression in the form /pat‐
258 tern/replacement/. Note that this expression is also used to
259 construct names of header files corresponding to
260 included/imported schemas. See also the REGEX AND SHELL QUOTING
261 section below.
262 --ixx-regex regex
264 Use the provided expression to construct the name of the inline
265 file. regex is a Perl-like regular expression in the form /pat‐
266 tern/replacement/. See also the REGEX AND SHELL QUOTING section
267 below.
268 --cxx-regex regex
270 Use the provided expression to construct the name of the source
271 file. regex is a Perl-like regular expression in the form /pat‐
272 tern/replacement/. See also the REGEX AND SHELL QUOTING section
273 below.
274 --fwd-regex regex
276 Use the provided expression to construct the name of the forward
277 declaration file. regex is a Perl-like regular expression in the
278 form /pattern/replacement/. See also the REGEX AND SHELL QUOTING
279 section below.
280 --hxx-prologue text
282 Insert text at the beginning of the header file.
283 --ixx-prologue text
285 Insert text at the beginning of the inline file.
286 --cxx-prologue text
288 Insert text at the beginning of the source file.
289 --fwd-prologue text
291 Insert text at the beginning of the forward declaration file.
292 --prologue text
294 Insert text at the beginning of each generated file for which
295 there is no file-specific prologue.
296 --hxx-epilogue text
298 Insert text at the end of the header file.
299 --ixx-epilogue text
301 Insert text at the end of the inline file.
302 --cxx-epilogue text
304 Insert text at the end of the source file.
305 --fwd-epilogue text
307 Insert text at the end of the forward declaration file.
308 --epilogue text
310 Insert text at the end of each generated file for which there is
311 no file-specific epilogue.
312 --hxx-prologue-file file
314 Insert the content of the file at the beginning of the header
315 file.
316 --ixx-prologue-file file
318 Insert the content of the file at the beginning of the inline
319 file.
320 --cxx-prologue-file file
322 Insert the content of the file at the beginning of the source
323 file.
324 --fwd-prologue-file file
326 Insert the content of the file at the beginning of the forward
327 declaration file.
328 --prologue-file file
330 Insert the content of the file at the beginning of each gener‐
331 ated file for which there is no file-specific prologue file.
332 --hxx-epilogue-file file
334 Insert the content of the file at the end of the header file.
335 --ixx-epilogue-file file
337 Insert the content of the file at the end of the inline file.
338 --cxx-epilogue-file file
340 Insert the content of the file at the end of the source file.
341 --fwd-epilogue-file file
343 Insert the content of the file at the end of the forward decla‐
344 ration file.
345 --epilogue-file file
347 Insert the content of the file at the end of each generated file
348 for which there is no file-specific epilogue file.
349 --export-symbol symbol
351 Insert symbol in places where DLL export/import control state‐
352 ments (__declspec(dllexport/dllimport)) are necessary.
353 --export-xml-schema
355 Export/import types in the XML Schema namespace using the export
356 symbol provided with the --export-symbol option. The
357 XSD_NO_EXPORT macro can be used to omit this code during C++
358 compilation, which may be useful if you would like to use the
359 same generated code across multiple platforms.
360 --export-maps
362 Export polymorphism support maps from a Win32 DLL into which
363 this generated code is placed. This is necessary when your type
364 hierarchy is split across several DLLs since otherwise each DLL
365 will have its own set of maps. In this situation the generated
366 code for the DLL which contains base types and/or substitution
367 group heads should be compiled with this option and the gener‐
368 ated code for all other DLLs should be compiled with --import-
369 maps. This option is only valid together with --generate-poly‐
370 morphic. The XSD_NO_EXPORT macro can be used to omit this code
371 during C++ compilation, which may be useful if you would like to
372 use the same generated code across multiple platforms.
373 --import-maps
375 Import polymorphism support maps to a Win32 DLL or executable
376 into which this generated code is linked. See the --export-maps
377 option documentation for details. This options is only valid
378 together with --generate-polymorphic. The XSD_NO_EXPORT macro
379 can be used to omit this code during C++ compilation, which may
380 be useful if you would like to use the same generated code
381 across multiple platforms.
382 --generate-dep
384 Generate make dependency information. This option triggers the
385 creation of the .d file containing the dependencies of the gen‐
386 erated files on the main schema file as well as all the schema
387 files that it includes/imports, transitively. This dependency
388 file is then normally included into the main makefile to imple‐
389 ment automatic dependency tracking.
390 Note also that automatic dependency generation is not supported
392 in the file-per-type mode (--file-per-type). In this case, all
393 the generated files are produced with a single compiler invoca‐
394 tion and depend on all the schemas. As a result, it is easier to
395 establish such a dependency manually, perhaps with the help of
396 the --file-list* options.
397 --generate-dep-only
399 Generate make dependency information only.
400 --dep-phony
402 Generate phony targets for included/imported schema files, caus‐
403 ing each to depend on nothing. Such dummy rules work around make
404 errors caused by the removal of schema files without also updat‐
405 ing the dependency file to match.
406 --dep-target target
408 Change the target of the dependency rule. By default it contains
409 all the generated C++ files as well as the dependency file
410 itself, without any directory prefixes. If you require multiple
411 targets, then you can specify them as a single, space-separated
412 argument or you can repeat this option multiple times.
413 --dep-suffix suffix
415 Use the provided suffix instead of the default .d to construct
416 the name of the dependency file.
417 --dep-regex regex
419 Use the provided expression to construct the name of the depen‐
420 dency file. regex is a Perl-like regular expression in the form
421 /pattern/replacement/. See also the REGEX AND SHELL QUOTING sec‐
422 tion below.
423 --disable-warning warn
425 Disable printing warning with id warn. If all is specified for
426 the warning id then all warnings are disabled.
427 --options-file file
429 Read additional options from file. Each option should appearing
430 on a separate line optionally followed by space and an option
431 value. Empty lines and lines starting with # are ignored. Option
432 values can be enclosed in double (") or single (') quotes to
433 preserve leading and trailing whitespaces as well as to specify
434 empty values. If the value itself contains trailing or leading
435 quotes, enclose it with an extra pair of quotes, for example
436 '"x"'. Non-leading and non-trailing quotes are interpreted as
437 being part of the option value.
438 The semantics of providing options in a file is equivalent to
440 providing the same set of options in the same order on the com‐
441 mand line at the point where the --options-file option is speci‐
442 fied except that the shell escaping and quoting is not required.
443 You can repeat this option to specify more than one options
444 file.
445 --show-sloc
447 Show the number of generated physical source lines of code
448 (SLOC).
449 --sloc-limit num
451 Check that the number of generated physical source lines of code
452 (SLOC) does not exceed num.
453 --proprietary-license
455 Indicate that the generated code is licensed under a proprietary
456 license instead of the GPL.
457 --custom-literals file
459 Load custom XML string to C++ literal mappings from file. This
460 mechanism can be useful if you are using a custom character
461 encoding and some of the strings in your schemas, for example
462 element/attribute names or enumeration values, contain non-ASCII
463 characters. In this case you will need to provide a custom map‐
464 ping to C++ literals for such strings. The format of this file
465 is specified in the custom-literals.xsd XML Schema file that can
466 be found in the documentation directory.
467 --preserve-anonymous
469 Preserve anonymous types. By default anonymous types are auto‐
470 matically named with names derived from the enclosing ele‐
471 ments/attributes. Because mappings implemented by this compiler
472 require all types to be named, this option is only useful if you
473 want to make sure your schemas don't have anonymous types.
474 --show-anonymous
476 Show elements and attributes that are of anonymous types. This
477 option only makes sense together with the --preserve-anonymous
478 option.
479 --anonymous-regex regex
481 Add regex to the list of regular expressions used to derive
482 names for anonymous types from the enclosing attributes/ele‐
483 ments. regex is a Perl-like regular expression in the form /pat‐
484 tern/replacement/. Any character can be used as a delimiter
485 instead of '/'. Escaping of the delimiter character in pattern
486 or replacement is not supported.
487 All the regular expressions are pushed into a stack with the
489 last specified expression considered first. The first match that
490 succeeds is used. Regular expressions are applied to a string in
491 the form
492 filename namespace xpath
494 For instance:
496 hello.xsd http://example.com/hello element
498 hello.xsd http://example.com/hello type/element
500 As an example, the following expression makes all the derived
502 names start with capital letters. This could be useful when your
503 naming convention requires type names to start with capital let‐
504 ters:
505 %.* .* (.+/)*(.+)%\u$2%
507 See also the REGEX AND SHELL QUOTING section below.
509 --anonymous-regex-trace
511 Trace the process of applying regular expressions specified with
512 the --anonymous-regex option. Use this option to find out why
513 your regular expressions don't do what you expected them to do.
514 --location-map ol=nl
516 Map the original schema location ol that is specified in the XML
517 Schema include or import elements to new schema location nl.
518 Repeat this option to map more than one schema location. For
519 example, the following option maps the http://exam‐
520 ple.com/foo.xsd URL to the foo.xsd local file.
521 --location-map http://example.com/foo.xsd=foo.xsd
523 --location-regex regex
525 Add regex to the list of regular expressions used to map schema
526 locations that are specified in the XML Schema include or import
527 elements. regex is a Perl-like regular expression in the form
528 /pattern/replacement/. Any character can be used as a delimiter
529 instead of '/'. Escaping of the delimiter character in pattern
530 or replacement is not supported. All the regular expressions are
531 pushed into a stack with the last specified expression consid‐
532 ered first. The first match that succeeds is used.
533 For example, the following expression maps URL locations in the
535 form http://example.com/foo/bar.xsd to local files in the form
536 bar.xsd:
537 %http://.+/(.+)%$1%
539 See also the REGEX AND SHELL QUOTING section below.
541 --location-regex-trace
543 Trace the process of applying regular expressions specified with
544 the --location-regex option. Use this option to find out why
545 your regular expressions don't do what you expected them to do.
546 --file-per-type
548 Generate a separate set of C++ files for each type defined in
549 XML Schema. Note that in this mode you only need to compile the
550 root schema(s) and the code will be generated for all included
551 and imported schemas. This compilation mode is primarily useful
552 when some of your schemas cannot be compiled separately or have
553 cyclic dependencies which involve type inheritance. Other
554 options related to this mode are: --type-file-regex, --schema-
555 file-regex, --fat-type-file, and --file-list.
556 --type-file-regex regex
558 Add regex to the list of regular expressions used to translate
559 type names to file names when the --file-per-type option is
560 specified. regex is a Perl-like regular expression in the form
561 /pattern/replacement/. Any character can be used as a delimiter
562 instead of '/'. Escaping of the delimiter character in pattern
563 or replacement is not supported. All the regular expressions are
564 pushed into a stack with the last specified expression consid‐
565 ered first. The first match that succeeds is used. Regular
566 expressions are applied to a string in the form
567 namespace type-name
569 For example, the following expression maps type foo that is
571 defined in the http://example.com/bar namespace to file name
572 bar-foo:
573 %http://example.com/(.+) (.+)%$1-$2%
575 See also the REGEX AND SHELL QUOTING section below.
577 --type-file-regex-trace
579 Trace the process of applying regular expressions specified with
580 the --type-file-regex option. Use this option to find out why
581 your regular expressions don't do what you expected them to do.
582 --schema-file-regex regex
584 Add regex to the list of regular expressions used to translate
585 schema file names when the --file-per-type option is specified.
586 regex is a Perl-like regular expression in the form /pat‐
587 tern/replacement/. Any character can be used as a delimiter
588 instead of '/'. Escaping of the delimiter character in pattern
589 or replacement is not supported. All the regular expressions are
590 pushed into a stack with the last specified expression consid‐
591 ered first. The first match that succeeds is used. Regular
592 Expressions are applied to the absolute filesystem path of a
593 schema file and the result, including the directory part, if
594 any, is used to derive the #include directive paths as well as
595 the generated C++ file paths. This option, along with --type-
596 file-regex are primarily useful to place the generated files
597 into subdirectories or to resolve file name conflicts.
598 For example, the following expression maps schema files in the
600 foo/1.0.0/ subdirectory to the files in the foo/ subdirectory.
601 As a result, the #include directive paths for such schemas will
602 be in the foo/schema.hxx form and the generated C++ files will
603 be placed into the foo/ subdirectory:
604 %.*/foo/1.0.0/(.+)%foo/$1%
606 See also the REGEX AND SHELL QUOTING section below.
608 --schema-file-regex-trace
610 Trace the process of applying regular expressions specified with
611 the --schema-file-regex option. Use this option to find out why
612 your regular expressions don't do what you expected them to do.
613 --fat-type-file
615 Generate code corresponding to global elements into type files
616 instead of schema files when the --type-file-regex option is
617 specified. This option is primarily useful when trying to mini‐
618 mize the amount of object code that is linked to an executable
619 by packaging compiled generated code into a static (archive)
620 library.
621 --file-list file
623 Write a list of generated C++ files to file. This option is pri‐
624 marily useful in the file-per-type compilation mode (--file-per-
625 type) to create a list of generated C++ files, for example, as a
626 makefile fragment.
627 --file-list-prologue text
629 Insert text at the beginning of the file list. As a convenience,
630 all occurrences of the \n character sequence in text are
631 replaced with new lines. This option can, for example, be used
632 to assign the generated file list to a makefile variable.
633 --file-list-epilogue text
635 Insert text at the end of the file list. As a convenience, all
636 occurrences of the \n character sequence in text are replaced
637 with new lines.
638 --file-list-delim text
640 Delimit file names written to the file list with text instead of
641 new lines. As a convenience, all occurrences of the \n character
642 sequence in text are replaced with new lines.
643 cxx-tree command options
645 --generate-polymorphic
646 Generate polymorphism-aware code. Specify this option if you use
647 substitution groups or xsi:type. Use the --polymorphic-type or
648 --polymorphic-type-all option to specify which type hierarchies
649 are polymorphic.
650 --polymorphic-type type
652 Indicate that type is a root of a polymorphic type hierarchy.
653 The compiler can often automatically determine which types are
654 polymorphic based on the substitution group declarations. How‐
655 ever, you may need to use this option if you are not using sub‐
656 stitution groups or if substitution groups are defined in
657 another schema. You need to specify this option when compiling
658 every schema file that references type. The type argument is an
659 XML Schema type name that can be optionally qualified with a
660 namespace in the namespace#name form.
661 --polymorphic-type-all
663 Indicate that all types should be treated as polymorphic.
664 --polymorphic-plate num
666 Specify the polymorphic map plate the generated code should reg‐
667 ister on. This functionality is primarily useful to segregate
668 multiple schemas that define the same polymorphic types.
669 --ordered-type type
671 Indicate that element order in type is significant. An example
672 would be a complex type with unbounded choice as a content model
673 where the element order in XML has application-specific seman‐
674 tics. For ordered types the compiler generates a special con‐
675 tainer data member and a corresponding set of accessors and mod‐
676 ifiers that are used to capture the order of elements and, for
677 mixed content, of text.
678 The type argument is an XML Schema type name that can be option‐
680 ally qualified with a namespace in the namespace#name form.
681 Note also that you will need to specify this option when compil‐
682 ing every schema file that has other ordered types derived from
683 this type.
684 --ordered-type-derived
686 Automatically treat types derived from ordered bases as also
687 ordered. This is primarily useful if you would like to be able
688 to iterate over the complete content using the content order
689 container.
690 --ordered-type-mixed
692 Automatically treat complex types with mixed content as ordered.
693 --ordered-type-all
695 Indicate that element order in all types is significant.
696 --order-container type
698 Specify a custom class template that should be used as a con‐
699 tainer for the content order in ordered types instead of the
700 default std::vector. See --ordered-type for more information on
701 ordered type. This option is primarily useful if you need to
702 perform more complex lookups in the content order container, for
703 example by element id. In this case, a container like Boost
704 multi-index may be more convenient. Note that if using a custom
705 container, you will also most likely need to include the rele‐
706 vant headers using the --hxx-prologue* options.
707 --generate-serialization
709 Generate serialization functions. Serialization functions con‐
710 vert the object model back to XML.
711 --generate-ostream
713 Generate ostream insertion operators (operator<<) for generated
714 types. This allows one to easily print a fragment or the whole
715 object model for debugging or logging.
716 --generate-doxygen
718 Generate documentation comments suitable for extraction by the
719 Doxygen documentation system. Documentation from annotations is
720 added to the comments if present in the schema.
721 --generate-comparison
723 Generate comparison operators (operator== and operator!=) for
724 complex types. Comparison is performed member-wise.
725 --generate-default-ctor
727 Generate default constructors even for types that have required
728 members. Required members of an instance constructed using such
729 a constructor are not initialized and accessing them results in
730 undefined behavior.
731 --generate-from-base-ctor
733 Generate constructors that expect an instance of a base type
734 followed by all required members.
735 --suppress-assignment
737 Suppress the generation of copy assignment operators for complex
738 types. If this option is specified, the copy assignment opera‐
739 tors for such types are declared private and left unimplemented.
740 --generate-detach
742 Generate detach functions for required elements and attributes.
743 Detach functions for optional and sequence cardinalities are
744 provided by the respective containers. These functions, for
745 example, allow you to move sub-trees in the object model either
746 within the same tree or between different trees.
747 --generate-wildcard
749 Generate accessors and modifiers as well as parsing and serial‐
750 ization code for XML Schema wildcards (any and anyAttribute).
751 XML content matched by wildcards is presented as DOM fragments.
752 Note that you need to initialize the Xerces-C++ runtime if you
753 are using this option.
754 --generate-any-type
756 Extract and store content of the XML Schema anyType type as a
757 DOM fragment. Note that you need to initialize the Xerces-C++
758 runtime if you are using this option.
759 --generate-insertion os
761 Generate data representation stream insertion operators for the
762 os output stream type. Repeat this option to specify more than
763 one stream type. The ACE CDR stream (ACE_OutputCDR) and RPC XDR
764 are recognized by the compiler and the necessary #include direc‐
765 tives are automatically generated. For custom stream types use
766 the --hxx-prologue* options to provide the necessary declara‐
767 tions.
768 --generate-extraction is
770 Generate data representation stream extraction constructors for
771 the is input stream type. Repeat this option to specify more
772 than one stream type. The ACE CDR stream (ACE_InputCDR) and RPC
773 XDR are recognized by the compiler and the necessary #include
774 directives are automatically generated. For custom stream types
775 use the --hxx-prologue* options to provide the necessary decla‐
776 rations.
777 --generate-forward
779 Generate a separate header file with forward declarations for
780 the types being generated.
781 --suppress-parsing
783 Suppress the generation of the parsing functions and construc‐
784 tors. Use this option to reduce the generated code size when
785 parsing from XML is not needed.
786 --generate-element-type
788 Generate types instead of parsing and serialization functions
789 for root elements. This is primarily useful to distinguish
790 object models with the same root type but with different root
791 elements.
792 --generate-element-map
794 Generate a root element map that allows uniform parsing and
795 serialization of multiple root elements. This option is only
796 valid together with --generate-element-type.
797 --generate-intellisense
799 Generate workarounds for IntelliSense bugs in Visual Studio 2005
800 (8.0). When this option is used, the resulting code is slightly
801 more verbose. IntelliSense in Visual Studio 2008 (9.0) and
802 later does not require these workarounds. Support for Intel‐
803 liSense in Visual Studio 2003 (7.1) is improved with this option
804 but is still incomplete.
805 --omit-default-attributes
807 Omit attributes with default and fixed values from serialized
808 XML documents.
809 --type-naming style
811 Specify the type naming convention that should be used in the
812 generated code. Valid styles are knr (default), ucc, and java.
813 See the NAMING CONVENTION section below for more information.
814 --function-naming style
816 Specify the function naming convention that should be used in
817 the generated code. Valid styles are knr (default), lcc, and
818 java. See the NAMING CONVENTION section below for more informa‐
819 tion.
820 --type-regex regex
822 Add regex to the list of regular expressions used to translate
823 XML Schema type names to C++ type names. See the NAMING CONVEN‐
824 TION section below for more information.
825 --accessor-regex regex
827 Add regex to the list of regular expressions used to translate
828 XML Schema names of elements/attributes to C++ accessor function
829 names. See the NAMING CONVENTION section below for more informa‐
830 tion.
831 --one-accessor-regex regex
833 Add regex to the list of regular expressions used to translate
834 XML Schema names of elements/attributes with cardinality one to
835 C++ accessor function names. See the NAMING CONVENTION section
836 below for more information.
837 --opt-accessor-regex regex
839 Add regex to the list of regular expressions used to translate
840 XML Schema names of elements/attributes with cardinality
841 optional to C++ accessor function names. See the NAMING CONVEN‐
842 TION section below for more information.
843 --seq-accessor-regex regex
845 Add regex to the list of regular expressions used to translate
846 XML Schema names of elements/attributes with cardinality
847 sequence to C++ accessor function names. See the NAMING CONVEN‐
848 TION section below for more information.
849 --modifier-regex regex
851 Add regex to the list of regular expressions used to translate
852 XML Schema names of elements/attributes to C++ modifier function
853 names. See the NAMING CONVENTION section below for more informa‐
854 tion.
855 --one-modifier-regex regex
857 Add regex to the list of regular expressions used to translate
858 XML Schema names of elements/attributes with cardinality one to
859 C++ modifier function names. See the NAMING CONVENTION section
860 below for more information.
861 --opt-modifier-regex regex
863 Add regex to the list of regular expressions used to translate
864 XML Schema names of elements/attributes with cardinality
865 optional to C++ modifier function names. See the NAMING CONVEN‐
866 TION section below for more information.
867 --seq-modifier-regex regex
869 Add regex to the list of regular expressions used to translate
870 XML Schema names of elements/attributes with cardinality
871 sequence to C++ modifier function names. See the NAMING CONVEN‐
872 TION section below for more information.
873 --parser-regex regex
875 Add regex to the list of regular expressions used to translate
876 XML Schema element names to C++ parsing function names. See the
877 NAMING CONVENTION section below for more information.
878 --serializer-regex regex
880 Add regex to the list of regular expressions used to translate
881 XML Schema element names to C++ serialization function names.
882 See the NAMING CONVENTION section below for more information.
883 --const-regex regex
885 Add regex to the list of regular expressions used to translate
886 XML Schema-derived names to C++ constant names. See the NAMING
887 CONVENTION section below for more information.
888 --enumerator-regex regex
890 Add regex to the list of regular expressions used to translate
891 XML Schema enumeration values to C++ enumerator names. See the
892 NAMING CONVENTION section below for more information.
893 --element-type-regex regex
895 Add regex to the list of regular expressions used to translate
896 XML Schema element names to C++ element type names. See the NAM‐
897 ING CONVENTION section below for more information.
898 --name-regex-trace
900 Trace the process of applying regular expressions specified with
901 the name transformation options. Use this option to find out why
902 your regular expressions don't do what you expected them to do.
903 --root-element-first
905 Treat only the first global element as a document root. By
906 default all global elements are considered document roots.
907 --root-element-last
909 Treat only the last global element as a document root. By
910 default all global elements are considered document roots.
911 --root-element-all
913 Treat all global elements as document roots. This is the default
914 behavior. By explicitly specifying this option you can suppress
915 the warning that is issued if more than one global element is
916 defined.
917 --root-element-none
919 Do not treat any global elements as document roots. By default
920 all global elements are considered document roots.
921 --root-element element
923 Treat only element as a document root. Repeat this option to
924 specify more than one root element.
925 --custom-type map
927 Use a custom C++ type instead of the generated class. The map
928 argument is in the form name[=type[/base]], where name is a type
929 name as defined in XML Schema and type is a C++ type name that
930 should be used instead. If type is not present or empty then the
931 custom type is assumed to have the same name and be defined in
932 the same namespace as the generated class would have. If base is
933 specified then the generated class is still generated but with
934 that name.
935 --custom-type-regex regex
937 Use custom C++ types instead of the generated classes. The regex
938 argument is in the form /name-pat/[type-sub/[base-sub/]], where
939 name-pat is a regex pattern that will be matched against type
940 names as defined in XML Schema and type-sub is a C++ type name
941 substitution that should be used instead. If type-sub is not
942 present or its substitution results in an empty string then the
943 custom type is assumed to have the same name and be defined in
944 the same namespace as the generated class would have. If base-
945 sub is present and its substitution results in a non-empty
946 string then the generated class is still generated but with the
947 result of this substitution as its name. The pattern and substi‐
948 tutions are in the Perl regular expression format. See also the
949 REGEX AND SHELL QUOTING section below.
950 --parts num
952 Split generated source code into num parts. This is useful when
953 translating large, monolithic schemas and a C++ compiler is not
954 able to compile the resulting source code at once (usually due
955 to insufficient memory).
956 --parts-suffix suffix
958 Use suffix instead of the default '-' to separate the file name
959 from the part number.
960 cxx-parser command options
965 --type-map mapfile
966 Read XML Schema to C++ type mapping information from mapfile.
967 Repeat this option to specify several type maps. Type maps are
968 considered in order of appearance and the first match is used.
969 By default all user-defined types are mapped to void. See the
970 TYPE MAP section below for more information.
971 --xml-parser parser
973 Use parser as the underlying XML parser. Valid values are xerces
974 for Xerces-C++ (default) and expat for Expat.
975 --generate-validation
977 Generate validation code. The validation code ("perfect parser")
978 ensures that instance documents conform to the schema. Valida‐
979 tion code is generated by default when the selected underlying
980 XML parser is non-validating (expat).
981 --suppress-validation
983 Suppress the generation of validation code. Validation is sup‐
984 pressed by default when the selected underlying XML parser is
985 validating (xerces).
986 --generate-polymorphic
988 Generate polymorphism-aware code. Specify this option if you use
989 substitution groups or xsi:type.
990 --generate-noop-impl
992 Generate a sample parser implementation that does nothing (no
993 operation). The sample implementation can then be filled with
994 the application-specific code. For an input file in the form
995 name.xsd this option triggers the generation of two additional
996 C++ files in the form: name-pimpl.hxx (parser implementation
997 header file) and name-pimpl.cxx (parser implementation source
998 file).
999 --generate-print-impl
1001 Generate a sample parser implementation that prints the XML data
1002 to STDOUT. For an input file in the form name.xsd this option
1003 triggers the generation of two additional C++ files in the form:
1004 name-pimpl.hxx (parser implementation header file) and name-
1005 pimpl.cxx (parser implementation source file).
1006 --generate-test-driver
1008 Generate a test driver for the sample parser implementation. For
1009 an input file in the form name.xsd this option triggers the gen‐
1010 eration of an additional C++ file in the form name-driver.cxx.
1011 --force-overwrite
1013 Force overwriting of the existing implementation and test driver
1014 files. Use this option only if you do not mind loosing the
1015 changes you have made in the sample implementation or test
1016 driver files.
1017 --root-element-first
1019 Indicate that the first global element is the document root.
1020 This information is used to generate the test driver for the
1021 sample implementation.
1022 --root-element-last
1024 Indicate that the last global element is the document root. This
1025 information is used to generate the test driver for the sample
1026 implementation.
1027 --root-element element
1029 Indicate that element is the document root. This information is
1030 used to generate the test driver for the sample implementation.
1031 --skel-type-suffix suffix
1033 Use the provided suffix instead of the default _pskel to con‐
1034 struct the names of the generated parser skeletons.
1035 --skel-file-suffix suffix
1037 Use the provided suffix instead of the default -pskel to con‐
1038 struct the names of the generated parser skeleton files.
1039 --impl-type-suffix suffix
1041 Use the provided suffix instead of the default _pimpl to con‐
1042 struct the names of the parser implementations for the built-in
1043 XML Schema types as well as sample parser implementations.
1044 --impl-file-suffix suffix
1046 Use the provided suffix instead of the default -pimpl to con‐
1047 struct the names of the generated sample parser implementation
1048 files.
1049
1055 The compiler can be instructed to use a particular naming convention in
1056 the generated code. A number of widely-used conventions can be selected
1057 using the --type-naming and --function-naming options. A custom naming
1058 convention can be achieved using the --type-regex, --accessor-regex,
1059 --one-accessor-regex, --opt-accessor-regex, --seq-accessor-regex,
1060 --modifier-regex, --one-modifier-regex, --opt-modifier-regex, --seq-
1061 modifier-regex, --parser-regex, --serializer-regex, --const-regex,
1062 --enumerator-regex, and --element-type-regex options.
1063 The --type-naming option specifies the convention that should be used
1065 for naming C++ types. Possible values for this option are knr
1066 (default), ucc, and java. The knr value (stands for K&R) signifies the
1067 standard, lower-case naming convention with the underscore used as a
1068 word delimiter, for example: foo, foo_bar. The ucc (stands for upper-
1069 camel-case) and java values a synonyms for the same naming convention
1070 where the first letter of each word in the name is capitalized, for
1071 example: Foo, FooBar.
1072 Similarly, the --function-naming option specifies the convention that
1074 should be used for naming C++ functions. Possible values for this
1075 option are knr (default), lcc, and java. The knr value (stands for
1076 K&R) signifies the standard, lower-case naming convention with the
1077 underscore used as a word delimiter, for example: foo(), foo_bar().
1078 The lcc value (stands for lower-camel-case) signifies a naming conven‐
1079 tion where the first letter of each word except the first is capital‐
1080 ized, for example: foo(), fooBar(). The java naming convention is simi‐
1081 lar to the lower-camel-case one except that accessor functions are pre‐
1082 fixed with get, modifier functions are prefixed with set, parsing func‐
1083 tions are prefixed with parse, and serialization functions are prefixed
1084 with serialize, for example: getFoo(), setFooBar(), parseRoot(), seri‐
1085 alizeRoot().
1086 Note that the naming conventions specified with the --type-naming and
1088 --function-naming options perform only limited transformations on the
1089 names that come from the schema in the form of type, attribute, and
1090 element names. In other words, to get consistent results, your schemas
1091 should follow a similar naming convention as the one you would like to
1092 have in the generated code. Alternatively, you can use the --*-regex
1093 options (discussed below) to perform further transformations on the
1094 names that come from the schema.
1095 The --type-regex, --accessor-regex, --one-accessor-regex, --opt-acces‐
1097 sor-regex, --seq-accessor-regex, --modifier-regex, --one-modifier-
1098 regex, --opt-modifier-regex, --seq-modifier-regex, --parser-regex,
1099 --serializer-regex, --const-regex, --enumerator-regex, and --element-
1100 type-regex options allow you to specify extra regular expressions for
1101 each name category in addition to the predefined set that is added
1102 depending on the --type-naming and --function-naming options. Expres‐
1103 sions that are provided with the --*-regex options are evaluated prior
1104 to any predefined expressions. This allows you to selectively override
1105 some or all of the predefined transformations. When debugging your own
1106 expressions, it is often useful to see which expressions match which
1107 names. The --name-regex-trace option allows you to trace the process of
1108 applying regular expressions to names.
1109 The value for the --*-regex options should be a perl-like regular
1111 expression in the form /pattern/replacement/. Any character can be
1112 used as a delimiter instead of /. Escaping of the delimiter character
1113 in pattern or replacement is not supported. All the regular expressions
1114 for each category are pushed into a category-specific stack with the
1115 last specified expression considered first. The first match that suc‐
1116 ceeds is used. For the --one-accessor-regex (accessors with cardinality
1117 one), --opt-accessor-regex (accessors with cardinality optional), and
1118 --seq-accessor-regex (accessors with cardinality sequence) categories
1119 the --accessor-regex expressions are used as a fallback. For the --one-
1120 modifier-regex, --opt-modifier-regex, and --seq-modifier-regex cate‐
1121 gories the --modifier-regex expressions are used as a fallback. For the
1122 --element-type-regex category the --type-regex expressions are used as
1123 a fallback.
1124 The type name expressions (--type-regex) are evaluated on the name
1126 string that has the following format:
1127 [namespace ]name[,name][,name][,name]
1129 The element type name expressions (--element-type-regex), effective
1131 only when the --generate-element-type option is specified, are evalu‐
1132 ated on the name string that has the following format:
1133 namespace name
1135 In the type name format the namespace part followed by a space is only
1137 present for global type names. For global types and elements defined in
1138 schemas without a target namespace, the namespace part is empty but the
1139 space is still present. In the type name format after the initial name
1140 component, up to three additional name components can be present, sepa‐
1141 rated by commas. For example:
1142 http://example.com/hello type
1144 foo
1146 foo,iterator
1148 foo,const,iterator
1150 The following set of predefined regular expressions is used to trans‐
1152 form type names when the upper-camel-case naming convention is
1153 selected:
1154 /(?:[^ ]* )?([^,]+)/\u$1/
1156 /(?:[^ ]* )?([^,]+),([^,]+)/\u$1\u$2/
1158 /(?:[^ ]* )?([^,]+),([^,]+),([^,]+)/\u$1\u$2\u$3/
1160 /(?:[^ ]* )?([^,]+),([^,]+),([^,]+),([^,]+)/\u$1\u$2\u$3\u$4/
1162 The accessor and modifier expressions (--*accessor-regex and --*modi‐
1164 fier-regex) are evaluated on the name string that has the following
1165 format:
1166 name[,name][,name]
1168 After the initial name component, up to two additional name components
1170 can be present, separated by commas. For example:
1171 foo
1173 dom,document
1175 foo,default,value
1177 The following set of predefined regular expressions is used to trans‐
1179 form accessor names when the java naming convention is selected:
1180 /([^,]+)/get\u$1/
1182 /([^,]+),([^,]+)/get\u$1\u$2/
1184 /([^,]+),([^,]+),([^,]+)/get\u$1\u$2\u$3/
1186 For the parser, serializer, and enumerator categories, the correspond‐
1188 ing regular expressions are evaluated on local names of elements and on
1189 enumeration values, respectively. For example, the following predefined
1190 regular expression is used to transform parsing function names when the
1191 java naming convention is selected:
1192 /(.+)/parse\u$1/
1194 The const category is used to create C++ constant names for the ele‐
1196 ment/wildcard/text content ids in ordered types.
1197 See also the REGEX AND SHELL QUOTING section below.
1199
1205 Type map files are used in C++/Parser to define a mapping between XML
1206 Schema and C++ types. The compiler uses this information to determine
1207 the return types of post_* functions in parser skeletons corresponding
1208 to XML Schema types as well as argument types for callbacks correspond‐
1209 ing to elements and attributes of these types.
1210 The compiler has a set of predefined mapping rules that map built-in
1212 XML Schema types to suitable C++ types (discussed below) and all other
1213 types to void. By providing your own type maps you can override these
1214 predefined rules. The format of the type map file is presented below:
1215 namespace schema-namespace [ cxx-namespace ]
1217 {
1218 ( include file-name; )*
1219 ([ type ] schema-type cxx-ret-type [ cxx-arg-type ]; )*
1220 }
1221 Both schema-namespace and schema-type are regex patterns while cxx-
1223 namespace, cxx-ret-type, and cxx-arg-type are regex pattern substitu‐
1224 tions. All names can be optionally enclosed in " ", for example, to
1225 include white-spaces.
1226 schema-namespace determines XML Schema namespace. Optional cxx-names‐
1228 pace is prefixed to every C++ type name in this namespace declaration.
1229 cxx-ret-type is a C++ type name that is used as a return type for the
1230 post_* functions. Optional cxx-arg-type is an argument type for call‐
1231 back functions corresponding to elements and attributes of this type.
1232 If cxx-arg-type is not specified, it defaults to cxx-ret-type if cxx-
1233 ret-type ends with * or & (that is, it is a pointer or a reference) and
1234 const cxx-ret-type& otherwise. file-name is a file name either in the
1235 " " or < > format and is added with the #include directive to the gen‐
1236 erated code.
1237 The # character starts a comment that ends with a new line or end of
1239 file. To specify a name that contains # enclose it in " ". For example:
1240 namespace http://www.example.com/xmlns/my my
1242 {
1243 include "my.hxx";
1244 # Pass apples by value.
1246 #
1247 apple apple;
1248 # Pass oranges as pointers.
1250 #
1251 orange orange_t*;
1252 }
1253 In the example above, for the http://www.example.com/xmlns/my#orange
1255 XML Schema type, the my::orange_t* C++ type will be used as both return
1256 and argument types.
1257 Several namespace declarations can be specified in a single file. The
1259 namespace declaration can also be completely omitted to map types in a
1260 schema without a namespace. For instance:
1261 include "my.hxx";
1263 apple apple;
1264 namespace http://www.example.com/xmlns/my
1266 {
1267 orange "const orange_t*";
1268 }
1269 The compiler has a number of predefined mapping rules that can be pre‐
1272 sented as the following map files. The string-based XML Schema built-in
1273 types are mapped to either std::string or std::wstring depending on the
1274 character type selected with the --char-type option (char by default).
1275 namespace http://www.w3.org/2001/XMLSchema
1277 {
1278 boolean bool bool;
1279 byte "signed char" "signed char";
1281 unsignedByte "unsigned char" "unsigned char";
1282 short short short;
1284 unsignedShort "unsigned short" "unsigned short";
1285 int int int;
1287 unsignedInt "unsigned int" "unsigned int";
1288 long "long long" "long long";
1290 unsignedLong "unsigned long long" "unsigned long long";
1291 integer "long long" "long long";
1293 negativeInteger "long long" "long long";
1295 nonPositiveInteger "long long" "long long";
1296 positiveInteger "unsigned long long" "unsigned long long";
1298 nonNegativeInteger "unsigned long long" "unsigned long long";
1299 float float float;
1301 double double double;
1302 decimal double double;
1303 string std::string;
1305 normalizedString std::string;
1306 token std::string;
1307 Name std::string;
1308 NMTOKEN std::string;
1309 NCName std::string;
1310 ID std::string;
1311 IDREF std::string;
1312 language std::string;
1313 anyURI std::string;
1314 NMTOKENS xml_schema::string_sequence;
1316 IDREFS xml_schema::string_sequence;
1317 QName xml_schema::qname;
1319 base64Binary std::auto_ptr<xml_schema::buffer>
1321 std::auto_ptr<xml_schema::buffer>;
1322 hexBinary std::auto_ptr<xml_schema::buffer>
1323 std::auto_ptr<xml_schema::buffer>;
1324 date xml_schema::date;
1326 dateTime xml_schema::date_time;
1327 duration xml_schema::duration;
1328 gDay xml_schema::gday;
1329 gMonth xml_schema::gmonth;
1330 gMonthDay xml_schema::gmonth_day;
1331 gYear xml_schema::gyear;
1332 gYearMonth xml_schema::gyear_month;
1333 time xml_schema::time;
1334 }
1335 The last predefined rule maps anything that wasn't mapped by previous
1338 rules to void:
1339 namespace .*
1341 {
1342 .* void void;
1343 }
1344 When you provide your own type maps with the --type-map option, they
1346 are evaluated first. This allows you to selectively override predefined
1347 rules.
1348
1351 When entering a regular expression argument in the shell command line
1352 it is often necessary to use quoting (enclosing the argument in " " or
1353 ' ') in order to prevent the shell from interpreting certain charac‐
1354 ters, for example, spaces as argument separators and $ as variable
1355 expansions.
1356 Unfortunately it is hard to achieve this in a manner that is portable
1358 across POSIX shells, such as those found on GNU/Linux and UNIX, and
1359 Windows shell. For example, if you use " " for quoting you will get a
1360 wrong result with POSIX shells if your expression contains $. The stan‐
1361 dard way of dealing with this on POSIX systems is to use ' ' instead.
1362 Unfortunately, Windows shell does not remove ' ' from arguments when
1363 they are passed to applications. As a result you may have to use ' '
1364 for POSIX and " " for Windows ($ is not treated as a special character
1365 on Windows).
1366 Alternatively, you can save regular expression options into a file, one
1368 option per line, and use this file with the --options-file option. With
1369 this approach you don't need to worry about shell quoting.
1370
1373 If the input file is not a valid W3C XML Schema definition, xsdcxx will
1374 issue diagnostic messages to STDERR and exit with non-zero exit code.
1375
1377 Send bug reports to the xsd-users@codesynthesis.com mailing list.
1378
1380 Copyright (c) 2005-2017 Code Synthesis Tools CC.
1381 Permission is granted to copy, distribute and/or modify this document
1383 under the terms of the GNU Free Documentation License, version 1.2;
1384 with no Invariant Sections, no Front-Cover Texts and no Back-Cover
1385 Texts. Copy of the license can be obtained from http://codesynthe‐
1386 sis.com/licenses/fdl-1.2.txt
1387XSDCXX 4.1.0 July 2014 XSDCXX(1)