.. _xmlio-getting-started:

Overview and Quick Start
========================

Purpose
-------

``xmlio`` supplies the XML boundary for applications that want readable input
files without exposing a parser-specific C API throughout their code. It owns
parsed documents, evaluates XPath expressions, converts XML text to typed C++
values, and builds well-formed output documents.

The public interface has four main pieces:

``XMLReader``
   Loads a document and evaluates absolute or context-relative XPath queries.

``XMLWriter``, ``XMLBufferWriter``, and ``XMLFileWriter``
   Build documents with a current-element stack and validated XML insertion.

``read`` and ``write``
   Serialize library types, standard containers, and user-defined records.

``GroupXml``
   Retains a typed XML subtree until an application selects a concrete model or
   operation.

Requirements
------------

The library requires a C++23 compiler, CMake 3.24 or newer, and libxml2 2.9 or
newer. Doxygen, Python, Sphinx, and LaTeX are only needed to build this manual.

Build and test
--------------

From the package directory:

.. code-block:: console

   cmake -S . -B build \
     -DXMLIO_BUILD_TESTS=ON \
     -DXMLIO_BUILD_EXAMPLES=ON
   cmake --build build
   ctest --test-dir build --output-on-failure

Run the introductory example with:

.. code-block:: console

   ./build/examples/xmlio_example

First round trip
----------------

This complete program constructs a small document, reparses it, and reads its
values with explicit C++ types:

.. literalinclude:: examples/quick_start.cpp
   :language: cpp
   :linenos:

The writer produces the following document:

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8"?>
   <project name="example">
     <enabled>true</enabled>
     <iterations>12</iterations>
     <weights>0.25 0.75</weights>
   </project>

The example introduces the normal workflow:

#. Construct a writer with one document root.
#. Use ``write`` for typed child elements and ``set_attr`` for attributes.
#. Obtain XML text or let a file writer persist the document.
#. Construct a reader from an explicit source.
#. Read values through absolute or relative XPath expressions.

Choosing an input constructor
-----------------------------

New code should say whether a string is XML text or a filename:

.. code-block:: cpp

   auto from_disk = xmlio::XMLReader::from_file("settings.xml");
   auto from_memory = xmlio::XMLReader::from_string("<settings/>");

The historical ``XMLReader(std::string)`` constructor remains available for
migration. It treats a first non-whitespace ``<`` as XML text and anything else
as a filename. Explicit construction avoids ambiguity and communicates intent.

Where to continue
-----------------

The :ref:`xmlio-reading` and :ref:`xmlio-writing` chapters cover the two sides
of the document boundary. :ref:`xmlio-serialization` defines every built-in XML
representation. :ref:`xmlio-custom-types` then shows how an application adds
its own records without modifying ``xmlio``.