Add: {not-}done option for :todo selector

[Walheimat]

This is in reference to #267.

Users can now set :todo {not-}done to match to-do keywords that are part of org-{not-}done-keywords in that agenda item.

This means that when using "TODO | ACHIEVED" in one item but "TODO | DONE" in another, :todo done will match both "ACHIEVED" and "DONE".

Notes

When I run ./makem.sh test I get errors with and without my changes and I'm not quite sure how to write a test for this new feature. But I'd first like to know if this is going in the right direction in your opinion.

[alphapapa]

Hi Krister,

Thanks for working on this. I don't necessarily dislike the :todo done/:todo not-done API, but since Org QL already provides similar functionality, and since I intend for them to be interoperable to some extent, I think I'd prefer to follow its API more closely. So, e.g. since Org QL provides this via (todo) for not-done items, and (done) for done ones, I'd suggest that in org-super-agenda we add a new :done selector that mirrors the :todo selector but only matching done keywords.

Then we might need to consider making the :todo selector only match not-done keywords (but that could be a breaking change, so it'd have to be considered carefully).

What do you think?

[Walheimat]

Thanks for taking a look.

So you'd express "not done" then with :done nil? I think having a new selector could also be nice, and maybe make it easier to extend that with something like :done today or :done past (although I'm not sure you can even get agenda items that are done in the past to show up in the first place, but I'm no expert).

I did take a look at org-ql but I couldn't easily find what I'd take from there implementation-wise (but maybe you just meant the semantics?). It seemed to me that using the existing macro to be in the context of the item's buffer and (cl-member (org-find-text-property-in-string 'todo-state item) org-done-keywords :test 'string=) was sufficient for our purposes. If you'd like a change there I'd have to dig a bit deeper.

[alphapapa]

Thanks for taking a look.

So you'd express "not done" then with :done nil?

No, with :todo t. This should be explained in the documentation.

I think having a new selector could also be nice, and maybe make it easier to extend that with something like :done today or :done past

That's a nice idea too.

(although I'm not sure you can even get agenda items that are done in the past to show up in the first place, but I'm no expert).

You can do pretty much whatever you want. Note that there's no such thing as an "agenda item". Org headings represent "entries," and those entries can be searched with org-agenda or org-ql and then shown in an "Agenda buffer" or an org-ql-view buffer. (Forgive any pedantry, but using "correct" terminology helps understand how the pieces work together.)

I did take a look at org-ql but I couldn't easily find what I'd take from there implementation-wise (but maybe you just meant the semantics?). It seemed to me that using the existing macro to be in the context of the item's buffer and (cl-member (org-find-text-property-in-string 'todo-state item) org-done-keywords :test 'string=) was sufficient for our purposes. If you'd like a change there I'd have to dig a bit deeper.

Please see https://github.com/alphapapa/org-ql/blob/b6f8a315e966123fbfd1ac240d35da5c2b48d6ac/org-ql.el#L2077 and https://github.com/alphapapa/org-ql/blob/b6f8a315e966123fbfd1ac240d35da5c2b48d6ac/org-ql.el#L1386 for what I basically mean. org-super-agenda doesn't work exactly the same way, so some reference to org-super-agenda code will be necessary also. I mean that the org-super-agenda user API should be close to the org-ql one, i.e. since org-ql uses (done), org-super-agenda should use :done.