prism 0.16.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +16 -1
  3. data/Makefile +6 -0
  4. data/README.md +1 -1
  5. data/config.yml +50 -35
  6. data/docs/fuzzing.md +1 -1
  7. data/docs/serialization.md +28 -29
  8. data/ext/prism/api_node.c +802 -770
  9. data/ext/prism/api_pack.c +20 -9
  10. data/ext/prism/extension.c +464 -162
  11. data/ext/prism/extension.h +1 -1
  12. data/include/prism/ast.h +3173 -763
  13. data/include/prism/defines.h +32 -9
  14. data/include/prism/diagnostic.h +36 -3
  15. data/include/prism/enc/pm_encoding.h +118 -28
  16. data/include/prism/node.h +38 -13
  17. data/include/prism/options.h +204 -0
  18. data/include/prism/pack.h +44 -33
  19. data/include/prism/parser.h +445 -200
  20. data/include/prism/prettyprint.h +12 -1
  21. data/include/prism/regexp.h +16 -2
  22. data/include/prism/util/pm_buffer.h +94 -16
  23. data/include/prism/util/pm_char.h +162 -48
  24. data/include/prism/util/pm_constant_pool.h +126 -32
  25. data/include/prism/util/pm_list.h +68 -38
  26. data/include/prism/util/pm_memchr.h +18 -3
  27. data/include/prism/util/pm_newline_list.h +70 -27
  28. data/include/prism/util/pm_state_stack.h +25 -7
  29. data/include/prism/util/pm_string.h +115 -27
  30. data/include/prism/util/pm_string_list.h +25 -6
  31. data/include/prism/util/pm_strncasecmp.h +32 -0
  32. data/include/prism/util/pm_strpbrk.h +31 -17
  33. data/include/prism/version.h +27 -2
  34. data/include/prism.h +224 -31
  35. data/lib/prism/compiler.rb +6 -3
  36. data/lib/prism/debug.rb +23 -7
  37. data/lib/prism/dispatcher.rb +33 -18
  38. data/lib/prism/dsl.rb +10 -5
  39. data/lib/prism/ffi.rb +132 -80
  40. data/lib/prism/lex_compat.rb +25 -15
  41. data/lib/prism/mutation_compiler.rb +10 -5
  42. data/lib/prism/node.rb +370 -135
  43. data/lib/prism/node_ext.rb +1 -1
  44. data/lib/prism/node_inspector.rb +1 -1
  45. data/lib/prism/pack.rb +79 -40
  46. data/lib/prism/parse_result/comments.rb +7 -2
  47. data/lib/prism/parse_result/newlines.rb +4 -0
  48. data/lib/prism/parse_result.rb +150 -30
  49. data/lib/prism/pattern.rb +11 -0
  50. data/lib/prism/ripper_compat.rb +28 -10
  51. data/lib/prism/serialize.rb +86 -54
  52. data/lib/prism/visitor.rb +10 -3
  53. data/lib/prism.rb +20 -2
  54. data/prism.gemspec +4 -2
  55. data/rbi/prism.rbi +104 -60
  56. data/rbi/prism_static.rbi +16 -2
  57. data/sig/prism.rbs +72 -43
  58. data/sig/prism_static.rbs +14 -1
  59. data/src/diagnostic.c +56 -53
  60. data/src/enc/pm_big5.c +1 -0
  61. data/src/enc/pm_euc_jp.c +1 -0
  62. data/src/enc/pm_gbk.c +1 -0
  63. data/src/enc/pm_shift_jis.c +1 -0
  64. data/src/enc/pm_tables.c +316 -80
  65. data/src/enc/pm_unicode.c +53 -8
  66. data/src/enc/pm_windows_31j.c +1 -0
  67. data/src/node.c +334 -321
  68. data/src/options.c +170 -0
  69. data/src/prettyprint.c +74 -47
  70. data/src/prism.c +1642 -856
  71. data/src/regexp.c +151 -95
  72. data/src/serialize.c +44 -20
  73. data/src/token_type.c +3 -1
  74. data/src/util/pm_buffer.c +45 -15
  75. data/src/util/pm_char.c +103 -57
  76. data/src/util/pm_constant_pool.c +51 -21
  77. data/src/util/pm_list.c +12 -4
  78. data/src/util/pm_memchr.c +5 -3
  79. data/src/util/pm_newline_list.c +20 -12
  80. data/src/util/pm_state_stack.c +9 -3
  81. data/src/util/pm_string.c +95 -85
  82. data/src/util/pm_string_list.c +14 -15
  83. data/src/util/pm_strncasecmp.c +10 -3
  84. data/src/util/pm_strpbrk.c +25 -19
  85. metadata +5 -3
  86. data/docs/prism.png +0 -0
