From bec5ca37a0bda370a176aefbf62f4b5ac69cf90a Mon Sep 17 00:00:00 2001 From: Kevin Newton Date: Mon, 30 Oct 2023 23:09:18 -0400 Subject: [PATCH] Even more C documentation --- include/prism/util/pm_buffer.h | 105 +++++++++++--- include/prism/util/pm_char.h | 205 +++++++++++++++++++++------- include/prism/util/pm_state_stack.h | 27 +++- include/prism/util/pm_string.h | 85 +++++++++--- include/prism/util/pm_string_list.h | 29 +++- rakelib/check_manifest.rake | 1 + src/prism.c | 22 +-- src/util/pm_buffer.c | 60 ++++++-- src/util/pm_char.c | 160 ++++++++++++++-------- src/util/pm_state_stack.c | 12 +- src/util/pm_string.c | 48 ++----- src/util/pm_string_list.c | 14 +- 12 files changed, 547 insertions(+), 221 deletions(-) diff --git a/include/prism/util/pm_buffer.h b/include/prism/util/pm_buffer.h index 69edb1525af..a2bccb3d001 100644 --- a/include/prism/util/pm_buffer.h +++ b/include/prism/util/pm_buffer.h @@ -9,52 +9,125 @@ #include #include -// A pm_buffer_t is a simple memory buffer that stores data in a contiguous -// block of memory. It is used to store the serialized representation of a -// prism tree. +/** + * A pm_buffer_t is a simple memory buffer that stores data in a contiguous + * block of memory. + */ typedef struct { + /** The length of the buffer in bytes. */ size_t length; + + /** The capacity of the buffer in bytes that has been allocated. */ size_t capacity; + + /** A pointer to the start of the buffer. */ char *value; } pm_buffer_t; -// Return the size of the pm_buffer_t struct. +/** + * Return the size of the pm_buffer_t struct. + * + * @returns The size of the pm_buffer_t struct. + */ PRISM_EXPORTED_FUNCTION size_t pm_buffer_sizeof(void); -// Initialize a pm_buffer_t with the given capacity. +/** + * Initialize a pm_buffer_t with the given capacity. + * + * @param buffer The buffer to initialize. + * @param capacity The capacity of the buffer. + * @returns True if the buffer was initialized successfully, false otherwise. + */ bool pm_buffer_init_capacity(pm_buffer_t *buffer, size_t capacity); -// Initialize a pm_buffer_t with its default values. +/** + * Initialize a pm_buffer_t with its default values. + * + * @param buffer The buffer to initialize. + * @returns True if the buffer was initialized successfully, false otherwise. + */ PRISM_EXPORTED_FUNCTION bool pm_buffer_init(pm_buffer_t *buffer); -// Return the value of the buffer. +/** + * 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(pm_buffer_t *buffer); -// Return the length of the buffer. +/** + * 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(pm_buffer_t *buffer); -// Append the given amount of space as zeroes to the buffer. +/** + * Append the given amount of space as zeroes to the buffer. + * + * @param buffer The buffer to append to. + * @param length The amount of space to append and zero. + */ void pm_buffer_append_zeroes(pm_buffer_t *buffer, size_t length); -// Append a formatted string to the buffer. +/** + * Append a formatted string to the buffer. + * + * @param buffer The buffer to append to. + * @param format The format string to append. + * @param ... The arguments to the format string. + */ void pm_buffer_append_format(pm_buffer_t *buffer, const char *format, ...) PRISM_ATTRIBUTE_FORMAT(2, 3); -// Append a string to the buffer. +/** + * Append a string to the buffer. + * + * @param buffer The buffer to append to. + * @param value The string to append. + * @param length The length of the string to append. + */ void pm_buffer_append_string(pm_buffer_t *buffer, const char *value, size_t length); -// Append a list of bytes to the buffer. +/** + * Append a list of bytes to the buffer. + * + * @param buffer The buffer to append to. + * @param value The bytes to append. + * @param length The length of the bytes to append. + */ void pm_buffer_append_bytes(pm_buffer_t *buffer, const uint8_t *value, size_t length); -// Append a single byte to the buffer. +/** + * Append a single byte to the buffer. + * + * @param buffer The buffer to append to. + * @param value The byte to append. + */ void pm_buffer_append_byte(pm_buffer_t *buffer, uint8_t value); -// Append a 32-bit unsigned integer to the buffer. +/** + * Append a 32-bit unsigned integer to the buffer as a variable-length integer. + * + * @param buffer The buffer to append to. + * @param value The integer to append. + */ void pm_buffer_append_varint(pm_buffer_t *buffer, uint32_t value); -// Append one buffer onto another. +/** + * Concatenate one buffer onto another. + * + * @param destination The buffer to concatenate onto. + * @param source The buffer to concatenate. + */ void pm_buffer_concat(pm_buffer_t *destination, const pm_buffer_t *source); -// Free the memory associated with the buffer. +/** + * Free the memory associated with the buffer. + * + * @param buffer The buffer to free. + */ PRISM_EXPORTED_FUNCTION void pm_buffer_free(pm_buffer_t *buffer); #endif diff --git a/include/prism/util/pm_char.h b/include/prism/util/pm_char.h index f7f195eecc0..2bdc67de4a4 100644 --- a/include/prism/util/pm_char.h +++ b/include/prism/util/pm_char.h @@ -7,85 +7,194 @@ #include #include -// 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. + * + * @param string The string to search. + * @param length The maximum number of characters to search. + * @return The number of characters at the start of the string that are + * whitespace. + */ size_t pm_strspn_whitespace(const uint8_t *string, ptrdiff_t length); -// 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. + * + * @param string The string to search. + * @param length The maximum number of characters to search. + * @param newline_list The list of newlines to populate. + * @return The number of characters at the start of the string that are + * whitespace. + */ size_t pm_strspn_whitespace_newlines(const uint8_t *string, ptrdiff_t length, pm_newline_list_t *newline_list); -// 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. + * + * @param string The string to search. + * @param length The maximum number of characters to search. + * @return The number of characters at the start of the string that are inline + * whitespace. + */ size_t pm_strspn_inline_whitespace(const uint8_t *string, ptrdiff_t length); -// 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. + * + * @param string The string to search. + * @param length The maximum number of characters to search. + * @return The number of characters at the start of the string that are decimal + * digits. + */ size_t pm_strspn_decimal_digit(const uint8_t *string, ptrdiff_t length); -// 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. + * + * @param string The string to search. + * @param length The maximum number of characters to search. + * @return The number of characters at the start of the string that are + * hexadecimal digits. + */ size_t pm_strspn_hexadecimal_digit(const uint8_t *string, ptrdiff_t length); -// 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. + * + * @param string The string to search. + * @param length The maximum number of characters to search. + * @param invalid The pointer to set to the index of the first invalid + * underscore. + * @return The number of characters at the start of the string that are octal + * digits or underscores. + */ size_t pm_strspn_octal_number(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid); -// 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. + * + * @param string The string to search. + * @param length The maximum number of characters to search. + * @param invalid The pointer to set to the index of the first invalid + * underscore. + * @return The number of characters at the start of the string that are decimal + * digits or underscores. + */ size_t pm_strspn_decimal_number(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid); -// 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. + * + * @param string The string to search. + * @param length The maximum number of characters to search. + * @param invalid The pointer to set to the index of the first invalid + * underscore. + * @return The number of characters at the start of the string that are + * hexadecimal digits or underscores. + */ size_t pm_strspn_hexadecimal_number(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid); -// 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. + * + * @param string The string to search. + * @param length The maximum number of characters to search. + * @return The number of characters at the start of the string that are regexp + * options. + */ size_t pm_strspn_regexp_option(const uint8_t *string, ptrdiff_t length); -// 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. + * + * @param string The string to search. + * @param length The maximum number of characters to search. + * @param invalid The pointer to set to the index of the first invalid + * underscore. + * @return The number of characters at the start of the string that are binary + * digits or underscores. + */ size_t pm_strspn_binary_number(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid); -// Returns true if the given character is a whitespace character. +/** + * Returns true if the given character is a whitespace character. + * + * @param b The character to check. + * @return True if the given character is a whitespace character. + */ bool pm_char_is_whitespace(const uint8_t b); -// Returns true if the given character is an inline whitespace character. +/** + * Returns true if the given character is an inline whitespace character. + * + * @param b The character to check. + * @return True if the given character is an inline whitespace character. + */ bool pm_char_is_inline_whitespace(const uint8_t b); -// Returns true if the given character is a binary digit. +/** + * Returns true if the given character is a binary digit. + * + * @param b The character to check. + * @return True if the given character is a binary digit. + */ bool pm_char_is_binary_digit(const uint8_t b); -// Returns true if the given character is an octal digit. +/** + * Returns true if the given character is an octal digit. + * + * @param b The character to check. + * @return True if the given character is an octal digit. + */ bool pm_char_is_octal_digit(const uint8_t b); -// Returns true if the given character is a decimal digit. +/** + * Returns true if the given character is a decimal digit. + * + * @param b The character to check. + * @return True if the given character is a decimal digit. + */ bool pm_char_is_decimal_digit(const uint8_t b); -// Returns true if the given character is a hexadecimal digit. +/** + * Returns true if the given character is a hexadecimal digit. + * + * @param b The character to check. + * @return True if the given character is a hexadecimal digit. + */ bool pm_char_is_hexadecimal_digit(const uint8_t b); #endif diff --git a/include/prism/util/pm_state_stack.h b/include/prism/util/pm_state_stack.h index aef639074aa..268243085a1 100644 --- a/include/prism/util/pm_state_stack.h +++ b/include/prism/util/pm_state_stack.h @@ -6,19 +6,36 @@ #include #include -// A struct that represents a stack of bools. +/** + * A struct that represents a stack of boolean values. + */ typedef uint32_t pm_state_stack_t; -// Initializes the state stack to an empty stack. +/** + * Initializes the state stack to an empty stack. + */ #define PM_STATE_STACK_EMPTY ((pm_state_stack_t) 0) -// Pushes a value onto the stack. +/** + * Pushes a value onto the stack. + * + * @param stack The stack to push the value onto. + * @param value The value to push onto the stack. + */ void pm_state_stack_push(pm_state_stack_t *stack, bool value); -// Pops a value off the stack. +/** + * Pops a value off the stack. + * + * @param stack The stack to pop the value off of. + */ void pm_state_stack_pop(pm_state_stack_t *stack); -// Returns the value at the top of the stack. +/** + * Returns the value at the top of the stack. + * + * @param stack The stack to get the value from. + */ bool pm_state_stack_p(pm_state_stack_t *stack); #endif diff --git a/include/prism/util/pm_string.h b/include/prism/util/pm_string.h index 5f0fc7b046a..b0b7c6bf2dc 100644 --- a/include/prism/util/pm_string.h +++ b/include/prism/util/pm_string.h @@ -9,34 +9,80 @@ #include #include -// This struct represents a string value. +// The following headers are necessary to read files using demand paging. +#ifdef _WIN32 +#include +#else +#include +#include +#include +#include +#endif + +/** + * A generic string type that can have various ownership semantics. + */ typedef struct { + /** A pointer to the start of the string. */ const uint8_t *source; + + /** The length of the string in bytes of memory. */ size_t length; - // This field is not the first one, because otherwise things like .pm_string_t_field = 123/pm_constant_id_t does not warn or error - enum { PM_STRING_SHARED, PM_STRING_OWNED, PM_STRING_CONSTANT, PM_STRING_MAPPED } type; + + /** The type of the string. This field determines how the string should be freed. */ + enum { + /** This string is a constant string, and should not be freed. */ + PM_STRING_CONSTANT, + + /** This is a slice of another string, and should not be freed. */ + PM_STRING_SHARED, + + /** This string owns its memory, and should be freed using `pm_string_free`. */ + PM_STRING_OWNED, + + /** This string is a memory-mapped file, and should be freed using `pm_string_free`. */ + PM_STRING_MAPPED + } type; } pm_string_t; -#define PM_EMPTY_STRING ((pm_string_t) { .type = PM_STRING_CONSTANT, .source = NULL, .length = 0 }) +/** + * Returns the size of the pm_string_t struct. This is necessary to allocate the + * correct amount of memory in the FFI backend. + * + * @return The size of the pm_string_t struct. + */ +PRISM_EXPORTED_FUNCTION size_t pm_string_sizeof(void); + +/** + * 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 = NULL, .length = 0 }) /** * Initialize a shared string that is based on initial input. * - * @memberof pm_string_t + * @param string The string to initialize. + * @param start The start of the string. + * @param end The end of the string. */ void pm_string_shared_init(pm_string_t *string, const uint8_t *start, const uint8_t *end); /** * Initialize an owned string that is responsible for freeing allocated memory. * - * @memberof pm_string_t + * @param string The string to initialize. + * @param source The source of the string. + * @param length The length of the string. */ void pm_string_owned_init(pm_string_t *string, uint8_t *source, size_t length); /** * Initialize a constant string that doesn't own its memory source. * - * @memberof pm_string_t + * @param string The string to initialize. + * @param source The source of the string. + * @param length The length of the string. */ void pm_string_constant_init(pm_string_t *string, const char *source, size_t length); @@ -51,14 +97,17 @@ void pm_string_constant_init(pm_string_t *string, const char *source, size_t len * `MapViewOfFile`, on POSIX systems that have access to `mmap` we'll use * `mmap`, and on other POSIX systems we'll use `read`. * - * @memberof pm_string_t + * @param string The string to initialize. + * @param filepath The filepath to read. + * @return Whether or not the file was successfully mapped. */ PRISM_EXPORTED_FUNCTION bool pm_string_mapped_init(pm_string_t *string, const char *filepath); /** * Returns the memory size associated with the string. * - * @memberof pm_string_t + * @param string The string to get the memory size of. + * @return The size of the memory associated with the string. */ size_t pm_string_memsize(const pm_string_t *string); @@ -66,35 +115,31 @@ size_t pm_string_memsize(const pm_string_t *string); * Ensure the string is owned. If it is not, then reinitialize it as owned and * copy over the previous source. * - * @memberof pm_string_t + * @param string The string to ensure is owned. */ void pm_string_ensure_owned(pm_string_t *string); /** * Returns the length associated with the string. * - * @memberof pm_string_t + * @param string The string to get the length of. + * @return The length of the string. */ PRISM_EXPORTED_FUNCTION size_t pm_string_length(const pm_string_t *string); /** * Returns the start pointer associated with the string. * - * @memberof pm_string_t + * @param string The string to get the start pointer of. + * @return The start pointer of the string. */ PRISM_EXPORTED_FUNCTION const uint8_t * pm_string_source(const pm_string_t *string); /** * Free the associated memory of the given string. * - * @memberof pm_string_t + * @param string The string to free. */ PRISM_EXPORTED_FUNCTION void pm_string_free(pm_string_t *string); -/** - * Returns the size of the pm_string_t struct. This is necessary to allocate the - * correct amount of memory in the FFI backend. - */ -PRISM_EXPORTED_FUNCTION size_t pm_string_sizeof(void); - -#endif // PRISM_STRING_H +#endif diff --git a/include/prism/util/pm_string_list.h b/include/prism/util/pm_string_list.h index 1eec7a34da3..5aa37587758 100644 --- a/include/prism/util/pm_string_list.h +++ b/include/prism/util/pm_string_list.h @@ -7,19 +7,40 @@ #include #include +/** + * A list of strings. + */ typedef struct { - pm_string_t *strings; + /** The length of the string list. */ size_t length; + + /** The capacity of the string list that has been allocated. */ size_t capacity; + + /** A pointer to the start of the string list. */ + pm_string_t *strings; } pm_string_list_t; -// Initialize a pm_string_list_t with its default values. +/** + * Initialize a pm_string_list_t with its default values. + * + * @param string_list The string list to initialize. + */ PRISM_EXPORTED_FUNCTION void pm_string_list_init(pm_string_list_t *string_list); -// Append a pm_string_t to the given string list. +/** + * Append a pm_string_t to the given string list. + * + * @param string_list The string list to append to. + * @param string The string to append. + */ void pm_string_list_append(pm_string_list_t *string_list, pm_string_t *string); -// Free the memory associated with the string list. +/** + * Free the memory associated with the string list. + * + * @param string_list The string list to free. + */ PRISM_EXPORTED_FUNCTION void pm_string_list_free(pm_string_list_t *string_list); #endif diff --git a/rakelib/check_manifest.rake b/rakelib/check_manifest.rake index 531e4c6894b..ce039e6bc30 100644 --- a/rakelib/check_manifest.rake +++ b/rakelib/check_manifest.rake @@ -34,6 +34,7 @@ task :check_manifest => [:templates] do .gitignore .gitmodules *.iml + Doxyfile Gemfile Gemfile.lock Makefile diff --git a/src/prism.c b/src/prism.c index ec8a7927daf..3422aa5894d 100644 --- a/src/prism.c +++ b/src/prism.c @@ -4240,7 +4240,7 @@ pm_regular_expression_node_create_unescaped(pm_parser_t *parser, const pm_token_ // Allocate a new initialize a new RegularExpressionNode node. static inline pm_regular_expression_node_t * pm_regular_expression_node_create(pm_parser_t *parser, const pm_token_t *opening, const pm_token_t *content, const pm_token_t *closing) { - return pm_regular_expression_node_create_unescaped(parser, opening, content, closing, &PM_EMPTY_STRING); + return pm_regular_expression_node_create_unescaped(parser, opening, content, closing, &PM_STRING_EMPTY); } // Allocate a new RequiredParameterNode node. @@ -4588,7 +4588,7 @@ pm_string_node_create_unescaped(pm_parser_t *parser, const pm_token_t *opening, // Allocate a new StringNode node. static pm_string_node_t * pm_string_node_create(pm_parser_t *parser, const pm_token_t *opening, const pm_token_t *content, const pm_token_t *closing) { - return pm_string_node_create_unescaped(parser, opening, content, closing, &PM_EMPTY_STRING); + return pm_string_node_create_unescaped(parser, opening, content, closing, &PM_STRING_EMPTY); } // Allocate a new StringNode node and create it using the current string on the @@ -4596,7 +4596,7 @@ pm_string_node_create(pm_parser_t *parser, const pm_token_t *opening, const pm_t static pm_string_node_t * pm_string_node_create_current_string(pm_parser_t *parser, const pm_token_t *opening, const pm_token_t *content, const pm_token_t *closing) { pm_string_node_t *node = pm_string_node_create_unescaped(parser, opening, content, closing, &parser->current_string); - parser->current_string = PM_EMPTY_STRING; + parser->current_string = PM_STRING_EMPTY; return node; } @@ -4663,14 +4663,14 @@ pm_symbol_node_create_unescaped(pm_parser_t *parser, const pm_token_t *opening, // Allocate and initialize a new SymbolNode node. static inline pm_symbol_node_t * pm_symbol_node_create(pm_parser_t *parser, const pm_token_t *opening, const pm_token_t *value, const pm_token_t *closing) { - return pm_symbol_node_create_unescaped(parser, opening, value, closing, &PM_EMPTY_STRING); + return pm_symbol_node_create_unescaped(parser, opening, value, closing, &PM_STRING_EMPTY); } // Allocate and initialize a new SymbolNode node with the current string. static pm_symbol_node_t * pm_symbol_node_create_current_string(pm_parser_t *parser, const pm_token_t *opening, const pm_token_t *value, const pm_token_t *closing) { pm_symbol_node_t *node = pm_symbol_node_create_unescaped(parser, opening, value, closing, &parser->current_string); - parser->current_string = PM_EMPTY_STRING; + parser->current_string = PM_STRING_EMPTY; return node; } @@ -5047,7 +5047,7 @@ pm_xstring_node_create_unescaped(pm_parser_t *parser, const pm_token_t *opening, // Allocate and initialize a new XStringNode node. static inline pm_x_string_node_t * pm_xstring_node_create(pm_parser_t *parser, const pm_token_t *opening, const pm_token_t *content, const pm_token_t *closing) { - return pm_xstring_node_create_unescaped(parser, opening, content, closing, &PM_EMPTY_STRING); + return pm_xstring_node_create_unescaped(parser, opening, content, closing, &PM_STRING_EMPTY); } // Allocate a new YieldNode node. @@ -12428,7 +12428,7 @@ parse_strings(pm_parser_t *parser) { // start with a single string content node. pm_string_t unescaped; if (match1(parser, PM_TOKEN_EOF)) { - unescaped = PM_EMPTY_STRING; + unescaped = PM_STRING_EMPTY; } else { unescaped = parser->current_string; } @@ -12986,9 +12986,9 @@ parse_expression_prefix(pm_parser_t *parser, pm_binding_power_t binding_power) { pm_token_t content = parse_strings_empty_content(parser->previous.start); if (quote == PM_HEREDOC_QUOTE_BACKTICK) { - node = (pm_node_t *) pm_xstring_node_create_unescaped(parser, &opening, &content, &parser->previous, &PM_EMPTY_STRING); + node = (pm_node_t *) pm_xstring_node_create_unescaped(parser, &opening, &content, &parser->previous, &PM_STRING_EMPTY); } else { - node = (pm_node_t *) pm_string_node_create_unescaped(parser, &opening, &content, &parser->previous, &PM_EMPTY_STRING); + node = (pm_node_t *) pm_string_node_create_unescaped(parser, &opening, &content, &parser->previous, &PM_STRING_EMPTY); } node->location.end = opening.end; @@ -15696,7 +15696,7 @@ pm_parser_init(pm_parser_t *parser, const uint8_t *source, size_t size, const ch .constant_pool = PM_CONSTANT_POOL_EMPTY, .newline_list = PM_NEWLINE_LIST_EMPTY, .integer_base = 0, - .current_string = PM_EMPTY_STRING, + .current_string = PM_STRING_EMPTY, .command_start = true, .recovering = false, .encoding_changed = false, @@ -15876,7 +15876,7 @@ pm_parse_serialize_comments(const uint8_t *source, size_t size, pm_buffer_t *buf #undef PM_CASE_KEYWORD #undef PM_CASE_OPERATOR #undef PM_CASE_WRITABLE -#undef PM_EMPTY_STRING +#undef PM_STRING_EMPTY #undef PM_LOCATION_NODE_BASE_VALUE #undef PM_LOCATION_NODE_VALUE #undef PM_LOCATION_NULL_VALUE diff --git a/src/util/pm_buffer.c b/src/util/pm_buffer.c index db2415a8077..acc6cad7256 100644 --- a/src/util/pm_buffer.c +++ b/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); diff --git a/src/util/pm_char.c b/src/util/pm_char.c index 59a188ae0a4..13eddbba481 100644 --- a/src/util/pm_char.c +++ b/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); diff --git a/src/util/pm_state_stack.c b/src/util/pm_state_stack.c index f7f9c245dd3..2a424b4c03c 100644 --- a/src/util/pm_state_stack.c +++ b/src/util/pm_state_stack.c @@ -1,18 +1,24 @@ #include "prism/util/pm_state_stack.h" -// Pushes a value onto the stack. +/** + * Pushes a value onto the stack. + */ void pm_state_stack_push(pm_state_stack_t *stack, bool value) { *stack = (*stack << 1) | (value & 1); } -// Pops a value off the stack. +/** + * Pops a value off the stack. + */ void pm_state_stack_pop(pm_state_stack_t *stack) { *stack >>= 1; } -// Returns the value at the top of the stack. +/** + * Returns the value at the top of the stack. + */ bool pm_state_stack_p(pm_state_stack_t *stack) { return *stack & 1; diff --git a/src/util/pm_string.c b/src/util/pm_string.c index 6ffedc86ba9..46913be266a 100644 --- a/src/util/pm_string.c +++ b/src/util/pm_string.c @@ -1,19 +1,16 @@ #include "prism/util/pm_string.h" -// The following headers are necessary to read files using demand paging. -#ifdef _WIN32 -#include -#else -#include -#include -#include -#include -#endif +/** + * Returns the size of the pm_string_t struct. This is necessary to allocate the + * correct amount of memory in the FFI backend. + */ +PRISM_EXPORTED_FUNCTION size_t +pm_string_sizeof(void) { + return sizeof(pm_string_t); +} /** * Initialize a shared string that is based on initial input. - * - * @memberof pm_string_t */ void pm_string_shared_init(pm_string_t *string, const uint8_t *start, const uint8_t *end) { @@ -28,8 +25,6 @@ pm_string_shared_init(pm_string_t *string, const uint8_t *start, const uint8_t * /** * Initialize an owned string that is responsible for freeing allocated memory. - * - * @memberof pm_string_t */ void pm_string_owned_init(pm_string_t *string, uint8_t *source, size_t length) { @@ -42,8 +37,6 @@ pm_string_owned_init(pm_string_t *string, uint8_t *source, size_t length) { /** * Initialize a constant string that doesn't own its memory source. - * - * @memberof pm_string_t */ void pm_string_constant_init(pm_string_t *string, const char *source, size_t length) { @@ -64,8 +57,6 @@ pm_string_constant_init(pm_string_t *string, const char *source, size_t length) * for large files). This means that if we're on windows we'll use * `MapViewOfFile`, on POSIX systems that have access to `mmap` we'll use * `mmap`, and on other POSIX systems we'll use `read`. - * - * @memberof pm_string_t */ bool pm_string_mapped_init(pm_string_t *string, const char *filepath) { @@ -90,7 +81,7 @@ pm_string_mapped_init(pm_string_t *string, const char *filepath) { // the source to a constant empty string and return. if (file_size == 0) { CloseHandle(file); - *string = PM_EMPTY_STRING; + *string = PM_STRING_EMPTY; return true; } @@ -136,7 +127,7 @@ pm_string_mapped_init(pm_string_t *string, const char *filepath) { if (size == 0) { close(fd); - *string = PM_EMPTY_STRING; + *string = PM_STRING_EMPTY; return true; } @@ -154,8 +145,6 @@ pm_string_mapped_init(pm_string_t *string, const char *filepath) { /** * Returns the memory size associated with the string. - * - * @memberof pm_string_t */ size_t pm_string_memsize(const pm_string_t *string) { @@ -169,8 +158,6 @@ pm_string_memsize(const pm_string_t *string) { /** * Ensure the string is owned. If it is not, then reinitialize it as owned and * copy over the previous source. - * - * @memberof pm_string_t */ void pm_string_ensure_owned(pm_string_t *string) { @@ -188,8 +175,6 @@ pm_string_ensure_owned(pm_string_t *string) { /** * Returns the length associated with the string. - * - * @memberof pm_string_t */ PRISM_EXPORTED_FUNCTION size_t pm_string_length(const pm_string_t *string) { @@ -198,8 +183,6 @@ pm_string_length(const pm_string_t *string) { /** * Returns the start pointer associated with the string. - * - * @memberof pm_string_t */ PRISM_EXPORTED_FUNCTION const uint8_t * pm_string_source(const pm_string_t *string) { @@ -208,8 +191,6 @@ pm_string_source(const pm_string_t *string) { /** * Free the associated memory of the given string. - * - * @memberof pm_string_t */ PRISM_EXPORTED_FUNCTION void pm_string_free(pm_string_t *string) { @@ -225,12 +206,3 @@ pm_string_free(pm_string_t *string) { #endif } } - -/** - * Returns the size of the pm_string_t struct. This is necessary to allocate the - * correct amount of memory in the FFI backend. - */ -PRISM_EXPORTED_FUNCTION size_t -pm_string_sizeof(void) { - return sizeof(pm_string_t); -} diff --git a/src/util/pm_string_list.c b/src/util/pm_string_list.c index 87e63a43eb0..fa7f20619f1 100644 --- a/src/util/pm_string_list.c +++ b/src/util/pm_string_list.c @@ -1,14 +1,18 @@ #include "prism/util/pm_string_list.h" -// Initialize a pm_string_list_t with its default values. +/** + * Initialize a pm_string_list_t with its default values. + */ void pm_string_list_init(pm_string_list_t *string_list) { - string_list->strings = (pm_string_t *) malloc(sizeof(pm_string_t)); string_list->length = 0; string_list->capacity = 1; + string_list->strings = (pm_string_t *) malloc(sizeof(pm_string_t)); } -// Append a pm_string_t to the given string list. +/** + * Append a pm_string_t to the given string list. + */ void pm_string_list_append(pm_string_list_t *string_list, pm_string_t *string) { if (string_list->length + 1 > string_list->capacity) { @@ -22,7 +26,9 @@ pm_string_list_append(pm_string_list_t *string_list, pm_string_t *string) { string_list->strings[string_list->length++] = *string; } -// Free the memory associated with the string list. +/** + * Free the memory associated with the string list + */ void pm_string_list_free(pm_string_list_t *string_list) { free(string_list->strings);