prism 1.9.0 → 2.0.0.rc2

data/include/prism/buffer.h

@@ -0,0 +1,52 @@
+/**
+ * @file buffer.h
+ *
+ * A wrapper around a contiguous block of allocated memory.
+ */
+#ifndef PRISM_BUFFER_H
+#define PRISM_BUFFER_H
+
+#include "prism/compiler/exported.h"
+#include "prism/compiler/nodiscard.h"
+#include "prism/compiler/nonnull.h"
+
+#include <stddef.h>
+
+/**
+ * A wrapper around a contiguous block of allocated memory.
+ */
+typedef struct pm_buffer_t pm_buffer_t;
+
+/**
+ * Allocate and initialize a new buffer. If the buffer cannot be allocated, this
+ * function will abort the process.
+ *
+ * @returns A pointer to the initialized buffer. The caller is responsible for
+ *     freeing the buffer with pm_buffer_free.
+ */
+PRISM_NODISCARD PRISM_EXPORTED_FUNCTION pm_buffer_t * pm_buffer_new(void);
+
+/**
+ * Free both the memory held by the buffer and the buffer itself.
+ *
+ * @param buffer The buffer to free.
+ */
+PRISM_EXPORTED_FUNCTION void pm_buffer_free(pm_buffer_t *buffer) PRISM_NONNULL(1);
+
+/**
+ * Return the value of the buffer.
+ *
+ * @param buffer The buffer to get the value of.
+ * @returns The value of the buffer.
+ */
+PRISM_EXPORTED_FUNCTION char * pm_buffer_value(const pm_buffer_t *buffer) PRISM_NONNULL(1);
+
+/**
+ * Return the length of the buffer.
+ *
+ * @param buffer The buffer to get the length of.
+ * @returns The length of the buffer.
+ */
+PRISM_EXPORTED_FUNCTION size_t pm_buffer_length(const pm_buffer_t *buffer) PRISM_NONNULL(1);
+
+#endif

data/include/prism/comments.h

@@ -0,0 +1,55 @@
+/**
+ * @file comments.h
+ *
+ * Types and functions related to comments found during parsing.
+ */
+#ifndef PRISM_COMMENTS_H
+#define PRISM_COMMENTS_H
+
+#include "prism/compiler/exported.h"
+#include "prism/compiler/nodiscard.h"
+#include "prism/compiler/nonnull.h"
+
+#include "prism/ast.h"
+
+#include <stddef.h>
+
+/** This is the type of a comment that we've found while parsing. */
+typedef enum {
+    PM_COMMENT_INLINE,
+    PM_COMMENT_EMBDOC
+} pm_comment_type_t;
+
+/** An opaque pointer to a comment found while parsing. */
+typedef struct pm_comment_t pm_comment_t;
+
+/**
+ * The comments owned by a node, as a slice of the comment attachments of the
+ * parser that produced it.
+ */
+typedef struct {
+    /** The index of the first attachment owned by the node. */
+    uint32_t index;
+
+    /** The number of attachments owned by the node. */
+    uint32_t length;
+} pm_comment_range_t;
+
+/**
+ * Returns the location associated with the given comment.
+ *
+ * @param comment the comment whose location we want to get
+ * @returns the location associated with the given comment
+ */
+PRISM_EXPORTED_FUNCTION pm_location_t pm_comment_location(const pm_comment_t *comment) PRISM_NONNULL(1);
+
+/**
+ * Returns the type associated with the given comment.
+ *
+ * @param comment the comment whose type we want to get
+ * @returns the type associated with the given comment. This can either be
+ *     PM_COMMENT_INLINE or PM_COMMENT_EMBDOC.
+ */
+PRISM_EXPORTED_FUNCTION pm_comment_type_t pm_comment_type(const pm_comment_t *comment) PRISM_NONNULL(1);
+
+#endif

data/include/prism/compiler/accel.h

@@ -0,0 +1,26 @@
+/**
+ * @file compiler/accel.h
+ */
+#ifndef PRISM_COMPILER_ACCEL_H
+#define PRISM_COMPILER_ACCEL_H
+
+#include "prism/compiler/endianness.h"
+
+/**
+ * Platform detection for SIMD/fast-path implementations. At most one of these
+ * macros is defined, selecting the best available vectorization strategy.
+ *
+ * Selection is made at compile time with no runtime CPU detection, and
+ * precompiled binaries run on machines other than the one that built them. So
+ * each strategy relies only on instructions that the architecture baseline
+ * guarantees: NEON is mandatory on AArch64 and SSE2 is mandatory on x86-64.
+ */
+#if (defined(__aarch64__) && defined(__ARM_NEON)) || (defined(_MSC_VER) && defined(_M_ARM64))
+#   define PRISM_HAS_NEON
+#elif (defined(__x86_64__) && defined(__SSE2__)) || (defined(_MSC_VER) && defined(_M_X64))
+#   define PRISM_HAS_SSE2
+#elif defined(PRISM_LITTLE_ENDIAN_COMPTIME)
+#   define PRISM_HAS_SWAR
+#endif
+
+#endif