@@ -1,8 +1,12 @@
1
- // The constant pool is a data structure that stores a set of strings. Each
2
- // string is assigned a unique id, which can be used to compare strings for
3
- // equality. This comparison ends up being much faster than strcmp, since it
4
- // only requires a single integer comparison.
5
-
1
+ /**
2
+ * @file pm_constant_pool.h
3
+ *
4
+ * A data structure that stores a set of strings.
5
+ *
6
+ * Each string is assigned a unique id, which can be used to compare strings for
7
+ * equality. This comparison ends up being much faster than strcmp, since it
8
+ * only requires a single integer comparison.
9
+ */
6
10
  #ifndef PRISM_CONSTANT_POOL_H
7
11
  #define PRISM_CONSTANT_POOL_H
8
12
 
@@ -14,84 +18,174 @@
14
18
  #include <stdlib.h>
15
19
  #include <string.h>
16
20
 
21
+ /**
22
+ * A constant id is a unique identifier for a constant in the constant pool.
23
+ */
17
24
  typedef uint32_t pm_constant_id_t;
18
25
 
26
+ /**
27
+ * A list of constant IDs. Usually used to represent a set of locals.
28
+ */
19
29
  typedef struct {
20
- pm_constant_id_t *ids;
30
+ /** The number of constant ids in the list. */
21
31
  size_t size;
32
+
33
+ /** The number of constant ids that have been allocated in the list. */
22
34
  size_t capacity;
35
+
36
+ /** The constant ids in the list. */
37
+ pm_constant_id_t *ids;
23
38
  } pm_constant_id_list_t;
24
39
 
25
- // Initialize a list of constant ids.
40
+ /**
41
+ * Initialize a list of constant ids.
42
+ *
43
+ * @param list The list to initialize.
44
+ */
26
45
  void pm_constant_id_list_init(pm_constant_id_list_t *list);
27
46
 
28
- // Append a constant id to a list of constant ids. Returns false if any
29
- // potential reallocations fail.
47
+ /**
48
+ * Append a constant id to a list of constant ids. Returns false if any
49
+ * potential reallocations fail.
50
+ *
51
+ * @param list The list to append to.
52
+ * @param id The id to append.
53
+ * @return Whether the append succeeded.
54
+ */
30
55
  bool pm_constant_id_list_append(pm_constant_id_list_t *list, pm_constant_id_t id);
31
56
 
32
- // Checks if the current constant id list includes the given constant id.
33
- bool
34
- pm_constant_id_list_includes(pm_constant_id_list_t *list, pm_constant_id_t id);
35
-
36
- // Get the memory size of a list of constant ids.
57
+ /**
58
+ * Checks if the current constant id list includes the given constant id.
59
+ *
60
+ * @param list The list to check.
61
+ * @param id The id to check for.
62
+ * @return Whether the list includes the given id.
63
+ */
64
+ bool pm_constant_id_list_includes(pm_constant_id_list_t *list, pm_constant_id_t id);
65
+
66
+ /**
67
+ * Get the memory size of a list of constant ids.
68
+ *
69
+ * @param list The list to get the memory size of.
70
+ * @return The memory size of the list.
71
+ */
37
72
  size_t pm_constant_id_list_memsize(pm_constant_id_list_t *list);
