prism 2.0.0.rc2 → 2.0.0

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

data/include/prism/parser.h

@@ -16,6 +16,10 @@
 #include "prism/magic_comments.h"
 #include "prism/options.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
  * The parser used to parse Ruby source.
  */
@@ -150,6 +154,24 @@ PRISM_EXPORTED_FUNCTION const pm_string_t * pm_parser_filepath(const pm_parser_t
  */
 PRISM_EXPORTED_FUNCTION pm_constant_id_t pm_parser_constant_find(const pm_parser_t *parser, const uint8_t *start, size_t length) PRISM_NONNULL(1, 2);
 
+/**
+ * Add a constant to the parser's constant pool, for naming a node that was not
+ * parsed from the source. If the constant is already in the pool, its existing
+ * id is returned. Otherwise the parser copies the bytes, so they only need to
+ * remain valid for the duration of the call.
+ *
+ * Adding a constant makes the pool larger, so a cache with one entry per
+ * constant built beforehand from pm_parser_constants_size and
+ * pm_parser_constant_at does not cover it. Build such caches after adding any
+ * constants.
+ *
+ * @param parser the parser whose constant pool we want to add to
+ * @param start a pointer to the start of the string to add
+ * @param length the length of the string to add
+ * @returns the id of the constant
+ */
+PRISM_EXPORTED_FUNCTION pm_constant_id_t pm_parser_constant_insert(pm_parser_t *parser, const uint8_t *start, size_t length) PRISM_NONNULL(1, 2);
+
 /**
  * Returns the frozen string literal value of the parser, as determined by the
  * frozen_string_literal magic comment or the option set on the parser.
@@ -227,22 +249,19 @@ PRISM_EXPORTED_FUNCTION int pm_parser_lex_state(const pm_parser_t *parser) PRISM
 PRISM_EXPORTED_FUNCTION size_t pm_parser_comments_size(const pm_parser_t *parser) PRISM_NONNULL(1);
 
 /**
- * A callback function that can be used to process comments found while parsing.
- */
-typedef void (*pm_comment_callback_t)(const pm_comment_t *comment, void *data);
-
-/**
- * Iterates over the comments associated with the given parser and calls the
- * given callback for each comment.
+ * Returns the first comment associated with the given parser. Iterate over the
+ * rest with pm_comment_next, as in:
+ *
+ * ```c
+ * for (const pm_comment_t *comment = pm_parser_comments_first(parser); comment != NULL; comment = pm_comment_next(comment)) {
+ *     pm_location_t location = pm_comment_location(comment);
+ * }
+ * ```
  *
  * @param parser the parser whose comments we want to iterate over
- * @param callback the callback function to call for each comment. This function
- *     will be passed a pointer to the comment and the data parameter passed to
- *     this function.
- * @param data the data to pass to the callback function for each comment. This
- *     can be NULL if no data needs to be passed to the callback function.
+ * @returns the first comment, or NULL if there are no comments
  */
-PRISM_EXPORTED_FUNCTION void pm_parser_comments_each(const pm_parser_t *parser, pm_comment_callback_t callback, void *data) PRISM_NONNULL(1);
+PRISM_EXPORTED_FUNCTION const pm_comment_t * pm_parser_comments_first(const pm_parser_t *parser) PRISM_NONNULL(1);
 
 /**
  * Returns the number of comments owned by the given node. This is 0 if the
@@ -309,22 +328,13 @@ PRISM_EXPORTED_FUNCTION pm_comment_range_t pm_parser_comment_range(const pm_pars
 PRISM_EXPORTED_FUNCTION size_t pm_parser_magic_comments_size(const pm_parser_t *parser) PRISM_NONNULL(1);
 
 /**
- * A callback function that can be used to process magic comments found while parsing.
- */
-typedef void (*pm_magic_comment_callback_t)(const pm_magic_comment_t *magic_comment, void *data);
-
-/**
- * Iterates over the magic comments associated with the given parser and calls the
- * given callback for each magic comment.
+ * Returns the first magic comment associated with the given parser. Iterate
+ * over the rest with pm_magic_comment_next.
  *
  * @param parser the parser whose magic comments we want to iterate over
- * @param callback the callback function to call for each magic comment. This
- *     function will be passed a pointer to the magic comment and the data
- *     parameter passed to this function.
- * @param data the data to pass to the callback function for each magic comment.
- *     This can be NULL if no data needs to be passed to the callback function.
+ * @returns the first magic comment, or NULL if there are no magic comments
  */
-PRISM_EXPORTED_FUNCTION void pm_parser_magic_comments_each(const pm_parser_t *parser, pm_magic_comment_callback_t callback, void *data) PRISM_NONNULL(1);
+PRISM_EXPORTED_FUNCTION const pm_magic_comment_t * pm_parser_magic_comments_first(const pm_parser_t *parser) PRISM_NONNULL(1);
 
 /**
  * Returns the number of errors associated with the given parser.
@@ -343,36 +353,22 @@ PRISM_EXPORTED_FUNCTION size_t pm_parser_errors_size(const pm_parser_t *parser)
 PRISM_EXPORTED_FUNCTION size_t pm_parser_warnings_size(const pm_parser_t *parser) PRISM_NONNULL(1);
 
 /**
- * A callback function that can be used to process diagnostics found while
- * parsing.
- */
-typedef void (*pm_diagnostic_callback_t)(const pm_diagnostic_t *diagnostic, void *data);
-
-/**
- * Iterates over the errors associated with the given parser and calls the
- * given callback for each error.
+ * Returns the first error associated with the given parser. Iterate over the
+ * rest with pm_diagnostic_next.
  *
  * @param parser the parser whose errors we want to iterate over
- * @param callback the callback function to call for each error. This function
- *     will be passed a pointer to the error and the data parameter passed to
- *     this function.
- * @param data the data to pass to the callback function for each error. This
- *     can be NULL if no data needs to be passed to the callback function.
+ * @returns the first error, or NULL if there are no errors
  */
-PRISM_EXPORTED_FUNCTION void pm_parser_errors_each(const pm_parser_t *parser, pm_diagnostic_callback_t callback, void *data) PRISM_NONNULL(1);
+PRISM_EXPORTED_FUNCTION const pm_diagnostic_t * pm_parser_errors_first(const pm_parser_t *parser) PRISM_NONNULL(1);
 
 /**
- * Iterates over the warnings associated with the given parser and calls the
- * given callback for each warning.
+ * Returns the first warning associated with the given parser. Iterate over the
+ * rest with pm_diagnostic_next.
  *
  * @param parser the parser whose warnings we want to iterate over
- * @param callback the callback function to call for each warning. This function
- *     will be passed a pointer to the warning and the data parameter passed to
- *     this function.
- * @param data the data to pass to the callback function for each warning. This
- *     can be NULL if no data needs to be passed to the callback function.
+ * @returns the first warning, or NULL if there are no warnings
  */
-PRISM_EXPORTED_FUNCTION void pm_parser_warnings_each(const pm_parser_t *parser, pm_diagnostic_callback_t callback, void *data) PRISM_NONNULL(1);
+PRISM_EXPORTED_FUNCTION const pm_diagnostic_t * pm_parser_warnings_first(const pm_parser_t *parser) PRISM_NONNULL(1);
 
 /**
  * Returns the number of constants in the constant pool associated with the
@@ -386,30 +382,38 @@ PRISM_EXPORTED_FUNCTION void pm_parser_warnings_each(const pm_parser_t *parser,
 PRISM_EXPORTED_FUNCTION size_t pm_parser_constants_size(const pm_parser_t *parser) PRISM_NONNULL(1);
 
 /**
- * A callback function that can be used to process constants found while
- * parsing.
- */
-typedef void (*pm_constant_callback_t)(const pm_constant_t *constant, void *data);
-
-/**
- * Iterates over the constants in the constant pool associated with the given
- * parser and calls the given callback for each constant.
+ * Returns the constant at the given index in the constant pool associated with
+ * the given parser. Together with pm_constant_id_index, this lets a caller
+ * build a cache with one entry per constant and then find the entry for any
+ * constant id, as in:
  *
- * @param parser the parser whose constants we want to iterate over
- * @param callback the callback function to call for each constant. This function
- *     will be passed a pointer to the constant and the data parameter passed to
- *     this function.
- * @param data the data to pass to the callback function for each constant. This
- *     can be NULL if no data needs to be passed to the callback function.
+ * ```c
+ * size_t size = pm_parser_constants_size(parser);
+ * for (size_t index = 0; index < size; index++) {
+ *     cache[index] = convert(pm_parser_constant_at(parser, index));
+ * }
+ *
+ * value = cache[pm_constant_id_index(constant_id)];
+ * ```
+ *
+ * For any constant id, pm_parser_constant_at(parser,
+ * pm_constant_id_index(constant_id)) is pm_parser_constant(parser,
+ * constant_id).
+ *
+ * @param parser the parser whose constant pool we want to look up from
+ * @param index the index of the constant, which must be less than
+ *     pm_parser_constants_size(parser)
+ * @returns a pointer to the constant at the given index
  */
-PRISM_EXPORTED_FUNCTION void pm_parser_constants_each(const pm_parser_t *parser, pm_constant_callback_t callback, void *data) PRISM_NONNULL(1);
+PRISM_EXPORTED_FUNCTION const pm_constant_t * pm_parser_constant_at(const pm_parser_t *parser, size_t index) PRISM_NONNULL(1);
 
 /**
  * Returns a pointer to the constant at the given id in the constant pool
  * associated with the given parser.
  *
  * @param parser the parser whose constant pool we want to look up from
- * @param constant_id the id of the constant to look up (1-based)
+ * @param constant_id the id of the constant to look up. Optional constant
+ *     fields on nodes hold 0 when they are absent, which is not a valid id.
  * @returns a pointer to the constant at the given id
  */
 PRISM_EXPORTED_FUNCTION const pm_constant_t * pm_parser_constant(const pm_parser_t *parser, pm_constant_id_t constant_id) PRISM_NONNULL(1);
@@ -422,4 +426,8 @@ PRISM_EXPORTED_FUNCTION const pm_constant_t * pm_parser_constant(const pm_parser
  */
 PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse(pm_parser_t *parser) PRISM_NONNULL(1);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif