From a5c8188bef470c73db144fdf9bc2e93c230c99c9 Mon Sep 17 00:00:00 2001
From: Toyosatomimi no Miko <110693261+mikomikotaishi@users.noreply.github.com>
Date: Sat, 22 Nov 2025 17:26:39 -0500
Subject: [PATCH] Add support for C++ modules
---
CMakeLists.txt | 41 ++++++++++
readme.md | 201 ++++++++++++++++++++++++++++---------------------
tinyxml2.cppm | 71 +++++++++++++++++
tinyxml2.h | 17 ++++-
xmltest.cpp | 25 ++++++
5 files changed, 266 insertions(+), 89 deletions(-)
create mode 100644 tinyxml2.cppm
diff --git a/CMakeLists.txt b/CMakeLists.txt
index b7bdf86a..fea20eb3 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -4,6 +4,12 @@ project(tinyxml2 VERSION 11.0.0)
include(CTest)
option(tinyxml2_BUILD_TESTING "Build tests for tinyxml2" "${BUILD_TESTING}")
+if (CMAKE_VERSION VERSION_GREATER_EQUAL 3.28)
+ option(tinyxml2_BUILD_MODULE "Build C++ module for tinyxml2" OFF)
+else ()
+ set(tinyxml2_BUILD_MODULE OFF)
+endif ()
+
##
## Honor tinyxml2_SHARED_LIBS to match install interface
##
@@ -55,6 +61,30 @@ if (tinyxml2_BUILD_TESTING)
set_tests_properties(xmltest PROPERTIES PASS_REGULAR_EXPRESSION ", Fail 0")
endif ()
+##
+## C++ Module build
+##
+
+if (tinyxml2_BUILD_MODULE AND CMAKE_VERSION VERSION_GREATER_EQUAL 3.28)
+
+ add_library(tinyxml2_module)
+ target_sources(tinyxml2_module
+ PUBLIC
+ FILE_SET CXX_MODULES FILES
+ tinyxml2.cppm
+ )
+ target_link_libraries(tinyxml2_module PUBLIC tinyxml2::tinyxml2)
+ target_compile_features(tinyxml2_module PUBLIC cxx_std_20)
+ add_library(tinyxml2::tinyxml2_module ALIAS tinyxml2_module)
+
+ set_target_properties(
+ tinyxml2_module
+ PROPERTIES
+ VERSION "${tinyxml2_VERSION}"
+ SOVERSION "${tinyxml2_VERSION_MAJOR}"
+ )
+endif ()
+
##
## Installation
##
@@ -83,6 +113,17 @@ install(
INCLUDES DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
)
+if (tinyxml2_BUILD_MODULE)
+ install(
+ TARGETS tinyxml2_module EXPORT tinyxml2-targets
+ RUNTIME COMPONENT tinyxml2_runtime
+ LIBRARY COMPONENT tinyxml2_runtime
+ NAMELINK_COMPONENT tinyxml2_development
+ ARCHIVE COMPONENT tinyxml2_development
+ FILE_SET CXX_MODULES DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+ )
+endif ()
+
# Type-specific targets
if (BUILD_SHARED_LIBS)
diff --git a/readme.md b/readme.md
index 6609015d..2f20bddb 100644
--- a/readme.md
+++ b/readme.md
@@ -37,7 +37,7 @@ code without creating a document first.
TinyXML-2 is designed to be easy and fast to learn. It is one header and
one cpp file. Simply add these to your project and off you go.
-There is an example file - xmltest.cpp - to get you started.
+There is an example file - `xmltest.cpp` - to get you started.
TinyXML-2 is released under the ZLib license,
so you can use it in open source or commercial code. The details
@@ -45,7 +45,8 @@ of the license are at the top of every source file.
TinyXML-2 attempts to be a flexible parser, but with truly correct and
compliant XML output. TinyXML-2 should compile on any reasonably C++
-compliant system. It does not rely on exceptions, RTTI, or the STL.
+compliant system. It does not rely on exceptions, run-time type information,
+or the C++ Standard Library.
What it doesn't do.
-------------------
@@ -67,7 +68,7 @@ rich test cases. But the implementation of the parser is completely re-written
to make it more appropriate for use in a game. It uses less memory, is faster,
and uses far fewer memory allocations.
-TinyXML-2 has no requirement or support for STL.
+TinyXML-2 has no requirement or support for the C++ Standard Library.
Features
--------
@@ -81,17 +82,17 @@ Filenames for loading / saving are passed unchanged to the underlying OS.
### Memory Model
-An XMLDocument is a C++ object like any other, that can be on the stack, or
-new'd and deleted on the heap.
+An `XMLDocument` is a C++ object like any other, that can be on the stack, or
+`new`'d and `delete`d on the heap.
-However, any sub-node of the Document, XMLElement, XMLText, etc, can only
-be created by calling the appropriate XMLDocument::NewElement, NewText, etc.
+However, any sub-node of the `XMLDocument`, `XMLElement`, `XMLText`, etc, can only
+be created by calling the appropriate `XMLDocument::NewElement`, `NewText`, etc.
method. Although you have pointers to these objects, they are still owned
-by the Document. When the Document is deleted, so are all the nodes it contains.
+by the `XMLDocument`. When the `XMLDocument` is deleted, so are all the nodes it contains.
### White Space
-#### Whitespace Preservation (default, PRESERVE_WHITESPACE)
+#### Whitespace Preservation (default, `PRESERVE_WHITESPACE`)
Microsoft has an excellent article on white space: http://msdn.microsoft.com/en-us/library/ms256097.aspx
@@ -103,51 +104,57 @@ line-feed character, as required by the XML spec.
White space in text is preserved. For example:
- Hello, World
+```xml
+ Hello, World
+```
The leading space before the "Hello" and the double space after the comma are
preserved. Line-feeds are preserved, as in this example:
- Hello again,
- World
+```xml
+ Hello again,
+ World
+```
However, white space between elements is **not** preserved. Although not strictly
compliant, tracking and reporting inter-element space is awkward, and not normally
valuable. TinyXML-2 sees these as the same XML:
-
- 1
- 2
- 3
-
+```xml
+
+ 1
+ 2
+ 3
+
- 123
+123
+```
-#### Whitespace Collapse (COLLAPSE_WHITESPACE)
+#### Whitespace Collapse (`COLLAPSE_WHITESPACE`)
For some applications, it is preferable to collapse whitespace. Collapsing
whitespace gives you "HTML-like" behavior, which is sometimes more suitable
for hand typed documents.
-TinyXML-2 supports this with the 'whitespace' parameter to the XMLDocument constructor.
+TinyXML-2 supports this with the `whitespace` parameter to the `XMLDocument` constructor.
(The default is to preserve whitespace, as described above.)
-However, you may also use COLLAPSE_WHITESPACE, which will:
+However, you may also use `COLLAPSE_WHITESPACE`, which will:
* Remove leading and trailing whitespace
* Convert newlines and line-feeds into a space character
* Collapse a run of any number of space characters into a single space character
-Note that (currently) there is a performance impact for using COLLAPSE_WHITESPACE.
+Note that (currently) there is a performance impact for using `COLLAPSE_WHITESPACE`.
It essentially causes the XML to be parsed twice.
-#### Pedantic Whitespace (PEDANTIC_WHITESPACE)
+#### Pedantic Whitespace (`PEDANTIC_WHITESPACE`)
For applications that need to know about text nodes that are composed entirely of
-whitespace, PEDANTIC_WHITESPACE is available. PEDANTIC_WHITESPACE maintains all the
+whitespace, `PEDANTIC_WHITESPACE` is available. `PEDANTIC_WHITESPACE` maintains all the
whilespace between elements.
-PEDANTIC_WHITESPACE is a new mode and not as tested as the other whitespace modes.
+`PEDANTIC_WHITESPACE` is a new mode and not as tested as the other whitespace modes.
### Error Reporting
@@ -163,18 +170,22 @@ line number information for error messages.
TinyXML-2 recognizes the pre-defined "character entities", meaning special
characters. Namely:
- & &
- < <
- > >
- " "
- ' '
+```xml
+& &
+< <
+> >
+" "
+' '
+```
These are recognized when the XML document is read, and translated to their
UTF-8 equivalents. For instance, text with the XML of:
- Far & Away
+```xml
+Far & Away
+```
-will have the Value() of "Far & Away" when queried from the XMLText object,
+will have the `Value()` of `"Far & Away"` when queried from the `XMLText` object,
and will be written back to the XML stream/file as an ampersand.
Additionally, any character can be specified by its Unicode code point:
@@ -188,101 +199,121 @@ regular code point. The output is correct, but the entity syntax isn't preserved
#### Print to file
You can directly use the convenience function:
- XMLDocument doc;
- ...
- doc.SaveFile( "foo.xml" );
+```cpp
+XMLDocument doc;
+// ...
+doc.SaveFile("foo.xml");
+```
-Or the XMLPrinter class:
+Or the `XMLPrinter` class:
- XMLPrinter printer( fp );
- doc.Print( &printer );
+```cpp
+XMLPrinter printer(fp);
+doc.Print(&printer);
+```
#### Print to memory
-Printing to memory is supported by the XMLPrinter.
+Printing to memory is supported by the `XMLPrinter`.
- XMLPrinter printer;
- doc.Print( &printer );
- // printer.CStr() has a const char* to the XML
+```cpp
+XMLPrinter printer;
+doc.Print(&printer);
+// printer.CStr() has a const char* to the XML
+```
-#### Print without an XMLDocument
+#### Print without an `XMLDocument`
When loading, an XML parser is very useful. However, sometimes
when saving, it just gets in the way. The code is often set up
for streaming, and constructing the DOM is just overhead.
-The Printer supports the streaming case. The following code
+The `XMLPrinter` supports the streaming case. The following code
prints out a trivially simple XML file without ever creating
an XML document.
- XMLPrinter printer( fp );
- printer.OpenElement( "foo" );
- printer.PushAttribute( "foo", "bar" );
- printer.CloseElement();
+```cpp
+XMLPrinter printer(fp);
+printer.OpenElement("foo");
+printer.PushAttribute("foo", "bar");
+printer.CloseElement();
+```
Examples
--------
#### Load and parse an XML file.
- /* ------ Example 1: Load and parse an XML file. ---- */
- {
- XMLDocument doc;
- doc.LoadFile( "dream.xml" );
- }
+```cpp
+/* ------ Example 1: Load and parse an XML file. ---- */
+{
+ XMLDocument doc;
+ doc.LoadFile("dream.xml");
+}
+```
#### Lookup information.
- /* ------ Example 2: Lookup information. ---- */
- {
- XMLDocument doc;
- doc.LoadFile( "dream.xml" );
-
- // Structure of the XML file:
- // - Element "PLAY" the root Element, which is the
- // FirstChildElement of the Document
- // - - Element "TITLE" child of the root PLAY Element
- // - - - Text child of the TITLE Element
-
- // Navigate to the title, using the convenience function,
- // with a dangerous lack of error checking.
- const char* title = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->GetText();
- printf( "Name of play (1): %s\n", title );
-
- // Text is just another Node to TinyXML-2. The more
- // general way to get to the XMLText:
- XMLText* textNode = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->FirstChild()->ToText();
- title = textNode->Value();
- printf( "Name of play (2): %s\n", title );
- }
+```cpp
+/* ------ Example 2: Lookup information. ---- */
+{
+ XMLDocument doc;
+ doc.LoadFile("dream.xml");
+
+ // Structure of the XML file:
+ // - Element "PLAY" the root Element, which is the
+ // FirstChildElement of the Document
+ // - - Element "TITLE" child of the root PLAY Element
+ // - - - Text child of the TITLE Element
+
+ // Navigate to the title, using the convenience function,
+ // with a dangerous lack of error checking.
+ const char* title = doc.FirstChildElement("PLAY")->FirstChildElement("TITLE")->GetText();
+ printf("Name of play (1): %s\n", title);
+
+ // Text is just another Node to TinyXML-2. The more
+ // general way to get to the XMLText:
+ XMLText* textNode = doc.FirstChildElement("PLAY")->FirstChildElement("TITLE")->FirstChild()->ToText();
+ title = textNode->Value();
+ printf("Name of play (2): %s\n", title);
+}
+```
Using and Installing
--------------------
There are 2 files in TinyXML-2:
-* tinyxml2.cpp
-* tinyxml2.h
+* `tinyxml2.cpp`
+* `tinyxml2.h`
And additionally a test file:
-* xmltest.cpp
+* `xmltest.cpp`
-Generally speaking, the intent is that you simply include the tinyxml2.cpp and
-tinyxml2.h files in your project and build with your other source code.
+And additionally a module:
+* `tinyxml2.cppm`
+
+Generally speaking, the intent is that you simply include the `tinyxml2.cpp` and
+`tinyxml2.h` files in your project and build with your other source code.
There is also a CMake build included. CMake is the general build for TinyXML-2.
(Additional build systems are costly to maintain, and tend to bit-rot. They are
being removed over time.)
+If using C++20 or latre and CMake 3.28+, the option `tinyxml2_BUILD_MODULE` may be enabled,
+which enables building the `tinyxml2` module.
+
Building TinyXML-2 - Using vcpkg
--------------------------------
You can download and install TinyXML-2 using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
- git clone https://github.com/Microsoft/vcpkg.git
- cd vcpkg
- ./bootstrap-vcpkg.sh
- ./vcpkg integrate install
- ./vcpkg install tinyxml2
+```bash
+git clone https://github.com/Microsoft/vcpkg.git
+cd vcpkg
+./bootstrap-vcpkg.sh
+./vcpkg integrate install
+./vcpkg install tinyxml2
+```
The TinyXML-2 port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
diff --git a/tinyxml2.cppm b/tinyxml2.cppm
new file mode 100644
index 00000000..70776791
--- /dev/null
+++ b/tinyxml2.cppm
@@ -0,0 +1,71 @@
+/*
+Original code by Lee Thomason (www.grinninglizard.com)
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any
+damages arising from the use of this software.
+
+Permission is granted to anyone to use this software for any
+purpose, including commercial applications, and to alter it and
+redistribute it freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must
+not claim that you wrote the original software. If you use this
+software in a product, an acknowledgment in the product documentation
+would be appreciated but is not required.
+
+2. Altered source versions must be plainly marked as such, and
+must not be misrepresented as being the original software.
+
+3. This notice may not be removed or altered from any source
+distribution.
+*/
+
+module;
+
+#include "tinyxml2.h"
+
+export module tinyxml2;
+
+export using ::TIXML2_MAJOR_VERSION;
+export using ::TIXML2_MINOR_VERSION;
+export using ::TIXML2_PATCH_VERSION;
+export using ::TINYXML2_MAX_ELEMENT_DEPTH;
+
+#pragma push_macro("TINYXML2_MAJOR_VERSION")
+#undef TINYXML2_MAJOR_VERSION
+export inline constexpr int TINYXML2_MAJOR_VERSION =
+#pragma pop_macro("TINYXML2_MAJOR_VERSION")
+ TINYXML2_MAJOR_VERSION;
+
+#pragma push_macro("TINYXML2_MINOR_VERSION")
+#undef TINYXML2_MINOR_VERSION
+export inline constexpr int TINYXML2_MINOR_VERSION =
+#pragma pop_macro("TINYXML2_MINOR_VERSION")
+ TINYXML2_MINOR_VERSION;
+
+#pragma push_macro("TINYXML2_PATCH_VERSION")
+#undef TINYXML2_PATCH_VERSION
+export inline constexpr int TINYXML2_PATCH_VERSION =
+#pragma pop_macro("TINYXML2_PATCH_VERSION")
+ TINYXML2_PATCH_VERSION;
+
+export namespace tinyxml2 {
+ using tinyxml2::DynArray;
+ using tinyxml2::StrPair;
+ using tinyxml2::Whitespace;
+ using tinyxml2::XMLAttribute;
+ using tinyxml2::XMLComment;
+ using tinyxml2::XMLConstHandle;
+ using tinyxml2::XMLDeclaration;
+ using tinyxml2::XMLDocument;
+ using tinyxml2::XMLElement;
+ using tinyxml2::XMLError;
+ using tinyxml2::XMLHandle;
+ using tinyxml2::XMLNode;
+ using tinyxml2::XMLPrinter;
+ using tinyxml2::XMLText;
+ using tinyxml2::XMLUnknown;
+ using tinyxml2::XMLUtil;
+ using tinyxml2::XMLVisitor;
+} // namespace tinyxml2
diff --git a/tinyxml2.h b/tinyxml2.h
index c8011174..da5f4200 100644
--- a/tinyxml2.h
+++ b/tinyxml2.h
@@ -93,12 +93,21 @@ distribution.
#endif
#endif
+
+#if defined(__cplusplus) && __cplusplus >= 201703L
+#define TINYXML2_CONSTANT inline constexpr
+#elif defined(__cplusplus) && __cplusplus >= 201103L
+#define TINYXML2_CONSTANT static constexpr
+#else
+#define TINYXML2_CONSTANT static const
+#endif
+
/* Versioning, past 1.0.14:
http://semver.org/
*/
-static const int TIXML2_MAJOR_VERSION = 11;
-static const int TIXML2_MINOR_VERSION = 0;
-static const int TIXML2_PATCH_VERSION = 0;
+TINYXML2_CONSTANT int TIXML2_MAJOR_VERSION = 11;
+TINYXML2_CONSTANT int TIXML2_MINOR_VERSION = 0;
+TINYXML2_CONSTANT int TIXML2_PATCH_VERSION = 0;
#define TINYXML2_MAJOR_VERSION 11
#define TINYXML2_MINOR_VERSION 0
@@ -109,7 +118,7 @@ static const int TIXML2_PATCH_VERSION = 0;
// system, and the capacity of the stack. On the other hand, it's a trivial
// attack that can result from ill, malicious, or even correctly formed XML,
// so there needs to be a limit in place.
-static const int TINYXML2_MAX_ELEMENT_DEPTH = 500;
+TINYXML2_CONSTANT int TINYXML2_MAX_ELEMENT_DEPTH = 500;
namespace tinyxml2
{
diff --git a/xmltest.cpp b/xmltest.cpp
index 75d4babf..c4d5d1cf 100644
--- a/xmltest.cpp
+++ b/xmltest.cpp
@@ -10,6 +10,31 @@
#include
#include
+#ifdef TINYXML2_USE_MODULE
+// modules doesn't export macros
+#if !defined(TIXMLASSERT)
+#if defined(TINYXML2_DEBUG)
+# if defined(_MSC_VER)
+# // "(void)0," is for suppressing C4127 warning in "assert(false)", "assert(true)" and the like
+# define TIXMLASSERT( x ) do { if ( !((void)0,(x))) { __debugbreak(); } } while(false)
+# elif defined (ANDROID_NDK)
+# include
+# define TIXMLASSERT( x ) do { if ( !(x)) { __android_log_assert( "assert", "grinliz", "ASSERT in '%s' at %d.", __FILE__, __LINE__ ); } } while(false)
+# else
+# include
+# define TIXMLASSERT assert
+# endif
+#else
+# define TIXMLASSERT( x ) do {} while(false)
+#endif
+#endif
+#undef NULL
+#define NULL nullptr
+import tinyxml2;
+#else
+#include "tinyxml2.h"
+#endif
+
#if defined( _MSC_VER ) || defined (WIN32)
#include
#define WIN32_LEAN_AND_MEAN