prism 2.0.0.rc1-x86_64-linux-gnu → 2.0.0-x86_64-linux-gnu

data/include/prism/node.h

@@ -11,6 +11,10 @@
 
 #include "prism/ast.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
  * Loop through each node in the node list, writing each node to the given
  * pm_node_t pointer.
@@ -18,6 +22,18 @@
 #define PM_NODE_LIST_FOREACH(list, index, node) \
     for (size_t index = 0; index < (list)->size && ((node) = (list)->nodes[index]); index++)
 
+/**
+ * Append a node to the end of a node list. If the list is full, its storage is
+ * grown by allocating from the given arena, so the arena must live as long as
+ * the list does. For a list in a parsed tree, that is the arena that was passed
+ * to pm_parser_new.
+ *
+ * @param arena The arena to allocate the list's storage from.
+ * @param list The list to append to.
+ * @param node The node to append.
+ */
+PRISM_EXPORTED_FUNCTION void pm_node_list_append(pm_arena_t *arena, pm_node_list_t *list, pm_node_t *node) PRISM_NONNULL(1, 2, 3);
+
 /**
  * Returns a string representation of the given node type.
  *
@@ -26,20 +42,41 @@
  */
 PRISM_EXPORTED_FUNCTION const char * pm_node_type(pm_node_type_t node_type);
 
+/**
+ * The value returned by a visitor callback, which determines where the walk
+ * goes next.
+ */
+typedef enum {
+    /** Continue the walk without visiting this node's children. */
+    PM_VISIT_SKIP,
+
+    /** Continue the walk by visiting this node's children. */
+    PM_VISIT_DESCEND,
+
+    /** End the walk without visiting any more nodes. */
+    PM_VISIT_STOP
+} pm_visit_result_t;
+
+/**
+ * A callback that is called for each node visited by pm_visit_node and
+ * pm_visit_child_nodes. The data parameter is the opaque pointer that was
+ * passed to the function that started the walk.
+ */
+typedef pm_visit_result_t (*pm_visit_callback_t)(const pm_node_t *node, void *data);
+
 /**
  * Visit each of the nodes in this subtree using the given visitor callback. The
- * callback function will be called for each node in the subtree. If it returns
- * false, then that node's children will not be visited. If it returns true,
- * then the children will be visited. The data parameter is treated as an opaque
- * pointer and is passed to the visitor callback for consumers to use as they
- * see fit.
+ * callback function will be called for each node in the subtree, and its
+ * return value determines whether the walk visits that node's children, skips
+ * them, or stops entirely. The data parameter is treated as an opaque pointer
+ * and is passed to the visitor callback for consumers to use as they see fit.
  *
  * As an example:
  *
  * ```c
  * #include "prism.h"
  *
- * bool visit(const pm_node_t *node, void *data) {
+ * pm_visit_result_t visit(const pm_node_t *node, void *data) {
  *     size_t *indent = (size_t *) data;
  *     for (size_t i = 0; i < *indent * 2; i++) putc(' ', stdout);
  *     printf("%s\n", pm_node_type(node->type));
@@ -48,7 +85,7 @@ PRISM_EXPORTED_FUNCTION const char * pm_node_type(pm_node_type_t node_type);
  *     size_t *next_data = &next_indent;
  *     pm_visit_child_nodes(node, visit, next_data);
  *
- *     return false;
+ *     return PM_VISIT_SKIP;
  * }
  *
  * int main(void) {
@@ -77,18 +114,26 @@ PRISM_EXPORTED_FUNCTION const char * pm_node_type(pm_node_type_t node_type);
  * @param node The root node to start visiting from.
  * @param visitor The callback to call for each node in the subtree.
  * @param data An opaque pointer that is passed to the visitor callback.
+ * @returns false if the visitor stopped the walk by returning PM_VISIT_STOP,
+ *     true otherwise.
  */
-PRISM_EXPORTED_FUNCTION void pm_visit_node(const pm_node_t *node, bool (*visitor)(const pm_node_t *node, void *data), void *data) PRISM_NONNULL(1);
+PRISM_EXPORTED_FUNCTION bool pm_visit_node(const pm_node_t *node, pm_visit_callback_t visitor, void *data) PRISM_NONNULL(1);
 
 /**
  * Visit the children of the given node with the given callback. This is the
  * default behavior for walking the tree that is called from pm_visit_node if
- * the callback returns true.
+ * the callback returns PM_VISIT_DESCEND.
  *
  * @param node The node to visit the children of.
  * @param visitor The callback to call for each child node.
  * @param data An opaque pointer that is passed to the visitor callback.
+ * @returns false if the visitor stopped the walk by returning PM_VISIT_STOP,
+ *     true otherwise.
  */
