interop with std and boost any

CMakeLists.txt

@@ -94,6 +94,7 @@ set(
 
 if (BOOST_OPENMETHOD_BUILD_TESTS OR BOOST_OPENMETHOD_MRDOCS_BUILD)
     list(APPEND BOOST_OPENMETHOD_DEPENDENCIES Boost::smart_ptr)
+    list(APPEND BOOST_OPENMETHOD_DEPENDENCIES Boost::any)
 endif()
 
 foreach (BOOST_OPENMETHOD_DEPENDENCY ${BOOST_OPENMETHOD_DEPENDENCIES})
@@ -219,5 +220,7 @@ if (BOOST_OPENMETHOD_BUILD_TESTS)
     # Examples
     if (BOOST_OPENMETHOD_BUILD_EXAMPLES)
         add_subdirectory(doc/modules/ROOT/examples)
+        # Sources behind the `include:` markers in the reference doc comments.
+        add_subdirectory(doc/modules/ROOT/snippets)
     endif ()
 endif ()

doc/antora.yml

@@ -15,6 +15,12 @@ asciidoc:
   attributes:
     source-language: asciidoc@
     table-caption: false
+    # Base of the links to the header sources in ref_headers.adoc. It must be
+    # an absolute url: neither the PR previews nor boost.org serve the library
+    # sources next to the docs. The previews publish libs/openmethod/doc only,
+    # and boost.org serves the headers from doc/libs/<version>/boost, not from
+    # libs/openmethod/include.
+    headers-url: https://github.com/boostorg/openmethod/blob/develop/include
 nav:
   - modules/ROOT/nav.adoc
 ext:

doc/build_antora.sh

@@ -22,82 +22,14 @@ fi
 SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
 cd "$SCRIPT_DIR"
 
-if [ -z "${BOOST_SRC_DIR:-}" ]; then
-  CANDIDATE=$( cd "$SCRIPT_DIR/../../.." 2>/dev/null && pwd )
-  if [ -n "$CANDIDATE" ]; then
-    BOOST_SRC_DIR_IS_VALID=ON
-    for F in "CMakeLists.txt" "Jamroot" "boost-build.jam" "bootstrap.sh" "libs"; do
-      if [ ! -e "$CANDIDATE/$F" ]; then
-        BOOST_SRC_DIR_IS_VALID=OFF
-        break
-      fi
-    done
-    if [ "$BOOST_SRC_DIR_IS_VALID" = "ON" ]; then
-      export BOOST_SRC_DIR="$CANDIDATE"
-      echo "Using BOOST_SRC_DIR=$BOOST_SRC_DIR"
-    fi
-  fi
-fi
-
-BRANCH=master
-
-if [ -n "${BOOST_SRC_DIR:-}" ]; then
-  if [ -n "${CIRCLE_REPOSITORY_URL:-}" ]; then
-    if [[ "$CIRCLE_REPOSITORY_URL" =~ boostorg/boost(\.git)?$ ]]; then
-      LIB="$(basename "$(dirname "$SCRIPT_DIR")")"
-      REPOSITORY="boostorg/${LIB}"
-      BRANCH=$(git -C "$BOOST_SRC_DIR" rev-parse --abbrev-ref HEAD)
-    else
-      ACCOUNT="${CIRCLE_REPOSITORY_URL#*:}"
-      ACCOUNT="${ACCOUNT%%/*}"
-      LIB=$(basename "$(git rev-parse --show-toplevel)")
-      REPOSITORY="${ACCOUNT}/${LIB}"
-    fi
-    SHA=$(git -C "$BOOST_SRC_DIR/libs" ls-tree HEAD | grep -w openmethod | awk '{print $3}')
-  elif [ -n "${GITHUB_REPOSITORY:-}" ]; then
-    REPOSITORY="${GITHUB_REPOSITORY}"
-    SHA="${GITHUB_SHA}"
-  fi
-fi
-
-cd "$SCRIPT_DIR"
-
-if [ -n "${REPOSITORY}" ] && [ -n "${SHA}" ]; then
-  BASE_URL="https://github.com/${REPOSITORY}/blob/${SHA}"
-  echo "Setting base-url to $BASE_URL"
-  cp mrdocs.yml mrdocs.yml.bak
-  perl -i -pe 's{^\s*base-url:.*$}{base-url: '"$BASE_URL/"'}' mrdocs.yml
-else
-  echo "REPOSITORY or SHA not set; skipping base-url modification"
-fi
-
 echo "Building documentation with Antora..."
+
 echo "Installing npm dependencies..."
 npm ci
 
 echo "Building docs in custom dir..."
 PATH="$(pwd)/node_modules/.bin:${PATH}"
 export PATH
-npx antora --clean --fetch "$PLAYBOOK" --stacktrace # --log-level all
-
-echo "Fixing links to non-mrdocs URIs..."
-echo "BRANCH='${BRANCH:-}'"
-echo "BASE_URL='${BASE_URL:-}'"
-
-for f in $(find html -name '*.html'); do
-  perl -i -pe "s{&lcub;&lcub;(.*?)&rcub;&rcub;}{<a href=\"../../../\$1.html\">\$1</a>}g" "$f"
-  perl -i -pe "s{<a href=\"motivation.html\">Boost.OpenMethod</a>}{<a href=\"https://www.boost.org/library/${BRANCH}/openmethod/\">Boost.OpenMethod</a>}g" "$f"
-done
-
-if [ -n "${BASE_URL:-}" ]; then
-  if [ -f mrdocs.yml.bak ]; then
-    mv -f mrdocs.yml.bak mrdocs.yml
-    echo "Restored original mrdocs.yml"
-  else
-    echo "mrdocs.yml.bak not found; skipping restore"
-  fi
-  perl -i -pe "s[{{BASE_URL}}][$BASE_URL]g" \
-    html/openmethod/ref_headers.html html/openmethod/BOOST_OPENMETHOD*.html
-fi
+npx antora --clean --fetch "$PLAYBOOK" --stacktrace --log-level all
 
 echo "Done"

doc/modules/ROOT/examples/registry_identity.cpp

@@ -0,0 +1,55 @@
+// Copyright (c) 2018-2025 Jean-Louis Leroy
+// Distributed under the Boost Software License, Version 1.0.
+// See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+#include <cassert>
+#include <type_traits>
+
+#include <boost/openmethod.hpp>
+#include <boost/openmethod/policies/vptr_map.hpp>
+
+using namespace boost::openmethod;
+
+namespace same_policies {
+
+// tag::shared[]
+struct animals : registry<policies::std_rtti, policies::vptr_map<>> {};
+struct vehicles : registry<policies::std_rtti, policies::vptr_map<>> {};
+
+// the policy lists are identical, so this is one registry, not two
+static_assert(std::is_same_v<animals::registry_type, vehicles::registry_type>);
+// end::shared[]
+
+} // namespace same_policies
+
+namespace distinct_policies {
+
+// tag::distinct[]
+// a policy in a category of its own, carrying nothing but a number
+struct marker_category {
+    using category = marker_category;
+};
+
+template<int N>
+struct marker final : marker_category {
+    template<class Registry>
+    struct fn {};
+};
+
+struct animals : default_registry::with<marker<1>> {};
+struct vehicles : default_registry::with<marker<2>> {};
+
+static_assert(!std::is_same_v<animals::registry_type, vehicles::registry_type>);
+// end::distinct[]
+
+} // namespace distinct_policies
+
+auto main() -> int {
+    // the shared pair reach one state, the distinct pair two
+    assert(same_policies::animals::id() == same_policies::vehicles::id());
+    assert(
+        distinct_policies::animals::id() != distinct_policies::vehicles::id());
+
+    return 0;
+}

doc/modules/ROOT/examples/virtual_any.cpp

@@ -0,0 +1,63 @@
+// Copyright (c) 2018-2026 Jean-Louis Leroy
+// Distributed under the Boost Software License, Version 1.0.
+// See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+// clang-format off
+
+// tag::content[]
+#include <any>
+#include <iostream>
+#include <string>
+
+#include <boost/openmethod.hpp>
+#include <boost/openmethod/interop/std_any.hpp>
+
+using namespace boost::openmethod;
+
+struct Dog {
+    std::string name;
+};
+
+// `std::any` becomes the common base of the types it may contain.
+BOOST_OPENMETHOD_REGISTER(use_std_any_types<Dog, std::string, int, float>);
+
+BOOST_OPENMETHOD(name, (virtual_<const std::any&>), std::string);
+
+// An overrider takes the contained value...
+BOOST_OPENMETHOD_OVERRIDE(name, (const Dog& dog), std::string) {
+    return dog.name + " the dog";
+}
+
+BOOST_OPENMETHOD_OVERRIDE(name, (const std::string& name), std::string) {
+    return name;
+}
+
+BOOST_OPENMETHOD_OVERRIDE(name, (const int& value), std::string) {
+    return std::to_string(value) + " the integer";
+}
+
+// ...or the `any` itself, which makes it a catch-all.
+BOOST_OPENMETHOD_OVERRIDE(name, (const std::any&), std::string) {
+    return "something else";
+}
+
+#include <boost/openmethod/initialize.hpp>
+
+int main() {
+    initialize();
+
+    std::any spot = Dog{"Spot"};
+    std::any felix = std::string("Felix the cat");
+    std::any answer = 42;
+    std::any pi = 3.14f;
+
+    std::cout << name(spot) << "\n";   // Spot the dog
+    std::cout << name(felix) << "\n";  // Felix the cat
+    std::cout << name(answer) << "\n"; // 42 the integer
+
+    // `float` is registered, but has no overrider of its own, so the
+    // catch-all applies.
+    std::cout << name(pi) << "\n";     // something else
+}
+// end::content[]

doc/modules/ROOT/nav.adoc

@@ -13,8 +13,9 @@
 ** xref:custom_rtti.adoc[Custom RTTI]
 ** xref:error_handling.adoc[Error Handling]
 ** xref:virtual_ptr_alt.adoc[Virtual Pointer Alternatives]
+** xref:interop_any.adoc[Interoperation with `any`]
 ** xref:shared_libraries.adoc[Shared Libraries]
-* Reference
+* xref:reference:index.adoc[Reference]
 ** xref:ref_headers.adoc[Headers]
 ** xref:ref_macros.adoc[Macros]
 ** xref:reference:boost/openmethod.adoc[Namespace boost::openmethod]