CXX-2745 relocate top-level dependencies into v1 headers (#1318)

* format: add v1 header groups
* Fix library name in mongocxx doc.hpp
* v1: add config, detail, and stdx headers
* v1: add BSONCXX_VERSION_STRING
* Use consistent prefix for private macros used in public headers
* Move comparison-related type traits into type_traits.hpp

Author: eramongodb

.clang-format

@@ -83,8 +83,8 @@ AttributeMacros:
   - BSONCXX_ABI_NO_EXPORT
   - BSONCXX_DEPRECATED
   - BSONCXX_ENUM
-  - BSONCXX_PRAGMA
-  - BSONCXX_RETURNS
+  - BSONCXX_PRIVATE_PRAGMA
+  - BSONCXX_PRIVATE_RETURNS
   - MONGOCXX_ABI_CDECL
   - MONGOCXX_ABI_EXPORT
   - MONGOCXX_ABI_NO_EXPORT
@@ -144,24 +144,40 @@ IncludeBlocks:   Regroup
 IncludeCategories:
   - Regex: '".*"' # relative headers
     Priority: 10
+  - Regex: 'bsoncxx/v1/.*/prelude\.hpp' # v1 preludes
+    Priority: 20
+  - Regex: 'mongocxx/v1/.*/prelude\.hpp' # v1 preludes
+    Priority: 21
+  - Regex: 'bsoncxx/v1/.*(-|\/)fwd\.hpp' # v1 forward headers
+    Priority: 22
+  - Regex: 'mongocxx/v1/.*(-|\/)fwd\.hpp' # v1 forward headers
+    Priority: 23
+  - Regex: 'bsoncxx/v1/.*\.hpp' # v1 public headers
+    Priority: 24
+  - Regex: 'mongocxx/v1/.*\.hpp' # v1 public headers
+    Priority: 25
+  - Regex: 'bsoncxx/v1/.*\.hh' # v1 private headers
+    Priority: 26
+  - Regex: 'mongocxx/v1/.*\.hh' # v1 private headers
+    Priority: 27
   - Regex: 'bsoncxx/config(/private)?/prelude\.(hpp|hh)' # v_noabi preludes
-    Priority: 50
+    Priority: 60
   - Regex: 'mongocxx/config(/private)?/prelude\.(hpp|hh)' # v_noabi preludes
-    Priority: 51
+    Priority: 61
   - Regex: 'bsoncxx/test/.*' # test headers
-    Priority: 60
+    Priority: 70
   - Regex: 'mongocxx/test/.*' # test headers
-    Priority: 61
+    Priority: 71
   - Regex: '<[[:alnum:]_.]+>' # system headers
-    Priority: 20
-  - Regex: 'bsoncxx/.*(-|\/)fwd\.(hpp|hh)' # all driver forwarding headers
     Priority: 30
-  - Regex: 'mongocxx/.*(-|\/)fwd\.(hpp|hh)' # all driver forwarding headers
-    Priority: 31
-  - Regex: 'bsoncxx/.*' # all remaining (normal) driver headers
+  - Regex: 'bsoncxx/.*(-|\/)fwd\.(hpp|hh)' # all remaining forward headers
     Priority: 40
-  - Regex: 'mongocxx/.*' # all remaining (normal) driver headers
+  - Regex: 'mongocxx/.*(-|\/)fwd\.(hpp|hh)' # all remaining forward headers
     Priority: 41
+  - Regex: 'bsoncxx/.*' # all remaining headers
+    Priority: 50
+  - Regex: 'mongocxx/.*' # all remaining headers
+    Priority: 51
   - Regex: '.*' # all other headers (third party)
     Priority: 90
 IncludeIsMainRegex: '([-_](test|unittest))?$'
@@ -274,14 +290,14 @@ SpacesInSquareBrackets: false
 Standard:        Cpp11
 StatementAttributeLikeMacros: []
 StatementMacros:
-  - BSONCXX_DISABLE_WARNING
-  - BSONCXX_FORCE_SEMICOLON
-  - BSONCXX_IF_CLANG
-  - BSONCXX_IF_GCC
-  - BSONCXX_IF_GNU_LIKE
-  - BSONCXX_IF_MSVC
-  - BSONCXX_POP_WARNINGS
-  - BSONCXX_PUSH_WARNINGS
+  - BSONCXX_PRIVATE_FORCE_SEMICOLON
+  - BSONCXX_PRIVATE_IF_CLANG
+  - BSONCXX_PRIVATE_IF_GCC
+  - BSONCXX_PRIVATE_IF_GNU_LIKE
+  - BSONCXX_PRIVATE_IF_MSVC
+  - BSONCXX_PRIVATE_WARNINGS_DISABLE
+  - BSONCXX_PRIVATE_WARNINGS_POP
+  - BSONCXX_PRIVATE_WARNINGS_PUSH
   - BSONCXX_SUPPRESS_DEPRECATION_WARNINGS_BEGIN
   - BSONCXX_SUPPRESS_DEPRECATION_WARNINGS_END
 TableGenBreakInsideDAGArg: DontBreak

examples/bsoncxx/getting_values.cpp

@@ -72,7 +72,7 @@ int EXAMPLES_CDECL main() {
     auto invalid1 = doc["name"]["middle"];
     auto invalid2 = doc["contribs"][1000];
     if (invalid1 || invalid2) {
-        BSONCXX_UNREACHABLE; // Not reached.
+        return EXIT_FAILURE; // Not reached.
     }
 
     // Similarly, indexed access (either by string or numeric index) into a type that is not
@@ -81,7 +81,7 @@ int EXAMPLES_CDECL main() {
     auto invalid3 = doc["_id"]["invalid"];
     auto invalid4 = doc["name"][3];
     if (invalid3 || invalid4) {
-        BSONCXX_UNREACHABLE; // Not reached.
+        return EXIT_FAILURE; // Not reached.
     }
 
     // Values are accessed through get_*() methods.

src/bsoncxx/CMakeLists.txt

@@ -192,14 +192,14 @@ if(1)
             BASE_NAME BSONCXX_ABI
             EXPORT_MACRO_NAME BSONCXX_ABI_EXPORT
             DEPRECATED_MACRO_NAME BSONCXX_DEPRECATED
-            EXPORT_FILE_NAME ${PROJECT_BINARY_DIR}/lib/bsoncxx/v_noabi/bsoncxx/config/export.hpp
+            EXPORT_FILE_NAME ${PROJECT_BINARY_DIR}/lib/bsoncxx/v1/config/export.hpp
             STATIC_DEFINE BSONCXX_STATIC
             CUSTOM_CONTENT_FROM_VARIABLE bsoncxx_export_header_custom_content
         )
 
         install(FILES
-            ${PROJECT_BINARY_DIR}/lib/bsoncxx/v_noabi/bsoncxx/config/export.hpp
-            DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/bsoncxx/v_noabi/bsoncxx/config
+            ${PROJECT_BINARY_DIR}/lib/bsoncxx/v1/config/export.hpp
+            DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/bsoncxx/v1/config
             COMPONENT dev
         )
     endfunction()

src/bsoncxx/include/bsoncxx/docs/v1.hpp

@@ -0,0 +1,56 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#if !defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+#error "This file is for documentation purposes only. It should not be included."
+#endif // !defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+///
+/// @file
+/// For documentation purposes only.
+///
+/// @note This header is not includable!
+///
+
+///
+/// @dir bsoncxx/v1
+/// Provides headers declaring entities in @ref bsoncxx::v1.
+///
+
+///
+/// @dir bsoncxx/v1/config
+/// Provides headers related to bsoncxx library configuration.
+///
+
+///
+/// @dir bsoncxx/v1/detail
+/// Provides headers for internal use only.
+///
+/// @warning For internal use only!
+///
+
+///
+/// @dir bsoncxx/v1/stdx
+/// Provides headers declaring entities in @ref bsoncxx::v1::stdx.
+///
+
+///
+/// @namespace bsoncxx::v1
+/// Declares entities whose ABI stability is guaranteed for documented symbols.
+///
+
+///
+/// @namespace bsoncxx::v1::stdx
+/// @copydoc bsoncxx::stdx
+///

src/bsoncxx/include/bsoncxx/docs/v_noabi.hpp

@@ -25,11 +25,10 @@
 
 ///
 /// @dir bsoncxx/v_noabi
-/// The directory relative to which headers declaring entities in @ref bsoncxx::v_noabi are
-/// typically included.
+/// Provides headers declaring entities in @ref bsoncxx::v_noabi.
 ///
-/// For backward compatibility, unstable ABI headers may be included using the syntax
-/// `<bsoncxx/foo.hpp>`, which is equivalent to `<bsoncxx/v_noabi/bsoncxx/foo.hpp>`.
+/// Unstable ABI headers may be included using the syntax `<bsoncxx/foo.hpp>`, which is equivalent to
+/// `<bsoncxx/v_noabi/bsoncxx/foo.hpp>`.
 ///
 
 ///

src/bsoncxx/include/bsoncxx/v1/detail/compare.hpp

@@ -0,0 +1,176 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <bsoncxx/v1/detail/prelude.hpp>
+
+#include <bsoncxx/v1/detail/macros.hpp>
+#include <bsoncxx/v1/detail/type_traits.hpp>
+
+#include <cstddef>
+#include <functional>
+#include <type_traits>
+
+namespace bsoncxx {
+namespace detail {
+
+// Callable object and tag type for equality comparison.
+struct equal_to {
+    template <typename L, typename R>
+    constexpr requires_t<bool, is_equality_comparable<L, R>> operator()(L&& l, R&& r) const noexcept(noexcept(l == r)) {
+        return l == r;
+    }
+};
+
+// Derive from this class to define ADL-only operator== and operator!= on the basis of
+// an ADL-only tag_invoke(equal_to, l, r).
+class equality_operators {
+    template <typename L, typename R>
+    constexpr static auto impl(rank<1>, L& l, R& r) BSONCXX_PRIVATE_RETURNS(tag_invoke(equal_to{}, l, r));
+
+    template <typename L, typename R>
+    constexpr static auto impl(rank<0>, L& l, R& r) BSONCXX_PRIVATE_RETURNS(tag_invoke(equal_to{}, r, l));
+
+    // @cond DOXYGEN_DISABLE "Found ';' while parsing initializer list!"
+    template <typename Left, typename Other>
+    constexpr friend auto operator==(Left const& self, Other const& other)
+        BSONCXX_PRIVATE_RETURNS(equality_operators::impl(rank<1>{}, self, other));
+    // @endcond
+
+    // @cond DOXYGEN_DISABLE "Found ';' while parsing initializer list!"
+    template <typename Left, typename Other>
+    constexpr friend auto operator!=(Left const& self, Other const& other)
+        BSONCXX_PRIVATE_RETURNS(!equality_operators::impl(rank<1>{}, self, other));
+    // @endcond
+};
+
+// Very basic impl of C++20 std::strong_ordering.
+//
+// We don't need other weaker orderings yet, so this is all that we have.
+class strong_ordering {
+    signed char _c;
+    struct _construct {};
+
+    constexpr strong_ordering(_construct, signed char c) noexcept : _c(c) {}
+
+   public:
+    static strong_ordering const less;
+    static strong_ordering const greater;
+    static strong_ordering const equivalent;
+    static strong_ordering const equal;
+
+    constexpr strong_ordering(std::nullptr_t) noexcept : strong_ordering(_construct{}, 0) {}
+
+    constexpr bool operator==(strong_ordering o) const noexcept {
+        return _c == o._c;
+    }
+    constexpr bool operator!=(strong_ordering o) const noexcept {
+        return !(*this == o);
+    }
+#pragma push_macro("DEFOP")
+#undef DEFOP
+#define DEFOP(Op)                                               \
+    constexpr bool operator Op(std::nullptr_t) const noexcept { \
+        return _c Op 0;                                         \
+    }                                                           \
+    static_assert(true, "")
+    DEFOP(<);
+    DEFOP(>);
+    DEFOP(<=);
+    DEFOP(>=);
+#pragma pop_macro("DEFOP")
+
+    // nonstd: Swap greater/less values
+    constexpr strong_ordering inverted() const noexcept {
+        return *this < nullptr ? greater : *this > nullptr ? less : *this;
+    }
+};
+
+#pragma push_macro("INLINE_VAR")
+#undef INLINE_VAR
+#define INLINE_VAR                             \
+    BSONCXX_PRIVATE_IF_GNU_LIKE([[gnu::weak]]) \
+    BSONCXX_PRIVATE_IF_MSVC(__declspec(selectany))
+
+INLINE_VAR const strong_ordering strong_ordering::less = strong_ordering(strong_ordering::_construct{}, -1);
+INLINE_VAR const strong_ordering strong_ordering::greater = strong_ordering(strong_ordering::_construct{}, 1);
+INLINE_VAR const strong_ordering strong_ordering::equivalent = strong_ordering(strong_ordering::_construct{}, 0);
+INLINE_VAR const strong_ordering strong_ordering::equal = strong_ordering(strong_ordering::_construct{}, 0);
+
+#pragma pop_macro("INLINE_VAR")
+
+// Implements a three-way comparison between two objects. That is, in
+// a single operation, determine whether the left operand is less-than, greater-than,
+// or equal-to the right-hand operand.
+struct compare_three_way {
+    BSONCXX_PRIVATE_WARNINGS_PUSH();
+    BSONCXX_PRIVATE_WARNINGS_DISABLE(GNU("-Wfloat-equal"));
+    template <
+        typename L,
+        typename R,
+        typename = decltype(std::declval<L>() < std::declval<R>()),
+        typename = decltype(std::declval<L>() == std::declval<R>())>
+    constexpr static strong_ordering impl(L const& l, R const& r, rank<1>) {
+        return (l < r) ? strong_ordering::less : (l == r ? strong_ordering::equal : strong_ordering::greater);
+    }
+    BSONCXX_PRIVATE_WARNINGS_POP();
+
+    template <
+        typename L,
+        typename R,
+        typename = decltype(tag_invoke(std::declval<compare_three_way>(), std::declval<L>(), std::declval<R>()))>
+    constexpr static strong_ordering impl(L const& l, R const& r, rank<2>) {
+        return tag_invoke(compare_three_way{}, l, r);
+    }
+
+    template <typename L, typename R>
+    constexpr auto operator()(L const& l, R const& r) const BSONCXX_PRIVATE_RETURNS((impl)(l, r, rank<2>{}));
+};
+
+// Inherit to define ADL-visible ordering operators based on an ADL-visible
+// implementation of tag_invoke(compare_three_way, l, r).
+struct ordering_operators {
+    template <typename L, typename R>
+    constexpr static auto impl(L const& l, R const& r, rank<1>)
+        BSONCXX_PRIVATE_RETURNS(tag_invoke(compare_three_way{}, l, r));
+
+    template <typename L, typename R>
+    constexpr static auto impl(L const& l, R const& r, rank<0>)
+        BSONCXX_PRIVATE_RETURNS(tag_invoke(compare_three_way{}, r, l).inverted());
+
+#pragma push_macro("DEFOP")
+#undef DEFOP
+#define DEFOP(Oper)                                             \
+    template <typename L, typename R>                           \
+    constexpr friend auto operator Oper(L const& l, R const& r) \
+        BSONCXX_PRIVATE_RETURNS(ordering_operators::impl(l, r, rank<1>{}) Oper nullptr)
+    DEFOP(<);
+    DEFOP(>);
+    DEFOP(<=);
+    DEFOP(>=);
+#pragma pop_macro("DEFOP")
+};
+
+} // namespace detail
+} // namespace bsoncxx
+
+#include <bsoncxx/v1/detail/postlude.hpp>
+
+///
+/// @file
+/// For internal use only!
+///
+/// @warning For internal use only!
+///