prism 1.4.0 → 1.5.0

data/include/prism/options.h

@@ -82,14 +82,20 @@ typedef void (*pm_options_shebang_callback_t)(struct pm_options *options, const
  * parse in the same way as a specific version of CRuby would have.
  */
 typedef enum {
-    /** The current version of prism. */
-    PM_OPTIONS_VERSION_LATEST = 0,
+    /** If an explicit version is not provided, the current version of prism will be used. */
+    PM_OPTIONS_VERSION_UNSET = 0,
 
     /** The vendored version of prism in CRuby 3.3.x. */
     PM_OPTIONS_VERSION_CRUBY_3_3 = 1,
 
     /** The vendored version of prism in CRuby 3.4.x. */
-    PM_OPTIONS_VERSION_CRUBY_3_4 = 2
+    PM_OPTIONS_VERSION_CRUBY_3_4 = 2,
+
+    /** The vendored version of prism in CRuby 3.5.x. */
+    PM_OPTIONS_VERSION_CRUBY_3_5 = 3,
+
+    /** The current version of prism. */
+    PM_OPTIONS_VERSION_LATEST = PM_OPTIONS_VERSION_CRUBY_3_5
 } pm_options_version_t;
 
 /**
@@ -231,6 +237,8 @@ static const uint8_t PM_OPTIONS_COMMAND_LINE_X = 0x20;
  * @param shebang_callback The shebang callback to set.
  * @param shebang_callback_data Any additional data that should be passed along
  *   to the callback.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_shebang_callback_set(pm_options_t *options, pm_options_shebang_callback_t shebang_callback, void *shebang_callback_data);
 
@@ -239,6 +247,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_shebang_callback_set(pm_options_t *optio
  *
  * @param options The options struct to set the filepath on.
  * @param filepath The filepath to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_filepath_set(pm_options_t *options, const char *filepath);
 
@@ -247,6 +257,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_filepath_set(pm_options_t *options, cons
  *
  * @param options The options struct to set the line on.
  * @param line The line to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_line_set(pm_options_t *options, int32_t line);
 
@@ -255,6 +267,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_line_set(pm_options_t *options, int32_t
  *
  * @param options The options struct to set the encoding on.
  * @param encoding The encoding to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_encoding_set(pm_options_t *options, const char *encoding);
 
@@ -263,6 +277,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_encoding_set(pm_options_t *options, cons
  *
  * @param options The options struct to set the encoding_locked value on.
  * @param encoding_locked The encoding_locked value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_encoding_locked_set(pm_options_t *options, bool encoding_locked);
 
@@ -271,6 +287,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_encoding_locked_set(pm_options_t *option
  *
  * @param options The options struct to set the frozen string literal value on.
  * @param frozen_string_literal The frozen string literal value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_frozen_string_literal_set(pm_options_t *options, bool frozen_string_literal);
 
@@ -279,6 +297,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_frozen_string_literal_set(pm_options_t *
  *
  * @param options The options struct to set the command line option on.
  * @param command_line The command_line value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_command_line_set(pm_options_t *options, uint8_t command_line);
 
@@ -291,6 +311,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_command_line_set(pm_options_t *options,
  * @param version The version to set.
  * @param length The length of the version string.
  * @return Whether or not the version was parsed successfully.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION bool pm_options_version_set(pm_options_t *options, const char *version, size_t length);
 
@@ -299,6 +321,8 @@ PRISM_EXPORTED_FUNCTION bool pm_options_version_set(pm_options_t *options, const
  *
  * @param options The options struct to set the main script value on.
  * @param main_script The main script value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_main_script_set(pm_options_t *options, bool main_script);
 
@@ -307,6 +331,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_main_script_set(pm_options_t *options, b
  *
  * @param options The options struct to set the partial script value on.
  * @param partial_script The partial script value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_partial_script_set(pm_options_t *options, bool partial_script);
 
@@ -315,6 +341,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_partial_script_set(pm_options_t *options
  *
  * @param options The options struct to set the freeze value on.
  * @param freeze The freeze value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_freeze_set(pm_options_t *options, bool freeze);
 
@@ -324,6 +352,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_freeze_set(pm_options_t *options, bool f
  * @param options The options struct to initialize the scopes array on.
  * @param scopes_count The number of scopes to allocate.
  * @return Whether or not the scopes array was initialized successfully.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION bool pm_options_scopes_init(pm_options_t *options, size_t scopes_count);
 
@@ -333,6 +363,8 @@ PRISM_EXPORTED_FUNCTION bool pm_options_scopes_init(pm_options_t *options, size_
  * @param options The options struct to get the scope from.
  * @param index The index of the scope to get.
  * @return A pointer to the scope at the given index.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION const pm_options_scope_t * pm_options_scope_get(const pm_options_t *options, size_t index);
 
@@ -343,6 +375,8 @@ PRISM_EXPORTED_FUNCTION const pm_options_scope_t * pm_options_scope_get(const pm
  * @param scope The scope struct to initialize.
  * @param locals_count The number of locals to allocate.
  * @return Whether or not the scope was initialized successfully.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION bool pm_options_scope_init(pm_options_scope_t *scope, size_t locals_count);
 
@@ -352,6 +386,8 @@ PRISM_EXPORTED_FUNCTION bool pm_options_scope_init(pm_options_scope_t *scope, si
  * @param scope The scope struct to get the local from.
  * @param index The index of the local to get.
  * @return A pointer to the local at the given index.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION const pm_string_t * pm_options_scope_local_get(const pm_options_scope_t *scope, size_t index);
 
@@ -360,6 +396,8 @@ PRISM_EXPORTED_FUNCTION const pm_string_t * pm_options_scope_local_get(const pm_
  *
  * @param scope The scope struct to set the forwarding on.
  * @param forwarding The forwarding value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_scope_forwarding_set(pm_options_scope_t *scope, uint8_t forwarding);
 
@@ -367,6 +405,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_scope_forwarding_set(pm_options_scope_t
  * Free the internal memory associated with the options.
  *
  * @param options The options struct whose internal memory should be freed.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_free(pm_options_t *options);
 

data/include/prism/regexp.h

@@ -17,12 +17,12 @@
 #include <string.h>
 
 /**
- * This callback is called when a named capture group is found.
+ * This callback is called by pm_regexp_parse() when a named capture group is found.
  */
 typedef void (*pm_regexp_name_callback_t)(const pm_string_t *name, void *data);
 
 /**
- * This callback is called when a parse error is found.
+ * This callback is called by pm_regexp_parse() when a parse error is found.
  */
 typedef void (*pm_regexp_error_callback_t)(const uint8_t *start, const uint8_t *end, const char *message, void *data);
 

data/include/prism/util/pm_buffer.h

@@ -51,6 +51,8 @@ bool pm_buffer_init_capacity(pm_buffer_t *buffer, size_t capacity);
  *
  * @param buffer The buffer to initialize.
  * @returns True if the buffer was initialized successfully, false otherwise.
+ *
+ * \public \memberof pm_buffer_t
  */
 PRISM_EXPORTED_FUNCTION bool pm_buffer_init(pm_buffer_t *buffer);
 
@@ -59,6 +61,8 @@ PRISM_EXPORTED_FUNCTION bool pm_buffer_init(pm_buffer_t *buffer);
  *
  * @param buffer The buffer to get the value of.
  * @returns The value of the buffer.
+ *
+ * \public \memberof pm_buffer_t
  */
 PRISM_EXPORTED_FUNCTION char * pm_buffer_value(const pm_buffer_t *buffer);
 
@@ -67,6 +71,8 @@ PRISM_EXPORTED_FUNCTION char * pm_buffer_value(const pm_buffer_t *buffer);
  *
  * @param buffer The buffer to get the length of.
  * @returns The length of the buffer.
+ *
+ * \public \memberof pm_buffer_t
  */
 PRISM_EXPORTED_FUNCTION size_t pm_buffer_length(const pm_buffer_t *buffer);
 
@@ -222,6 +228,8 @@ void pm_buffer_insert(pm_buffer_t *buffer, size_t index, const char *value, size
  * Free the memory associated with the buffer.
  *
  * @param buffer The buffer to free.
+ *
+ * \public \memberof pm_buffer_t
  */
 PRISM_EXPORTED_FUNCTION void pm_buffer_free(pm_buffer_t *buffer);
 

data/include/prism/util/pm_integer.h

@@ -112,6 +112,8 @@ void pm_integers_reduce(pm_integer_t *numerator, pm_integer_t *denominator);
  *
  * @param buffer The buffer to append the string to.
  * @param integer The integer to convert to a string.
+ *
+ * \public \memberof pm_integer_t
  */
 PRISM_EXPORTED_FUNCTION void pm_integer_string(pm_buffer_t *buffer, const pm_integer_t *integer);
 
@@ -120,6 +122,8 @@ PRISM_EXPORTED_FUNCTION void pm_integer_string(pm_buffer_t *buffer, const pm_int
  * the integer exceeds the size of a single node in the linked list.
  *
  * @param integer The integer to free.
+ *
+ * \public \memberof pm_integer_t
  */
 PRISM_EXPORTED_FUNCTION void pm_integer_free(pm_integer_t *integer);
 

data/include/prism/util/pm_list.h

@@ -68,6 +68,8 @@ typedef struct {
  *
  * @param list The list to check.
  * @return True if the given list is empty, otherwise false.
+ *
+ * \public \memberof pm_list_t
  */
 PRISM_EXPORTED_FUNCTION bool pm_list_empty_p(pm_list_t *list);
 
@@ -76,6 +78,8 @@ PRISM_EXPORTED_FUNCTION bool pm_list_empty_p(pm_list_t *list);
  *
  * @param list The list to check.
  * @return The size of the list.
+ *
+ * \public \memberof pm_list_t
  */
 PRISM_EXPORTED_FUNCTION size_t pm_list_size(pm_list_t *list);
 
@@ -91,6 +95,8 @@ void pm_list_append(pm_list_t *list, pm_list_node_t *node);
  * Deallocate the internal state of the given list.
  *
  * @param list The list to free.
+ *
+ * \public \memberof pm_list_t
  */
 PRISM_EXPORTED_FUNCTION void pm_list_free(pm_list_t *list);
 

data/include/prism/util/pm_string.h

@@ -45,11 +45,11 @@ typedef struct {
         /** 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`. */
+        /** This string owns its memory, and should be freed using `pm_string_free()`. */
         PM_STRING_OWNED,
 
 #ifdef PRISM_HAS_MMAP
-        /** This string is a memory-mapped file, and should be freed using `pm_string_free`. */
+        /** This string is a memory-mapped file, and should be freed using `pm_string_free()`. */
         PM_STRING_MAPPED
 #endif
     } type;
@@ -130,6 +130,8 @@ typedef enum {
  * @param string The string to initialize.
  * @param filepath The filepath to read.
  * @return The success of the read, indicated by the value of the enum.
+ *
+ * \public \memberof pm_string_t
  */
 PRISM_EXPORTED_FUNCTION pm_string_init_result_t pm_string_mapped_init(pm_string_t *string, const char *filepath);
 
@@ -141,6 +143,8 @@ PRISM_EXPORTED_FUNCTION pm_string_init_result_t pm_string_mapped_init(pm_string_
  * @param string The string to initialize.
  * @param filepath The filepath to read.
  * @return The success of the read, indicated by the value of the enum.
+ *
+ * \public \memberof pm_string_t
  */
 PRISM_EXPORTED_FUNCTION pm_string_init_result_t pm_string_file_init(pm_string_t *string, const char *filepath);
 
@@ -169,6 +173,8 @@ int pm_string_compare(const pm_string_t *left, const pm_string_t *right);
  *
  * @param string The string to get the length of.
  * @return The length of the string.
+ *
+ * \public \memberof pm_string_t
  */
 PRISM_EXPORTED_FUNCTION size_t pm_string_length(const pm_string_t *string);
 
@@ -177,6 +183,8 @@ PRISM_EXPORTED_FUNCTION size_t pm_string_length(const pm_string_t *string);
  *
  * @param string The string to get the start pointer of.
  * @return The start pointer of the string.
+ *
+ * \public \memberof pm_string_t
  */
 PRISM_EXPORTED_FUNCTION const uint8_t * pm_string_source(const pm_string_t *string);
 
@@ -184,6 +192,8 @@ PRISM_EXPORTED_FUNCTION const uint8_t * pm_string_source(const pm_string_t *stri
  * Free the associated memory of the given string.
  *
  * @param string The string to free.
+ *
+ * \public \memberof pm_string_t
  */
 PRISM_EXPORTED_FUNCTION void pm_string_free(pm_string_t *string);
 

data/include/prism/version.h

@@ -14,7 +14,7 @@
 /**
  * The minor version of the Prism library as an int.
  */
-#define PRISM_VERSION_MINOR 4
+#define PRISM_VERSION_MINOR 5
 
 /**
  * The patch version of the Prism library as an int.
@@ -24,6 +24,6 @@
 /**
  * The version of the Prism library as a constant string.
  */
-#define PRISM_VERSION "1.4.0"
+#define PRISM_VERSION "1.5.0"
 
 #endif

data/include/prism.h

@@ -49,10 +49,15 @@ PRISM_EXPORTED_FUNCTION const char * pm_version(void);
 /**
  * Initialize a parser with the given start and end pointers.
  *
+ * The resulting parser must eventually be freed with `pm_parser_free()`.
+ *
  * @param parser The parser to initialize.
  * @param source The source to parse.
  * @param size The size of the source.
- * @param options The optional options to use when parsing.
+ * @param options The optional options to use when parsing. These options must
+ *   live for the whole lifetime of this parser.
+ *
+ * \public \memberof pm_parser
  */
 PRISM_EXPORTED_FUNCTION void pm_parser_init(pm_parser_t *parser, const uint8_t *source, size_t size, const pm_options_t *options);
 
@@ -62,13 +67,20 @@ PRISM_EXPORTED_FUNCTION void pm_parser_init(pm_parser_t *parser, const uint8_t *
  *
  * @param parser The parser to register the callback with.
  * @param callback The callback to register.
+ *
+ * \public \memberof pm_parser
  */
 PRISM_EXPORTED_FUNCTION void pm_parser_register_encoding_changed_callback(pm_parser_t *parser, pm_encoding_changed_callback_t callback);
 
 /**
  * Free any memory associated with the given parser.
  *
+ * This does not free the `pm_options_t` object that was used to initialize the
+ * parser.
+ *
  * @param parser The parser to free.
+ *
+ * \public \memberof pm_parser
  */
 PRISM_EXPORTED_FUNCTION void pm_parser_free(pm_parser_t *parser);
 
@@ -77,16 +89,25 @@ PRISM_EXPORTED_FUNCTION void pm_parser_free(pm_parser_t *parser);
  *
  * @param parser The parser to use.
  * @return The AST representing the source.
+ *
+ * \public \memberof pm_parser
  */
 PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse(pm_parser_t *parser);
 
 /**
- * This function is used in pm_parse_stream to retrieve a line of input from a
+ * This function is used in pm_parse_stream() 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.
  */
 typedef char * (pm_parse_stream_fgets_t)(char *string, int size, void *stream);
 
+/**
+ * This function is used in pm_parse_stream to check whether a stream is EOF.
+ * It closely mirrors that of feof so that feof can be used as the
+ * default implementation.
+ */
+typedef int (pm_parse_stream_feof_t)(void *stream);
+
 /**
  * Parse a stream of Ruby source and return the tree.
  *
@@ -94,10 +115,13 @@ typedef char * (pm_parse_stream_fgets_t)(char *string, int size, void *stream);
  * @param buffer The buffer to use.
  * @param stream The stream to parse.
  * @param stream_fgets The function to use to read from the stream.
+ * @param stream_feof The function to use to determine if the stream has hit eof.
  * @param options The optional options to use when parsing.
  * @return The AST representing the source.
+ *
+ * \public \memberof pm_parser
  */
-PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse_stream(pm_parser_t *parser, pm_buffer_t *buffer, void *stream, pm_parse_stream_fgets_t *stream_fgets, const pm_options_t *options);
+PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse_stream(pm_parser_t *parser, pm_buffer_t *buffer, void *stream, pm_parse_stream_fgets_t *stream_fgets, pm_parse_stream_feof_t *stream_feof, const pm_options_t *options);
 
 // We optionally support serializing to a binary string. For systems that don't
 // want or need this functionality, it can be turned off with the
@@ -111,9 +135,10 @@ PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse_stream(pm_parser_t *parser, pm_buff
  * @param buffer The buffer to serialize to.
  * @param stream The stream to parse.
  * @param stream_fgets The function to use to read from the stream.
+ * @param stream_feof The function to use to tell if the stream has hit eof.
  * @param data The optional data to pass to the parser.
  */
-PRISM_EXPORTED_FUNCTION void pm_serialize_parse_stream(pm_buffer_t *buffer, void *stream, pm_parse_stream_fgets_t *stream_fgets, const char *data);
+PRISM_EXPORTED_FUNCTION void pm_serialize_parse_stream(pm_buffer_t *buffer, void *stream, pm_parse_stream_fgets_t *stream_fgets, pm_parse_stream_feof_t *stream_feof, const char *data);
 
 /**
  * Serialize the given list of comments to the given buffer.
@@ -307,10 +332,10 @@ PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_method_name(const uint
  * to want to use and be aware of are:
  *
  * * `pm_parser_t` - the main parser structure
- * * `pm_parser_init` - initialize a parser
- * * `pm_parse` - parse and return the root node
- * * `pm_node_destroy` - deallocate the root node returned by `pm_parse`
- * * `pm_parser_free` - free the internal memory of the parser
+ * * `pm_parser_init()` - initialize a parser
+ * * `pm_parse()` - parse and return the root node
+ * * `pm_node_destroy()` - deallocate the root node returned by `pm_parse()`
+ * * `pm_parser_free()` - free the internal memory of the parser
  *
  * Putting all of this together would look something like:
  *
@@ -327,8 +352,8 @@ PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_method_name(const uint
  * }
  * ```
  *
- * All of the nodes "inherit" from `pm_node_t` by embedding those structures as
- * their first member. This means you can downcast and upcast any node in the
+ * All of the nodes "inherit" from `pm_node_t` by embedding those structures
+ * as their first member. This means you can downcast and upcast any node in the
  * tree to a `pm_node_t`.
  *
  * @section serializing Serializing
@@ -340,9 +365,9 @@ PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_method_name(const uint
  * use and be aware of are:
  *
  * * `pm_buffer_t` - a small buffer object that will hold the serialized AST
- * * `pm_buffer_free` - free the memory associated with the buffer
- * * `pm_serialize` - serialize the AST into a buffer
- * * `pm_serialize_parse` - parse and serialize the AST into a buffer
+ * * `pm_buffer_free()` - free the memory associated with the buffer
+ * * `pm_serialize()` - serialize the AST into a buffer
+ * * `pm_serialize_parse()` - parse and serialize the AST into a buffer
  *
  * Putting all of this together would look something like:
  *
@@ -360,7 +385,7 @@ PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_method_name(const uint
  * @section inspecting Inspecting
  *
  * Prism provides the ability to inspect the AST by pretty-printing nodes. You
- * can do this with the `pm_prettyprint` function, which you would use like:
+ * can do this with the `pm_prettyprint()` function, which you would use like:
  *
  * ```c
  * void prettyprint(const uint8_t *source, size_t length) {