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

data/include/prism/buffer.h

@@ -12,6 +12,10 @@
 
 #include <stddef.h>
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
  * A wrapper around a contiguous block of allocated memory.
  */
@@ -49,4 +53,8 @@ PRISM_EXPORTED_FUNCTION char * pm_buffer_value(const pm_buffer_t *buffer) PRISM_
  */
 PRISM_EXPORTED_FUNCTION size_t pm_buffer_length(const pm_buffer_t *buffer) PRISM_NONNULL(1);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif

data/include/prism/buffer.hpp

@@ -0,0 +1,55 @@
+/**
+ * @file buffer.hpp
+ *
+ * Ownership of buffers from C++, and access to their contents.
+ */
+#ifndef PRISM_BUFFER_HPP
+#define PRISM_BUFFER_HPP
+
+#include "prism/compiler/cplusplus.hpp"
+#include "prism/compiler/lifetimebound.hpp"
+
+#include "prism/buffer.h"
+
+#include <memory>
+#include <string_view>
+
+namespace prism {
+
+/** Frees a buffer with pm_buffer_free. */
+struct buffer_deleter {
+    /**
+     * Frees the given buffer.
+     *
+     * @param buffer The buffer to free.
+     */
+    void operator()(pm_buffer_t *buffer) const noexcept { pm_buffer_free(buffer); }
+};
+
+/** An owned buffer. */
+using unique_buffer = std::unique_ptr<pm_buffer_t, buffer_deleter>;
+
+/**
+ * Allocate a new empty buffer. Allocation failure aborts, so this never throws.
+ *
+ * @return A unique_buffer managing the newly allocated buffer.
+ */
+[[nodiscard]] inline unique_buffer
+make_buffer() noexcept {
+    return unique_buffer(pm_buffer_new());
+}
+
+/**
+ * The bytes written to the given buffer so far.
+ *
+ * @param buffer The buffer to view.
+ * @return A string_view of the contents of the buffer.
+ */
+[[nodiscard]] inline std::string_view
+view(const pm_buffer_t *buffer PRISM_LIFETIMEBOUND) noexcept {
+    return std::string_view(pm_buffer_value(buffer), pm_buffer_length(buffer));
+}
+
+}
+
+#endif

data/include/prism/comments.h