38
73
 
39
- // Free the memory associated with a list of constant ids.
74
+ /**
75
+ * Free the memory associated with a list of constant ids.
76
+ *
77
+ * @param list The list to free.
78
+ */
40
79
  void pm_constant_id_list_free(pm_constant_id_list_t *list);
41
80
 
42
- // Constant pool buckets can have a couple of different types.
81
+ /**
82
+ * The type of bucket in the constant pool hash map. This determines how the
83
+ * bucket should be freed.
84
+ */
43
85
  typedef unsigned int pm_constant_pool_bucket_type_t;
44
86
 
45
- // By default, each constant is a slice of the source.
87
+ /** By default, each constant is a slice of the source. */
46
88
  static const pm_constant_pool_bucket_type_t PM_CONSTANT_POOL_BUCKET_DEFAULT = 0;
47
89
 
48
- // An owned constant is one for which memory has been allocated.
90
+ /** An owned constant is one for which memory has been allocated. */
49
91
  static const pm_constant_pool_bucket_type_t PM_CONSTANT_POOL_BUCKET_OWNED = 1;
50
92
 
51
- // A constant constant is known at compile time.
93
+ /** A constant constant is known at compile time. */
52
94
  static const pm_constant_pool_bucket_type_t PM_CONSTANT_POOL_BUCKET_CONSTANT = 2;
53
95
 
96
+ /** A bucket in the hash map. */
54
97
  typedef struct {
98
+ /** The incremental ID used for indexing back into the pool. */
55
99
  unsigned int id: 30;
100
+
101
+ /** The type of the bucket, which determines how to free it. */
56
102
  pm_constant_pool_bucket_type_t type: 2;
103
+
104
+ /** The hash of the bucket. */
57
105
  uint32_t hash;
58
106
  } pm_constant_pool_bucket_t;
59
107
 
108
+ /** A constant in the pool which effectively stores a string. */
60
109
  typedef struct {
110
+ /** A pointer to the start of the string. */
61
111
  const uint8_t *start;
112
+
113
+ /** The length of the string. */
62
114
  size_t length;
63
115
  } pm_constant_t;
64
116
 
117
+ /** The overall constant pool, which stores constants found while parsing. */
65
118
  typedef struct {
119
+ /** The buckets in the hash map. */
66
120
  pm_constant_pool_bucket_t *buckets;
121
+
122
+ /** The constants that are stored in the buckets. */
67
123
  pm_constant_t *constants;
124
+
125
+ /** The number of buckets in the hash map. */
68
126
  uint32_t size;
127
+
128
+ /** The number of buckets that have been allocated in the hash map. */
69
129
  uint32_t capacity;
70
130
  } pm_constant_pool_t;
71
131
 
72
- // Define an empty constant pool.
73
- #define PM_CONSTANT_POOL_EMPTY ((pm_constant_pool_t) { .buckets = NULL, .constants = NULL, .size = 0, .capacity = 0 })
74
-
75
- // Initialize a new constant pool with a given capacity.
132
+ /**
133
+ * Initialize a new constant pool with a given capacity.
134
+ *
135
+ * @param pool The pool to initialize.
136
+ * @param capacity The initial capacity of the pool.
137
+ * @return Whether the initialization succeeded.
138
+ */
76
139
  bool pm_constant_pool_init(pm_constant_pool_t *pool, uint32_t capacity);
77
140
 
78
- // Return a pointer to the constant indicated by the given constant id.
141
+ /**
142
+ * Return a pointer to the constant indicated by the given constant id.
143
+ *
144
+ * @param pool The pool to get the constant from.
145
+ * @param constant_id The id of the constant to get.
146
+ * @return A pointer to the constant.
147
+ */
79
148
  pm_constant_t * pm_constant_pool_id_to_constant(const pm_constant_pool_t *pool, pm_constant_id_t constant_id);
80
149
 
