From ff61dd05d954d97ce8732396adf705eb1cd38825 Mon Sep 17 00:00:00 2001 From: Josh Holtrop Date: Tue, 17 Feb 2026 19:24:50 -0500 Subject: [PATCH] Rename p_free_tree() to p_tree_delete() --- CHANGELOG.md | 5 +++++ UPGRADING.md | 1 + assets/parser.c.erb | 12 +++++------ assets/parser.h.erb | 4 ++-- doc/user_guide.md | 20 +++++++++---------- spec/propane_spec.rb | 2 +- .../test_named_optional_rule_component_tree.c | 6 +++--- spec/test_optional_rule_component_tree.c | 6 +++--- spec/test_start_rule_tree.c | 2 +- spec/test_starting_rules_tree.c | 6 +++--- spec/test_tree.c | 6 +++--- ...c => test_tree_delete_token_node_memory.c} | 2 +- spec/test_tree_field_aliases.c | 2 +- spec/test_tree_invalid_positions.c | 8 ++++---- spec/test_tree_node_memory_remains.c | 2 +- spec/test_tree_ps.c | 6 +++--- spec/test_tree_token_positions.c | 4 ++-- 17 files changed, 50 insertions(+), 44 deletions(-) rename spec/{test_free_tree_token_node_memory.c => test_tree_delete_token_node_memory.c} (94%) diff --git a/CHANGELOG.md b/CHANGELOG.md index f587a34..cd4dbad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,13 @@ ## v4.0.0 +### New Features + +- Add `p_context_delete()`. + ### Breaking Changes - Replace `p_context_init()` with `p_context_new()` and `p_context_delete()`. +- Renamed `p_free_tree()` to `p_tree_delete()`. ## v3.0.0 diff --git a/UPGRADING.md b/UPGRADING.md index 9bc1527..38ad368 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -8,6 +8,7 @@ -> `context`). - Add a call to `p_context_delete()` (for C or C++) after lexing/parsing to reclaim context memory. +- Rename `p_free_tree()` calls to `p_tree_delete()`. ## v3.0.0 diff --git a/assets/parser.c.erb b/assets/parser.c.erb index b58d511..87d7776 100644 --- a/assets/parser.c.erb +++ b/assets/parser.c.erb @@ -1206,7 +1206,7 @@ size_t <%= @grammar.prefix %>user_terminate_code(<%= @grammar.prefix %>context_t } <% if @grammar.tree %> -static void free_tree_node(TreeNode * node) +static void tree_delete(TreeNode * node) { if (node->is_token) { @@ -1221,7 +1221,7 @@ static void free_tree_node(TreeNode * node) { if (node->fields[i] != NULL) { - free_tree_node(node->fields[i]); + tree_delete(node->fields[i]); } } } @@ -1231,18 +1231,18 @@ static void free_tree_node(TreeNode * node) /** * Free all tree node memory. */ -void <%= @grammar.prefix %>free_tree(<%= @grammar.tree_prefix %><%= @grammar.start_rules[0] %><%= @grammar.tree_suffix %> * tree) +void <%= @grammar.prefix %>tree_delete(<%= @grammar.tree_prefix %><%= @grammar.start_rules[0] %><%= @grammar.tree_suffix %> * tree) { - free_tree_node((TreeNode *)tree); + tree_delete((TreeNode *)tree); } <% @grammar.start_rules.each_with_index do |start_rule, i| %> /** * Free all tree node memory. */ -void <%= @grammar.prefix %>free_tree_<%= start_rule %>(<%= @grammar.tree_prefix %><%= start_rule %><%= @grammar.tree_suffix %> * tree) +void <%= @grammar.prefix %>tree_delete_<%= start_rule %>(<%= @grammar.tree_prefix %><%= start_rule %><%= @grammar.tree_suffix %> * tree) { - free_tree_node((TreeNode *)tree); + tree_delete((TreeNode *)tree); } <% end %> <% end %> diff --git a/assets/parser.h.erb b/assets/parser.h.erb index 84ed024..606d0be 100644 --- a/assets/parser.h.erb +++ b/assets/parser.h.erb @@ -211,9 +211,9 @@ size_t <%= @grammar.prefix %>parse_<%= start_rule %>(<%= @grammar.prefix %>conte <% end %> <% if @grammar.tree %> -void <%= @grammar.prefix %>free_tree(<%= @grammar.tree_prefix %><%= @grammar.start_rules[0] %><%= @grammar.tree_suffix %> * tree); +void <%= @grammar.prefix %>tree_delete(<%= @grammar.tree_prefix %><%= @grammar.start_rules[0] %><%= @grammar.tree_suffix %> * tree); <% @grammar.start_rules.each_with_index do |start_rule, i| %> -void <%= @grammar.prefix %>free_tree_<%= start_rule %>(<%= @grammar.tree_prefix %><%= start_rule %><%= @grammar.tree_suffix %> * tree); +void <%= @grammar.prefix %>tree_delete_<%= start_rule %>(<%= @grammar.tree_prefix %><%= start_rule %><%= @grammar.tree_suffix %> * tree); <% end %> <% end %> diff --git a/doc/user_guide.md b/doc/user_guide.md index 421dcae..78ab874 100644 --- a/doc/user_guide.md +++ b/doc/user_guide.md @@ -391,7 +391,7 @@ assert(itemsmore.pItem.pItem.pItem.pToken1 !is null); If user lexer code block allocates memory to store in a token node's `pvalue`, the `free_token_node` grammar statement can be used to specify the name of a -function which will be called during the `p_free_tree()` call to free the memory +function which will be called during the `p_tree_delete()` call to free the memory associated with a token node. Example: @@ -808,12 +808,12 @@ start Module ModuleItem Statement Expression; ``` When multiple start rules are specified, multiple `p_parse_*()` functions, -`p_result_*()`, and `p_free_tree_*()` functions (in tree mode) are generated. -A default `p_parse()`, `p_result()`, `p_free_tree()` are generated corresponding +`p_result_*()`, and `p_tree_delete_*()` functions (in tree mode) are generated. +A default `p_parse()`, `p_result()`, `p_tree_delete()` are generated corresponding to the first start rule. Additionally, each start rule causes the generation of another version of each of these functions, for example `p_parse_Statement()`, `p_result_Statement()`, -and `p_free_tree_Statement()`. +and `p_tree_delete_Statement()`. ##> Specifying the parser module name - the `module` statement @@ -1232,26 +1232,26 @@ assert(code_point == 0x1F9E1u); assert(code_point_length == 4u); ``` -### `p_free_tree` +### `p_tree_delete` -The `p_free_tree()` function can be used to free the memory used by the tree. +The `p_tree_delete()` function can be used to free the memory used by the tree. It should be passed the same value that is returned by `p_result()`. -The `p_free_tree()` function is only available for C/C++ output targets. +The `p_tree_delete()` function is only available for C/C++ output targets. Note that if any lexer user code block allocates memory to store in a token's `pvalue`, in order to properly free this memory a `free_token_node` function should be specified in the grammar file. If specified, the `free_token_node` function will be called during the -`p_free_tree()` process to allow user code to free any memory associated with +`p_tree_delete()` process to allow user code to free any memory associated with a token node's `pvalue`. -When multiple start rules are specified, a separate `p_free_tree` function is +When multiple start rules are specified, a separate `p_tree_delete` function is generated for each which frees the tree resulting from parsing the given rule. For example, if `Statement` is specified as a start rule: ``` -p_free_tree_Statement(statement_tree); +p_tree_delete_Statement(statement_tree); ``` In this case, Propane will free a `Statement` tree structure returned by the diff --git a/spec/propane_spec.rb b/spec/propane_spec.rb index e90d554..e0cb6df 100644 --- a/spec/propane_spec.rb +++ b/spec/propane_spec.rb @@ -1504,7 +1504,7 @@ token b << Start -> a:a b:b; EOF run_propane(language: language) - compile("spec/test_free_tree_token_node_memory.#{language}", language: language) + compile("spec/test_tree_delete_token_node_memory.#{language}", language: language) results = run_test(language: language) expect(results.stderr).to eq "" expect(results.status).to eq 0 diff --git a/spec/test_named_optional_rule_component_tree.c b/spec/test_named_optional_rule_component_tree.c index 2f7fea8..371e173 100644 --- a/spec/test_named_optional_rule_component_tree.c +++ b/spec/test_named_optional_rule_component_tree.c @@ -17,7 +17,7 @@ int main() assert(start->pR == NULL); assert(start->r == NULL); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); input = "abcd"; @@ -34,7 +34,7 @@ int main() assert(start->pR == start->r); assert_eq(TOKEN_c, start->pR->pToken1->token); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); input = "bdc"; @@ -46,7 +46,7 @@ int main() assert(start->r != NULL); assert_eq(TOKEN_d, start->pR->pToken1->token); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); return 0; diff --git a/spec/test_optional_rule_component_tree.c b/spec/test_optional_rule_component_tree.c index 0b10aad..9916367 100644 --- a/spec/test_optional_rule_component_tree.c +++ b/spec/test_optional_rule_component_tree.c @@ -16,7 +16,7 @@ int main() assert(start->pR3 == NULL); assert(start->pR == NULL); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); input = "abcd"; @@ -31,7 +31,7 @@ int main() assert(start->pR == start->pR3); assert_eq(TOKEN_c, start->pR->pToken1->token); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); input = "bdc"; @@ -43,7 +43,7 @@ int main() assert(start->pR != NULL); assert_eq(TOKEN_d, start->pR->pToken1->token); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); return 0; diff --git a/spec/test_start_rule_tree.c b/spec/test_start_rule_tree.c index b33b8ab..ed1ed36 100644 --- a/spec/test_start_rule_tree.c +++ b/spec/test_start_rule_tree.c @@ -13,7 +13,7 @@ int main() assert(top->pToken != NULL); assert_eq(TOKEN_hi, top->pToken->token); - p_free_tree(top); + p_tree_delete(top); p_context_delete(context); return 0; diff --git a/spec/test_starting_rules_tree.c b/spec/test_starting_rules_tree.c index ed739c6..a6967ca 100644 --- a/spec/test_starting_rules_tree.c +++ b/spec/test_starting_rules_tree.c @@ -15,7 +15,7 @@ int main() assert_not_null(start->bs->bs->b); assert_not_null(start->bs->bs->bs->b); assert_not_null(start->bs->bs->bs->bs->b); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); context = p_context_new((uint8_t const *)input, strlen(input)); @@ -25,7 +25,7 @@ int main() assert_not_null(bs->bs->b); assert_not_null(bs->bs->bs->b); assert_not_null(bs->bs->bs->bs->b); - p_free_tree_Bs(bs); + p_tree_delete_Bs(bs); p_context_delete(context); input = "c"; @@ -33,7 +33,7 @@ int main() assert(p_parse_R(context) == P_SUCCESS); R * r = p_result_R(context); assert_not_null(r->c); - p_free_tree_R(r); + p_tree_delete_R(r); p_context_delete(context); return 0; diff --git a/spec/test_tree.c b/spec/test_tree.c index 42d2bc5..d5a50fc 100644 --- a/spec/test_tree.c +++ b/spec/test_tree.c @@ -33,7 +33,7 @@ int main() assert_eq(22, itemsmore->pItem->pToken1->pvalue); assert(itemsmore->pItemsMore == NULL); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); input = ""; @@ -42,7 +42,7 @@ int main() start = p_result(context); assert(start->pItems == NULL); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); input = "2 1"; @@ -57,7 +57,7 @@ int main() assert(start->pItems->pItem->pDual->pTwo2 == NULL); assert(start->pItems->pItem->pDual->pOne1 == NULL); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); return 0; diff --git a/spec/test_free_tree_token_node_memory.c b/spec/test_tree_delete_token_node_memory.c similarity index 94% rename from spec/test_free_tree_token_node_memory.c rename to spec/test_tree_delete_token_node_memory.c index f973ea7..338c257 100644 --- a/spec/test_free_tree_token_node_memory.c +++ b/spec/test_tree_delete_token_node_memory.c @@ -15,6 +15,6 @@ int main() assert(start->b != NULL); assert(*start->b->pvalue == 2); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); } diff --git a/spec/test_tree_field_aliases.c b/spec/test_tree_field_aliases.c index 2aec19e..a5e975e 100644 --- a/spec/test_tree_field_aliases.c +++ b/spec/test_tree_field_aliases.c @@ -15,7 +15,7 @@ int main() assert_eq(TOKEN_b, start->second->pToken->token); assert_eq(TOKEN_c, start->third->pToken->token); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); return 0; diff --git a/spec/test_tree_invalid_positions.c b/spec/test_tree_invalid_positions.c index ba268ce..e3216b7 100644 --- a/spec/test_tree_invalid_positions.c +++ b/spec/test_tree_invalid_positions.c @@ -30,7 +30,7 @@ int main() assert_eq(3, start->end_position.row); assert_eq(8, start->end_position.col); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); input = "a\nbb"; @@ -57,7 +57,7 @@ int main() assert_eq(2, start->end_position.row); assert_eq(2, start->end_position.col); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); input = "a\nc\nc"; @@ -84,7 +84,7 @@ int main() assert_eq(3, start->end_position.row); assert_eq(1, start->end_position.col); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); input = "a"; @@ -107,7 +107,7 @@ int main() assert_eq(1, start->end_position.row); assert_eq(1, start->end_position.col); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); return 0; diff --git a/spec/test_tree_node_memory_remains.c b/spec/test_tree_node_memory_remains.c index 65d16b3..815b61f 100644 --- a/spec/test_tree_node_memory_remains.c +++ b/spec/test_tree_node_memory_remains.c @@ -412,7 +412,7 @@ int main(int argc, char * argv[]) } free(pfds); - p_free_tree(pmod); + p_tree_delete(pmod); p_context_delete(context); return 0; diff --git a/spec/test_tree_ps.c b/spec/test_tree_ps.c index 09c966d..c985eda 100644 --- a/spec/test_tree_ps.c +++ b/spec/test_tree_ps.c @@ -33,7 +33,7 @@ int main() assert_eq(22, itemsmore->pItem->pToken1->pvalue); assert(itemsmore->pItemsMore == NULL); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); input = ""; @@ -42,7 +42,7 @@ int main() start = p_result(context); assert(start->pItems == NULL); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); input = "2 1"; @@ -57,7 +57,7 @@ int main() assert(start->pItems->pItem->pDual->pTwo2 == NULL); assert(start->pItems->pItem->pDual->pOne1 == NULL); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); return 0; diff --git a/spec/test_tree_token_positions.c b/spec/test_tree_token_positions.c index aaa6aec..c276ad9 100644 --- a/spec/test_tree_token_positions.c +++ b/spec/test_tree_token_positions.c @@ -43,7 +43,7 @@ int main() assert_eq(1, start->end_position.row); assert_eq(6, start->end_position.col); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); input = "\n\n bb\nc\ncc\n\n a"; @@ -83,7 +83,7 @@ int main() assert_eq(7, start->end_position.row); assert_eq(6, start->end_position.col); - p_free_tree(start); + p_tree_delete(start); p_context_delete(context); return 0;