.. index::
    single: Reference

*************
API Reference
*************

This chapter contains the complete reference documentation for the public API
of the Erbsland Regular Expression library.

While the :doc:`Get Started <../../get-started/index>` section focuses on
learning the basics and building your first examples, the reference chapters
are designed to answer detailed questions about specific types, methods, and
behaviour. You typically come here once you already know *what* you want to do
and need to look up *how* a particular part of the API works.

The following example demonstrates a common real-world workflow using the
library:

*   compile regular expressions,
*   match them against input data, and
*   process the resulting matches.

.. code-block:: cpp
    :linenos:
    :emphasize-lines: 14, 20-23

    #include <erbsland/all_re.hpp>

    // ... std includes ...

    using namespace el::re;

    // ... type definitions and helper functions ...

    int main(int argc, char **argv) {
        try {
            if (argc < 2) {
                throw std::runtime_error(std::format("Usage: {} <html-file>\n", argv[0]));
            }

            const auto reTag = RegEx::compile(R"((?is)<([a-z]+)([^>]*)>)");
            const auto reAttribute = RegEx::compile(R"((?is)\s+([a-z]+)=("[^"]*"|\S+)?)");

            auto html = readFileToString(argv[1]);
            auto tagCounts = CountMap{};
            auto attributeCounts = CountMap{};

            std::cout << "Scanning file\n";

            for (const auto &match : reTag->findAllView(html)) {
                tagCounts[std::string(match->content(1))] += 1;

                for (const auto &attributeMatch : reAttribute->findAllView(match->content(2))) {
                    attributeCounts[std::string(attributeMatch->content(1))] += 1;
                }
            }

            const auto tagRows = sortedRowsFromCounts(tagCounts);
            const auto attributeRows = sortedRowsFromCounts(attributeCounts);

            printStats(tagRows, "Tag Statistics:");
            printStats(attributeRows, "Attribute Statistics:");

            return 0;
        } catch (const std::runtime_error &error) {
            std::cout << error.what() << '\n';
            return 1;
        }
    }

This example highlights a typical usage pattern of the API:
*compile → match → process match results*.

For clarity, helper functions and type declarations are omitted here. You can
find the complete example, including all supporting code, in
:doc:`../../get-started/03-write-the-main`.

The following reference pages document all public interfaces in detail.

.. button-ref:: regex
    :ref-type: doc
    :color: success
    :align: center
    :expand:
    :class: sd-fs-5 sd-font-weight-bold sd-p-2 sd-my-4

    The RegEx Interface →


.. toctree::
    :maxdepth: 1
    :hidden:

    regex
    match
    settings
    input
    error
    diagnostics