81
- // Insert a constant into a constant pool that is a slice of a source string.
82
- // Returns the id of the constant, or 0 if any potential calls to resize fail.
150
+ /**
151
+ * Insert a constant into a constant pool that is a slice of a source string.
152
+ * Returns the id of the constant, or 0 if any potential calls to resize fail.
153
+ *
154
+ * @param pool The pool to insert the constant into.
155
+ * @param start A pointer to the start of the constant.
156
+ * @param length The length of the constant.
157
+ * @return The id of the constant.
158
+ */
83
159
  pm_constant_id_t pm_constant_pool_insert_shared(pm_constant_pool_t *pool, const uint8_t *start, size_t length);
84
160
 
85
- // Insert a constant into a constant pool from memory that is now owned by the
86
- // constant pool. Returns the id of the constant, or 0 if any potential calls to
87
- // resize fail.
161
+ /**
162
+ * Insert a constant into a constant pool from memory that is now owned by the
163
+ * constant pool. Returns the id of the constant, or 0 if any potential calls to
164
+ * resize fail.
165
+ *
166
+ * @param pool The pool to insert the constant into.
167
+ * @param start A pointer to the start of the constant.
168
+ * @param length The length of the constant.
169
+ * @return The id of the constant.
170
+ */
88
171
  pm_constant_id_t pm_constant_pool_insert_owned(pm_constant_pool_t *pool, const uint8_t *start, size_t length);
89
172
 
90
- // Insert a constant into a constant pool from memory that is constant. Returns
91
- // the id of the constant, or 0 if any potential calls to resize fail.
173
+ /**
174
+ * Insert a constant into a constant pool from memory that is constant. Returns
175
+ * the id of the constant, or 0 if any potential calls to resize fail.
176
+ *
177
+ * @param pool The pool to insert the constant into.
178
+ * @param start A pointer to the start of the constant.
179
+ * @param length The length of the constant.
180
+ * @return The id of the constant.
181
+ */
92
182
  pm_constant_id_t pm_constant_pool_insert_constant(pm_constant_pool_t *pool, const uint8_t *start, size_t length);
93
183
 
94
- // Free the memory associated with a constant pool.
184
+ /**
185
+ * Free the memory associated with a constant pool.
186
+ *
187
+ * @param pool The pool to free.
188
+ */
95
189
  void pm_constant_pool_free(pm_constant_pool_t *pool);
96
190
 
97
191
  #endif
@@ -1,30 +1,8 @@
1
- // This struct represents an abstract linked list that provides common
2
- // functionality. It is meant to be used any time a linked list is necessary to
3
- // store data.
4
- //
5
- // The linked list itself operates off a set of pointers. Because the pointers
6
- // are not necessarily sequential, they can be of any size. We use this fact to
7
- // allow the consumer of this linked list to extend the node struct to include
8
- // any data they want. This is done by using the pm_list_node_t as the first
9
- // member of the struct.
10
- //
11
- // For example, if we want to store a list of integers, we can do the following:
12
- //
13
- // typedef struct {
14
- // pm_list_node_t node;
15
- // int value;
16
- // } pm_int_node_t;
17
- //
18
- // pm_list_t list = PM_LIST_EMPTY;
19
- // pm_int_node_t *node = malloc(sizeof(pm_int_node_t));
20
- // node->value = 5;
21
- //
22
- // pm_list_append(&list, &node->node);
23
- //
24
- // The pm_list_t struct is used to represent the overall linked list. It
25
- // contains a pointer to the head and tail of the list. This allows for easy
26
- // iteration and appending of new nodes.
27
-
1
+ /**
2
+ * @file pm_list.h
3
+ *
4
+ * An abstract linked list.
5
+ */
28
6
  #ifndef PRISM_LIST_H
29
7
  #define PRISM_LIST_H
30
8
 
@@ -35,33 +13,85 @@
35
13
  #include <stdint.h>
36
14
  #include <stdlib.h>
37
15
 
