prism 2.0.0-arm-linux-musl

data/include/prism/parser.hpp

@@ -0,0 +1,274 @@
+/**
+ * @file parser.hpp
+ *
+ * Ownership of parsers from C++, and lookups through a parser into the source,
+ * the constant pool, comments, and diagnostics.
+ */
+#ifndef PRISM_PARSER_HPP
+#define PRISM_PARSER_HPP
+
+#include "prism/compiler/cplusplus.hpp"
+#include "prism/compiler/lifetimebound.hpp"
+
+#include "prism/arena.h"
+#include "prism/constant_pool.h"
+#include "prism/line_offset_list.h"
+#include "prism/parser.h"
+
+#include <cassert>
+#include <cstddef>
+#include <cstdint>
+#include <iterator>
+#include <memory>
+#include <string_view>
+
+namespace prism {
+
+/** Frees a parser with pm_parser_free. */
+struct parser_deleter {
+    /**
+     * Free the given parser.
+     *
+     * @param parser The parser to free.
+     */
+    void operator()(pm_parser_t *parser) const noexcept { pm_parser_free(parser); }
+};
+
+/** An owned parser. */
+using unique_parser = std::unique_ptr<pm_parser_t, parser_deleter>;
+
+/**
+ * Allocate a new parser over the given source. The source, the arena, and the
+ * options (which may be null) are not copied, so all three must outlive the
+ * parser. Allocation failure aborts, so this never throws.
+ *
+ * @param arena The arena to use for allocations.
+ * @param source The source code to parse.
+ * @param options The parse options, or null for defaults.
+ * @return A unique_parser owning the newly allocated parser.
+ */
+[[nodiscard]] inline unique_parser
+make_parser(pm_arena_t *arena PRISM_LIFETIMEBOUND, std::string_view source PRISM_LIFETIMEBOUND, const pm_options_t *options PRISM_LIFETIMEBOUND = nullptr) noexcept {
+    return unique_parser(pm_parser_new(arena, reinterpret_cast<const std::uint8_t *>(source.data()), source.size(), options));
+}
+
+/**
+ * The name of the constant with the given id, which must not be zero. Fields
+ * holding an optional constant use zero for none, so check those first.
+ *
+ * @param parser The parser containing the constant.
+ * @param constant_id The id of the constant.
+ * @return The value of the constant.
+ */
+[[nodiscard]] inline std::string_view
+constant(const pm_parser_t *parser PRISM_LIFETIMEBOUND, pm_constant_id_t constant_id) noexcept {
+    assert(constant_id != 0);
+    const pm_constant_t *entry = pm_parser_constant(parser, constant_id);
+    return std::string_view(reinterpret_cast<const char *>(pm_constant_start(entry)), pm_constant_length(entry));
+}
+
+/**
+ * The bytes of source that the given location covers.
+ *
+ * @param parser The parser containing the source.
+ * @param location The location in the source.
+ * @return The bytes of source covered by the location.
+ */
+[[nodiscard]] inline std::string_view
+slice(const pm_parser_t *parser PRISM_LIFETIMEBOUND, pm_location_t location) noexcept {
+    return std::string_view(reinterpret_cast<const char *>(pm_parser_start(parser) + location.start), location.length);
+}
+
+/**
+ * The line and column of the given byte offset into the source. Lines start at
+ * the parser's start line, and columns are byte offsets from the line start.
+ *
+ * @param parser The parser containing the source.
+ * @param offset The byte offset into the source.
+ * @return The line and column of the byte offset.
+ */
+[[nodiscard]] inline pm_line_column_t
+line_column(const pm_parser_t *parser, std::uint32_t offset) noexcept {
+    return pm_line_offset_list_line_column(pm_parser_line_offsets(parser), offset, pm_parser_start_line(parser));
+}
+
+namespace detail {
+
+/**
+ * The diagnostics, comments, or magic comments found while parsing, usable in a
+ * range-based for loop and with the standard algorithms. Each element is a
+ * pointer to the C struct, which the C accessors read, and Next is the C
+ * function that returns the item after a given one. It refers to the parser
+ * rather than copying from it, so the parser must outlive it. It is used
+ * through diagnostic_range, comment_range, and magic_comment_range.
+ */
+template <typename T, const T *(*Next)(const T *)> class next_range {
+public:
+    /** Steps through the items one after another. */
+    class iterator {
+    public:
+        /** The iterator category, for the standard algorithms. */
+        using iterator_category = std::forward_iterator_tag;
+
+        /** The type of each element. */
+        using value_type = const T *;
+
+        /** The type of the distance between two iterators. */
+        using difference_type = std::ptrdiff_t;
+
+        /** The type of a pointer to an element. */
+        using pointer = const value_type *;
+
+        /** The type of a reference to an element. */
+        using reference = const value_type &;
+
+        /** Create the iterator that marks the end of the items. */
+        iterator() noexcept = default;
+
+        /**
+         * Create an iterator at the given item.
+         *
+         * @param current The current item.
+         */
+        explicit iterator(const T *current) noexcept : current_(current) {}
+
+        /**
+         * The item at this position, which must not be the end.
+         *
+         * @return The current item.
+         */
+        reference operator*() const noexcept { return current_; }
+
+        /**
+         * Advance to the next item.
+         *
+         * @return The iterator after advancing.
+         */
+        iterator &
+        operator++() noexcept {
+            assert(current_ != nullptr);
+            current_ = Next(current_);
+            return *this;
+        }
+
+        /**
+         * Advance to the next item, returning the iterator from before.
+         *
+         * @return The iterator from before advancing.
+         */
+        iterator
+        operator++(int) noexcept {
+            iterator previous = *this;
+            ++*this;
+            return previous;
+        }
+
+        /** Whether the two iterators are at the same item. */
+        friend bool operator==(iterator left, iterator right) noexcept { return left.current_ == right.current_; }
+
+        /** Whether the two iterators are at different items. */
+        friend bool operator!=(iterator left, iterator right) noexcept { return left.current_ != right.current_; }
+
+    private:
+        const T *current_ = nullptr;
+    };
+
+    /**
+     * Create a range of the given number of items starting at first.
+     *
+     * @param first The first item.
+     * @param size The number of items.
+     */
+    next_range(const T *first, std::size_t size) noexcept : first_(first), size_(size) {}
+
+    /**
+     * An iterator at the first item.
+     *
+     * @return An iterator at the first item.
+     */
+    iterator begin() const noexcept { return iterator(first_); }
+
+    /**
+     * An iterator past the last item.
+     *
+     * @return An iterator past the last item.
+     */
+    iterator end() const noexcept { return iterator(); }
+
+    /**
+     * The number of items.
+     *
+     * @return The number of items.
+     */
+    std::size_t size() const noexcept { return size_; }
+
+    /**
+     * Whether there are no items.
+     *
+     * @return Whether there are no items.
+     */
+    [[nodiscard]] bool empty() const noexcept { return size_ == 0; }
+
+private:
+    const T *first_;
+    std::size_t size_;
+};
+
+}
+
+/** The errors or warnings found while parsing. */
+using diagnostic_range = detail::next_range<pm_diagnostic_t, pm_diagnostic_next>;
+
+/** The comments found while parsing. */
+using comment_range = detail::next_range<pm_comment_t, pm_comment_next>;
+
+/** The magic comments found while parsing. */
+using magic_comment_range = detail::next_range<pm_magic_comment_t, pm_magic_comment_next>;
+
+/**
+ * The errors found while parsing.
+ *
+ * @param parser The parser containing the source.
+ * @return The range of errors found while parsing.
+ */
+[[nodiscard]] inline diagnostic_range
+errors(const pm_parser_t *parser PRISM_LIFETIMEBOUND) noexcept {
+    return diagnostic_range(pm_parser_errors_first(parser), pm_parser_errors_size(parser));
+}
+
+/**
+ * The warnings found while parsing.
+ *
+ * @param parser The parser containing the source.
+ * @return The range of warnings found while parsing.
+ */
+[[nodiscard]] inline diagnostic_range
+warnings(const pm_parser_t *parser PRISM_LIFETIMEBOUND) noexcept {
+    return diagnostic_range(pm_parser_warnings_first(parser), pm_parser_warnings_size(parser));
+}
+
+/**
+ * The comments found while parsing, in source order.
+ *
+ * @param parser The parser containing the source.
+ * @return The range of comments found while parsing.
+ */
+[[nodiscard]] inline comment_range
+comments(const pm_parser_t *parser PRISM_LIFETIMEBOUND) noexcept {
+    return comment_range(pm_parser_comments_first(parser), pm_parser_comments_size(parser));
+}
+
+/**
+ * The magic comments found while parsing.
+ *
+ * @param parser The parser containing the source.
+ * @return The range of magic comments found while parsing.
+ */
+[[nodiscard]] inline magic_comment_range
+magic_comments(const pm_parser_t *parser PRISM_LIFETIMEBOUND) noexcept {
+    return magic_comment_range(pm_parser_magic_comments_first(parser), pm_parser_magic_comments_size(parser));
+}
+
+}
+
+#endif