-PRISM_EXPORTED_FUNCTION void pm_visit_child_nodes(const pm_node_t *node, bool (*visitor)(const pm_node_t *node, void *data), void *data) PRISM_NONNULL(1);
+PRISM_EXPORTED_FUNCTION bool pm_visit_child_nodes(const pm_node_t *node, pm_visit_callback_t visitor, void *data) PRISM_NONNULL(1);
+
+#ifdef __cplusplus
+}
+#endif
 
 #endif

data/include/prism/node.hpp

@@ -0,0 +1,272 @@
+/**
+ * @file node.hpp
+ *
+ * Checked casts between node structs, iteration over lists of nodes, and
+ * walking the tree from C++.
+ */
+#ifndef PRISM_NODE_HPP
+#define PRISM_NODE_HPP
+
+#include "prism/compiler/cplusplus.hpp"
+#include "prism/compiler/exceptions.hpp"
+#include "prism/compiler/lifetimebound.hpp"
+
+#include "prism/ast.hpp"
+#include "prism/node.h"
+#include "prism/node_type.hpp"
+
+#include <cassert>
+#include <cstddef>
+#include <exception>
+#include <functional>
+#include <memory>
+#include <type_traits>
+
+namespace prism {
+
+/**
+ * Whether the given node, which must not be null, is of the given struct
+ *
+ * @tparam T The node struct type to check against.
+ * @param node The node to check.
+ * @return True if the node is of the given struct, false otherwise.
+ */
+template <typename T> [[nodiscard]] bool
+isa(const pm_node_t *node) noexcept {
+    static_assert(is_node_v<T>, "isa<T> requires a node struct declared in ast.h");
+    assert(node != nullptr);
+    return node->type == node_type_v<T>;
+}
+
+/**
+ * Cast the given node, which must not be null and must be of the given struct,
+ * to that struct. The type is checked in debug builds.
+ *
+ * @tparam T The node struct type to cast to.
+ * @param node The node to cast.
+ * @return The node cast to the given struct.
+ */
+template <typename T> [[nodiscard]] T *
+cast(pm_node_t *node) noexcept {
+    assert(isa<T>(node));
+    return reinterpret_cast<T *>(node);
+}
+
+/**
+ * Cast the given node, which must not be null and must be of the given struct,
+ * to that struct. The type is checked in debug builds.
+ *
+ * @tparam T The node struct type to cast to.
+ * @param node The node to cast.
+ * @return The node cast to the given struct.
+ */
+template <typename T> [[nodiscard]] const T *
+cast(const pm_node_t *node) noexcept {
+    assert(isa<T>(node));
+    return reinterpret_cast<const T *>(node);
+}
+
+/**
+ * Cast the given node to the given struct if it is of that struct, and return
+ * null otherwise. The node may be null, in which case this returns null.
+ *
+ * @tparam T The node struct type to cast to.
+ * @param node The node to cast.
+ * @return The node cast to the given struct if it is of that struct, or null
+ *   otherwise.
+ */
+template <typename T> [[nodiscard]] T *
+dyn_cast(pm_node_t *node) noexcept {
+    return (node != nullptr && isa<T>(node)) ? reinterpret_cast<T *>(node) : nullptr;
+}
+
+/**
+ * Cast the given node to the given struct if it is of that struct, and return
+ * null otherwise. The node may be null, in which case this returns null.
+ *
+ * @tparam T The node struct type to cast to.
+ * @param node The node to cast.
+ * @return The node cast to the given struct if it is of that struct, or null
+ *   otherwise.
+ */
+template <typename T> [[nodiscard]] const T *
+dyn_cast(const pm_node_t *node) noexcept {
+    return (node != nullptr && isa<T>(node)) ? reinterpret_cast<const T *>(node) : nullptr;
+}
+
+/**
+ * Return the pm_node_t embedded at the start of the given node struct.
+ *
+ * @tparam T The node struct type.
+ * @param node The node struct to upcast.
+ * @return The pm_node_t embedded at the start of the node struct.
+ */
+template <typename T> [[nodiscard]] pm_node_t *
+upcast(T *node) noexcept {
+    static_assert(is_node_v<T>, "upcast requires a node struct declared in ast.h");
+    return &node->base;
+}
+
+/**
+ * Return the pm_node_t embedded at the start of the given node struct.
+ *
+ * @tparam T The node struct type.
+ * @param node The node struct to upcast.
+ * @return The pm_node_t embedded at the start of the node struct.
+ */
+template <typename T> [[nodiscard]] const pm_node_t *
+upcast(const T *node) noexcept {
+    static_assert(is_node_v<T>, "upcast requires a node struct declared in ast.h");
+    return &node->base;
+}
+
+/**
+ * The nodes in a list, usable in a range-based for loop. It refers to the list
+ * rather than copying it, so the list must outlive it.
+ */
+class node_range {
+public:
+    /**
+     * Create a range over the nodes in the given list.
+     *
+     * @param list The list of nodes to create a range for.
+     */
+    explicit node_range(const pm_node_list_t &list PRISM_LIFETIMEBOUND) noexcept : list_(&list) {}
+
+    /**
+     * A pointer to the first node.
+     *
+     * @return A pointer to the first node, or null if the list is empty.
+     */
+    pm_node_t *const *begin() const noexcept { return list_->nodes; }
+
+    /**
+     * A pointer one past the last node.
+     *
+     * @return A pointer one past the last node, or null if the list is empty.
+     */
+    pm_node_t *const *end() const noexcept { return list_->nodes + list_->size; }
+
+    /**
+     * The number of nodes.
+     *
+     * @return The number of nodes.
+     */
+    std::size_t size() const noexcept { return list_->size; }
+
+    /**
+     * Whether there are no nodes.
+     *
+     * @return True if there are no nodes, false otherwise.
+     */
+    [[nodiscard]] bool empty() const noexcept { return list_->size == 0; }
+
+private:
+    const pm_node_list_t *list_;
+};
+
+namespace detail {
+
+/**
+ * The state shared between a walk and its C callback, passed through the C
+ * function's void * data parameter.
+ */
+template <typename F> struct visit_context {
+    /**
+     * The context for a visit, holding the visitor and any exception thrown.
+     *
+     * @param visitor The visitor callable to be used for each node.
+     */
+    explicit visit_context(F *visitor) noexcept : callable(visitor) {}
+
+    /** The visitor that the walk calls for each node. */
+    F *callable;
+
+#ifdef PRISM_HAS_EXCEPTIONS
+    /** The exception thrown by the visitor, if any. */
+    std::exception_ptr exception;
+#endif
+};
+
+/**
+ * Forwards the C visitor callback to a C++ callable. An exception cannot unwind
+ * through the C frames that call this function, so one thrown by the callable
+ * is caught here and the walk is stopped. The function that started the walk
+ * rethrows it once the C walk has returned. Without exceptions, the callable
+ * cannot throw, so it is called directly.
+ *
+ * @tparam F The type of the visitor callable.
+ * @param node The current node being visited.
+ * @param data The visit context containing the visitor and exception state.
+ * @return The result of the visit, indicating whether to descend, skip, or stop.
+ */
+template <typename F> pm_visit_result_t
+visit_callback(const pm_node_t *node, void *data) noexcept {
+    visit_context<F> *context = static_cast<visit_context<F> *>(data);
+
+#ifdef PRISM_HAS_EXCEPTIONS
+    try {
+        return std::invoke(*context->callable, node);
+    } catch (...) {
+        context->exception = std::current_exception();
+        return PM_VISIT_STOP;
+    }
+#else
+    return std::invoke(*context->callable, node);
+#endif
+}
+
+}
+
+/**
+ * Walk the tree rooted at the given node in pre-order, calling the visitor with
+ * each node. The visitor returns PM_VISIT_DESCEND to continue into that node's
+ * children, PM_VISIT_SKIP to continue past them, or PM_VISIT_STOP to end the
+ * walk. Returns false if the walk was stopped. If the visitor throws, the walk
+ * stops and the exception propagates from this function.
+ *
+ * @tparam F The type of the visitor callable.
+ * @param node The root node to start the walk from.
+ * @param visitor The visitor callable to invoke for each node.
+ * @return True if the walk completed, false if it was stopped.
+ */
+template <typename F> bool
+visit_node(const pm_node_t *node, F &&visitor) {
+    static_assert(std::is_invocable_r_v<pm_visit_result_t, F &, const pm_node_t *>, "visit_node requires a callable taking const pm_node_t * and returning pm_visit_result_t");
+    detail::visit_context<std::remove_reference_t<F>> context(std::addressof(visitor));
+    bool completed = pm_visit_node(node, detail::visit_callback<std::remove_reference_t<F>>, &context);
+
+#ifdef PRISM_HAS_EXCEPTIONS
+    if (context.exception) std::rethrow_exception(context.exception);
+#endif
+
+    return completed;
+}
+
+/**
+ * Walk the children of the given node, as visit_node does for every node whose
+ * visitor returns PM_VISIT_DESCEND. Returns false if the walk was stopped. If
+ * the visitor throws, the walk stops and the exception propagates from this
+ * function.
+ *
+ * @tparam F The type of the visitor callable.
+ * @param node The node whose children to walk.
+ * @param visitor The visitor callable to invoke for each child node.
+ * @return True if the walk completed, false if it was stopped.
+ */
+template <typename F> bool
+visit_child_nodes(const pm_node_t *node, F &&visitor) {
+    static_assert(std::is_invocable_r_v<pm_visit_result_t, F &, const pm_node_t *>, "visit_child_nodes requires a callable taking const pm_node_t * and returning pm_visit_result_t");
+    detail::visit_context<std::remove_reference_t<F>> context(std::addressof(visitor));
+    bool completed = pm_visit_child_nodes(node, detail::visit_callback<std::remove_reference_t<F>>, &context);
+
+#ifdef PRISM_HAS_EXCEPTIONS
+    if (context.exception) std::rethrow_exception(context.exception);
+#endif
+
+    return completed;
+}
+
+}
+
+#endif

