Extracting all valid Tags and attributes

gaekwad · 2017-12-11 10:52:02

Some years ago, I maintained a grid of valid Textpattern tags and their attributes. It was nicely presented in a Google Sheets document and is now, sadly, woefully out of date. It’s here if you’re interested.

The process of extracting tags and attributes was manual and involved picking through various files in the Textpattern directory structure. As winter 2017/2018 has settled in, I would like to revisit the matrix and get it updated.

My questions:

has this been done already for 4.6.2 and/or upcoming 4.7.0?
is there (or can there be) an automatic way to pull all the valid tags and attributes from Textpattern core?

Thank you in advance, and best wishes from a chilly Cornwall, UK.

jakob · 2017-12-11 11:04:05

Nice idea, Pete! I wonder, too, if this can be pulled out of the source code. Might something like pHPxref help, or does that only work for functions like this for 4.6.2 ?

I’ve also wondered if one could process the tag references on github for use with Dash or devdocs.io or something similar but self-hosted that I could run as a self-contained app using Fluid (or similar).

Bloke · 2017-12-11 11:05:38

It hasn’t been done as far as I’m aware, and it’d be damn handy because I noticed recently that a few of the tag builder attributes are wrong when I was tinkering with it. I made a note of the few I spotted but doubtless there are more.

In theory everything should be available in publish/taghandlers.php. If you look at the massive list of register() calls at the top of that file, you’ll see that most are still defined in the file itself, but some (yield, and a few if_first_* / if_last_* tags) have been migrated to their (probable) eventual resting place in vendors/Textpattern/Tag/Syntax.

There’s probably some dirty bash/awk script that could be run to follow the register() calls to read each file and extract the function names and their attributes in the lAtts() array. And if there’s a straight value instead of an array in the register() call, it’s not been migrated so the tag resides in the taghandlers.php file itself.

As a secondary step, it’d be really useful if, once the list has been compiled and spat into a suitable format for creating a cross-reference, we could run a check against the content of the functions defined in include/txp_tag.php to check the attributes in there align with the actual attributes in the tag.

Can’t think of any other neat ways to do it. PHP reflection won’t work, because the attributes are not true parameters.

gaekwad · 2017-12-11 11:07:54

There’s huge scope for adding syntax to text editors like Atom and Coda, too.

I’m a long-time user of Coda, but Atom just has the edge for me lately, especially with the solid GitHub integration, and anything that can speed up text entry with ‘approved’ syntax is worth investigating.

gaekwad · 2017-12-11 11:26:04

Bloke wrote #308241:

In theory everything should be available in publish/taghandlers.php. If you look at the massive list of register() calls at the top of that file, you’ll see that most are still defined in the file itself, but some (yield, and a few if_first_* / if_last_* tags) have been migrated to their (probable) eventual resting place in vendors/Textpattern/Tag/Syntax.

On the basis each tag has its own function (with attributes where appropriate), there are some outside of publish/taghandlers.php, too: article, article_custom, some (but not all) comment_* tags and possibly some others are stashed in textpattern/include/txp_tag.php.

Edit: formatting.

Last edited by gaekwad (2017-12-11 11:26:21)

Bloke · 2017-12-11 11:35:03

Ah yeah, there are anomalies like that too. Rats.

With regards article / article_custom I don’t think you’ve got a hope of programmatically extracting the available attributes for each, since both tags are processed by the same function, and certain attributes are just added/remove programmatically based on context. Note to self: figure out a way to make these proper tags that call one another and can be registered and implemented just like every other tag.

I thought that all comment_* tags had moved when Ruud migrated them a while ago, but I did spot one (maybe two?) the other day when I was poking around in publish/comments.php. Made a mental ToDo to figure out why these had been skipped. For now, I guess we’ll have to cover the few anomalies by hand.

You know what’d be really useful? A core function (or method in Register.php for when tags move there) or com_ plugin to read a given tag’s lAtts() and squirt out the attributes in some useful formats (JSON, XML, CSV, …) Then we could write a wrapper around it to iterate over the registered tags in taghandlers.php and dump the attribute list for each.

gaekwad · 2017-12-11 11:43:05

Bloke wrote #308248:

Ah yeah, there are anomalies like that too. Rats.

I’m assuming it’s that way for a reason and much smarter people than me can explain why. Not that I’m looking for an explanation, it was purely a “there’s stuff here, too” moment.

With regards article / article_custom I don’t think you’ve got a hope of programmatically extracting the available attributes for each, since both tags are processed by the same function, and certain attributes are just added/remove programmatically based on context.

I am happy to comb through any tags manually, I’m just aware that I end up doing Textpattern stuff to ‘warm up’ my brain sometimes and therefore not all synapses are a) firing or b) in time.

I thought that all comment_* tags had moved when Ruud migrated them a while ago, but I did spot one (maybe two?) the other day when I was poking around in publish/comments.php. Made a mental ToDo to figure out why these had been skipped.

It’s almost like there should be some kind of hub for issues to be noted down somewhere…(winky face thing here).

You know what’d be really useful? A core function (or method in Register.php for when tags move there) or com_ plugin to read a given tag’s lAtts() and squirt out the attributes in some useful formats (JSON, XML, CSV, …) Then we could write a wrapper around it to iterate over the registered tags in taghandlers.php and dump the attribute list for each.

You know, as a non-developer, I think I understood that! Great idea!

Last edited by gaekwad (2017-12-11 11:43:19)

etc · 2017-12-11 11:49:58

I wouldn’t like adding a permanent callback to lAtts(), it’s a critical function performance-wise. But in some branch we can.

Bloke · 2017-12-11 12:02:30

etc wrote #308252:

I wouldn’t like adding a permanent callback to lAtts()

Oooh, hell no! I meant something additional – probably a tiny plugin or dev tool – that we could call if needed to get a function’s attribute signature and return it. Just a dirty regex or some PHP lexer that found the given function name and grabbed the lAtts() array, then formatted the results (including defaults) in varying manners.

If we aggregated that to iterate the entire registered tag space, it’d be handy for checking the tag builder and to cross-check any documentation tasks that need to be added, as well as producing what Pete suggests as an “all-in-one” tag matrix that could even be filtered/sorted/searched if we so desired to replace (or at least regenerate) the ageing which atts are in which tag thing.

And yeah, Pete, I’ll add my mental ToDos to somewhere more public :-)

Last edited by Bloke (2017-12-11 12:05:30)

Textpattern CMS

Textpattern CMS support forum

#1 2017-12-11 10:52:02