data/include/prism/compiler/align.h

@@ -0,0 +1,36 @@
+/**
+ * @file compiler/align.h
+ */
+#ifndef PRISM_COMPILER_ALIGN_H
+#define PRISM_COMPILER_ALIGN_H
+
+/**
+ * Compiler-agnostic macros for specifying alignment of types and variables.
+ */
+#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L /* C11 or later */
+    /** Specify alignment for a type or variable. */
+    #define PRISM_ALIGNAS _Alignas
+
+    /** Get the alignment requirement of a type. */
+    #define PRISM_ALIGNOF _Alignof
+#elif defined(__GNUC__) || defined(__clang__)
+    /** Specify alignment for a type or variable. */
+    #define PRISM_ALIGNAS(size) __attribute__((aligned(size)))
+
+    /** Get the alignment requirement of a type. */
+    #define PRISM_ALIGNOF(type) __alignof__(type)
+#elif defined(_MSC_VER)
+    /** Specify alignment for a type or variable. */
+    #define PRISM_ALIGNAS(size) __declspec(align(size))
+
+    /** Get the alignment requirement of a type. */
+    #define PRISM_ALIGNOF(type) __alignof(type)
+#else
+    /** Void because this platform does not support specifying alignment. */
+    #define PRISM_ALIGNAS(size)
+
+    /** Fallback to sizeof as alignment requirement of a type. */
+    #define PRISM_ALIGNOF(type) sizeof(type)
+#endif
+
+#endif

data/include/prism/compiler/assume.h

@@ -0,0 +1,25 @@
+/**
+ * @file compiler/assume.h
+ */
+#ifndef PRISM_COMPILER_ASSUME_H
+#define PRISM_COMPILER_ASSUME_H
+
+/**
+ * Tell the compiler that the given expression can be assumed to be true. Unlike
+ * assert, this emits no runtime check — it only feeds the optimizer's value
+ * range analysis so it can prune impossible paths. Use it to communicate an
+ * invariant the caller guarantees but that the compiler cannot otherwise prove.
+ */
+#if defined(__clang__)
+    #define PRISM_ASSUME(expr_) __builtin_assume(expr_)
+#elif defined(_MSC_VER)
+    #define PRISM_ASSUME(expr_) __assume(expr_)
+#elif defined(__GNUC__) && (__GNUC__ >= 13)
+    #define PRISM_ASSUME(expr_) __attribute__((assume(expr_)))
+#elif defined(__GNUC__)
+    #define PRISM_ASSUME(expr_) ((expr_) ? (void) 0 : __builtin_unreachable())
+#else
+    #define PRISM_ASSUME(expr_) ((void) 0)
+#endif
+
+#endif

data/include/prism/compiler/bswap.h

@@ -0,0 +1,46 @@
+/**
+ * @file compiler/bswap.h
+ */
+#ifndef PRISM_COMPILER_BSWAP_H
+#define PRISM_COMPILER_BSWAP_H
+
+/**
+ * Byte swap utilities for 32-bit and 64-bit integers.
+ */
+#if defined(__GNUC__) || defined(__clang__)
+#define pm_bswap32(x_) __builtin_bswap32((x_))
+#define pm_bswap64(x_) __builtin_bswap64((x_))
+#elif defined(_MSC_VER)
+#include <stdlib.h>
+
+#define pm_bswap32(x_) _byteswap_ulong((x_))
+#define pm_bswap64(x_) _byteswap_uint64((x_))
+#else
+#include <stdint.h>
+
+static uint32_t
+pm_bswap32(uint32_t x) {
+    return (
+      ((x >> 24) & 0x000000FFUL) |
+      ((x << 24) & 0xFF000000UL) |
+      ((x >> 8)  & 0x0000FF00UL) |
+      ((x << 8)  & 0x00FF0000UL)
+    );
+}
+
+static uint64_t
+pm_bswap64(uint64_t x) {
+    return (
+      ((x >> 56) & 0x00000000000000FFULL) |
+      ((x << 56) & 0xFF00000000000000ULL) |
+      ((x >> 40) & 0x000000000000FF00ULL) |
+      ((x << 40) & 0x00FF000000000000ULL) |
+      ((x >> 24) & 0x0000000000FF0000ULL) |
+      ((x << 24) & 0x0000FF0000000000ULL) |
+      ((x >> 8)  & 0x00000000FF000000ULL) |
+      ((x << 8)  & 0x000000FF00000000ULL)
+    );
+}
+#endif
+
+#endif