data/include/prism/prettyprint.h

@@ -0,0 +1,39 @@
+/**
+ * @file prettyprint.h
+ *
+ * An AST node pretty-printer.
+ */
+#ifndef PRISM_PRETTYPRINT_H
+#define PRISM_PRETTYPRINT_H
+
+#include "prism/excludes.h"
+
+#ifndef PRISM_EXCLUDE_PRETTYPRINT
+
+#include "prism/compiler/exported.h"
+#include "prism/compiler/nonnull.h"
+
+#include "prism/ast.h"
+#include "prism/buffer.h"
+#include "prism/parser.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Pretty-prints the AST represented by the given node to the given buffer.
+ *
+ * @param output_buffer The buffer to write the pretty-printed AST to.
+ * @param parser The parser that parsed the AST.
+ * @param node The root node of the AST to pretty-print.
+ */
+PRISM_EXPORTED_FUNCTION void pm_prettyprint(pm_buffer_t *output_buffer, const pm_parser_t *parser, const pm_node_t *node) PRISM_NONNULL(1, 2, 3);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
+
+#endif

data/include/prism/serialize.h

@@ -0,0 +1,123 @@
+/**
+ * @file serialize.h
+ *
+ * The functions related to serializing the AST to a binary format.
+ */
+#ifndef PRISM_SERIALIZE_H
+#define PRISM_SERIALIZE_H
+
+#include "prism/excludes.h"
+
+/* We optionally support serializing to a binary string. For systems that do not
+ * want or need this functionality, it can be turned off with the
+ * PRISM_EXCLUDE_SERIALIZATION define. */
+#ifndef PRISM_EXCLUDE_SERIALIZATION
+
+#include "prism/compiler/exported.h"
+#include "prism/compiler/nonnull.h"
+
+#include "prism/buffer.h"
+#include "prism/errors_format.h"
+#include "prism/parser.h"
+#include "prism/source.h"
+#include "prism/stream.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Serialize the AST represented by the given node to the given buffer.
+ *
+ * @param parser The parser to serialize.
+ * @param node The node to serialize.
+ * @param buffer The buffer to serialize to.
+ */
+PRISM_EXPORTED_FUNCTION void pm_serialize(pm_parser_t *parser, pm_node_t *node, pm_buffer_t *buffer) PRISM_NONNULL(1, 2, 3);
+
+/**
+ * Parse the given source to the AST and dump the AST to the given buffer.
+ *
+ * @param buffer The buffer to serialize to.
+ * @param source The source to parse.
+ * @param size The size of the source.
+ * @param data The optional data to pass to the parser.
+ */
+PRISM_EXPORTED_FUNCTION void pm_serialize_parse(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data) PRISM_NONNULL(1, 2);
+
+/**
+ * Parse and serialize the AST represented by the given source into the given
+ * buffer.
+ *
+ * @param buffer The buffer to serialize to.
+ * @param source The source to parse.
+ * @param data The optional data to pass to the parser.
+ */
+PRISM_EXPORTED_FUNCTION void pm_serialize_parse_stream(pm_buffer_t *buffer, pm_source_t *source, const char *data) PRISM_NONNULL(1, 2);
+
+/**
+ * Parse and serialize the comments in the given source to the given buffer.
+ *
+ * @param buffer The buffer to serialize to.
+ * @param source The source to parse.
+ * @param size The size of the source.
+ * @param data The optional data to pass to the parser.
+ */
+PRISM_EXPORTED_FUNCTION void pm_serialize_parse_comments(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data) PRISM_NONNULL(1, 2);
+
+/**
+ * Lex the given source and serialize to the given buffer.
+ *
+ * @param source The source to lex.
+ * @param size The size of the source.
+ * @param buffer The buffer to serialize to.
+ * @param data The optional data to pass to the lexer.
+ */
+PRISM_EXPORTED_FUNCTION void pm_serialize_lex(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data) PRISM_NONNULL(1, 2);
+
+/**
+ * Parse and serialize both the AST and the tokens represented by the given
+ * source to the given buffer.
+ *
+ * @param buffer The buffer to serialize to.
+ * @param source The source to parse.
+ * @param size The size of the source.
+ * @param data The optional data to pass to the parser.
+ */
+PRISM_EXPORTED_FUNCTION void pm_serialize_parse_lex(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data) PRISM_NONNULL(1, 2);
+
+/**
+ * Parse the source and return true if it parses without errors or warnings.
+ *
+ * @param source The source to parse.
+ * @param size The size of the source.
+ * @param data The optional data to pass to the parser.
+ * @returns True if the source parses without errors or warnings.
+ */
+PRISM_EXPORTED_FUNCTION bool pm_serialize_parse_success_p(const uint8_t *source, size_t size, const char *data) PRISM_NONNULL(1);
+
+/**
+ * Parse the given source and format any errors that are encountered into the
+ * given buffer using the given format type. If the source parses without any
+ * errors, then -1 is returned and the buffer is left empty. Otherwise, the
+ * name of the encoding of the source is written to the buffer, followed by a
+ * null byte, followed by the formatted errors, and the error level of the
+ * error with the highest precedence is returned.
+ *
+ * @param buffer The buffer to write the encoding name and formatted errors to.
+ * @param source The source to parse.
+ * @param size The size of the source.
+ * @param data The optional data to pass to the parser.
+ * @param format_type The type of formatting to use when formatting the errors.
+ * @returns The error level of the error with the highest precedence, or -1 if
+ *   the source parsed without errors.
+ */
+PRISM_EXPORTED_FUNCTION int8_t pm_serialize_parse_errors_format(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data, pm_errors_format_type_t format_type) PRISM_NONNULL(1, 2);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
+
+#endif

