would $tags or $tag_stream be more useful names here? I think we discussed this at one point. seeing $processor here reads to me as if things are more complicated than they are.

$tag_stream = new WP_HTML_Tag_Processor( $content );
$tag_stream->next_tag();
$tag_stream->set_attribute( 'style', $styles );
$content = (string) $tag_stream;

not that I care how people name the instance of this class, but given that it's core code I recognize that we're setting the examples and how we do it will influence how people use it; I want our examples to be super clear. (not saying $tag_stream is universally clearer, just raising the point to discuss)

Good thinking. It's one of the reasons I wanted to have this PR opened early on so we can exercise this API in the codebase.

We still have some time to apply changes to the API or how we will promote usage. From the reader's perspective, I might prefer:

$tag_stream = new WP_HTML_Tag_Stream( $content );
$tag_stream->next();
$tag_stream->set_attribute( 'style', $styles );
$content = (string) $tag_stream;

I changed the name of the class to align with the variable. I also renamed next_tag to avoid repeating the word tag twice.

$tags is shorter, so it might be more desirable. It also feels similar to taxonomy tags, but I don't think they will be used too often together.

I also renamed next_tag to avoid repeating the word tag twice.

double-check with @adamziel. that seems like a much bigger change since it impacts the API and not only the application-side. if someone does create $p = new WP_HTML_Tag_Processor(); then they'll have $p->next()

in my original proposal I used ->find() as the query function but @adamziel had feelings about how ->next_tag() communicated forward progression through the document.

I could be fine with next(), given that we now have WP_HTML_Tag_Processor indicating what "next" is, but it does feel slightly sparser in the self-documenting way (and at the same time, repeating "tag" here doesn't feel like any real inconvenience)

It feels weird to say $tag_stream = new WP_HTML_Tag_Processor(); – I think I'd rather say something like $tags = new WP_HTML_Tag_Processor() or $tags = new WP_HTML_Tag_Stream(). The latter doesn't communicate the processing capabilities, though, so I'd go with $tags = new WP_HTML_Tag_Processor().

If we use $tags as the variable name, it makes sense to say ->next(), but if we don't, then I'd rather say ->next_tag(). Since we can only suggest these conventions but not enforce them, I feel like ->next_tag() will be more useful for the larger audience, even if a tiny bit more annoying to type.

I'm inclined to leave it as is for now. The following part doesn't look ideal:

$tags->set_attribute( 'foo', 'boo' );
$content = $tags->get_updated_html();

places like this make me appreciate the new interface.

We are in full agreement here 💯

💯 indeed