data/include/prism/compiler/endianness.h

@@ -0,0 +1,34 @@
+/**
+ * @file compiler/endianness.h
+ */
+#ifndef PRISM_COMPILER_ENDIANNESS_H
+#define PRISM_COMPILER_ENDIANNESS_H
+
+/**
+ * Detect endianness at compile-time through the use of predefined macros.
+ */
+#if defined(_WIN32) || defined(__LITTLE_ENDIAN__) || (defined(__BYTE_ORDER__) && defined(__ORDER_LITTLE_ENDIAN__) && __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__)
+#define PRISM_LITTLE_ENDIAN_COMPTIME
+#endif
+
+/**
+ * Determine endianness at runtime, either through predefined macros or through
+ * a runtime check that is usually folded.
+ */
+#if defined(PRISM_LITTLE_ENDIAN_COMPTIME)
+#define PRISM_LITTLE_ENDIAN_RUNTIME 1
+#elif defined(__BIG_ENDIAN__) || (defined(__BYTE_ORDER__) && defined(__ORDER_BIG_ENDIAN__) && __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__)
+#define PRISM_LITTLE_ENDIAN_RUNTIME 0
+#else
+#include <stdint.h>
+
+static inline int
+pm_little_endian(void) {
+    const union { uint32_t u; uint8_t c[4]; } one = { 1 };
+    return one.c[0];
+}
+
+#define PRISM_LITTLE_ENDIAN_RUNTIME pm_little_endian()
+#endif
+
+#endif

data/include/prism/compiler/exported.h

@@ -0,0 +1,24 @@
+/**
+ * @file compiler/exported.h
+ */
+#ifndef PRISM_COMPILER_EXPORTED_H
+#define PRISM_COMPILER_EXPORTED_H
+
+/**
+ * By default, we compile with -fvisibility=hidden. When this is enabled, we
+ * need to mark certain functions as being publically-visible. This macro does
+ * that in a compiler-agnostic way.
+ */
+#ifndef PRISM_EXPORTED_FUNCTION
+#   ifdef PRISM_EXPORT_SYMBOLS
+#       ifdef _WIN32
+#          define PRISM_EXPORTED_FUNCTION __declspec(dllexport) extern
+#       else
+#          define PRISM_EXPORTED_FUNCTION __attribute__((__visibility__("default"))) extern
+#       endif
+#   else
+#       define PRISM_EXPORTED_FUNCTION
+#   endif
+#endif
+
+#endif

data/include/prism/compiler/fallthrough.h

@@ -0,0 +1,22 @@
+/**
+ * @file compiler/fallthrough.h
+ */
+#ifndef PRISM_COMPILER_FALLTHROUGH_H
+#define PRISM_COMPILER_FALLTHROUGH_H
+
+/**
+ * We use -Wimplicit-fallthrough to guard potentially unintended fall-through
+ * between cases of a switch. Use PRISM_FALLTHROUGH to explicitly annotate cases
+ * where the fallthrough is intentional.
+ */
+#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202311L /* C23 or later */
+    #define PRISM_FALLTHROUGH [[fallthrough]];
+#elif defined(__GNUC__) || defined(__clang__)
+    #define PRISM_FALLTHROUGH __attribute__((fallthrough));
+#elif defined(_MSC_VER)
+    #define PRISM_FALLTHROUGH __fallthrough;
+#else
+    #define PRISM_FALLTHROUGH
+#endif
+
+#endif

data/include/prism/compiler/filesystem.h

