1XSD(1) General Commands Manual XSD(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 --char-type type
61 Generate code using the provided character type instead of the
62 default char. Valid values are char and wchar_t.
63 --char-encoding enc
65 Specify the character encoding that should be used in the gener‐
66 ated code. Valid values for the char character type are utf8
67 (default), iso8859-1,lcp (Xerces-C++ local code page), and cus‐
68 tom. If you pass custom as the value then you will need to
69 include the transcoder implementation header for your encoding
70 at the beginning of the generated header files (see the --hxx-
71 prologue option).
72 For the wchar_t character type the only valid value is auto and
74 the encoding is automatically selected between UTF-16 and
75 UTF-32/UCS-4, depending on the wchar_t type size.
76 --output-dir dir
78 Write generated files to dir instead of the current directory.
79 --namespace-map xns=cns
82 Map XML Schema namespace xns to C++ namespace cns. Repeat this
83 option to specify mapping for more than one XML Schema names‐
84 pace. For example, the following option:
85 --namespace-map http://example.com/foo/bar=foo::bar
87 will map the http://example.com/foo/bar XML Schema namespace to
89 the foo::bar C++ namespace.
90 --namespace-regex regex
92 Add regex to the list of regular expressions used to translate
93 XML Schema namespace names to C++ namespace names. regex is a
94 perl-like regular expression in the form /pattern/replacement/.
95 Any character can be used as a delimiter instead of /. Escaping
96 of the delimiter character in pattern or replacement is not sup‐
97 ported.
98 All the regular expressions are pushed into a stack with the
100 last specified expression considered first. The first match that
101 succeeds is used. Regular expressions are applied to a string in
102 the form
103 filename namespace
105 For example, if you have file hello.xsd with namespace
107 http://example.com/hello and you run xsdcxx on this file, then
108 the string in question will be:
109 hello.xsd. http://example.com/hello
111 For the built-in XML Schema namespace the string is:
113 XMLSchema.xsd http://www.w3.org/2001/XMLSchema
115 The following three steps are performed for each regular expres‐
117 sion until the match is found:
118 1. The expression is applied and if the result is empty the
120 next expression is considered.
121 2. All / are replaced with ::.
123 3. The result is verified to be a valid C++ scope name (e.g.,
125 foo::bar). If this test succeeds, the result is used as a
126 C++ namespace name.
127 As an example, the following expression maps XML Schema names‐
129 paces in the form http://example.com/foo/bar to C++ namespaces
130 in the form foo::bar:
131 %.* http://example.com/(.+)%$1%
133 See also the REGEX AND SHELL QUOTING section below.
135 --namespace-regex-trace
138 Trace the process of applying regular expressions specified with
139 the --namespace-regex option. Use this option to find out why
140 your regular expressions don't do what you expected them to do.
141 --reserved-name name[=rep]
148 Add name to the list of names that should not be used as identi‐
149 fiers. The name can optionally be followed by = and the replace‐
150 ment name that should be used instead. All the C++ keywords are
151 already in this list.
152 --include-with-brackets
159 Use angle brackets (<>) instead of quotes ("") in generated
160 #include directives.
161 --include-prefix prefix
164 Add prefix to generated #include directive paths.
165 For example, if you had the following import element in your
167 schema
168 <import namespace="..." schemaLocation="base.xsd"/>
170 and compiled this fragment with --include-prefix schemas/, then
172 the include directive in the generated code would be:
173 #include schemas/base.hxx
175 --include-regex regex
178 Add regex to the list of regular expressions used to transform
179 #include directive paths. regex is a perl-like regular expres‐
180 sion in the form /pattern/replacement/. Any character can be
181 used as a delimiter instead of /. Escaping of the delimiter
182 character in pattern or replacement is not supported.
183 All the regular expressions are pushed into a stack with the
185 last specified expression considered first. The first match that
186 succeeds is used.
187 As an example, the following expression transforms paths in the
189 form schemas/foo/bar to paths in the form generated/foo/bar:
190 %schemas/(.+)%generated/$1%
192 See also the REGEX AND SHELL QUOTING section below.
194 --include-regex-trace
197 Trace the process of applying regular expressions specified with
198 the --include-regex option. Use this option to find out why your
199 regular expressions don't do what you expected them to do.
200 --guard-prefix prefix
203 Add prefix to generated header inclusion guards. The prefix is
204 transformed to upper case and characters that are illegal in a
205 preprocessor macro name are replaced with underscores. If this
206 option is not specified then the directory part of the input
207 schema file is used as a prefix.
208 --hxx-suffix suffix
212 Use the provided suffix instead of the default .hxx to construct
213 the name of the header file. Note that this suffix is also used
214 to construct names for included/imported schemas.
215 --ixx-suffix suffix
218 Use the provided suffix instead of the default .ixx to construct
219 the name of the inline file.
220 --cxx-suffix suffix
223 Use the provided suffix instead of the default .cxx to construct
224 the name of the source file.
225 --hxx-regex regex
228 Use the provided expression to construct the name of the header
229 file. regex is a perl-like regular expression in the form /pat‐
230 tern/replacement/. Note that this expression is also used to
231 construct names for included/imported schemas. See also the
232 REGEX AND SHELL QUOTING section below.
233 --ixx-regex regex
236 Use the provided expression to construct the name of the inline
237 file. regex is a perl-like regular expression in the form /pat‐
238 tern/replacement/. See also the REGEX AND SHELL QUOTING section
239 below.
240 --cxx-regex regex
243 Use the provided expression to construct the name of the source
244 file. regex is a perl-like regular expression in the form /pat‐
245 tern/replacement/. See also the REGEX AND SHELL QUOTING section
246 below.
247 --hxx-prologue text
250 Insert text at the beginning of the header file.
251 --ixx-prologue text
254 Insert text at the beginning of the inline file.
255 --cxx-prologue text
258 Insert text at the beginning of the source file.
259 --prologue text
262 Insert text at the beginning of each generated file for which
263 there is no file-specific prologue.
264 --hxx-epilogue text
267 Insert text at the end of the header file.
268 --ixx-epilogue text
271 Insert text at the end of the inline file.
272 --cxx-epilogue text
275 Insert text at the end of the source file.
276 --epilogue text
279 Insert text at the end of each generated file for which there is
280 no file-specific epilogue.
281 --hxx-prologue-file file
284 Insert the content of the file at the beginning of the header
285 file.
286 --ixx-prologue-file file
289 Insert the content of the file at the beginning of the inline
290 file.
291 --cxx-prologue-file file
294 Insert the content of the file at the beginning of the source
295 file.
296 --prologue-file file
299 Insert the content of the file at the beginning of each gener‐
300 ated file for which there is no file-specific prologue file.
301 --hxx-epilogue-file file
304 Insert the content of the file at the end of the header file.
305 --ixx-epilogue-file file
308 Insert the content of the file at the end of the inline file.
309 --cxx-epilogue-file file
312 Insert the content of the file at the end of the source file.
313 --epilogue-file file
316 Insert the content of the file at the end of each generated file
317 for which there is no file-specific epilogue file.
318 --custom-literals file
321 Load custom XML string to C++ literal mappings from file. This
322 mechanism can be useful if you are using a custom character
323 encoding and some of the strings in your schemas, for example
324 element/attribute names or enumeration values, contain non-ASCII
325 characters. In this case you will need to provide a custom map‐
326 ping to C++ literals for such strings. The format of this file
327 is specified in the custom-literals.xsd XML Schema file that can
328 be found in the documentation directory.
329 --export-symbol symbol
332 Insert symbol in places where DLL export/import control state‐
333 ments ( __declspec(dllexport/dllimport)) are necessary.
334 --export-xml-schema
337 Export/import types in the XML Schema namespace using the export
338 symbol provided with the --export-symbol option. The
339 XSD_NO_EXPORT macro can be used to omit this code during C++
340 compilation, which may be useful if you would like to use the
341 same generated code across multiple platforms.
342 --export-maps
345 Export polymorphism support maps from a Win32 DLL into which
346 this generated code is linked. This is necessary when your type
347 hierarchy is split across several DLLs since otherwise each DLL
348 will have its own set of maps. In this situation the generated
349 code for the DLL which contains base types and/or substitution
350 group heads should be compiled with this option and the gener‐
351 ated code for all other DLLs should be compiled with --import-
352 maps. This option is only valid together with --generate-poly‐
353 morphic. The XSD_NO_EXPORT macro can be used to omit this code
354 during C++ compilation, which may be useful if you would like to
355 use the same generated code across multiple platforms.
356 --import-maps
359 Import polymorphism support maps to a Win32 DLL or executable
360 into which this generated code is linked. See the --export-maps
361 option documentation for details. This option is only valid
362 together with --generate-polymorphic. The XSD_NO_EXPORT macro
363 can be used to omit this code during C++ compilation, which may
364 be useful if you would like to use the same generated code
365 across multiple platforms.
366 --disable-warning warn
369 Disable printing warning with id warn. If all is specified for
370 the warning id then all warnings are disabled.
371 --show-sloc
374 Show the number of generated physical source lines of code
375 (SLOC).
376 --sloc-limit num
379 Check that the number of generated physical source lines of code
380 (SLOC) does not exceed num.
381 --options-file file
384 Read additional options from file. Each option should appear on
385 a separate line optionally followed by space and an argument.
386 Empty lines and lines starting with # are ignored. The semantics
387 of providing options in a file is equivalent to providing the
388 same set of options in the same order in the command line at the
389 point where the --options-file option is specified except that
390 shell escaping and quoting is not required. Repeat this option
391 to specify more than one options files.
392 --proprietary-license
395 Indicate that the generated code is licensed under a proprietary
396 license instead of the GPL.
397 --preserve-anonymous
400 Preserve anonymous types. By default anonymous types are auto‐
401 matically named with names derived from the enclosing ele‐
402 ments/attributes. Because mappings implemented by this compiler
403 require all types to be named, this option is only useful if you
404 want to make sure your schemas don't have anonymous types.
405 --show-anonymous
408 Show elements and attributes that are of anonymous types. This
409 option only makes sense together with the --preserve-anonymous
410 option.
411 --anonymous-regex regex
414 Add regex to the list of regular expressions used to derive
415 names for anonymous types from the enclosing attributes/ele‐
416 ments. regex is a perl-like regular expression in the form
417 /pattern/replacement/. Any character can be used as a delimiter
418 instead of /. Escaping of the delimiter character in pattern or
419 replacement is not supported.
420 All the regular expressions are pushed into a stack with the
422 last specified expression considered first. The first match that
423 succeeds is used. Regular expressions are applied to a string in
424 the form
425 filename namespace xpath
427 For instance:
429 hello.xsd http://example.com/hello element
431 hello.xsd http://example.com/hello type/element
433 As an example, the following expression makes all the derived
435 names start with capital letters. This could be useful when your
436 naming convention requires type names to start with capital let‐
437 ters:
438 %.* .* (.+/)*(.+)%\u$2%
440 See also the REGEX AND SHELL QUOTING section below.
442 --anonymous-regex-trace
445 Trace the process of applying regular expressions specified with
446 the --anonymous-regex option. Use this option to find out why
447 your regular expressions don't do what you expected them to do.
448 --location-map ol=nl
451 Map the original schema location ol that is specified in the XML
452 Schema include or import elements to new schema location nl.
453 Repeat this option to map more than one schema location. For
454 example, the following option maps the http://exam‐
455 ple.com/foo.xsd URL to the foo.xsd local file.
456 --location-map http://example.com/foo.xsd=foo.xsd
458 --location-regex regex
461 Add regex to the list of regular expressions used to map schema
462 locations that are specified in the XML Schema include or import
463 elements. regex is a perl-like regular expression in the form
464 /pattern/replacement/. Any character can be used as a delimiter
465 instead of /. Escaping of the delimiter character in pattern or
466 replacement is not supported. All the regular expressions are
467 pushed into a stack with the last specified expression consid‐
468 ered first. The first match that succeeds is used.
469 For example, the following expression maps URL locations in the
471 form http://example.com/foo/bar.xsd to local files in the form
472 bar.xsd:
473 %http://.+/(.+)%$1%
475 See also the REGEX AND SHELL QUOTING section below.
477 --location-regex-trace
480 Trace the process of applying regular expressions specified with
481 the --location-regex option. Use this option to find out why
482 your regular expressions don't do what you expected them to do.
483 --file-per-type
486 Generate a separate set of C++ files for each type defined in
487 XML Schema. Note that in this mode you only need to compile the
488 root schema(s) and the code will be generated for all included
489 and imported schemas. This compilation mode is primarily useful
490 when some of your schemas cannot be compiled separately or have
491 cyclic dependencies which involve type inheritance. Other
492 options related to this mode are: --type-file-regex, --schema-
493 file-regex, and --file-list.
494 --type-file-regex regex
497 Add regex to the list of regular expressions used to translate
498 type names to file names when the --file-per-type option is
499 specified. regex is a perl-like regular expression in the form
500 /pattern/replacement/. Any character can be used as a delimiter
501 instead of /. Escaping of the delimiter character in pattern or
502 replacement is not supported. All the regular expressions are
503 pushed into a stack with the last specified expression consid‐
504 ered first. The first match that succeeds is used. Regular
505 expressions are applied to a string in the form
506 namespace type-name
508 For example, the following expression maps type foo that is
510 defined in the http://example.com/bar namespace to file name
511 bar-foo:
512 %http://example.com/(.+) (.+)%$1-$2%
514 See also the REGEX AND SHELL QUOTING section below.
516 --type-file-regex-trace
519 Trace the process of applying regular expressions specified with
520 the --type-file-regex option. Use this option to find out why
521 your regular expressions don't do what you expected them to do.
522 --schema-file-regex regex
525 Add regex to the list of regular expressions used to translate
526 schema file names when the --file-per-type option is specified.
527 regex is a perl-like regular expression in the form /pat‐
528 tern/replacement/. Any character can be used as a delimiter
529 instead of /. Escaping of the delimiter character in pattern or
530 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. Regular
533 expressions are applied to the absolute filesystem path of a
534 schema file and the result, including the directory part, if
535 any, is used to derive the #include directive paths as well as
536 the generated C++ file paths. This option, along with --type-
537 file-regex are primarily used to place the generated files into
538 subdirectories or to resolve file name conflicts.
539 For example, the following expression maps schema files in the
541 foo/1.0.0/ subdirectory to the files in the foo/ subdirectory.
542 As a result, the #include directive paths for such schemas will
543 be in the foo/schema.hxx form and the generated C++ files will
544 be placed into the foo/ subdirectory:
545 %.*/foo/1.0.0/(.+)%foo/$1%
547 See also the REGEX AND SHELL QUOTING section below.
549 --schema-file-regex-trace
552 Trace the process of applying regular expressions specified with
553 the --schema-file-regex option. Use this option to find out why
554 your regular expressions don't do what you expected them to do.
555 --file-list file
558 Write a list of generated C++ files to file. This option is
559 primarily useful in the file-per-type compilation mode (--file-
560 per-type) to create a list of generated C++ files, for example,
561 as a makefile fragment.
562 --file-list-prologue text
565 Insert text at the beginning of the file list. As a convenience,
566 all occurrences of the \n character sequence in text are
567 replaced with new lines. This option can, for example, be used
568 to assign the generated file list to a makefile variable.
569 --file-list-epilogue text
572 Insert text at the end of the file list. As a convenience, all
573 occurrences of the \n character sequence in text are replaced
574 with new lines.
575 --file-list-delim text
578 Delimit file names written to the file list with text instead of
579 new lines. As a convenience, all occurrences of the \n character
580 sequence in text are replaced with new lines.
581 cxx-tree command options
584 --generate-polymorphic
585 Generate polymorphism-aware code. Specify this option if you use
586 substitution groups or xsi:type. Use the --polymorphic-type or
587 --polymorphic-type-all option to specify which type hierarchies
588 are polymorphic.
589 --polymorphic-type type
592 Indicate that type is a root of a polymorphic type hierarchy.
593 The compiler can often automatically determine which types are
594 polymorphic based on the substitution group declarations. How‐
595 ever, you may need to use this option if you are not using sub‐
596 stitution groups or if substitution groups are defined in
597 another schema. You need to specify this option when compiling
598 every schema file that references type. The type argument is an
599 XML Schema type name that can be optionally qualified with a
600 namespace in the namespace#name form.
601 --polymorphic-type-all
604 Indicate that all types should be treated as polymorphic.
605 --generate-serialization
608 Generate serialization functions. Serialization functions con‐
609 vert the object model back to XML.
610 --generate-inline
613 Generate simple functions inline. This option triggers creation
614 of the inline file.
615 --generate-ostream
618 Generate ostream insertion operators (operator<<) for generated
619 types. This allows to easily print a fragment or the whole
620 object model for debugging or logging.
621 --generate-doxygen
624 Generate documentation comments suitable for extraction by the
625 Doxygen documentation system. Documentation from annotations is
626 added to the comments if present in the schema.
627 --generate-comparison
630 Generate comparison operators (operator== and operator!=) for
631 complex types. Comparison is performed memberwise.
632 --generate-default-ctor
635 Generate default constructors even for types that have required
636 members. Required members of an instance constructed using such
637 a constructor are not initialized and accessing them results in
638 undefined behavior.
639 --generate-from-base-ctor
642 Generate constructors that expect an instance of a base type
643 followed by all required members.
644 --generate-detach
647 Generate detach functions for required elements and attributes
648 (detach functions for optional and sequence cardinalities are
649 provided by the respective containers). These functions, for
650 example, allow you to move sub-trees in the object model either
651 within the same tree or between different trees.
652 --generate-wildcard
655 Generate accessors and modifiers as well as parsing and serial‐
656 ization code for XML Schema wildcards (any and anyAttribute).
657 XML content matched by wildcards is presented as DOM fragments.
658 Note that you need to initialize the Xerces-C++ runtime if you
659 are using this option.
660 --generate-insertion os
663 Generate data representation stream insertion operators for the
664 os output stream type. Repeat this option to specify more than
665 one stream type. The ACE CDR stream (ACE_OutputCDR) and RPC XDR
666 are recognized by the compiler and the necessary #include direc‐
667 tives are automatically generated. For custom stream types use
668 the --hxx-prologue* options to provide the necessary declara‐
669 tions.
670 --generate-extraction is
673 Generate data representation stream extraction constructors for
674 the is input stream type. Repeat this option to specify more
675 than one stream type. The ACE CDR stream (ACE_InputCDR) and RPC
676 XDR are recognized by the compiler and the necessary #include
677 directives are automatically generated. For custom stream types
678 use the --hxx-prologue* options to provide the necessary decla‐
679 rations.
680 --generate-forward
683 Generate a separate header file with forward declarations for
684 the types being generated.
685 --generate-xml-schema
688 Generate a C++ header file as if the schema being compiled
689 defines the XML Schema namespace. In particular, the resulting
690 file will have definitions for all XML Schema built-in types.
691 The schema file provided to the compiler need not exist and is
692 only used to derive the name of the resulting header file. Use
693 the --extern-xml-schema option to include this file in the gen‐
694 erated files for other schemas.
695 --extern-xml-schema file
698 Include a header file derived from file instead of generating
699 the XML Schema namespace mapping inline. The provided file need
700 not exist and is only used to derive the name of the included
701 header file. Use the --generate-xml-schema option to generate
702 this header file.
703 --suppress-parsing
706 Suppress the generation of the parsing functions and construc‐
707 tors. Use this option to reduce the generated code size when
708 parsing from XML is not needed.
709 --generate-element-type
712 Generate types instead of parsing and serialization functions
713 for root elements. This is primarily useful to distinguish
714 object models with the same root type but with different root
715 elements.
716 --generate-element-map
719 Generate a root element map that allows uniform parsing and
720 serialization of multiple root elements. This option is only
721 valid together with --generate-element-type.
722 --generate-intellisense
725 Generate workarounds for IntelliSense bugs in Visual Studio 2005
726 (8.0). When this option is used, the resulting code is slightly
727 more verbose. IntelliSense in Visual Studio 2008 (9.0) does not
728 require these workarounds. Support for IntelliSense in Visual
729 Studio 2003 (7.1) is improved with this option but is still
730 incomplete.
731 --omit-default-attributes
734 Omit attributes with default and fixed values from serialized
735 XML documents.
736 --type-naming style
743 Specify the type naming convention that should be used in the
744 generated code. Valid styles are knr (default), ucc, and java.
745 See the NAMING CONVENTION section below for more information.
746 --function-naming style
749 Specify the function naming convention that should be used in
750 the generated code. Valid styles are knr (default), lcc, and
751 java. See the NAMING CONVENTION section below for more informa‐
752 tion.
753 --type-regex regex
756 Add regex to the list of regular expressions used to translate
757 XML Schema type names to C++ type names. See the NAMING CONVEN‐
758 TION section below for more information.
759 --accessor-regex regex
762 Add regex to the list of regular expressions used to translate
763 XML Schema names of elements/attributes to C++ accessor function
764 names. See the NAMING CONVENTION section below for more informa‐
765 tion.
766 --one-accessor-regex regex
769 Add regex to the list of regular expressions used to translate
770 XML Schema names of elements/attributes with cardinality one to
771 C++ accessor function names. See the NAMING CONVENTION section
772 below for more information.
773 --opt-accessor-regex regex
776 Add regex to the list of regular expressions used to translate
777 XML Schema names of elements/attributes with cardinality
778 optional to C++ accessor function names. See the NAMING CONVEN‐
779 TION section below for more information.
780 --seq-accessor-regex regex
783 Add regex to the list of regular expressions used to translate
784 XML Schema names of elements/attributes with cardinality
785 sequence to C++ accessor function names. See the NAMING CONVEN‐
786 TION section below for more information.
787 --modifier-regex regex
790 Add regex to the list of regular expressions used to translate
791 XML Schema names of elements/attributes to C++ modifier function
792 names. See the NAMING CONVENTION section below for more informa‐
793 tion.
794 --one-modifier-regex regex
797 Add regex to the list of regular expressions used to translate
798 XML Schema names of elements/attributes with cardinality one to
799 C++ modifier function names. See the NAMING CONVENTION section
800 below for more information.
801 --opt-modifier-regex regex
804 Add regex to the list of regular expressions used to translate
805 XML Schema names of elements/attributes with cardinality
806 optional to C++ modifier function names. See the NAMING CONVEN‐
807 TION section below for more information.
808 --seq-modifier-regex regex
811 Add regex to the list of regular expressions used to translate
812 XML Schema names of elements/attributes with cardinality
813 sequence to C++ modifier function names. See the NAMING CONVEN‐
814 TION section below for more information.
815 --parser-regex regex
818 Add regex to the list of regular expressions used to translate
819 XML Schema element names to C++ parsing function names. See the
820 NAMING CONVENTION section below for more information.
821 --serializer-regex regex
824 Add regex to the list of regular expressions used to translate
825 XML Schema element names to C++ serialization function names.
826 See the NAMING CONVENTION section below for more information.
827 --enumerator-regex regex
830 Add regex to the list of regular expressions used to translate
831 XML Schema enumeration values to C++ enumerator names. See the
832 NAMING CONVENTION section below for more information.
833 --element-type-regex regex
836 Add regex to the list of regular expressions used to translate
837 XML Schema element names to C++ element type names. See the NAM‐
838 ING CONVENTION section below for more information.
839 --name-regex-trace
842 Trace the process of applying regular expressions specified with
843 the name transformation options. Use this option to find out why
844 your regular expressions don't do what you expected them to do.
845 --root-element-first
852 Treat only the first global element as a document root. By
853 default all global elements are considered document roots.
854 --root-element-last
857 Treat only the last global element as a document root. By
858 default all global elements are considered document roots.
859 --root-element-all
862 Treat all global elements as document roots. This is the default
863 behavior. By explicitly specifying this option you can suppress
864 the warning that is issued if more than one global element is
865 defined.
866 --root-element-none
869 Do not treat any global elements as document roots. By default
870 all global elements are considered document roots.
871 --root-element element
874 Treat only element as a document root. Repeat this option to
875 specify more than one root element.
876 --custom-type name[=type[/base]]
883 Use a custom C++ type type instead of the generated class for
884 XML Schema type name. If type is not present or empty then the
885 custom type is assumed to have the same name and be defined in
886 the same namespace as the generated class would have. If base is
887 specified then the generated class is still generated but with
888 that name.
889 --custom-type-regex /name-pat/[type-sub/[base-sub/]]
892 For each type defined in XML Schema that matches the name-pat
893 pattern use a custom C++ type instead of the generated class.
894 The name of the custom type is obtained by substituting type-
895 sub. If type-sub is not present or its substitution results in
896 an empty string then the custom type is assumed to have the same
897 name and be defined in the same namespace as the generated class
898 would have. If base-sub is present and its substitution results
899 in a non-empty string then the generated class is still gener‐
900 ated but with the result of substitution as its name. The pat‐
901 tern and substitutions are in the perl regular expression for‐
902 mat. See also the REGEX AND SHELL QUOTING section below.
903 --fwd-suffix suffix
910 Use the provided suffix instead of the default -fwd.hxx to con‐
911 struct the name of the forward declaration file.
912 --fwd-regex regex
915 Use the provided expression to construct the name of the forward
916 declaration file. regex is a perl-like regular expression in
917 the form /pattern/replacement/. See also the REGEX AND SHELL
918 QUOTING section below.
919 --fwd-prologue text
922 Insert text at the beginning of the forward declaration file.
923 --fwd-epilogue text
926 Insert text at the end of the forward declaration file.
927 --fwd-prologue-file file
930 Insert the content of the file at the beginning of the forward
931 declaration file.
932 --fwd-epilogue-file file
935 Insert the content of the file at the end of the forward decla‐
936 ration file.
937 --parts num
944 Split generated source code into num parts. This is useful when
945 translating large, monolithic schemas and a C++ compiler is not
946 able to compile the resulting source code at once (usually due
947 to insufficient memory).
948 --parts-suffix suffix
951 Use suffix instead of the default '-' to separate the file name
952 from the part number.
953 cxx-parser command options
960 --type-map mapfile
961 Read XML Schema to C++ type mapping information from mapfile
962 Repeat this option to specify several type maps. Type maps are
963 considered in order of appearance and the first match is used.
964 By default all user-defined types are mapped to void. See the
965 TYPE MAP section below for more information.
966 --xml-parser parser
969 Use parser as the underlying XML parser. Valid values are xerces
970 for Xerces-C++ (default) and expat for Expat.
971 --generate-inline
974 Generate simple functions inline. This option triggers creation
975 of the inline file.
976 --generate-validation
979 Generate validation code ("perfect" parser) which ensures that
980 instance documents conform to the schema. Validation code is
981 generated by default when the selected underlying XML parser is
982 non-validating (expat).
983 --suppress-validation
986 Suppress the generation of validation code ("perfect" parser).
987 Validation is suppressed by default when the selected underlying
988 XML parser is validating (xerces).
989 --generate-polymorphic
992 Generate polymorphism-aware code. Specify this option if you use
993 substitution groups or xsi:type.
994 --generate-noop-impl
997 Generate a sample parser implementation that does nothing (no
998 operation). The sample implementation can then be filled with
999 the application-specific code. For an input file in the form
1000 name.xsd this option triggers the generation of the two addi‐
1001 tional C++ files in the form: name-pimpl.hxx (parser implementa‐
1002 tion header file) and name-pimpl.cxx (parser implementation
1003 source file).
1004 --generate-print-impl
1007 Generate a sample parser implementation that prints the XML data
1008 to STDOUT. For an input file in the form name.xsd this option
1009 triggers the generation of the two additional C++ files in the
1010 form: name-pimpl.hxx (parser implementation header file) and
1011 name-pimpl.cxx (parser implementation source file).
1012 --generate-test-driver
1015 Generate a test driver for the sample parser implementation. For
1016 an input file in the form name.xsd this option triggers the gen‐
1017 eration of an additional C++ file in the form name-driver.cxx.
1018 --force-overwrite
1021 Force overwriting of the existing implementation and test driver
1022 files. Use this option only if you do not mind loosing the
1023 changes you have made in the sample implementation or test
1024 driver files.
1025 --root-element-first
1028 Indicate that the first global element is the document root.
1029 This information is used to generate the test driver for the
1030 sample implementation.
1031 --root-element-last
1034 Indicate that the last global element is the document root. This
1035 information is used to generate the test driver for the sample
1036 implementation.
1037 --root-element element
1040 Indicate that element is the document root. This information is
1041 used to generate the test driver for the sample implementation.
1042 --generate-xml-schema
1045 Generate a C++ header file as if the schema being compiled
1046 defines the XML Schema namespace. In particular, the resulting
1047 file will have definitions for all parser skeletons and imple‐
1048 mentations corresponding to the XML Schema built-in types. The
1049 schema file provided to the compiler need not exist and is only
1050 used to derive the name of the resulting header file. Use the
1051 --extern-xml-schema option to include this file in the generated
1052 files for other schemas.
1053 --extern-xml-schema file
1056 Include a header file derived from file instead of generating
1057 the XML Schema namespace mapping inline. The provided file need
1058 not exist and is only used to derive the name of the included
1059 header file. Use the --generate-xml-schema option to generate
1060 this header file.
1061 --skel-type-suffix suffix
1064 Use the provided suffix instead of the default _pskel to con‐
1065 struct the names of generated parser skeletons.
1066 --skel-file-suffix suffix
1069 Use the provided suffix instead of the default -pskel to con‐
1070 struct the names of generated parser skeleton files.
1071 --impl-type-suffix suffix
1074 Use the provided suffix instead of the default _pimpl to con‐
1075 struct the names of parser implementations for the built-in XML
1076 Schema types and sample parser implementations.
1077 --impl-file-suffix suffix
1080 Use the provided suffix instead of the default -pimpl to con‐
1081 struct the names of generated sample parser implementation
1082 files.
1083
1090 The compiler can be instructed to use a particular naming convention in
1091 the generated code. A number of widely-used conventions can be selected
1092 using the --type-naming and --function-naming options. A custom naming
1093 convention can be achieved using the --type-regex, --accessor-regex,
1094 --one-accessor-regex, --opt-accessor-regex, --seq-accessor-regex,
1095 --modifier-regex, --one-modifier-regex, --opt-modifier-regex, --seq-
1096 modifier-regex, --parser-regex, --serializer-regex, --enumerator-regex,
1097 and --element-type-regex options.
1098 The --type-naming option specifies the convention that should be used
1100 for naming C++ types. Possible values for this option are knr
1101 (default), ucc, and java. The knr value (stands for K&R) signifies the
1102 standard, lower-case naming convention with the underscore used as a
1103 word delimiter, for example: foo, foo_bar. The ucc (stands for upper-
1104 camel-case) and java values a synonyms for the same naming convention
1105 where the first letter of each word in the name is capitalized, for
1106 example: Foo, FooBar.
1107 Similarly, the --function-naming option specifies the convention that
1109 should be used for naming C++ functions. Possible values for this
1110 option are knr (default), lcc, and java. The knr value (stands for
1111 K&R) signifies the standard, lower-case naming convention with the
1112 underscore used as a word delimiter, for example: foo(), foo_bar().
1113 The lcc value (stands for lower-camel-case) signifies a naming conven‐
1114 tion where the first letter of each word except the first is capital‐
1115 ized, for example: foo(), fooBar(). The java naming convention is simi‐
1116 lar to the lower-camel-case one except that accessor functions are pre‐
1117 fixed with get, modifier functions are prefixed with set, parsing func‐
1118 tions are prefixed with parse, and serialization functions are prefixed
1119 with serialize, for example: getFoo(), setFooBar(), parseRoot(), seri‐
1120 alizeRoot().
1121 Note that the naming conventions specified with the --type-naming and
1123 --function-naming options perform only limited transformations on the
1124 names that come from the schema in the form of type, attribute, and
1125 element names. In other words, to get consistent results, your schemas
1126 should follow a similar naming convention as the one you would like to
1127 have in the generated code. Alternatively, you can use the --*-regex
1128 options (discussed below) to perform further transformations on the
1129 names that come from the schema.
1130 The --type-regex, --accessor-regex, --one-accessor-regex, --opt-acces‐
1132 sor-regex, --seq-accessor-regex, --modifier-regex, --one-modifier-
1133 regex, --opt-modifier-regex, --seq-modifier-regex, --parser-regex,
1134 --serializer-regex, --enumerator-regex, and --element-type-regex
1135 options allow you to specify extra regular expressions for each name
1136 category in addition to the predefined set that is added depending on
1137 the --type-naming and --function-naming options. Expressions that are
1138 provided with the --*-regex options are evaluated prior to any prede‐
1139 fined expressions. This allows you to selectively override some or all
1140 of the predefined transformations. When debugging your own expres‐
1141 sions, it is often useful to see which expressions match which names.
1142 The --name-regex-trace option allows you to trace the process of apply‐
1143 ing regular expressions to names.
1144 The value for the --*-regex options should be a perl-like regular
1146 expression in the form /pattern/replacement/. Any character can be
1147 used as a delimiter instead of /. Escaping of the delimiter character
1148 in pattern or replacement is not supported. All the regular expressions
1149 for each category are pushed into a category-specific stack with the
1150 last specified expression considered first. The first match that suc‐
1151 ceeds is used. For the --one-accessor-regex (accessors with cardinality
1152 one), --opt-accessor-regex (accessors with cardinality optional), and
1153 --seq-accessor-regex (accessors with cardinality sequence) categories
1154 the --accessor-regex expressions are used as a fallback. For the --one-
1155 modifier-regex, --opt-modifier-regex, and --seq-modifier-regex cate‐
1156 gories the --modifier-regex expressions are used as a fallback. For the
1157 --element-type-regex category the --type-regex expressions are used as
1158 a fallback.
1159 The type name expressions (--type-regex) are evaluated on the name
1161 string that has the following format:
1162 [namespace ]name[,name][,name][,name]
1164 The element type name expressions (--element-type-regex), effective
1166 only when the --generate-element-type option is specified, are evalu‐
1167 ated on the name string that has the following format:
1168 namespace name
1170 In the type name format the namespace part followed by a space is only
1172 present for global type names. For global types and elements defined in
1173 schemas without a target namespace, the namespace part is empty but the
1174 space is still present. In the type name format after the initial name
1175 component, up to three additional name components can be present, sepa‐
1176 rated by commas. For example:
1177 http://example.com/hello type
1179 foo
1181 foo,iterator
1183 foo,const,iterator
1185 The following set of predefined regular expressions is used to trans‐
1187 form type names when the upper-camel-case naming convention is
1188 selected:
1189 /(?:[^ ]* )?([^,]+)/\u$1/
1191 /(?:[^ ]* )?([^,]+),([^,]+)/\u$1\u$2/
1193 /(?:[^ ]* )?([^,]+),([^,]+),([^,]+)/\u$1\u$2\u$3/
1195 /(?:[^ ]* )?([^,]+),([^,]+),([^,]+),([^,]+)/\u$1\u$2\u$3\u$4/
1197 The accessor and modifier expressions (--*accessor-regex and --*modi‐
1199 fier-regex) are evaluated on the name string that has the following
1200 format:
1201 name[,name][,name]
1203 After the initial name component, up to two additional name components
1205 can be present, separated by commas. For example:
1206 foo
1208 dom,document
1210 foo,default,value
1212 The following set of predefined regular expressions is used to trans‐
1214 form accessor names when the java naming convention is selected:
1215 /([^,]+)/get\u$1/
1217 /([^,]+),([^,]+)/get\u$1\u$2/
1219 /([^,]+),([^,]+),([^,]+)/get\u$1\u$2\u$3/
1221 For the parser, serializer, and enumerator categories, the correspond‐
1223 ing regular expressions are evaluated on local names of elements and on
1224 enumeration values, respectively. For example, the following predefined
1225 regular expression is used to transform parsing function names when the
1226 java naming convention is selected:
1227 /(.+)/parse\u$1/
1229 See also the REGEX AND SHELL QUOTING section below.
1231
1237 Type map files are used in C++/Parser to define a mapping between XML
1238 Schema and C++ types. The compiler uses this information to determine
1239 the return types of post_* functions in parser skeletons corresponding
1240 to XML Schema types as well as argument types for callbacks correspond‐
1241 ing to elements and attributes of these types.
1242 The compiler has a set of predefined mapping rules that map built-in
1244 XML Schema types to suitable C++ types (discussed below) and all other
1245 types to void. By providing your own type maps you can override these
1246 predefined rules. The format of the type map file is presented below:
1247 namespace schema-namespace [ cxx-namespace ]
1249 {
1250 ( include file-name; )*
1251 ([ type ] schema-type cxx-ret-type [ cxx-arg-type ]; )*
1252 }
1253 Both schema-namespace and schema-type are regex patterns while cxx-
1255 namespace, cxx-ret-type, and cxx-arg-type are regex pattern substitu‐
1256 tions. All names can be optionally enclosed in " ", for example, to
1257 include white-spaces.
1258 schema-namespace determines XML Schema namespace. Optional cxx-names‐
1260 pace is prefixed to every C++ type name in this namespace declaration.
1261 cxx-ret-type is a C++ type name that is used as a return type for the
1262 post_* functions. Optional cxx-arg-type is an argument type for call‐
1263 back functions corresponding to elements and attributes of this type.
1264 If cxx-arg-type is not specified, it defaults to cxx-ret-type if cxx-
1265 ret-type ends with * or & (that is, it is a pointer or a reference) and
1266 const cxx-ret-type& otherwise. file-name is a file name either in the
1267 " " or < > format and is added with the #include directive to the gen‐
1268 erated code.
1269 The # character starts a comment that ends with a new line or end of
1271 file. To specify a name that contains # enclose it in " ". For example:
1272 namespace http://www.example.com/xmlns/my my
1274 {
1275 include "my.hxx";
1276 # Pass apples by value.
1278 #
1279 apple apple;
1280 # Pass oranges as pointers.
1282 #
1283 orange orange_t*;
1284 }
1285 In the example above, for the http://www.example.com/xmlns/my#orange
1287 XML Schema type, the my::orange_t* C++ type will be used as both return
1288 and argument types.
1289 Several namespace declarations can be specified in a single file. The
1291 namespace declaration can also be completely omitted to map types in a
1292 schema without a namespace. For instance:
1293 include "my.hxx";
1295 apple apple;
1296 namespace http://www.example.com/xmlns/my
1298 {
1299 orange "const orange_t*";
1300 }
1301 The compiler has a number of predefined mapping rules that can be pre‐
1304 sented as the following map files. The string-based XML Schema built-in
1305 types are mapped to either std::string or std::wstring depending on the
1306 character type selected with the --char-type option (char by default).
1307 namespace http://www.w3.org/2001/XMLSchema
1309 {
1310 boolean bool bool;
1311 byte "signed char" "signed char";
1313 unsignedByte "unsigned char" "unsigned char";
1314 short short short;
1316 unsignedShort "unsigned short" "unsigned short";
1317 int int int;
1319 unsignedInt "unsigned int" "unsigned int";
1320 long "long long" "long long";
1322 unsignedLong "unsigned long long" "unsigned long long";
1323 integer "long long" "long long";
1325 negativeInteger "long long" "long long";
1327 nonPositiveInteger "long long" "long long";
1328 positiveInteger "unsigned long long" "unsigned long long";
1330 nonNegativeInteger "unsigned long long" "unsigned long long";
1331 float float float;
1333 double double double;
1334 decimal double double;
1335 string std::string;
1337 normalizedString std::string;
1338 token std::string;
1339 Name std::string;
1340 NMTOKEN std::string;
1341 NCName std::string;
1342 ID std::string;
1343 IDREF std::string;
1344 language std::string;
1345 anyURI std::string;
1346 NMTOKENS xml_schema::string_sequence;
1348 IDREFS xml_schema::string_sequence;
1349 QName xml_schema::qname;
1351 base64Binary std::auto_ptr<xml_schema::buffer>
1353 std::auto_ptr<xml_schema::buffer>;
1354 hexBinary std::auto_ptr<xml_schema::buffer>
1355 std::auto_ptr<xml_schema::buffer>;
1356 date xml_schema::date;
1358 dateTime xml_schema::date_time;
1359 duration xml_schema::duration;
1360 gDay xml_schema::gday;
1361 gMonth xml_schema::gmonth;
1362 gMonthDay xml_schema::gmonth_day;
1363 gYear xml_schema::gyear;
1364 gYearMonth xml_schema::gyear_month;
1365 time xml_schema::time;
1366 }
1367 The last predefined rule maps anything that wasn't mapped by previous
1370 rules to void:
1371 namespace .*
1373 {
1374 .* void void;
1375 }
1376 When you provide your own type maps with the --type-map option, they
1378 are evaluated first. This allows you to selectively override predefined
1379 rules.
1380
1383 When entering a regular expression argument in the shell command line
1384 it is often necessary to use quoting (enclosing the argument in " " or
1385 ' ') in order to prevent the shell from interpreting certain charac‐
1386 ters, for example, spaces as argument separators and $ as variable
1387 expansions.
1388 Unfortunately it is hard to achieve this in a manner that is portable
1390 across POSIX shells, such as those found on GNU/Linux and UNIX, and
1391 Windows shell. For example, if you use " " for quoting you will get a
1392 wrong result with POSIX shells if your expression contains $. The stan‐
1393 dard way of dealing with this on POSIX systems is to use ' ' instead.
1394 Unfortunately, Windows shell does not remove ' ' from arguments when
1395 they are passed to applications. As a result you may have to use ' '
1396 for POSIX and " " for Windows ($ is not treated as a special character
1397 on Windows).
1398 Alternatively, you can save regular expression options into a file, one
1400 option per line, and use this file with the --options-file option. With
1401 this approach you don't need to worry about shell quoting.
1402
1405 If the input file is not a valid W3C XML Schema definition, xsdcxx will
1406 issue diagnostic messages to STDERR and exit with non-zero exit code.
1407
1409 Send bug reports to the xsd-users@codesynthesis.com mailing list.
1410
1412 Copyright (c) 2005-2010 Code Synthesis Tools CC.
1413 Permission is granted to copy, distribute and/or modify this document
1415 under the terms of the GNU Free Documentation License, version 1.2;
1416 with no Invariant Sections, no Front-Cover Texts and no Back-Cover
1417 Texts. Copy of the license can be obtained from http://codesynthe‐
1418 sis.com/licenses/fdl-1.2.txt
1419XSD 3.3.0 April 2010 XSD(1)