data/include/prism/node_type.hpp

@@ -0,0 +1,38 @@
+/**
+ * @file node_type.hpp
+ *
+ * The traits that map node structs to node types. The specialization for each
+ * node struct is generated into ast.hpp.
+ */
+#ifndef PRISM_NODE_TYPE_HPP
+#define PRISM_NODE_TYPE_HPP
+
+#include "prism/compiler/cplusplus.hpp"
+
+#include "prism/ast.h"
+
+#include <type_traits>
+
+namespace prism {
+
+/**
+ * Maps a node struct to its node type, as in node_type<pm_call_node_t>::value
+ * being PM_CALL_NODE. Only the node structs declared in ast.h have a value.
+ */
+template <typename T> struct node_type {};
+
+/** The node type of the given node struct. */
+template <typename T> inline constexpr pm_node_type_t node_type_v = node_type<T>::value;
+
+/** Whether the given type is one of the node structs declared in ast.h. */
+template <typename T, typename = void> struct is_node : std::false_type {};
+
+/** Whether the given type is one of the node structs declared in ast.h. */
+template <typename T> struct is_node<T, std::void_t<decltype(node_type<T>::value)>> : std::true_type {};
+
+/** Whether the given type is one of the node structs declared in ast.h. */
+template <typename T> inline constexpr bool is_node_v = is_node<T>::value;
+
+}
+
+#endif