@@ -0,0 +1,32 @@
+/**
+ * @file compiler/filesystem.h
+ *
+ * Platform detection for mmap and filesystem support.
+ */
+#ifndef PRISM_COMPILER_FILESYSTEM_H
+#define PRISM_COMPILER_FILESYSTEM_H
+
+/**
+ * In general, libc for embedded systems does not support memory-mapped files.
+ * If the target platform is POSIX or Windows, we can map a file in memory and
+ * read it in a more efficient manner.
+ */
+#ifdef _WIN32
+#   define PRISM_HAS_MMAP
+#else
+#   include <unistd.h>
+#   ifdef _POSIX_MAPPED_FILES
+#       define PRISM_HAS_MMAP
+#   endif
+#endif
+
+/**
+ * If PRISM_HAS_NO_FILESYSTEM is defined, then we want to exclude all filesystem
+ * related code from the library. All filesystem related code should be guarded
+ * by PRISM_HAS_FILESYSTEM.
+ */
+#ifndef PRISM_HAS_NO_FILESYSTEM
+#   define PRISM_HAS_FILESYSTEM
+#endif
+
+#endif

data/include/prism/compiler/flex_array.h

@@ -0,0 +1,19 @@
+/**
+ * @file compiler/flex_array.h
+ */
+#ifndef PRISM_COMPILER_FLEX_ARRAY_H
+#define PRISM_COMPILER_FLEX_ARRAY_H
+
+/**
+ * A macro for helper define a flexible array member. C99 supports `data[]`, GCC
+ * supports `data[0]` as an extension, and older compilers require `data[1]`.
+ */
+#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
+    #define PM_FLEX_ARRAY_LENGTH   /* data[] */
+#elif defined(__GNUC__) && !defined(__STRICT_ANSI__)
+    #define PM_FLEX_ARRAY_LENGTH 0 /* data[0] */
+#else
+    #define PM_FLEX_ARRAY_LENGTH 1 /* data[1] */
+#endif
+
+#endif

data/include/prism/compiler/force_inline.h

@@ -0,0 +1,21 @@
+/**
+ * @file compiler/force_inline.h
+ */
+#ifndef PRISM_COMPILER_FORCE_INLINE_H
+#define PRISM_COMPILER_FORCE_INLINE_H
+
+#include "prism/compiler/inline.h"
+
+/**
+ * Force a function to be inlined at every call site. Use sparingly — only for
+ * small, hot functions where the compiler's heuristics fail to inline.
+ */
+#if defined(_MSC_VER)
+#   define PRISM_FORCE_INLINE __forceinline
+#elif defined(__GNUC__) || defined(__clang__)
+#   define PRISM_FORCE_INLINE PRISM_INLINE __attribute__((always_inline))
+#else
+#   define PRISM_FORCE_INLINE PRISM_INLINE
+#endif
+
+#endif

data/include/prism/compiler/format.h

@@ -0,0 +1,25 @@
+/**
+ * @file compiler/format.h
+ */
+#ifndef PRISM_COMPILER_FORMAT_H
+#define PRISM_COMPILER_FORMAT_H
+
+/**
+ * Certain compilers support specifying that a function accepts variadic
+ * parameters that look like printf format strings to provide a better developer
+ * experience when someone is using the function. This macro does that in a
+ * compiler-agnostic way.
+ */
+#if defined(__GNUC__)
+#   if defined(__MINGW_PRINTF_FORMAT)
+#       define PRISM_ATTRIBUTE_FORMAT(fmt_idx_, arg_idx_) __attribute__((format(__MINGW_PRINTF_FORMAT, fmt_idx_, arg_idx_)))
+#   else
+#       define PRISM_ATTRIBUTE_FORMAT(fmt_idx_, arg_idx_) __attribute__((format(printf, fmt_idx_, arg_idx_)))
+#   endif
+#elif defined(__clang__)
+#   define PRISM_ATTRIBUTE_FORMAT(fmt_idx_, arg_idx_) __attribute__((__format__(__printf__, fmt_idx_, arg_idx_)))
+#else
+#   define PRISM_ATTRIBUTE_FORMAT(fmt_idx_, arg_idx_)
+#endif
+
+#endif

data/include/prism/compiler/inline.h

@@ -0,0 +1,17 @@
+/**
+ * @file compiler/inline.h
+ */
+#ifndef PRISM_COMPILER_INLINE_H
+#define PRISM_COMPILER_INLINE_H
+
+/**
+ * Old Visual Studio versions do not support the inline keyword, so we need to
+ * define it to be __inline.
+ */
+#if defined(_MSC_VER) && !defined(inline)
+#   define PRISM_INLINE __inline
+#else
+#   define PRISM_INLINE inline
+#endif
+
+#endif

data/include/prism/compiler/nodiscard.h