38
- // This represents a node in the linked list.
16
+ /**
17
+ * This struct represents an abstract linked list that provides common
18
+ * functionality. It is meant to be used any time a linked list is necessary to
19
+ * store data.
20
+ *
21
+ * The linked list itself operates off a set of pointers. Because the pointers
22
+ * are not necessarily sequential, they can be of any size. We use this fact to
23
+ * allow the consumer of this linked list to extend the node struct to include
24
+ * any data they want. This is done by using the pm_list_node_t as the first
25
+ * member of the struct.
26
+ *
27
+ * For example, if we want to store a list of integers, we can do the following:
28
+ *
29
+ * ```c
30
+ * typedef struct {
31
+ * pm_list_node_t node;
32
+ * int value;
33
+ * } pm_int_node_t;
34
+ *
35
+ * pm_list_t list = { 0 };
36
+ * pm_int_node_t *node = malloc(sizeof(pm_int_node_t));
37
+ * node->value = 5;
38
+ *
39
+ * pm_list_append(&list, &node->node);
40
+ * ```
41
+ *
42
+ * The pm_list_t struct is used to represent the overall linked list. It
43
+ * contains a pointer to the head and tail of the list. This allows for easy
44
+ * iteration and appending of new nodes.
45
+ */
39
46
  typedef struct pm_list_node {
47
+ /** A pointer to the next node in the list. */
40
48
  struct pm_list_node *next;
41
49
  } pm_list_node_t;
42
50
 
43
- // This represents the overall linked list. It keeps a pointer to the head and
44
- // tail so that iteration is easy and pushing new nodes is easy.
51
+ /**
52
+ * This represents the overall linked list. It keeps a pointer to the head and
53
+ * tail so that iteration is easy and pushing new nodes is easy.
54
+ */
45
55
  typedef struct {
56
+ /** The size of the list. */
46
57
  size_t size;
58
+
59
+ /** A pointer to the head of the list. */
47
60
  pm_list_node_t *head;
61
+
62
+ /** A pointer to the tail of the list. */
48
63
  pm_list_node_t *tail;
49
64
  } pm_list_t;
50
65
 
51
- // This represents an empty list. It's used to initialize a stack-allocated list
52
- // as opposed to a method call.
53
- #define PM_LIST_EMPTY ((pm_list_t) { .size = 0, .head = NULL, .tail = NULL })
54
-
55
- // Returns true if the given list is empty.
66
+ /**
67
+ * Returns true if the given list is empty.
68
+ *
69
+ * @param list The list to check.
70
+ * @return True if the given list is empty, otherwise false.
71
+ */
56
72
  PRISM_EXPORTED_FUNCTION bool pm_list_empty_p(pm_list_t *list);
57
73
 
58
- // Returns the size of the list.
74
+ /**
75
+ * Returns the size of the list.
76
+ *
77
+ * @param list The list to check.
78
+ * @return The size of the list.
79
+ */
59
80
  PRISM_EXPORTED_FUNCTION size_t pm_list_size(pm_list_t *list);
60
81
 
61
- // Append a node to the given list.
82
+ /**
83
+ * Append a node to the given list.
84
+ *
85
+ * @param list The list to append to.
86
+ * @param node The node to append.
87
+ */
62
88
  void pm_list_append(pm_list_t *list, pm_list_node_t *node);
63
89
 
64
- // Deallocate the internal state of the given list.
90
+ /**
91
+ * Deallocate the internal state of the given list.
92
+ *
93
+ * @param list The list to free.
94
+ */
65
95
  PRISM_EXPORTED_FUNCTION void pm_list_free(pm_list_t *list);
66
96
 
67
97
  #endif
@@ -1,3 +1,8 @@
1
+ /**
2
+ * @file pm_memchr.h
3
+ *
4
+ * A custom memchr implementation.
5
+ */
1
6
  #ifndef PRISM_MEMCHR_H
2
7
  #define PRISM_MEMCHR_H
3
8
 
@@ -6,9 +11,19 @@
6
11
 
7
12
  #include <stddef.h>
8
13
 
