Clean up and document syntax tree child access API + mark public API#484
Clean up and document syntax tree child access API + mark public API#484
Conversation
c42f
force-pushed
the
caf/tree-API-cleanup
branch
2 times, most recently
from
6cd1b85 to
57c8c3c
Compare
timholy
left a comment
timholy
left a comment
There was a problem hiding this comment.
This looks good. I think TypedSyntax's tests do exploit multidimensional child, but that's an easy change. I presume this will become 0.5.0?
We need to get to 1.0 so we can use semver properly. So the next release will be 1.0.0 :-) I've been working really hard on a lot of 1.0.0 changes in the last few weeks, trying to get the documentation and APIs in better shape. See also #472, but I keep finding more to do - it turns out there's a lot of changes I want to squeeze in which are informed by the JuliaLowering work. |
We could keep |
c42f
force-pushed
the
caf/tree-API-cleanup
branch
from
bca9487 to
5aa4740
Compare
|
Either way is fine; it's not such a hard change to make to TypedSyntax's tests. A regex search suggests there are 74 uses of |
Here I commit to a more consistent but simpler child access API for syntax trees, as informed by the JuliaLowering work so far: * `is_leaf(node)` is given a precise definition (previously `!haschildren()` - but that had issues - see #483) * `children(node)` returns the child list, or `nothing` if there are no children. The `nothing` might be seen as inconvenient, but mapping across the children of a leaf node is probably an error and one should probably branch on `is_leaf` first. * `numchildren(node)` is documented * `node[i]`, `node[i:j]` are documented to index into the child list We distinguish `GreenNode` and its implementation of `span` from `SyntaxNode` and its implementation of `byte_range` and `sourcetext` - these seem to just have very different APIs, at least as of now. I've deleted the questionable overloads of multidimensional `getindex` and the `child` function in favor of single dimensional getindex. I don't know whether anyone ever ended up using these. But I didn't and they didn't seem useful+consistent enough to keep the complexity. I've kept setindex! for now, to set a child of a `SyntaxNode`. Though I'm not sure this is a good idea to support by default.
c42f
force-pushed
the
caf/tree-API-cleanup
branch
from
5aa4740 to
b644c87
Compare
|
Ok thanks! Let's go with the more minimal API then :) |
…ee-API-cleanup Clean up and document syntax tree child access API + mark public API
…ee-API-cleanup Clean up and document syntax tree child access API + mark public API
2 participants
Here I commit to a more consistent but simpler child access API for syntax trees, as informed by the JuliaLowering work so far:
is_leaf(node)is given a precise definition (previously!haschildren()- but that had issues - see Renamehaschildren()tois_leaf()#483)children(node)returns the child list, ornothingif there are no children. Thenothingmight be seen as inconvenient, but mapping across the children of a leaf node is probably an error and one should probably branch onis_leaffirst.numchildren(node)is documentednode[i],node[i:j]are documented to index into the child listWe distinguish
GreenNodeand its implementation ofspanfromSyntaxNodeand its implementation ofbyte_rangeandsourcetext- these seem to just have very different APIs, at least as of now.I've deleted the questionable overloads of multidimensional
getindexand thechildfunction in favor of single dimensional getindex. I don't know whether anyone ever ended up using these. But I didn't and they didn't seem useful+consistent enough to keep the complexity.I've kept setindex! for now, to set a child of a
SyntaxNode. Though I'm not sure this is a good idea to support by default and I didn't mark it public yet.Also I've added more docs!
Also mark the public parts of the API as
publicin Julia 1.11+