@@ -14,6 +14,10 @@
 
 #include <stddef.h>
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /** This is the type of a comment that we've found while parsing. */
 typedef enum {
     PM_COMMENT_INLINE,
@@ -52,4 +56,17 @@ PRISM_EXPORTED_FUNCTION pm_location_t pm_comment_location(const pm_comment_t *co
  */
 PRISM_EXPORTED_FUNCTION pm_comment_type_t pm_comment_type(const pm_comment_t *comment) PRISM_NONNULL(1);
 
+/**
+ * Returns the comment that follows the given comment among the comments
+ * associated with the parser that found it.
+ *
+ * @param comment the comment whose successor we want to get
+ * @returns the next comment, or NULL if the given comment is the last one
+ */
+PRISM_EXPORTED_FUNCTION const pm_comment_t * pm_comment_next(const pm_comment_t *comment) PRISM_NONNULL(1);
+
+#ifdef __cplusplus
+}
+#endif
+
 #endif

data/include/prism/compiler/branch.h

@@ -0,0 +1,26 @@
+/**
+ * @file compiler/branch.h
+ */
+#ifndef PRISM_COMPILER_BRANCH_H
+#define PRISM_COMPILER_BRANCH_H
+
+/**
+ * Branch prediction hints. These tell the compiler which side of a branch to
+ * predicate the fast path through, so it can lay out instructions to favour
+ * that side and steer the static branch predictor.
+ */
+#if defined(__GNUC__) || defined(__clang__)
+    /** The compiler should predicate that this branch will be taken. */
+    #define PRISM_LIKELY(x) __builtin_expect(!!(x), 1)
+
+    /** The compiler should predicate that this branch will not be taken. */
+    #define PRISM_UNLIKELY(x) __builtin_expect(!!(x), 0)
+#else
+    /** Void because this platform does not support branch prediction hints. */
+    #define PRISM_LIKELY(x)   (x)
+
+    /** Void because this platform does not support branch prediction hints. */
+    #define PRISM_UNLIKELY(x) (x)
+#endif
+
+#endif

data/include/prism/compiler/cplusplus.hpp

@@ -0,0 +1,16 @@
+/**
+ * @file compiler/cplusplus.hpp
+ */
+#ifndef PRISM_COMPILER_CPLUSPLUS_HPP
+#define PRISM_COMPILER_CPLUSPLUS_HPP
+
+/**
+ * The C++ interface relies on C++17 for inline variables, std::string_view,
+ * std::void_t, and std::is_invocable_r_v. MSVC reports __cplusplus as 199711L
+ * unless /Zc:__cplusplus is passed, so its own _MSVC_LANG is checked as well.
+ */
+#if !defined(__cplusplus) || ((__cplusplus < 201703L) && (!defined(_MSVC_LANG) || (_MSVC_LANG < 201703L)))
+#   error "the prism C++ interface requires C++17 or later"
+#endif
+
+#endif

data/include/prism/compiler/exceptions.hpp

@@ -0,0 +1,17 @@
+/**
+ * @file compiler/exceptions.hpp
+ */
+#ifndef PRISM_COMPILER_EXCEPTIONS_HPP
+#define PRISM_COMPILER_EXCEPTIONS_HPP
+
+/**
+ * Defined when C++ exceptions are enabled, so that code which catches them can
+ * still compile in builds that disable them, such as with -fno-exceptions.
+ * __cpp_exceptions is the standard feature test macro, and older versions of
+ * GCC and MSVC define __EXCEPTIONS and _CPPUNWIND instead.
+ */
+#if defined(__cpp_exceptions) || defined(__EXCEPTIONS) || defined(_CPPUNWIND)
+#   define PRISM_HAS_EXCEPTIONS
+#endif
+
+#endif

data/include/prism/compiler/format.h

@@ -4,6 +4,8 @@
 #ifndef PRISM_COMPILER_FORMAT_H
 #define PRISM_COMPILER_FORMAT_H
 
+#include <stdio.h>
+
 /**
  * Certain compilers support specifying that a function accepts variadic
  * parameters that look like printf format strings to provide a better developer

data/include/prism/compiler/lifetimebound.hpp

@@ -0,0 +1,25 @@
+/**
+ * @file compiler/lifetimebound.hpp
+ */
+#ifndef PRISM_COMPILER_LIFETIMEBOUND_HPP
+#define PRISM_COMPILER_LIFETIMEBOUND_HPP
+
+/**
+ * Mark a parameter that the return value points into, so that the compiler
+ * warns if a temporary is passed and the return value outlives it. If it is
+ * placed after the qualifiers of a member function, it marks the object
+ * instead.
+ */
+#if defined(__has_cpp_attribute)
+#   if __has_cpp_attribute(clang::lifetimebound)
+#       define PRISM_LIFETIMEBOUND [[clang::lifetimebound]]
+#   elif __has_cpp_attribute(msvc::lifetimebound)
+#       define PRISM_LIFETIMEBOUND [[msvc::lifetimebound]]
+#   endif
+#endif
+
+#ifndef PRISM_LIFETIMEBOUND
+#   define PRISM_LIFETIMEBOUND
+#endif
+
+#endif

data/include/prism/constant_pool.h

@@ -11,6 +11,7 @@
 #define PRISM_CONSTANT_POOL_H
 
 #include "prism/compiler/exported.h"
+#include "prism/compiler/inline.h"
 #include "prism/compiler/nodiscard.h"
 #include "prism/compiler/nonnull.h"
 
@@ -19,11 +20,31 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
  * A constant id is a unique identifier for a constant in the constant pool.
  */
 typedef uint32_t pm_constant_id_t;
 
+/**
+ * Returns the index of the constant with the given id among the constants of
+ * the parser that produced it. The indices run from 0 to one less than
+ * pm_parser_constants_size, so they can index a cache with one entry per
+ * constant that was filled using pm_parser_constant_at.
+ *
+ * @param constant_id the id of the constant. Optional constant fields on nodes
+ *     hold 0 when they are absent, which is not a valid id, so check for it
+ *     before calling this function.
+ * @returns the index of the constant
+ */
+static PRISM_INLINE size_t
+pm_constant_id_index(pm_constant_id_t constant_id) {
+    return (size_t) constant_id - 1;
+}
+
 /**
  * A list of constant IDs. Usually used to represent a set of locals.
  */
@@ -78,4 +99,8 @@ PRISM_EXPORTED_FUNCTION void pm_constant_id_list_init(pm_constant_id_list_t *lis
  */
 PRISM_EXPORTED_FUNCTION void pm_constant_id_list_append(pm_arena_t *arena, pm_constant_id_list_t *list, pm_constant_id_t id) PRISM_NONNULL(1, 2);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif

data/include/prism/diagnostic.h

@@ -12,6 +12,10 @@
 
 #include "prism/ast.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
  * An opaque pointer to a diagnostic generated during parsing.
  */
@@ -90,4 +94,18 @@ PRISM_EXPORTED_FUNCTION pm_error_level_t pm_diagnostic_error_level(const pm_diag
  */
 PRISM_EXPORTED_FUNCTION pm_warning_level_t pm_diagnostic_warning_level(const pm_diagnostic_t *diagnostic) PRISM_NONNULL(1);
 
+/**
+ * Get the diagnostic that follows the given diagnostic among the errors or the
+ * warnings of the parser that produced it.
+ *
+ * @param diagnostic The diagnostic to get the successor of.
+ * @returns The next diagnostic of the same kind, or NULL if the given
+ *     diagnostic is the last one.
+ */
+PRISM_EXPORTED_FUNCTION const pm_diagnostic_t * pm_diagnostic_next(const pm_diagnostic_t *diagnostic) PRISM_NONNULL(1);
+
+#ifdef __cplusplus
+}
+#endif
+
 #endif

data/include/prism/errors_format.h

@@ -14,6 +14,10 @@
 #include "prism/diagnostic.h"
 #include "prism/parser.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /** The type of formatting to use when formatting errors. */
 typedef enum {
     /** Format errors in a plain format with no colors or styles. Typically
@@ -50,4 +54,8 @@ typedef enum {
  */
 PRISM_EXPORTED_FUNCTION pm_error_level_t pm_errors_format(const pm_parser_t *parser, pm_buffer_t *buffer, pm_errors_format_type_t format_type) PRISM_NONNULL(1, 2);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif

data/include/prism/internal/node.h

@@ -14,14 +14,18 @@
 #define PM_LOCATION_END(location_) ((location_)->start + (location_)->length)
 
 /*
- * Slow path for pm_node_list_append: grow the list and append the node.
- * Do not call directly — use pm_node_list_append instead.
+ * Slow path for pm_node_list_append_inline: grow the list and append the node.
+ * Do not call directly — use pm_node_list_append_inline instead.
  */
 void pm_node_list_append_slow(pm_arena_t *arena, pm_node_list_t *list, pm_node_t *node);
 
-/* Append a new node onto the end of the node list. */
+/*
+ * Append a new node onto the end of the node list, handling the common case
+ * inline and growing the list through pm_node_list_append_slow. This is the
+ * version for prism's own code; others call the exported pm_node_list_append.
+ */
 static PRISM_FORCE_INLINE void
-pm_node_list_append(pm_arena_t *arena, pm_node_list_t *list, pm_node_t *node) {
+pm_node_list_append_inline(pm_arena_t *arena, pm_node_list_t *list, pm_node_t *node) {
     if (list->size < list->capacity) {
         list->nodes[list->size++] = node;
     } else {

data/include/prism/internal/stringy.h

@@ -12,7 +12,7 @@ static const uint8_t empty_source[] = "";
  * Defines an empty string. This is useful for initializing a string that will
  * be filled in later.
  */
-#define PM_STRING_EMPTY ((pm_string_t) { .type = PM_STRING_CONSTANT, .source = empty_source, .length = 0 })
+#define PM_STRING_EMPTY ((pm_string_t) { .source = empty_source, .length = 0 })
 
 /*
  * Initialize a shared string that is based on initial input.
@@ -27,9 +27,4 @@ void pm_string_shared_init(pm_string_t *string, const uint8_t *start, const uint
  */
 int pm_string_compare(const pm_string_t *left, const pm_string_t *right);
 
-/*
- * Free the associated memory of the given string.
- */
-void pm_string_cleanup(pm_string_t *string);
-
 #endif

data/include/prism/json.h

@@ -18,6 +18,10 @@
 #include "prism/buffer.h"
 #include "prism/parser.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
  * Dump JSON to the given buffer.
  *
@@ -27,6 +31,10 @@
  */
 PRISM_EXPORTED_FUNCTION void pm_dump_json(pm_buffer_t *buffer, const pm_parser_t *parser, const pm_node_t *node) PRISM_NONNULL(1, 2, 3);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif
 
 #endif

data/include/prism/line_offset_list.h

@@ -20,6 +20,10 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
  * A list of offsets of the start of lines in a string. The offsets are assumed
  * to be sorted/inserted in ascending order.
@@ -58,4 +62,8 @@ typedef struct {
  */
 PRISM_EXPORTED_FUNCTION pm_line_column_t pm_line_offset_list_line_column(const pm_line_offset_list_t *list, uint32_t cursor, int32_t start_line) PRISM_NONNULL(1);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif

data/include/prism/magic_comments.h

@@ -13,6 +13,10 @@
 
 #include <stddef.h>
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /** An opaque pointer to a magic comment found while parsing. */
 typedef struct pm_magic_comment_t pm_magic_comment_t;
 
@@ -32,4 +36,18 @@ PRISM_EXPORTED_FUNCTION pm_location_t pm_magic_comment_key(const pm_magic_commen
  */
 PRISM_EXPORTED_FUNCTION pm_location_t pm_magic_comment_value(const pm_magic_comment_t *magic_comment) PRISM_NONNULL(1);
 
+/**
+ * Returns the magic comment that follows the given magic comment among the
+ * magic comments associated with the parser that found it.
+ *
+ * @param magic_comment the magic comment whose successor we want to get
+ * @returns the next magic comment, or NULL if the given magic comment is the
+ *     last one
+ */
+PRISM_EXPORTED_FUNCTION const pm_magic_comment_t * pm_magic_comment_next(const pm_magic_comment_t *magic_comment) PRISM_NONNULL(1);
+
+#ifdef __cplusplus
+}
+#endif
+
 #endif

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