Mark lexy::parse_tree_input and lexy::dsl::tnode/pnode as

experimental
foonathan · Nov 8, 2023 · 76b8de9 · 76b8de9
1 parent 706acd5
commit 76b8de9
Show file tree

Hide file tree

Showing 20 changed files with 69 additions and 22 deletions.
diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
@@ -12,7 +12,7 @@
 
 === New Features
 
-* Add `lexy::parse_tree_input` and `lexy::dsl::tnode`/`lexy::dsl::pnode` to support multi-pass parsing.
+* **Experimental**: Add `lexy::parse_tree_input` and `lexy::dsl::tnode`/`lexy::dsl::pnode` to support multi-pass parsing.
 * Add `lexy::dsl::byte.if_`/`set`/`range`/`ascii` methods to match specific bytes.
 * Add an overload of `fatal_error()` on scanners that allows construction of type-erased generic errors (#134).
 * Add `lexy::buffer::release()` and `lexy::buffer::adopt()` to deconstruct a buffer into its components and re-assemble it later.

diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss
@@ -59,12 +59,19 @@ h6 {
 
 a, a svg, button svg {
     color: $link-color;
+    fill: $link-color;
+    stroke: $link-color;
     transition: color ease 0.3s;
 }
-a:hover, a svg:hover, button svg:hover {
+a:hover, button:hover {
     color: $highlight-color;
+    svg {
+        color: $highlight-color;
+        fill: $highlight-color;
+        stroke: $highlight-color;
+    }
 }
-a:focus, a svg:focus, button svg:focus {
+a:focus, button:focus {
     outline: none;
 }
 

diff --git a/docs/assets/examples/parse_tree_parsing.cpp b/docs/assets/examples/parse_tree_parsing.cpp
@@ -1,5 +1,6 @@
 #include <cstdio>
 
+#define LEXY_EXPERIMENTAL 1
 #include <lexy/action/parse.hpp>
 #include <lexy/action/parse_as_tree.hpp>
 #include <lexy/callback.hpp>

diff --git a/docs/assets/icons/beta.svg b/docs/assets/icons/beta.svg
diff --git a/docs/content/learn/build.adoc b/docs/content/learn/build.adoc
@@ -28,8 +28,10 @@ It exposes the following targets:
   Link to this library if you want to use advanced Unicode rules that require the Unicode character database.
 `foonathan::lexy::ext` (header-only)::
   Link to this library if you want to use the extension headers in `lexy_ext/`.
+`foonathan::lexy::experimental` (header-only)::
+  Link to this library if you want to use experimental features.
 `foonathan::lexy` (library)::
-  Umbrella target that links to all other targets.
+  Umbrella target that links to all targets except for `foonathan::lexy::experimental`.
 
 A minimal `CMakeLists.txt` that uses lexy can look like this:
 

diff --git a/docs/content/learn/versioning.adoc b/docs/content/learn/versioning.adoc
@@ -26,7 +26,7 @@ We promise:
 We reserve the right to:
 
 * Deprecate existing functionality and remove previously deprecated functionality.
-* Change anything that is not documented.
+* Change anything that is not documented or explicitly marked as experimental (enabled by linking `foonathan::lexy::experimental`).
   In particular, writing custom rules, readers, or parse actions is not guaranteed to work across major releases.
 * Change everything about the extension headers.
 * Change the behavior of rules on invalid input.

diff --git a/docs/content/reference/dsl/parse_tree_node.adoc b/docs/content/reference/dsl/parse_tree_node.adoc
@@ -1,5 +1,6 @@
 ---
 header: "lexy/dsl/parse_tree_node.hpp"
+experimental: true
 entities:
   "lexy::dsl::tnode": tnode
   "lexy::dsl::pnode": pnode
@@ -12,7 +13,7 @@ Rules for parsing a {{% docref "lexy::parse_tree_input" %}}.
 {{% godbolt-example "parse_tree_parsing" "Re-parse a parse tree" %}}
 
 [#tnode]
-== Rule DSL `lexy::dsl::tnode`
+== Rule DSL `lexy::dsl::tnode` {{< experimental >}}
 
 {{% interface %}}
 ----
@@ -56,7 +57,7 @@ Errors::
 Parse tree::
   A single token node that contains the node of the input parse tree with the same token kind.
 
-=== Branch rule `lexy::dsl::tnode(lexeme_rule)``
+=== Branch rule `lexy::dsl::tnode(lexeme_rule)`
 
 {{% interface %}}
 ----
@@ -76,7 +77,7 @@ Errors::
 NOTE: `lexeme_rule` matches characters, not other nodes.
 
 [#pnode]
-== Rule DSL `lexy::dsl::pnode`
+== Rule DSL `lexy::dsl::pnode` {{< experimental >}}
 
 {{% interface %}}
 ----
@@ -118,7 +119,7 @@ Matching::
 Errors::
   {{% docref "lexy::expected_char_class" %}} with the name of the production, at the starting reader position.
 
-=== Branch rule `lexy::dsl::pnode(child_rule)``
+=== Branch rule `lexy::dsl::pnode(child_rule)`
 
 {{% interface %}}
 ----

diff --git a/docs/content/reference/input/parse_tree_input.adoc b/docs/content/reference/input/parse_tree_input.adoc
@@ -1,5 +1,6 @@
 ---
 header: "lexy/input/parse_tree_input.hpp"
+experimental: true
 entities:
   "lexy::parse_tree_encoding": parse_tree_encoding
   "lexy::parse_tree_input": parse_tree_input
@@ -13,7 +14,7 @@ entities:
 Inputs that read a {{% docref "lexy::parse_tree" %}}.
 
 [#parse_tree_encoding]
-== Encoding `lexy::parse_tree_encoding`
+== Encoding `lexy::parse_tree_encoding` {{< experimental >}}
 
 {{% interface %}}
 ----
@@ -29,7 +30,7 @@ The {{% encoding %}} of a {{% docref "lexy::parse_tree_input" %}}.
 It is a node encoding of the specified `Node` type, which must be a `lexy::parse_tree::node`.
 
 [#parse_tree_input]
-== Input `lexy::parse_tree_input`
+== Input `lexy::parse_tree_input` {{< experimental >}}
 
 {{% interface %}}
 ----

diff --git a/docs/layouts/reference/single.html b/docs/layouts/reference/single.html
@@ -18,11 +18,16 @@
 
 <article id="doc">
     <header>
+        <h1>
         {{ if (isset .Params "header") }}
-        <h1>Header <code>{{ .Params.header }}</code> </h1>
+            Header <code>{{ .Params.header }}</code>
         {{ else }}
-        <h1>{{ .Page.Title }}</h1>
+            {{ .Page.Title }}
         {{ end }}
+        {{ if (index .Params "experimental" | default false) }}
+            <i>{{ (resources.Get "icons/beta.svg").Content | safeHTML }}</i>
+        {{ end }}
+        </h1>
         <nav>
             <a href="{{ .Site.Params.github_src_prefix }}/include/{{ .Params.header }}">
                 {{ (resources.Get "icons/github.svg").Content | safeHTML }} View source

diff --git a/docs/layouts/shortcodes/docref.adoc b/docs/layouts/shortcodes/docref.adoc
@@ -7,7 +7,11 @@
       {{- if ne $.Page.Permalink .Permalink -}}
         {{- $.Page.Scratch.SetInMap "see-also" $name (printf "<a href=%s><code>%s</code></a>" $url $name) -}}
       {{- end -}}
-      link:{{ $url }}[{{ $text }}]
+      link:{{ $url }}[{{ $text }}{nbsp}
+      {{- if (index .Params "experimental" | default false) -}}
+          +++{{- (resources.Get "icons/beta.svg").Content | safeHTML -}}+++
+      {{- end -}}
+      ]
       {{- $found = true -}}
   {{- end -}}
 {{- end -}}

diff --git a/docs/layouts/shortcodes/experimental.html b/docs/layouts/shortcodes/experimental.html
@@ -0,0 +1 @@
+<i>{{ (resources.Get "icons/beta.svg").Content | safeHTML }}</i>
diff --git a/include/lexy/_detail/config.hpp b/include/lexy/_detail/config.hpp
@@ -17,6 +17,14 @@
 #    endif
 #endif
 
+#ifndef LEXY_HAS_UNICODE_DATABASE
+#    define LEXY_HAS_UNICODE_DATABASE 0
+#endif
+
+#ifndef LEXY_EXPERIMENTAL
+#    define LEXY_EXPERIMENTAL 0
+#endif
+
 //=== utility traits===//
 #define LEXY_MOV(...) static_cast<std::remove_reference_t<decltype(__VA_ARGS__)>&&>(__VA_ARGS__)
 #define LEXY_FWD(...) static_cast<decltype(__VA_ARGS__)>(__VA_ARGS__)

diff --git a/include/lexy/code_point.hpp b/include/lexy/code_point.hpp
@@ -8,10 +8,6 @@
 #include <lexy/_detail/assert.hpp>
 #include <lexy/_detail/config.hpp>
 
-#ifndef LEXY_HAS_UNICODE_DATABASE
-#    define LEXY_HAS_UNICODE_DATABASE 0
-#endif
-
 #if LEXY_HAS_UNICODE_DATABASE
 #    define LEXY_UNICODE_CONSTEXPR constexpr
 #else

diff --git a/include/lexy/dsl.hpp b/include/lexy/dsl.hpp
@@ -40,7 +40,6 @@
 #include <lexy/dsl/operator.hpp>
 #include <lexy/dsl/option.hpp>
 #include <lexy/dsl/parse_as.hpp>
-#include <lexy/dsl/parse_tree_node.hpp>
 #include <lexy/dsl/peek.hpp>
 #include <lexy/dsl/position.hpp>
 #include <lexy/dsl/production.hpp>
@@ -61,5 +60,9 @@
 #include <lexy/dsl/until.hpp>
 #include <lexy/dsl/whitespace.hpp>
 
+#if LEXY_EXPERIMENTAL
+#    include <lexy/dsl/parse_tree_node.hpp>
+#endif
+
 #endif // LEXY_DSL_HPP_INCLUDED
 
diff --git a/include/lexy/dsl/parse_tree_node.hpp b/include/lexy/dsl/parse_tree_node.hpp
@@ -7,6 +7,10 @@
 #include <lexy/dsl/base.hpp>
 #include <lexy/dsl/token.hpp>
 
+#if !LEXY_EXPERIMENTAL
+#    error "lexy::dsl::tnode/pnode are experimental"
+#endif
+
 //=== impl ===//
 namespace lexyd
 {

diff --git a/include/lexy/input/parse_tree_input.hpp b/include/lexy/input/parse_tree_input.hpp
@@ -9,6 +9,10 @@
 #include <lexy/input/base.hpp>
 #include <lexy/lexeme.hpp>
 
+#if !LEXY_EXPERIMENTAL
+#    error "lexy::parse_tree_input is experimental"
+#endif
+
 namespace lexy
 {
 template <typename Node>

diff --git a/include/lexy/parse_tree.hpp b/include/lexy/parse_tree.hpp
@@ -1220,6 +1220,7 @@ class parse_tree<Reader, TokenKind, MemoryResource>::traverse_range
 };
 } // namespace lexy
 
+#if LEXY_EXPERIMENTAL
 namespace lexy
 {
 template <typename Reader, typename TokenKind>
@@ -1282,6 +1283,7 @@ struct parse_tree_input_traits<_pt_node<Reader, TokenKind>>
     }
 };
 } // namespace lexy
+#endif
 
 #endif // LEXY_PARSE_TREE_HPP_INCLUDED
 
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
@@ -216,3 +216,9 @@ target_sources(lexy_ext INTERFACE ${ext_headers_files})
 add_library(lexy INTERFACE)
 add_alias(lexy lexy)
 target_link_libraries(lexy INTERFACE foonathan::lexy::core foonathan::lexy::file foonathan::lexy::unicode foonathan::lexy::ext)
+
+# Link to enable experimental features.
+add_library(lexy_experimental INTERFACE)
+add_alias(lexy::experimental lexy_experimental)
+target_compile_definitions(lexy_experimental INTERFACE LEXY_EXPERIMENTAL=1)
+
diff --git a/tests/lexy/CMakeLists.txt b/tests/lexy/CMakeLists.txt
@@ -122,5 +122,5 @@ set(tests
     )
 
 add_executable(lexy_test ${tests})
-target_link_libraries(lexy_test PRIVATE lexy_test_base)
+target_link_libraries(lexy_test PRIVATE lexy_test_base foonathan::lexy::experimental)
 
diff --git a/tests/playground/CMakeLists.txt b/tests/playground/CMakeLists.txt
@@ -15,7 +15,7 @@ target_link_libraries(lexy_test_godbolt PRIVATE lexy_test_base)
 #===
 # Compile-only godbolt example tests.
 add_library(lexy_test_godbolt_examples OBJECT)
-target_link_libraries(lexy_test_godbolt_examples PRIVATE lexy_test_base)
+target_link_libraries(lexy_test_godbolt_examples PRIVATE lexy_test_base foonathan::lexy::experimental)
 target_compile_definitions(lexy_test_godbolt_examples PRIVATE LEXY_DISABLE_FILE)
 target_precompile_headers(lexy_test_godbolt_examples PRIVATE
         <lexy/dsl.hpp> <lexy/callback.hpp> <lexy_ext/report_error.hpp> <lexy_ext/compiler_explorer.hpp>)