Fixing #16 and introducing polyfill namespaces. (#18)

thirtytwobits · web-flow · commit f4fbd653074a · 2023-03-21T11:12:10.000-07:00
* Fixing #16 and introducing polyfill namespaces. * changed everything to .hpp
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -10,6 +10,8 @@
         "/(lib)?cyphal/g",
         "/ovfl/g",
         "/Cyphal/ig",
+        "/cetl/i",
+        "/cetlvast/i",
         "/tparam/g",
         "/\\.hpp/g",
         "/endcode/g",
@@ -20,14 +22,18 @@
         "/g(oogle)?test/",
         "/(?:de?|con)struct(?:able?|or)/i",
         "/copydoc/",
-        "/(r)?begin/",
-        "/(r)?end/",
+        "/\\b(r)?begin/",
+        "/\\b(r)?end/",
         "/cetl(vast)?/",
         "/(c|d)tor/i",
         "/arr/",
         "/subspan/i",
-        "/nodiscar/",
-        "/trimleft/"
+        "/nodiscard/",
+        "/trimleft/",
+        "/polyfill/i",
+        "/autosar/i",
+        "/__cplusplus/",
+        "/<cassert>/"
     ],
     "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
     "cmake.configureOnOpen": false,
@@ -42,7 +48,6 @@
     ],
     "editor.wordWrapColumn": 120,
     "editor.rulers": [
-        80,
         120
     ],
     "files.eol": "\n",
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -58,11 +58,13 @@ docker run --rm -it -v ${PWD}:/repo ghcr.io/opencyphal/toolshed:ts22.4.x
 ```
 3. cd into the CETLVaSt test suite directory then run the verify script to
 configure the unittest suite with `--configure-only` and (we suggest)
-`--force-ninja`. By including `-vv` you can see the exact cmake commands
-verify.py is executing and you and use `--dry-run` if you really don't
-like my python script so much that you want to do all the typing yourself
-(It's not like I spent a ton of time documenting all of these options for
-you. No no. It's fine. Don't try to apologize now...):
+`--force-ninja`. This step is important because it pulls test-only dependencies
+from github (i.e. googletest) and configures them for use by CETLVaSt. By
+including `-vv` you can see the exact cmake commands verify.py is executing and
+you and use `--dry-run` if you really hate my python script so much that you
+want to do all the typing yourself (It's not like I spent a ton of time
+documenting all of these options for you. No no. It's fine. Don't try to
+apologize now...):
 ```
 cd cetlvast
 ./verify.py -vv --configure-only --force-ninja unittest
diff --git a/README.md b/README.md
@@ -10,7 +10,16 @@ Cyphal Embedded Template Library
 
 ## include
 