@@ -0,0 +1,22 @@
+/**
+ * @file compiler/nodiscard.h
+ */
+#ifndef PRISM_COMPILER_NODISCARD_H
+#define PRISM_COMPILER_NODISCARD_H
+
+/**
+ * Mark the return value of a function as important so that the compiler warns
+ * if a caller ignores it. This is useful for functions that return error codes
+ * or allocated resources that must be freed.
+ */
+#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202311L
+#   define PRISM_NODISCARD [[nodiscard]]
+#elif defined(__GNUC__) || defined(__clang__)
+#   define PRISM_NODISCARD __attribute__((__warn_unused_result__))
+#elif defined(_MSC_VER)
+#   define PRISM_NODISCARD _Check_return_
+#else
+#   define PRISM_NODISCARD
+#endif
+
+#endif

data/include/prism/compiler/nonnull.h

@@ -0,0 +1,18 @@
+/**
+ * @file compiler/nonnull.h
+ */
+#ifndef PRISM_COMPILER_NONNULL_H
+#define PRISM_COMPILER_NONNULL_H
+
+/**
+ * Mark the parameters of a function as non-null. This allows the compiler to
+ * warn if a caller passes NULL for a parameter that should never be NULL. The
+ * arguments are the 1-based indices of the parameters.
+ */
+#if defined(__GNUC__) || defined(__clang__)
+#   define PRISM_NONNULL(...) __attribute__((__nonnull__(__VA_ARGS__)))
+#else
+#   define PRISM_NONNULL(...)
+#endif
+
+#endif

data/include/prism/compiler/unused.h

@@ -0,0 +1,18 @@
+/**
+ * @file compiler/unused.h
+ */
+#ifndef PRISM_COMPILER_UNUSED_H
+#define PRISM_COMPILER_UNUSED_H
+
+/**
+ * GCC will warn if you specify a function or parameter that is unused at
+ * runtime. This macro allows you to mark a function or parameter as unused in a
+ * compiler-agnostic way.
+ */
+#if defined(__GNUC__)
+#   define PRISM_UNUSED __attribute__((unused))
+#else
+#   define PRISM_UNUSED
+#endif
+
+#endif

data/include/prism/constant_pool.h

@@ -0,0 +1,81 @@
+/**
+ * @file constant_pool.h
+ *
+ * A data structure that stores a set of strings.
+ *
+ * Each string is assigned a unique id, which can be used to compare strings for
+ * equality. This comparison ends up being much faster than strcmp, since it
+ * only requires a single integer comparison.
+ */
+#ifndef PRISM_CONSTANT_POOL_H
+#define PRISM_CONSTANT_POOL_H
+
+#include "prism/compiler/exported.h"
+#include "prism/compiler/nodiscard.h"
+#include "prism/compiler/nonnull.h"
+
+#include "prism/arena.h"
+
+#include <stddef.h>
+#include <stdint.h>
+
+/**
+ * A constant id is a unique identifier for a constant in the constant pool.
+ */
+typedef uint32_t pm_constant_id_t;
+
+/**
+ * A list of constant IDs. Usually used to represent a set of locals.
+ */
+typedef struct {
+    /** The number of constant ids in the list. */
+    size_t size;
+
+    /** The number of constant ids that have been allocated in the list. */
+    size_t capacity;
+
+    /** The constant ids in the list. */
+    pm_constant_id_t *ids;
+} pm_constant_id_list_t;
+
+/** A constant in the pool which effectively stores a string. */
+typedef struct pm_constant_t pm_constant_t;
+
+/**
+ * The overall constant pool, which stores constants found while parsing.
+ */
+typedef struct pm_constant_pool_t pm_constant_pool_t;
+
+/**
+ * Return a raw pointer to the start of a constant.
+ *
+ * @param constant The constant to get the start of.
+ * @returns A raw pointer to the start of the constant.
+ */
+PRISM_EXPORTED_FUNCTION const uint8_t * pm_constant_start(const pm_constant_t *constant) PRISM_NONNULL(1);
+
+/**
+ * Return the length of a constant.
+ *
+ * @param constant The constant to get the length of.
+ * @returns The length of the constant.
+ */
+PRISM_EXPORTED_FUNCTION size_t pm_constant_length(const pm_constant_t *constant) PRISM_NONNULL(1);
+
+/**
+ * Initialize a list of constant ids.
+ *
+ * @param list The list to initialize.
+ */
+PRISM_EXPORTED_FUNCTION void pm_constant_id_list_init(pm_constant_id_list_t *list) PRISM_NONNULL(1);
+
+/**
+ * Append a constant id to a list of constant ids.
+ *
+ * @param arena The arena to use for allocations.
+ * @param list The list to append to.
+ * @param id The constant id to append.
+ */
+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);
+
+#endif