data/include/prism/source.h

@@ -0,0 +1,163 @@
+/**
+ * @file source.h
+ *
+ * An opaque type representing the source code being parsed, regardless of
+ * origin (constant memory, file, memory-mapped file, or stream).
+ */
+#ifndef PRISM_SOURCE_H
+#define PRISM_SOURCE_H
+
+#include "prism/compiler/exported.h"
+#include "prism/compiler/filesystem.h"
+#include "prism/compiler/nodiscard.h"
+#include "prism/compiler/nonnull.h"
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * An opaque type representing source code being parsed.
+ */
+typedef struct pm_source_t pm_source_t;
+
+/**
+ * This function is used to retrieve a line of input from a stream. It closely
+ * mirrors that of fgets so that fgets can be used as the default
+ * implementation.
+ *
+ * As with fgets, implementations MUST write at most `size` bytes into
+ * `string`, including the terminating NUL byte (i.e. at most `size - 1` bytes
+ * of data followed by a '\0'). The caller relies on this bound for memory
+ * safety, so an implementation that reads from a source which may return more
+ * data than requested (for example a multi-byte-aware `gets`) is responsible
+ * for clamping the amount it copies. Returns `string`, or NULL on EOF.
+ */
+typedef char * (pm_source_stream_fgets_t)(char *string, int size, void *stream);
+
+/**
+ * This function is used to check whether a stream is at EOF. It closely mirrors
+ * that of feof so that feof can be used as the default implementation.
+ */
+typedef int (pm_source_stream_feof_t)(void *stream);
+
+/**
+ * Represents the result of initializing a source from a file.
+ */
+typedef enum {
+    /** Indicates that the source was successfully initialized. */
+    PM_SOURCE_INIT_SUCCESS = 0,
+
+    /**
+     * Indicates a generic error from a source init function, where the type
+     * of error should be read from `errno` or `GetLastError()`.
+     */
+    PM_SOURCE_INIT_ERROR_GENERIC = 1,
+
+    /**
+     * Indicates that the file that was attempted to be opened was a directory.
+     */
+    PM_SOURCE_INIT_ERROR_DIRECTORY = 2,
+
+    /**
+     * Indicates that the file is not a regular file (e.g. a pipe or character
+     * device) and the caller should handle reading it.
+     */
+    PM_SOURCE_INIT_ERROR_NON_REGULAR = 3
+} pm_source_init_result_t;
+
+/**
+ * Create a new source that wraps existing constant memory. The memory is not
+ * owned and will not be freed.
+ *
+ * @param data The pointer to the source data.
+ * @param length The length of the source data in bytes.
+ * @returns A new source. Aborts on allocation failure.
+ */
+PRISM_NODISCARD PRISM_EXPORTED_FUNCTION pm_source_t * pm_source_constant_new(const uint8_t *data, size_t length);
+
+/**
+ * Create a new source that wraps existing shared memory. The memory is not
+ * owned and will not be freed. Semantically a "slice" of another source.
+ *
+ * @param data The pointer to the source data.
+ * @param length The length of the source data in bytes.
+ * @returns A new source. Aborts on allocation failure.
+ */
+PRISM_NODISCARD PRISM_EXPORTED_FUNCTION pm_source_t * pm_source_shared_new(const uint8_t *data, size_t length);
+
+/**
+ * Create a new source that owns its memory. The memory will be freed with
+ * xfree when the source is freed.
+ *
+ * @param data The pointer to the heap-allocated source data.
+ * @param length The length of the source data in bytes.
+ * @returns A new source. Aborts on allocation failure.
+ */
+PRISM_NODISCARD PRISM_EXPORTED_FUNCTION pm_source_t * pm_source_owned_new(uint8_t *data, size_t length);
+
+/**
+ * Create a new source by reading a file into a heap-allocated buffer.
+ *
+ * @param filepath The path to the file to read.
+ * @param result Out parameter for the result of the initialization.
+ * @returns A new source, or NULL on error (with result written to out param).
+ */
+PRISM_NODISCARD PRISM_EXPORTED_FUNCTION pm_source_t * pm_source_file_new(const char *filepath, pm_source_init_result_t *result) PRISM_NONNULL(1, 2);
+
+/**
+ * Create a new source by memory-mapping a file. Falls back to file reading on
+ * platforms without mmap support.
+ *
+ * If the file is a non-regular file (e.g. a pipe or character device),
+ * PM_SOURCE_INIT_ERROR_NON_REGULAR is returned, allowing the caller to handle
+ * it appropriately (e.g. by reading it through their own I/O layer).
+ *
+ * @param filepath The path to the file to read.
+ * @param open_flags Additional flags to pass to open(2) (e.g. O_NONBLOCK).
+ * @param result Out parameter for the result of the initialization.
+ * @returns A new source, or NULL on error (with result written to out param).
+ */
+PRISM_NODISCARD PRISM_EXPORTED_FUNCTION pm_source_t * pm_source_mapped_new(const char *filepath, int open_flags, pm_source_init_result_t *result) PRISM_NONNULL(1, 3);
+
+/**
+ * Create a new source by reading from a stream using the provided callbacks.
+ *
+ * @param stream The stream to read from.
+ * @param fgets The function to use to read from the stream.
+ * @param feof The function to use to check if the stream is at EOF.
+ * @returns A new source. Aborts on allocation failure.
+ */
+PRISM_NODISCARD PRISM_EXPORTED_FUNCTION pm_source_t * pm_source_stream_new(void *stream, pm_source_stream_fgets_t *fgets, pm_source_stream_feof_t *feof);
+
+/**
+ * Free the given source and any memory it owns.
+ *
+ * @param source The source to free.
+ */
+PRISM_EXPORTED_FUNCTION void pm_source_free(pm_source_t *source) PRISM_NONNULL(1);
+
+/**
+ * Returns the length of the source data in bytes.
+ *
+ * @param source The source to get the length of.
+ * @returns The length of the source data.
+ */
+PRISM_EXPORTED_FUNCTION size_t pm_source_length(const pm_source_t *source) PRISM_NONNULL(1);
+
+/**
+ * Returns a pointer to the source data.
+ *
+ * @param source The source to get the data of.
+ * @returns A pointer to the source data.
+ */
+PRISM_EXPORTED_FUNCTION const uint8_t * pm_source_source(const pm_source_t *source) PRISM_NONNULL(1);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

data/include/prism/stream.h

@@ -0,0 +1,36 @@
+/**
+ * @file stream.h
+ *
+ * Functions for parsing streams.
+ */
+#ifndef PRISM_STREAM_H
+#define PRISM_STREAM_H
+
+#include "prism/compiler/exported.h"
+#include "prism/compiler/nonnull.h"
+
+#include "prism/arena.h"
+#include "prism/options.h"
+#include "prism/parser.h"
+#include "prism/source.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Parse a stream of Ruby source and return the tree.
+ *
+ * @param parser The out parameter to write the parser to.
+ * @param arena The arena to use for all AST-lifetime allocations.
+ * @param source The source to use, created via pm_source_stream_new.
+ * @param options The optional options to use when parsing.
+ * @returns The AST representing the source.
+ */
+PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse_stream(pm_parser_t **parser, pm_arena_t *arena, pm_source_t *source, const pm_options_t *options) PRISM_NONNULL(1, 2, 3);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif