v5.2.0

CHANGELOG.md

@@ -1,3 +1,13 @@
+## v5.2.0
+
+### New Features
+
+- Tree node handles can now be used directly as a boolean condition (e.g.
+  `if (node)`) in C++ (an `explicit operator bool()`) and D (an
+  `opCast!bool`), equivalent to testing `valid()` / `valid`. C and Rust do not
+  support a user-defined conversion to a boolean condition; use
+  `p_node_valid(node)` and `node.valid()` there.
+
 ## v5.1.0
 
 ### New Features

assets/parser.d.erb

@@ -149,6 +149,12 @@ public struct <%= @grammar.tree_prefix %>Token<%= @grammar.tree_suffix %>
         return __id != 0u;
     }
 
+    /** Support using this handle directly as a boolean condition. */
+    bool opCast(T : bool)()
+    {
+        return __id != 0u;
+    }
+
     /** Return the node ID (for identity comparison). */
     @property <%= @grammar.prefix %>node_id_t node_id()
     {
@@ -183,6 +189,12 @@ public struct <%= @grammar.tree_prefix %><%= rule_set.name %><%= @grammar.tree_s
         return __id != 0u;
     }
 
+    /** Support using this handle directly as a boolean condition. */
+    bool opCast(T : bool)()
+    {
+        return __id != 0u;
+    }
+
     /** Return the node ID (for identity comparison). */
     @property <%= @grammar.prefix %>node_id_t node_id()
     {

doc/user_guide.md

@@ -360,6 +360,20 @@ accessors on a node handle:
     record, for token user fields), and `node.node_id()` (for identity
     comparison).
 
+In C++ and D, a node handle can also be used directly as a boolean condition,
+which is equivalent to testing `valid()` (C++) or `valid` (D):
+
+```
+if (node)
+{
+    /* node refers to a valid (non-null) tree node. */
+}
+```
+
+For C, use the `p_node_valid(node)` macro, and for Rust use the `node.valid()`
+method; neither language supports a user-defined conversion to a boolean
+condition.
+
 The positional position expansions (`${$.position}`, `${N.position}`, etc...)
 are not available in tree generation mode; use the position accessors above
 instead.

lib/propane/generator.rb

@@ -712,6 +712,7 @@ class Propane
       out << "    #{p}context_t * __context;"
       out << "    #{p}node_id_t __id;"
       out << "    bool valid() const { return __id != 0u; }"
+      out << "    explicit operator bool() const { return __id != 0u; }"
       out << "    #{p}node_id_t node_id() const { return __id; }"
       out << "    #{p}node_data_t * data() const;"
       out << "    #{p}position_t position() const;"
@@ -728,6 +729,7 @@ class Propane
         out << "    #{p}context_t * __context;"
         out << "    #{p}node_id_t __id;"
         out << "    bool valid() const { return __id != 0u; }"
+        out << "    explicit operator bool() const { return __id != 0u; }"
         out << "    #{p}node_id_t node_id() const { return __id; }"
         out << "    #{p}node_data_t * data() const;"
         out << "    #{p}position_t position() const;"

lib/propane/version.rb

@@ -1,3 +1,3 @@
 class Propane
-  VERSION = "5.1.0"
+  VERSION = "5.2.0"
 end

spec/test_tree.c

@@ -17,6 +17,8 @@ int main()
     assert(p_node_valid(p_tree_walk_Items(items, pItem, pToken1)));
     assert_eq(TOKEN_a, p_tree_walk_Items(items, pItem, pToken1, token));
     assert_eq(11, p_tree_walk_Items(items, pItem, pToken1, pvalue));
+    /* A token node handle from an unmatched rule is invalid. */
+    assert(!p_node_valid(p_tree_walk_Items(items, pItem, pDual, pOne1, pToken1)));
     assert(p_node_valid(p_Items_pItemsMore(items)));
     ItemsMore itemsmore = p_Items_pItemsMore(items);
     assert(p_node_valid(p_ItemsMore_pItem(itemsmore)));