-The include directory contains the CETL headers all within a folder, "cetl".
+The include directory contains the CETL headers all within a folder, "cetl". Types found under "cetl/pfXX" folders and
+within `cetl::pfxx` namespaces are ["polyfill"](https://en.wikipedia.org/wiki/Polyfill_(programming)) types that adhere
+to the XX standard. For example, `cetl::pf20::span` is a type that adheres, as closely as possible, to the C++20
+specification for the `std::span` type.
+
+> Any type found directly under the cetl folder does *not* adhere to a known standard and is specific only to CETL.
+
+Also under each "cetl/pfXX" folder will be a "cetlpf.hpp" header. These headers enable automatic polyfill behavior but do
+so by violating certain AUTOSAR-14 rules. We recommend using the CETL polyfill types directly in code that adheres
+to AUTOSAR-14.
 
 TODO: Once [Issue #12](https://github.com/OpenCyphal-Garage/CETL/issues/12) is complete we'll provide some more
 info here on how we expect you to take a dependency on CETL.
@@ -39,13 +48,13 @@ mimicking other support libraries like Boost.
 the default STL allocator but will always support an alternative way to manage their memory.
 - **CETL minimizes type aliasing and never injects typedef or macros into external namespaces.** – If an `std::uint8_t`
 will suffice CETL uses that explicitly. If a function should be constexpr the constexpr keyword will be used. etc.
-- **CETL tries really, really hard to not use macros** – With the exception of include guard ifndef clauses, CETL does
+- **CETL tries really, really hard to not use macros** – Except where AUTOSAR-14 Rule A16-0-1 permits, CETL does
 not use any C macros where a C++ template or other construct will suffice.
 - **CETL is [Autosar C++14](https://www.autosar.org/fileadmin/standards/adaptive/20-11/AUTOSAR_RS_CPP14Guidelines.pdf)
 compliant** – Where it violates Autosar rules comments will provide a clear rationale.
-- **CETL headers have minimal dependencies** – While there is a `cetl/cetl.h` it is minimal and does not drag a large
+- **CETL headers have minimal dependencies** – While there is a `cetl/cetl.hpp` it is minimal and does not drag a large
 set of conventions, typedefs, and other constructs that will pollute your code. Each type provided is isolated as much
-as practical and users that want to copy and paste one of the CETL headers into their project can easily elide cetl.h
+as practical and users that want to copy and paste one of the CETL headers into their project can easily elide cetl.hpp
 with minimal effort.
 
 
diff --git a/cetlvast/cmake/modules/Finddocs.cmake b/cetlvast/cmake/modules/Finddocs.cmake
@@ -43,7 +43,7 @@ function (create_docs_target ARG_DOCS_TARGET_NAME ARG_ADD_TO_ALL ARG_EXAMPLES_PA
     file(GLOB_RECURSE DOXYGEN_INPUT_LIST
         LIST_DIRECTORIES false
         CONFIGURE_DEPENDS
-        ${CETL_ROOT}/include/**/*.h
+        ${CETL_ROOT}/include/**/*.hpp
     )
 
     list(APPEND DOXYGEN_INPUT_LIST "${CETL_ROOT}/README.md")
diff --git a/cetlvast/cmake/suites/compile.cmake b/cetlvast/cmake/suites/compile.cmake
@@ -85,3 +85,11 @@ add_custom_target(
      DEPENDS
           ${ALL_TESTS}
 )
+
+add_custom_target(
+     suite_all
+     COMMENT
+        "All CETL suites define this target as a default action scripts can rely on."
+     DEPENDS
+        test_all
+)
diff --git a/cetlvast/cmake/suites/docs.cmake b/cetlvast/cmake/suites/docs.cmake
@@ -89,3 +89,11 @@ add_custom_target(
 find_package(docs REQUIRED)
 
 create_docs_target(docs ON ${CETLVAST_PROJECT_ROOT}/suites/docs/examples "${ALL_EXAMPLES}")
+
+add_custom_target(
+     suite_all
+     COMMENT
+        "All CETL suites define this target as a default action scripts can rely on."
+     DEPENDS
+        docs
+)
diff --git a/cetlvast/cmake/suites/lint.cmake b/cetlvast/cmake/suites/lint.cmake
@@ -9,4 +9,12 @@
 # +---------------------------------------------------------------------------+
 find_package(clangformat REQUIRED)
 
-create_check_style_target(format-check ${CETLVAST_STYLE_CHECK} "${CETL_INCLUDE}/**/*.h")
+create_check_style_target(format-check ${CETLVAST_STYLE_CHECK} "${CETL_INCLUDE}/**/*.hpp")
+
+add_custom_target(
+     suite_all
+     COMMENT
+        "All CETL suites define this target as a default action scripts can rely on."
+     DEPENDS
+        format-check
+)
diff --git a/cetlvast/cmake/suites/unittest.cmake b/cetlvast/cmake/suites/unittest.cmake
@@ -176,23 +176,13 @@ add_custom_target(
           ${ALL_TESTS}
 )
 
-# +---------------------------------------------------------------------------+
-#   If we can we try to upload the report to sonarqube.
-#
-find_package(sonar-scanner)
-
-if (SONAR_SCANNER_FOUND)
-     message(STATUS "sonarqube upload binary was defined. Adding the upload target: sonarqube_upload")
-     add_custom_target(
-          sonarqube_upload
-          ${SONARQUBE} --root ${CMAKE_CURRENT_SOURCE_DIR} ${CETLVAST_NATIVE_TEST_BINARY_DIR}/coverage.info -v
-          COMMENT "Upload to sonarqube (requires that SONARQUBE_TOKEN is defined in the environment)."
-     )
-
-else()
-     message(STATUS "sonarqube upload script not found. Upload target will not be available.")
-endif()
-
+add_custom_target(
+     suite_all
+     COMMENT
+        "All CETL suites define this target as a default action scripts can rely on."
+     DEPENDS
+        test_all
+)
 
 # Write a README to create the tests folder.
 file(WRITE ${CETLVAST_NATIVE_TEST_BINARY_DIR}/README.txt
diff --git a/cetlvast/include/cetlvast/helpers.hpp b/cetlvast/include/cetlvast/helpers.hpp
diff --git a/cetlvast/suites/compile/test_span_empty.cpp b/cetlvast/suites/compile/test_span_empty.cpp
@@ -7,16 +7,16 @@
 /// Copyright Amazon.com Inc. or its affiliates.
 /// SPDX-License-Identifier: MIT
 ///
-#include "cetl/cetl.h"
-#include "cetl/span.h"
+#include "cetl/cetl.hpp"
+#include "cetl/pf20/span.hpp"
 
 #ifndef CETLVAST_COMPILETEST_PRECHECK
 static_assert(__cplusplus >= CETL_CPP_STANDARD_17, "We simply pass this test (i.e. fail to compile) for C++14");
 #endif
 
 int main()
 {
-    cetl::span<int,0> subject;
+    cetl::pf20::span<int,0> subject;
 #ifndef CETLVAST_COMPILETEST_PRECHECK
     subject.empty(); // this should fail because nodiscard is available
 #else
diff --git a/cetlvast/suites/docs/examples/example_01_polyfill.cpp b/cetlvast/suites/docs/examples/example_01_polyfill.cpp
@@ -0,0 +1,31 @@
+/// @file
+/// Example of using one of the CETL polyfill headers.
+///
+/// @copyright
+/// Copyright (C) OpenCyphal Development Team  <opencyphal.org>
+/// Copyright Amazon.com Inc. or its affiliates.
+/// SPDX-License-Identifier: MIT
+///
+#include "cetl/pf20/cetlpf.hpp"
+#include <iostream>
+#include <string>
+#include <algorithm>
+#include <type_traits>
+
+
+int main()
+{
+    std::string greeting{"Hello Dynamic World."};
+    std::span<const char> dynamic{greeting.c_str(), 13};
+    auto print = [](const char c) { std::cout << c; };
+
+    // Print just the characters in the span...
+    std::for_each(dynamic.begin(), dynamic.end(), print);
+    std::cout << std::endl;
+
+    // or...
+    std::string substring{dynamic.begin(), dynamic.end()};
+    std::cout << substring << std::endl;
+
+    return 0;
+}
diff --git a/cetlvast/suites/docs/examples/example_01_span_dynamic.cpp b/cetlvast/suites/docs/examples/example_01_span_dynamic.cpp
@@ -6,7 +6,7 @@
 /// Copyright Amazon.com Inc. or its affiliates.
 /// SPDX-License-Identifier: MIT
 ///
-#include "cetl/span.h"
+#include "cetl/pf20/span.hpp"
 #include <iostream>
 #include <string>
 #include <algorithm>
@@ -15,7 +15,7 @@ int main()
 {
 //! [main]
     std::string greeting{"Hello Dynamic World."};
-    cetl::span<const char> dynamic{greeting.c_str(), 13};
+    cetl::pf20::span<const char> dynamic{greeting.c_str(), 13};
     auto print = [](const char c) { std::cout << c; };
 
     // Print just the characters in the span...
diff --git a/cetlvast/suites/docs/examples/example_01_span_static.cpp b/cetlvast/suites/docs/examples/example_01_span_static.cpp
@@ -6,14 +6,14 @@
 /// Copyright Amazon.com Inc. or its affiliates.
 /// SPDX-License-Identifier: MIT
 ///
-#include "cetl/span.h"
+#include "cetl/pf20/span.hpp"
 #include <iostream>
 #include <string>
 #include <algorithm>
 
 //! [global]
 template<typename T, std::size_t Extent>
-std::ostream& operator<<(std::ostream& os, const cetl::span<T, Extent>& sp)
+std::ostream& operator<<(std::ostream& os, const cetl::pf20::span<T, Extent>& sp)
 {
     std::for_each(sp.begin(), sp.end(), [&os](const char c) { os << c; });
     return os;
@@ -24,7 +24,7 @@ int main()
 {
 //! [main]
     constexpr const char* greeting = "Hello Static World";
-    std::cout << cetl::span<const char, 12>{greeting, 12} << std::endl;
+    std::cout << cetl::pf20::span<const char, 12>{greeting, 12} << std::endl;
 //! [main]
     return 0;
 }
diff --git a/cetlvast/suites/docs/examples/example_02_polyfill.cpp b/cetlvast/suites/docs/examples/example_02_polyfill.cpp
@@ -0,0 +1,42 @@
+/// @file
+/// Example of AUTOSAR-14 compliant use of CETL.
+///
+/// @copyright
+/// Copyright (C) OpenCyphal Development Team  <opencyphal.org>
+/// Copyright Amazon.com Inc. or its affiliates.
+/// SPDX-License-Identifier: MIT
+///
+#include "cetl/pf20/span.hpp"
+#include <iostream>
+#include <string>
+#include <algorithm>
+#include <type_traits>
+
+namespace
+{
+
+// Use CETL in this file but make it easy to switch to std:: if we upgrade
+// our compiler.
+constexpr std::size_t my_dynamic_extent = cetl::pf20::dynamic_extent;
+
+template <typename T, std::size_t Extent = my_dynamic_extent>
+using myspan = cetl::pf20::span<T, Extent>;
+
+}  // end anonymous namespace
+
+int main()
+{
+    std::string        greeting{"Hello Dynamic World."};
+    myspan<const char> dynamic{greeting.c_str(), 13};
+    auto               print = [](const char c) { std::cout << c; };
+
+    // Print just the characters in the span...
+    std::for_each(dynamic.begin(), dynamic.end(), print);
+    std::cout << std::endl;
+
+    // or...
+    std::string substring{dynamic.begin(), dynamic.end()};
+    std::cout << substring << std::endl;
+
+    return 0;
+}
diff --git a/cetlvast/suites/unittest/test_pf20.cpp b/cetlvast/suites/unittest/test_pf20.cpp
@@ -0,0 +1,24 @@
+/// @file
+/// Unit tests for the behavior of the cetl/pf20/cetlpf.hpp header.
+///
+/// @copyright
+/// Copyright (C) OpenCyphal Development Team  <opencyphal.org>
+/// Copyright Amazon.com Inc. or its affiliates.
+/// SPDX-License-Identifier: MIT
+///
+
+#include "cetlvast/helpers.hpp"
+#include "cetl/pf20/cetlpf.hpp"
+
+namespace
+{
+
+TEST(PF20TestSuite, TestSpanIsSpantastic)
+{
+    std::uint32_t data[5] = {0, 1, 2, 3, 4};
+    std::span<std::uint32_t, 3> always_std(&data[1], &data[4]);
+    ASSERT_EQ(1, always_std[0]);
+    ASSERT_EQ(3, always_std.back());
+}
+
+}  // namespace
diff --git a/cetlvast/suites/unittest/test_span.cpp b/cetlvast/suites/unittest/test_span.cpp
diff --git a/cetlvast/suites/unittest/test_span_asserts.cpp b/cetlvast/suites/unittest/test_span_asserts.cpp
diff --git a/include/cetl/cetl.h b/include/cetl/cetl.h
diff --git a/include/cetl/cetl.hpp b/include/cetl/cetl.hpp
diff --git a/include/cetl/pf20/cetlpf.hpp b/include/cetl/pf20/cetlpf.hpp
diff --git a/include/cetl/pf20/span.hpp b/include/cetl/pf20/span.hpp

Original file line number	Diff line number	Diff line change
`@@ -43,7 +43,7 @@ function (create_docs_target ARG_DOCS_TARGET_NAME ARG_ADD_TO_ALL ARG_EXAMPLES_PA`
`43`	`43`	`file(GLOB_RECURSE DOXYGEN_INPUT_LIST`
`44`	`44`	`LIST_DIRECTORIES false`
`45`	`45`	`CONFIGURE_DEPENDS`
`46`		`- ${CETL_ROOT}/include/*/.h`
	`46`	`+ ${CETL_ROOT}/include/*/.hpp`
`47`	`47`	`)`
`48`	`48`
`49`	`49`	`list(APPEND DOXYGEN_INPUT_LIST "${CETL_ROOT}/README.md")`