Refactor AST utilities #1914
Refactor AST utilities #1914
Conversation
Something is definitely better than nothing. We'll likely be going the LDoc route eventually (c.f. #1337) but it will be much easier to adapt something than nothing! |
core/utilities-ast.lua
Outdated
| ---@param tree table AST tree | ||
| ---@param command string command name | ||
| ---@return table|nil AST command node | ||
| function ast.extractFromTree (tree, command) |
There was a problem hiding this comment.
I don't think "extract" is the right verb here, at least to me that implies getting a node out in isolation, but also I would have assumed it left the original tree alone. This removes it from the tree, so "slice" or perhaps "extricate" might be a better name that suggests the original is being removed.
There was a problem hiding this comment.
maybe simply removeFromTree (and the @return becomes "Removed AST command node") ?
|
By the way @alerque I was about to ask whether we should actually split utilities in subfolders (rather than Would that be ok if we go on splitting the utilities in subfolders? Currently we still have in the main file:
Perhaps starting to split them would allow us to properly group them by "nature" and document them progressively? |
That could be another issue addressed later, obviously, just asking here as it sounds quite logical. |
Yes. Smaller files/modules with tighter scopes are almost always better for Lua in my opinion. |
BREAKING CHANGE: For modules that rely on `SILE.utilities` (`SU`), and in particular raw content handling functions `subContent()`, `walkContent()`, `stripContentPos()`, `hasContent()`, and `contentToString()`, these and similar functions have been moved into `SILE.utilities.ast` (`SU.ast`). The `subContent()` implementation also no longer adds id="stuff" attributes to everything.
alerque
force-pushed
the
refactor-ast-utilities-develop
branch
from
af91cd2 to
06d9ea4
Compare
|
P.S. I'm also seriously scratching my head why we have "core" and "utilities". It seems to me the way our source organization is sorting out almost everything in "core" is just utilities. Basically anything that is just a function as opposed to a class than gets instantiated and maintains some sort of state as SILE runs. |
The line is blurry, indeed.
So there could be some different levels of concern and design here ;-) |
Proposal, motivated by #1866
SU.astSILE.processetc.), having some convenience function to manipulate is good -- and a must-have for inputter and package designers. The existing utilities were however scattered (some at the root ofSU, one as an inputter method, another in the inputfilter package, etc.)...SU, a better organization makes maintenance of similar functions easier and is the path for curating those utilities progressively. Later, we might at a glance easily check these if we ever want to change the AST (add new constructs, make it more object-oriented, etc.)SU.ast.extractFromTree- complementsSU.ast.findInTreeSU.ast.createCommand- as in inputfilter, but in inputters etc. this is convenient (and we might not even have loaded any package yet, there, by nature)SU.ast.createStructuredCommand- convenience when passing an array of nodes (avoiding useless nesting)SU.ast.trimSubContentandSU.ast.processAsStructure- fairly useful esp. in XML parsing context, when the schema defines structured elements where text/spaces aren't expected (unless due do indentation, but to be ignored in the ouput).SU.ast.subContentis simplified and no longer includes a weirdid=stuffentry - discussed in Functional coding vs. AST munching in commands: a design issue and many questions #1834 (items B1 and B2)