data/include/prism/options.h

@@ -15,6 +15,10 @@
 #include <stdbool.h>
 #include <stddef.h>
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
  * A scope of locals surrounding the code that is being parsed.
  */
@@ -335,7 +339,8 @@ PRISM_EXPORTED_FUNCTION const pm_string_t * pm_options_scope_local(const pm_opti
 
 /**
  * Return a mutable pointer to the local at the given index within the given
- * scope.
+ * scope, for setting the local's name with pm_string_init. The parser copies
+ * the name when it is created, so its bytes must remain valid until then.
  *
  * @param scope The scope struct to get the local from.
  * @param index The index of the local to get.
@@ -351,4 +356,8 @@ PRISM_EXPORTED_FUNCTION pm_string_t * pm_options_scope_local_mut(pm_options_scop
  */
 PRISM_EXPORTED_FUNCTION void pm_options_scope_forwarding_set(pm_options_scope_t *scope, uint8_t forwarding) PRISM_NONNULL(1);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif

data/include/prism/options.hpp

@@ -0,0 +1,43 @@
+/**
+ * @file options.hpp
+ *
+ * Ownership of parse options from C++.
+ */
+#ifndef PRISM_OPTIONS_HPP
+#define PRISM_OPTIONS_HPP
+
+#include "prism/compiler/cplusplus.hpp"
+
+#include "prism/options.h"
+
+#include <memory>
+
+namespace prism {
+
+/** Frees options with pm_options_free. */
+struct options_deleter {
+    /**
+     * Free the given options.
+     *
+     * @param options The options to free.
+     */
+    void operator()(pm_options_t *options) const noexcept { pm_options_free(options); }
+};
+
+/** An owned set of options. */
+using unique_options = std::unique_ptr<pm_options_t, options_deleter>;
+
+/**
+ * Allocate a new set of options with every option at its default. Allocation
+ * failure aborts, so this never throws.
+ *
+ * @return A unique_options owning the newly allocated options.
+ */
+[[nodiscard]] inline unique_options
+make_options() noexcept {
+    return unique_options(pm_options_new());
+}
+
+}
+
+#endif