From c30090c48302795e3d10ed6e587d408841136d2d Mon Sep 17 00:00:00 2001 From: Allen Webster Date: Tue, 30 Mar 2021 19:02:00 -0700 Subject: [PATCH] [docs] documentation of MD_Node --- docs/md_docs.md | 31 +++++++++++++++++++++++++------ source/md.h | 8 +++++--- source/md_impl.c | 14 +++++++------- 3 files changed, 37 insertions(+), 16 deletions(-) diff --git a/docs/md_docs.md b/docs/md_docs.md index 7dc28c9..97c8388 100644 --- a/docs/md_docs.md +++ b/docs/md_docs.md @@ -139,41 +139,60 @@ CharLiteral, }; -@doc("") +@doc("Controls matching rules in routines that compare MD_Node trees") @prefix(MD_NodeMatchFlag) @base_type(MD_u32) @flags MD_NodeMatchFlags: { + @doc("When this flag is set, differences in the order and names of tags on a node count as differences in the input nodes. Without this flag tags are ignored in tree comparisons.") Tags, + + @doc("When this flag is set in addition to MD_NodeMatchFlag_Tags, the differences in the arguments of each tag (the tag's children in the tree) are count as differences in the input nodes. Tag arguments are compared with fully recursive compares, whether or not the compare routine would be recursive or not.") TagArguments, }; +@doc("The main 'lego-brick' for modeling the result of a metadesk parse. Also used in some auxiliary data structures.") @struct MD_Node: { + @doc("The next sibling in the hierarchy, or the next tag in a list of tags, or next node in an externally chained linked list.") next: *MD_Node, + @doc("The previous sibling in the hierarchy, or the previous tag in a list of tags, or previous node in an externally chained linked list.") prev: *MD_Node, + @doc("The parent in the hierarchy, or root node of an externally chained linked list.") parent: *MD_Node, + @doc("The first child in the hierarchy, or the first node in an externally chained linked list.") first_child: *MD_Node, + @doc("The last child in the hierarchy, or the last node in an externally chained linked list.") last_child: *MD_Node, - // Tag list. + @doc("The first tag attached to a node.") first_tag: *MD_Node, + @doc("The last tag attached to a node.") last_tag: *MD_Node, - // Node info. + @doc("Indicates the role that the node plays in metadesk node graph.") kind: MD_NodeKind, + @doc("Extra information about the source that generated this node in the parse.") flags: MD_NodeFlags, + @doc("The string of the token labeling this node, after processing. Processing removing quote marks that delimits string literals and character literals") string: MD_String8, + @doc("The raw string of the token labeling this node.") whole_string: MD_String8, + @doc("A hash of the string field using the metadesk built in hash function.") string_hash: MD_u64, - ref_target: *MD_Node, - // Comments. + @doc("The raw string of the comment token before this node, if there is one.") comment_before: MD_String8, + @doc("The raw string of the comment token after this node, if there is one.") comment_after: MD_String8, - // Source code location information. + @doc("The name of the file from which this node was parsed; or the name that was passed to the parse call.") filename: MD_String8, + @doc("The pointer to the base of the raw string from which this node was parsed.") file_contents: *MD_u8, + @doc("A pointer into the raw string from which this was parsed indicating the beginning of the text that generated this node.") at: *MD_u8, + + @doc("The external pointer from an MD_NodeKind_Reference kind node in an externally linked list.") + ref_target: *MD_Node, }; //////////////////////////////// diff --git a/source/md.h b/source/md.h index dd92218..3a597aa 100644 --- a/source/md.h +++ b/source/md.h @@ -356,7 +356,6 @@ struct MD_Node MD_String8 string; MD_String8 whole_string; MD_u64 string_hash; - MD_Node *ref_target; // Comments. MD_String8 comment_before; @@ -366,6 +365,9 @@ struct MD_Node MD_String8 filename; MD_u8 *file_contents; MD_u8 *at; + + // Reference. + MD_Node *ref_target; }; //~ Code Location Info. @@ -749,8 +751,8 @@ MD_FUNCTION MD_Node * MD_Deref(MD_Node *node); // NOTE(rjf): For-Loop Helpers #define MD_EachNode(it, first) MD_Node *it = (first); !MD_NodeIsNil(it); it = it->next #define MD_EachNodeRef(it, first) MD_Node *it##_r = (first), *it = MD_Deref(it##_r); \ - !MD_NodeIsNil(it##_r); \ - it##_r = it##_r->next, it = MD_Deref(it##_r) +!MD_NodeIsNil(it##_r); \ +it##_r = it##_r->next, it = MD_Deref(it##_r) //~ Error/Warning Helpers MD_FUNCTION void MD_NodeMessage(MD_Node *node, MD_MessageKind kind, MD_String8 str); diff --git a/source/md_impl.c b/source/md_impl.c index f8568b5..3cc7d3d 100644 --- a/source/md_impl.c +++ b/source/md_impl.c @@ -2213,13 +2213,13 @@ MD_PushTag(MD_Node *node, MD_Node *tag) } MD_FUNCTION_IMPL MD_b32 -MD_NodeMatch(MD_Node *a, MD_Node *b, MD_StringMatchFlags str_flags, MD_NodeMatchFlags node_flags) +MD_NodeMatch(MD_Node *a, MD_Node *b, MD_StringMatchFlags str_flags, MD_NodeMatchFlags match_flags) { MD_b32 result = 0; if(a->kind == b->kind && MD_StringMatch(a->string, b->string, str_flags)) { result = 1; - if(a->kind != MD_NodeKind_Tag && node_flags & MD_NodeMatchFlag_Tags) + if(a->kind != MD_NodeKind_Tag && (match_flags & MD_NodeMatchFlag_Tags)) { for(MD_Node *a_tag = a->first_tag, *b_tag = b->first_tag; !MD_NodeIsNil(a_tag) || !MD_NodeIsNil(b_tag); @@ -2227,13 +2227,13 @@ MD_NodeMatch(MD_Node *a, MD_Node *b, MD_StringMatchFlags str_flags, MD_NodeMatch { if(MD_NodeMatch(a_tag, b_tag, str_flags, 0)) { - if(node_flags & MD_NodeMatchFlag_TagArguments) + if(match_flags & MD_NodeMatchFlag_TagArguments) { for(MD_Node *a_tag_arg = a_tag->first_child, *b_tag_arg = b_tag->first_child; !MD_NodeIsNil(a_tag_arg) || !MD_NodeIsNil(b_tag_arg); a_tag_arg = a_tag_arg->next, b_tag_arg = b_tag_arg->next) { - if(!MD_NodeDeepMatch(a_tag_arg, b_tag_arg, str_flags, node_flags)) + if(!MD_NodeDeepMatch(a_tag_arg, b_tag_arg, str_flags, match_flags)) { result = 0; goto end; @@ -2254,16 +2254,16 @@ MD_NodeMatch(MD_Node *a, MD_Node *b, MD_StringMatchFlags str_flags, MD_NodeMatch } MD_FUNCTION_IMPL MD_b32 -MD_NodeDeepMatch(MD_Node *a, MD_Node *b, MD_StringMatchFlags str_flags, MD_NodeMatchFlags node_flags) +MD_NodeDeepMatch(MD_Node *a, MD_Node *b, MD_StringMatchFlags str_flags, MD_NodeMatchFlags match_flags) { - MD_b32 result = MD_NodeMatch(a, b, str_flags, node_flags); + MD_b32 result = MD_NodeMatch(a, b, str_flags, match_flags); if(result) { for(MD_Node *a_child = a->first_child, *b_child = b->first_child; !MD_NodeIsNil(a_child) || !MD_NodeIsNil(b_child); a_child = a_child->next, b_child = b_child->next) { - if(!MD_NodeDeepMatch(a_child, b_child, str_flags, node_flags)) + if(!MD_NodeDeepMatch(a_child, b_child, str_flags, match_flags)) { result = 0; goto end;