prism 0.16.0 → 0.17.0

data/src/util/pm_buffer.c

@@ -1,12 +1,16 @@
 #include "prism/util/pm_buffer.h"
 
-// Return the size of the pm_buffer_t struct.
+/**
+ * Return the size of the pm_buffer_t struct.
+ */
 size_t
 pm_buffer_sizeof(void) {
     return sizeof(pm_buffer_t);
 }
 
-// Initialize a pm_buffer_t with the given capacity.
+/**
+ * Initialize a pm_buffer_t with the given capacity.
+ */
 bool
 pm_buffer_init_capacity(pm_buffer_t *buffer, size_t capacity) {
     buffer->length = 0;
@@ -16,25 +20,33 @@ pm_buffer_init_capacity(pm_buffer_t *buffer, size_t capacity) {
     return buffer->value != NULL;
 }
 
-// Initialize a pm_buffer_t with its default values.
+/**
+ * Initialize a pm_buffer_t with its default values.
+ */
 bool
 pm_buffer_init(pm_buffer_t *buffer) {
     return pm_buffer_init_capacity(buffer, 1024);
 }
 
-// Return the value of the buffer.
+/**
+ * Return the value of the buffer.
+ */
 char *
 pm_buffer_value(pm_buffer_t *buffer) {
     return buffer->value;
 }
 
-// Return the length of the buffer.
+/**
+ * Return the length of the buffer.
+ */
 size_t
 pm_buffer_length(pm_buffer_t *buffer) {
     return buffer->length;
 }
 
-// Append the given amount of space to the buffer.
+/**
+ * Append the given amount of space to the buffer.
+ */
 static inline void
 pm_buffer_append_length(pm_buffer_t *buffer, size_t length) {
     size_t next_length = buffer->length + length;
@@ -54,7 +66,9 @@ pm_buffer_append_length(pm_buffer_t *buffer, size_t length) {
     buffer->length = next_length;
 }
 
-// Append a generic pointer to memory to the buffer.
+/**
+ * Append a generic pointer to memory to the buffer.
+ */
 static inline void
 pm_buffer_append(pm_buffer_t *buffer, const void *source, size_t length) {
     size_t cursor = buffer->length;
@@ -62,7 +76,9 @@ pm_buffer_append(pm_buffer_t *buffer, const void *source, size_t length) {
     memcpy(buffer->value + cursor, source, length);
 }
 
-// Append the given amount of space as zeroes to the buffer.
+/**
+ * Append the given amount of space as zeroes to the buffer.
+ */
 void
 pm_buffer_append_zeroes(pm_buffer_t *buffer, size_t length) {
     size_t cursor = buffer->length;
@@ -70,7 +86,9 @@ pm_buffer_append_zeroes(pm_buffer_t *buffer, size_t length) {
     memset(buffer->value + cursor, 0, length);
 }
 
-// Append a formatted string to the buffer.
+/**
+ * Append a formatted string to the buffer.
+ */
 void
 pm_buffer_append_format(pm_buffer_t *buffer, const char *format, ...) {
     va_list arguments;
@@ -91,26 +109,34 @@ pm_buffer_append_format(pm_buffer_t *buffer, const char *format, ...) {
     buffer->length--;
 }
 
-// Append a string to the buffer.
+/**
+ * Append a string to the buffer.
+ */
 void
 pm_buffer_append_string(pm_buffer_t *buffer, const char *value, size_t length) {
     pm_buffer_append(buffer, value, length);
 }
 
-// Append a list of bytes to the buffer.
+/**
+ * Append a list of bytes to the buffer.
+ */
 void
 pm_buffer_append_bytes(pm_buffer_t *buffer, const uint8_t *value, size_t length) {
     pm_buffer_append(buffer, (const char *) value, length);
 }
 
-// Append a single byte to the buffer.
+/**
+ * Append a single byte to the buffer.
+ */
 void
 pm_buffer_append_byte(pm_buffer_t *buffer, uint8_t value) {
     const void *source = &value;
     pm_buffer_append(buffer, source, sizeof(uint8_t));
 }
 
-// Append a 32-bit unsigned integer to the buffer as a variable-length integer.
+/**
+ * Append a 32-bit unsigned integer to the buffer as a variable-length integer.
+ */
 void
 pm_buffer_append_varint(pm_buffer_t *buffer, uint32_t value) {
     if (value < 128) {
@@ -125,7 +151,9 @@ pm_buffer_append_varint(pm_buffer_t *buffer, uint32_t value) {
     }
 }
 
-// Concatenate one buffer onto another.
+/**
+ * Concatenate one buffer onto another.
+ */
 void
 pm_buffer_concat(pm_buffer_t *destination, const pm_buffer_t *source) {
     if (source->length > 0) {
@@ -133,7 +161,9 @@ pm_buffer_concat(pm_buffer_t *destination, const pm_buffer_t *source) {
     }
 }
 
-// Free the internal memory associated with the buffer.
+/**
+ * Free the memory associated with the buffer.
+ */
 void
 pm_buffer_free(pm_buffer_t *buffer) {
     free(buffer->value);

data/src/util/pm_char.c

@@ -53,6 +53,10 @@ static const uint8_t pm_number_table[256] = {
     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Fx
 };
 
+/**
+ * Returns the number of characters at the start of the string that match the
+ * given kind. Disallows searching past the given maximum number of characters.
+ */
 static inline size_t
 pm_strspn_char_kind(const uint8_t *string, ptrdiff_t length, uint8_t kind) {
     if (length <= 0) return 0;
@@ -64,16 +68,20 @@ pm_strspn_char_kind(const uint8_t *string, ptrdiff_t length, uint8_t kind) {
     return size;
 }
 
-// Returns the number of characters at the start of the string that are
-// whitespace. Disallows searching past the given maximum number of characters.
+/**
+ * Returns the number of characters at the start of the string that are
+ * whitespace. Disallows searching past the given maximum number of characters.
+ */
 size_t
 pm_strspn_whitespace(const uint8_t *string, ptrdiff_t length) {
     return pm_strspn_char_kind(string, length, PRISM_CHAR_BIT_WHITESPACE);
 }
 
-// Returns the number of characters at the start of the string that are
-// whitespace while also tracking the location of each newline. Disallows
-// searching past the given maximum number of characters.
+/**
+ * Returns the number of characters at the start of the string that are
+ * whitespace while also tracking the location of each newline. Disallows
+ * searching past the given maximum number of characters.
+ */
 size_t
 pm_strspn_whitespace_newlines(const uint8_t *string, ptrdiff_t length, pm_newline_list_t *newline_list) {
     if (length <= 0) return 0;
@@ -92,40 +100,53 @@ pm_strspn_whitespace_newlines(const uint8_t *string, ptrdiff_t length, pm_newlin
     return size;
 }
 
-// Returns the number of characters at the start of the string that are inline
-// whitespace. Disallows searching past the given maximum number of characters.
+/**
+ * Returns the number of characters at the start of the string that are inline
+ * whitespace. Disallows searching past the given maximum number of characters.
+ */
 size_t
 pm_strspn_inline_whitespace(const uint8_t *string, ptrdiff_t length) {
     return pm_strspn_char_kind(string, length, PRISM_CHAR_BIT_INLINE_WHITESPACE);
 }
 
-// Returns the number of characters at the start of the string that are regexp
-// options. Disallows searching past the given maximum number of characters.
+/**
+ * Returns the number of characters at the start of the string that are regexp
+ * options. Disallows searching past the given maximum number of characters.
+ */
 size_t
 pm_strspn_regexp_option(const uint8_t *string, ptrdiff_t length) {
     return pm_strspn_char_kind(string, length, PRISM_CHAR_BIT_REGEXP_OPTION);
 }
 
+/**
+ * Returns true if the given character matches the given kind.
+ */
 static inline bool
 pm_char_is_char_kind(const uint8_t b, uint8_t kind) {
     return (pm_byte_table[b] & kind) != 0;
 }
 
-// Returns true if the given character is a whitespace character.
+/**
+ * Returns true if the given character is a whitespace character.
+ */
 bool
 pm_char_is_whitespace(const uint8_t b) {
     return pm_char_is_char_kind(b, PRISM_CHAR_BIT_WHITESPACE);
 }
 
-// Returns true if the given character is an inline whitespace character.
+/**
+ * Returns true if the given character is an inline whitespace character.
+ */
 bool
 pm_char_is_inline_whitespace(const uint8_t b) {
     return pm_char_is_char_kind(b, PRISM_CHAR_BIT_INLINE_WHITESPACE);
 }
 
-// Scan through the string and return the number of characters at the start of
-// the string that match the given kind. Disallows searching past the given
-// maximum number of characters.
+/**
+ * Scan through the string and return the number of characters at the start of
+ * the string that match the given kind. Disallows searching past the given
+ * maximum number of characters.
+ */
 static inline size_t
 pm_strspn_number_kind(const uint8_t *string, ptrdiff_t length, uint8_t kind) {
     if (length <= 0) return 0;
@@ -137,12 +158,14 @@ pm_strspn_number_kind(const uint8_t *string, ptrdiff_t length, uint8_t kind) {
     return size;
 }
 
-// Scan through the string and return the number of characters at the start of
-// the string that match the given kind. Disallows searching past the given
-// maximum number of characters.
-//
-// Additionally, report the location of the last invalid underscore character
-// found in the string through the out invalid parameter.
+/**
+ * Scan through the string and return the number of characters at the start of
+ * the string that match the given kind. Disallows searching past the given
+ * maximum number of characters.
+ *
+ * Additionally, report the location of the last invalid underscore character
+ * found in the string through the out invalid parameter.
+ */
 static inline size_t
 pm_strspn_number_kind_underscores(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid, uint8_t kind) {
     if (length <= 0) return 0;
@@ -166,93 +189,116 @@ pm_strspn_number_kind_underscores(const uint8_t *string, ptrdiff_t length, const
     return size;
 }
 
-// Returns the number of characters at the start of the string that are binary
-// digits or underscores. Disallows searching past the given maximum number of
-// characters.
-//
-// If multiple underscores are found in a row or if an underscore is
-// found at the end of the number, then the invalid pointer is set to the index
-// of the first invalid underscore.
+/**
+ * Returns the number of characters at the start of the string that are binary
+ * digits or underscores. Disallows searching past the given maximum number of
+ * characters.
+ *
+ * If multiple underscores are found in a row or if an underscore is
+ * found at the end of the number, then the invalid pointer is set to the index
+ * of the first invalid underscore.
+ */
 size_t
 pm_strspn_binary_number(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid) {
     return pm_strspn_number_kind_underscores(string, length, invalid, PRISM_NUMBER_BIT_BINARY_NUMBER);
 }
 
-// Returns the number of characters at the start of the string that are octal
-// digits or underscores. Disallows searching past the given maximum number of
-// characters.
-//
-// If multiple underscores are found in a row or if an underscore is
-// found at the end of the number, then the invalid pointer is set to the index
-// of the first invalid underscore.
+/**
+ * Returns the number of characters at the start of the string that are octal
+ * digits or underscores. Disallows searching past the given maximum number of
+ * characters.
+ *
+ * If multiple underscores are found in a row or if an underscore is
+ * found at the end of the number, then the invalid pointer is set to the index
+ * of the first invalid underscore.
+ */
 size_t
 pm_strspn_octal_number(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid) {
     return pm_strspn_number_kind_underscores(string, length, invalid, PRISM_NUMBER_BIT_OCTAL_NUMBER);
 }
 
-// Returns the number of characters at the start of the string that are decimal
-// digits. Disallows searching past the given maximum number of characters.
+/**
+ * Returns the number of characters at the start of the string that are decimal
+ * digits. Disallows searching past the given maximum number of characters.
+ */
 size_t
 pm_strspn_decimal_digit(const uint8_t *string, ptrdiff_t length) {
     return pm_strspn_number_kind(string, length, PRISM_NUMBER_BIT_DECIMAL_DIGIT);
 }
 
-// Returns the number of characters at the start of the string that are decimal
-// digits or underscores. Disallows searching past the given maximum number of
-// characters.
-//
-// If multiple underscores are found in a row or if an underscore is
-// found at the end of the number, then the invalid pointer is set to the index
-// of the first invalid underscore.
+/**
+ * Returns the number of characters at the start of the string that are decimal
+ * digits or underscores. Disallows searching past the given maximum number of
+ * characters.
+ *
+ * If multiple underscores are found in a row or if an underscore is
+ * found at the end of the number, then the invalid pointer is set to the index
+ * of the first invalid underscore
+ */
 size_t
 pm_strspn_decimal_number(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid) {
     return pm_strspn_number_kind_underscores(string, length, invalid, PRISM_NUMBER_BIT_DECIMAL_NUMBER);
 }
 
-// Returns the number of characters at the start of the string that are
-// hexadecimal digits. Disallows searching past the given maximum number of
-// characters.
+/**
+ * Returns the number of characters at the start of the string that are
+ * hexadecimal digits. Disallows searching past the given maximum number of
+ * characters.
+ */
 size_t
 pm_strspn_hexadecimal_digit(const uint8_t *string, ptrdiff_t length) {
     return pm_strspn_number_kind(string, length, PRISM_NUMBER_BIT_HEXADECIMAL_DIGIT);
 }
 
-// Returns the number of characters at the start of the string that are
-// hexadecimal digits or underscores. Disallows searching past the given maximum
-// number of characters.
-//
-// If multiple underscores are found in a row or if an underscore is
-// found at the end of the number, then the invalid pointer is set to the index
-// of the first invalid underscore.
+/**
+ * Returns the number of characters at the start of the string that are
+ * hexadecimal digits or underscores. Disallows searching past the given maximum
+ * number of characters.
+ *
+ * If multiple underscores are found in a row or if an underscore is
+ * found at the end of the number, then the invalid pointer is set to the index
+ * of the first invalid underscore.
+ */
 size_t
 pm_strspn_hexadecimal_number(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid) {
     return pm_strspn_number_kind_underscores(string, length, invalid, PRISM_NUMBER_BIT_HEXADECIMAL_NUMBER);
 }
 
+/**
+ * Returns true if the given character matches the given kind.
+ */
 static inline bool
 pm_char_is_number_kind(const uint8_t b, uint8_t kind) {
     return (pm_number_table[b] & kind) != 0;
 }
 
-// Returns true if the given character is a binary digit.
+/**
+ * Returns true if the given character is a binary digit.
+ */
 bool
 pm_char_is_binary_digit(const uint8_t b) {
     return pm_char_is_number_kind(b, PRISM_NUMBER_BIT_BINARY_DIGIT);
 }
 
-// Returns true if the given character is an octal digit.
+/**
+ * Returns true if the given character is an octal digit.
+ */
 bool
 pm_char_is_octal_digit(const uint8_t b) {
     return pm_char_is_number_kind(b, PRISM_NUMBER_BIT_OCTAL_DIGIT);
 }
 
-// Returns true if the given character is a decimal digit.
+/**
+ * Returns true if the given character is a decimal digit.
+ */
 bool
 pm_char_is_decimal_digit(const uint8_t b) {
     return pm_char_is_number_kind(b, PRISM_NUMBER_BIT_DECIMAL_DIGIT);
 }
 
-// Returns true if the given character is a hexadecimal digit.
+/**
+ * Returns true if the given character is a hexadecimal digit.
+ */
 bool
 pm_char_is_hexadecimal_digit(const uint8_t b) {
     return pm_char_is_number_kind(b, PRISM_NUMBER_BIT_HEXADECIMAL_DIGIT);

data/src/util/pm_constant_pool.c

@@ -1,6 +1,8 @@
 #include "prism/util/pm_constant_pool.h"
 
-// Initialize a list of constant ids.
+/**
+ * Initialize a list of constant ids.
+ */
 void
 pm_constant_id_list_init(pm_constant_id_list_t *list) {
     list->ids = NULL;
@@ -8,8 +10,10 @@ pm_constant_id_list_init(pm_constant_id_list_t *list) {
     list->capacity = 0;
 }
 
-// Append a constant id to a list of constant ids. Returns false if any
-// potential reallocations fail.
+/**
+ * Append a constant id to a list of constant ids. Returns false if any
+ * potential reallocations fail.
+ */
 bool
 pm_constant_id_list_append(pm_constant_id_list_t *list, pm_constant_id_t id) {
     if (list->size >= list->capacity) {
@@ -22,7 +26,9 @@ pm_constant_id_list_append(pm_constant_id_list_t *list, pm_constant_id_t id) {
     return true;
 }
 
-// Checks if the current constant id list includes the given constant id.
+/**
+ * Checks if the current constant id list includes the given constant id.
+ */
 bool
 pm_constant_id_list_includes(pm_constant_id_list_t *list, pm_constant_id_t id) {
     for (size_t index = 0; index < list->size; index++) {
@@ -31,13 +37,17 @@ pm_constant_id_list_includes(pm_constant_id_list_t *list, pm_constant_id_t id) {
     return false;
 }
 
-// Get the memory size of a list of constant ids.
+/**
+ * Get the memory size of a list of constant ids.
+ */
 size_t
 pm_constant_id_list_memsize(pm_constant_id_list_t *list) {
     return sizeof(pm_constant_id_list_t) + (list->capacity * sizeof(pm_constant_id_t));
 }
 
-// Free the memory associated with a list of constant ids.
+/**
+ * Free the memory associated with a list of constant ids.
+ */
 void
 pm_constant_id_list_free(pm_constant_id_list_t *list) {
     if (list->ids != NULL) {
@@ -45,8 +55,10 @@ pm_constant_id_list_free(pm_constant_id_list_t *list) {
     }
 }
 
-// A relatively simple hash function (djb2) that is used to hash strings. We are
-// optimizing here for simplicity and speed.
+/**
+ * A relatively simple hash function (djb2) that is used to hash strings. We are
+ * optimizing here for simplicity and speed.
+ */
 static inline uint32_t
 pm_constant_pool_hash(const uint8_t *start, size_t length) {
     // This is a prime number used as the initial value for the hash function.
@@ -59,7 +71,9 @@ pm_constant_pool_hash(const uint8_t *start, size_t length) {
     return value;
 }
 
-// https://graphics.stanford.edu/~seander/bithacks.html#RoundUpPowerOf2
+/**
+ * https://graphics.stanford.edu/~seander/bithacks.html#RoundUpPowerOf2
+ */
 static uint32_t
 next_power_of_two(uint32_t v) {
     // Avoid underflow in subtraction on next line.
@@ -84,7 +98,9 @@ is_power_of_two(uint32_t size) {
 }
 #endif
 
-// Resize a constant pool to a given capacity.
+/**
+ * Resize a constant pool to a given capacity.
+ */
 static inline bool
 pm_constant_pool_resize(pm_constant_pool_t *pool) {
     assert(is_power_of_two(pool->capacity));
@@ -136,7 +152,9 @@ pm_constant_pool_resize(pm_constant_pool_t *pool) {
     return true;
 }
 
-// Initialize a new constant pool with a given capacity.
+/**
+ * Initialize a new constant pool with a given capacity.
+ */
 bool
 pm_constant_pool_init(pm_constant_pool_t *pool, uint32_t capacity) {
     const uint32_t maximum = (~((uint32_t) 0));
@@ -154,14 +172,18 @@ pm_constant_pool_init(pm_constant_pool_t *pool, uint32_t capacity) {
     return true;
 }
 
-// Return a pointer to the constant indicated by the given constant id.
+/**
+ * Return a pointer to the constant indicated by the given constant id.
+ */
 pm_constant_t *
 pm_constant_pool_id_to_constant(const pm_constant_pool_t *pool, pm_constant_id_t constant_id) {
     assert(constant_id > 0 && constant_id <= pool->size);
     return &pool->constants[constant_id - 1];
 }
 
-// Insert a constant into a constant pool and return its index in the pool.
+/**
+ * Insert a constant into a constant pool and return its index in the pool.
+ */
 static inline pm_constant_id_t
 pm_constant_pool_insert(pm_constant_pool_t *pool, const uint8_t *start, size_t length, pm_constant_pool_bucket_type_t type) {
     if (pool->size >= (pool->capacity / 4 * 3)) {
@@ -225,29 +247,37 @@ pm_constant_pool_insert(pm_constant_pool_t *pool, const uint8_t *start, size_t l
     return id;
 }
 
-// Insert a constant into a constant pool. Returns the id of the constant, or 0
-// if any potential calls to resize fail.
+/**
+ * Insert a constant into a constant pool. Returns the id of the constant, or 0
+ * if any potential calls to resize fail.
+ */
 pm_constant_id_t
 pm_constant_pool_insert_shared(pm_constant_pool_t *pool, const uint8_t *start, size_t length) {
     return pm_constant_pool_insert(pool, start, length, PM_CONSTANT_POOL_BUCKET_DEFAULT);
 }
 
-// Insert a constant into a constant pool from memory that is now owned by the
-// constant pool. Returns the id of the constant, or 0 if any potential calls to
-// resize fail.
+/**
+ * Insert a constant into a constant pool from memory that is now owned by the
+ * constant pool. Returns the id of the constant, or 0 if any potential calls to
+ * resize fail.
+ */
 pm_constant_id_t
 pm_constant_pool_insert_owned(pm_constant_pool_t *pool, const uint8_t *start, size_t length) {
     return pm_constant_pool_insert(pool, start, length, PM_CONSTANT_POOL_BUCKET_OWNED);
 }
 
-// Insert a constant into a constant pool from memory that is constant. Returns
-// the id of the constant, or 0 if any potential calls to resize fail.
+/**
+ * Insert a constant into a constant pool from memory that is constant. Returns
+ * the id of the constant, or 0 if any potential calls to resize fail.
+ */
 pm_constant_id_t
 pm_constant_pool_insert_constant(pm_constant_pool_t *pool, const uint8_t *start, size_t length) {
     return pm_constant_pool_insert(pool, start, length, PM_CONSTANT_POOL_BUCKET_CONSTANT);
 }
 
-// Free the memory associated with a constant pool.
+/**
+ * Free the memory associated with a constant pool.
+ */
 void
 pm_constant_pool_free(pm_constant_pool_t *pool) {
     // For each constant in the current constant pool, free the contents if the

data/src/util/pm_list.c

@@ -1,18 +1,24 @@
 #include "prism/util/pm_list.h"
 
-// Returns true if the given list is empty.
+/**
+ * Returns true if the given list is empty.
+ */
 PRISM_EXPORTED_FUNCTION bool
 pm_list_empty_p(pm_list_t *list) {
     return list->head == NULL;
 }
 
-// Returns the size of the list.
+/**
+ * Returns the size of the list.
+ */
 PRISM_EXPORTED_FUNCTION size_t
 pm_list_size(pm_list_t *list) {
     return list->size;
 }
 
-// Append a node to the given list.
+/**
+ * Append a node to the given list.
+ */
 void
 pm_list_append(pm_list_t *list, pm_list_node_t *node) {
     if (list->head == NULL) {
@@ -25,7 +31,9 @@ pm_list_append(pm_list_t *list, pm_list_node_t *node) {
     list->size++;
 }
 
-// Deallocate the internal state of the given list.
+/**
+ * Deallocate the internal state of the given list.
+ */
 PRISM_EXPORTED_FUNCTION void
 pm_list_free(pm_list_t *list) {
     pm_list_node_t *node = list->head;

data/src/util/pm_memchr.c

@@ -2,9 +2,11 @@
 
 #define PRISM_MEMCHR_TRAILING_BYTE_MINIMUM 0x40
 
-// We need to roll our own memchr to handle cases where the encoding changes and
-// we need to search for a character in a buffer that could be the trailing byte
-// of a multibyte character.
+/**
+ * We need to roll our own memchr to handle cases where the encoding changes and
+ * we need to search for a character in a buffer that could be the trailing byte
+ * of a multibyte character.
+ */
 void *
 pm_memchr(const void *memory, int character, size_t number, bool encoding_changed, pm_encoding_t *encoding) {
     if (encoding_changed && encoding->multibyte && character >= PRISM_MEMCHR_TRAILING_BYTE_MINIMUM) {