9
- // We need to roll our own memchr to handle cases where the encoding changes and
10
- // we need to search for a character in a buffer that could be the trailing byte
11
- // of a multibyte character.
14
+ /**
15
+ * We need to roll our own memchr to handle cases where the encoding changes and
16
+ * we need to search for a character in a buffer that could be the trailing byte
17
+ * of a multibyte character.
18
+ *
19
+ * @param source The source string.
20
+ * @param character The character to search for.
21
+ * @param number The maximum number of bytes to search.
22
+ * @param encoding_changed Whether the encoding changed.
23
+ * @param encoding A pointer to the encoding.
24
+ * @return A pointer to the first occurrence of the character in the source
25
+ * string, or NULL if no such character exists.
26
+ */
12
27
  void * pm_memchr(const void *source, int character, size_t number, bool encoding_changed, pm_encoding_t *encoding);
13
28
 
14
29
  #endif
@@ -1,11 +1,16 @@
1
- // When compiling the syntax tree, it's necessary to know the line and column
2
- // of many nodes. This is necessary to support things like error messages,
3
- // tracepoints, etc.
4
- //
5
- // It's possible that we could store the start line, start column, end line, and
6
- // end column on every node in addition to the offsets that we already store,
7
- // but that would be quite a lot of memory overhead.
8
-
1
+ /**
2
+ * @file pm_newline_list.h
3
+ *
4
+ * A list of byte offsets of newlines in a string.
5
+ *
6
+ * When compiling the syntax tree, it's necessary to know the line and column
7
+ * of many nodes. This is necessary to support things like error messages,
8
+ * tracepoints, etc.
9
+ *
10
+ * It's possible that we could store the start line, start column, end line, and
11
+ * end column on every node in addition to the offsets that we already store,
12
+ * but that would be quite a lot of memory overhead.
13
+ */
9
14
  #ifndef PRISM_NEWLINE_LIST_H
10
15
  #define PRISM_NEWLINE_LIST_H
11
16
 
@@ -16,46 +21,84 @@
16
21
  #include <stddef.h>
17
22
  #include <stdlib.h>
18
23
 
19
- // A list of offsets of newlines in a string. The offsets are assumed to be
20
- // sorted/inserted in ascending order.
24
+ /**
25
+ * A list of offsets of newlines in a string. The offsets are assumed to be
26
+ * sorted/inserted in ascending order.
27
+ */
21
28
  typedef struct {
29
+ /** A pointer to the start of the source string. */
22
30
  const uint8_t *start;
23
31
 
24
- size_t *offsets;
32
+ /** The number of offsets in the list. */
25
33
  size_t size;
34
+
35
+ /** The capacity of the list that has been allocated. */
26
36
  size_t capacity;
27
37
 
28
- size_t last_offset;
29
- size_t last_index;
38
+ /** The list of offsets. */
39
+ size_t *offsets;
30
40
  } pm_newline_list_t;
31
41
 
32
- // A line and column in a string.
42
+ /**
43
+ * A line and column in a string.
44
+ */
33
45
  typedef struct {
46
+ /** The line number. */
34
47
  size_t line;
48
+
49
+ /** The column number. */
35
50
  size_t column;
36
51
  } pm_line_column_t;
37
52
 
38
- #define PM_NEWLINE_LIST_EMPTY ((pm_newline_list_t) { \
39
- .start = NULL, .offsets = NULL, .size = 0, .capacity = 0, .last_offset = 0, .last_index = 0 \
40
- })
41
-
42
- // Initialize a new newline list with the given capacity. Returns true if the
43
- // allocation of the offsets succeeds, otherwise returns false.
53
+ /**
54
+ * Initialize a new newline list with the given capacity. Returns true if the
55
+ * allocation of the offsets succeeds, otherwise returns false.
56
+ *
57
+ * @param list The list to initialize.
58
+ * @param start A pointer to the start of the source string.
59
+ * @param capacity The initial capacity of the list.
60
+ * @return True if the allocation of the offsets succeeds, otherwise false.
61
+ */
44
62
  bool pm_newline_list_init(pm_newline_list_t *list, const uint8_t *start, size_t capacity);