spec/test_tree.cpp

@@ -12,6 +12,13 @@ int main()
     Start start = p_result(context);
     assert(start.pItems1().valid());
     assert(start.pItems().valid());
+    // A rule node handle is usable directly as a boolean condition.
+    assert(start);
+    assert(start.pItems());
+    if (!start.pItems())
+    {
+        return 1;
+    }
     Items items = start.pItems();
     assert_ne(0u, items.node_id());
     assert_eq(start.pItems().node_id(), items.node_id());
@@ -19,6 +26,21 @@ int main()
     assert(items.pItem().pToken1().valid());
     assert_eq(TOKEN_a, items.pItem().pToken1().token());
     assert_eq(11, items.pItem().pToken1().pvalue());
+    // A token node handle is usable directly as a boolean condition.
+    Token token = items.pItem().pToken1();
+    assert(token);
+    if (!token)
+    {
+        return 1;
+    }
+    // An invalid token node handle converts to false.
+    Token invalid_token = items.pItem().pDual().pOne1().pToken1();
+    assert(!invalid_token.valid());
+    assert(!invalid_token);
+    if (invalid_token)
+    {
+        return 1;
+    }
     assert(items.pItemsMore().valid());
     ItemsMore itemsmore = items.pItemsMore();
     assert(itemsmore.pItem().valid());
@@ -42,6 +64,12 @@ int main()
     assert_eq(P_SUCCESS, p_parse(context));
     start = p_result(context);
     assert(!start.pItems().valid());
+    // An invalid rule node handle converts to false.
+    assert(!start.pItems());
+    if (start.pItems())
+    {
+        return 1;
+    }
     assert_eq(0u, start.pItems().node_id());
 
     p_context_delete(context);

spec/test_tree.d

@@ -15,11 +15,33 @@ unittest
     Start start = p_result(context);
     assert(start.pItems1.valid);
     assert(start.pItems.valid);
+    // A rule node handle is usable directly as a boolean condition.
+    assert(start);
+    assert(start.pItems);
+    if (!start.pItems)
+    {
+        assert(false);
+    }
     Items items = start.pItems;
     assert(items.pItem.valid);
     assert(items.pItem.pToken1.valid);
     assert_eq(TOKEN_a, items.pItem.pToken1.token);
     assert_eq(11, items.pItem.pToken1.pvalue);
+    // A token node handle is usable directly as a boolean condition.
+    Token token = items.pItem.pToken1;
+    assert(token);
+    if (!token)
+    {
+        assert(false);
+    }
+    // An invalid token node handle converts to false.
+    Token invalidToken = items.pItem.pDual.pOne1.pToken1;
+    assert(!invalidToken.valid);
+    assert(!invalidToken);
+    if (invalidToken)
+    {
+        assert(false);
+    }
     assert(items.pItemsMore.valid);
     ItemsMore itemsmore = items.pItemsMore;
     assert(itemsmore.pItem.valid);
@@ -43,6 +65,12 @@ unittest
     assert_eq(P_SUCCESS, p_parse(context));
     start = p_result(context);
     assert(!start.pItems.valid);
+    // An invalid rule node handle converts to false.
+    assert(!start.pItems);
+    if (start.pItems)
+    {
+        assert(false);
+    }
 
     p_context_delete(context);
 

spec/test_tree.rs

@@ -13,6 +13,8 @@ fn main() {
         assert!(items.pItem().pToken1().valid());
         assert_eq!(TOKEN_a, items.pItem().pToken1().token());
         assert_eq!(11, items.pItem().pToken1().pvalue());
+        /* A token node handle from an unmatched rule is invalid. */
+        assert!(!items.pItem().pDual().pOne1().pToken1().valid());
         let itemsmore = items.pItemsMore();
         assert!(itemsmore.pItem().pItem().pItem().pToken1().valid());
         assert_eq!(TOKEN_b, itemsmore.pItem().pItem().pItem().pToken1().token());