45
63
 
46
- // Append a new offset to the newline list. Returns true if the reallocation of
47
- // the offsets succeeds (if one was necessary), otherwise returns false.
64
+ /**
65
+ * Append a new offset to the newline list. Returns true if the reallocation of
66
+ * the offsets succeeds (if one was necessary), otherwise returns false.
67
+ *
68
+ * @param list The list to append to.
69
+ * @param cursor A pointer to the offset to append.
70
+ * @return True if the reallocation of the offsets succeeds (if one was
71
+ * necessary), otherwise false.
72
+ */
48
73
  bool pm_newline_list_append(pm_newline_list_t *list, const uint8_t *cursor);
49
74
 
50
- // Conditionally append a new offset to the newline list, if the value passed in is a newline.
75
+ /**
76
+ * Conditionally append a new offset to the newline list, if the value passed in
77
+ * is a newline.
78
+ *
79
+ * @param list The list to append to.
80
+ * @param cursor A pointer to the offset to append.
81
+ * @return True if the reallocation of the offsets succeeds (if one was
82
+ * necessary), otherwise false.
83
+ */
51
84
  bool pm_newline_list_check_append(pm_newline_list_t *list, const uint8_t *cursor);
52
85
 
53
- // Returns the line and column of the given offset. If the offset is not in the
54
- // list, the line and column of the closest offset less than the given offset
55
- // are returned.
86
+ /**
87
+ * Returns the line and column of the given offset. If the offset is not in the
88
+ * list, the line and column of the closest offset less than the given offset
89
+ * are returned.
90
+ *
91
+ * @param list The list to search.
92
+ * @param cursor A pointer to the offset to search for.
93
+ * @return The line and column of the given offset.
94
+ */
56
95
  pm_line_column_t pm_newline_list_line_column(const pm_newline_list_t *list, const uint8_t *cursor);
57
96
 
58
- // Free the internal memory allocated for the newline list.
97
+ /**
98
+ * Free the internal memory allocated for the newline list.
99
+ *
100
+ * @param list The list to free.
101
+ */
59
102
  void pm_newline_list_free(pm_newline_list_t *list);
60
103
 
61
104
  #endif
@@ -1,3 +1,8 @@
1
+ /**
2
+ * @file pm_state_stack.h
3
+ *
4
+ * A stack of boolean values.
5
+ */
1
6
  #ifndef PRISM_STATE_STACK_H
2
7
  #define PRISM_STATE_STACK_H
3
8
 
@@ -6,19 +11,32 @@
6
11
  #include <stdbool.h>
7
12
  #include <stdint.h>
8
13
 
9
- // A struct that represents a stack of bools.
14
+ /**
15
+ * A struct that represents a stack of boolean values.
16
+ */
10
17
  typedef uint32_t pm_state_stack_t;
11
18
 
12
- // Initializes the state stack to an empty stack.
13
- #define PM_STATE_STACK_EMPTY ((pm_state_stack_t) 0)
14
-
15
- // Pushes a value onto the stack.
19
+ /**
20
+ * Pushes a value onto the stack.
21
+ *
22
+ * @param stack The stack to push the value onto.
23
+ * @param value The value to push onto the stack.
24
+ */
16
25
  void pm_state_stack_push(pm_state_stack_t *stack, bool value);
17
26
 
18
- // Pops a value off the stack.
27
+ /**
28
+ * Pops a value off the stack.
29
+ *
30
+ * @param stack The stack to pop the value off of.
31
+ */
19
32
  void pm_state_stack_pop(pm_state_stack_t *stack);
20
33
 
21
- // Returns the value at the top of the stack.
34
+ /**
35
+ * Returns the value at the top of the stack.
36
+ *
37
+ * @param stack The stack to get the value from.
38
+ * @return The value at the top of the stack.
39
+ */
22
40
  bool pm_state_stack_p(pm_state_stack_t *stack);
23
41
 
24
42
  #endif