feat: allow to define multiple todo keyword sequences

[seflue]

They can be defined in the config or within an org file.

Summary

This PR adds the ability to define multiple todo keyword sets as described in Orgmode manual.

Related Issues

Relates to #250, #157, PR #956

Closes #250

Changes

• additionally to a single keyword sequence org_todo_keywords allows to define a table of keyword sets
• an org file can have multiple #+TODO: directives
• if multiple keyword sets are defined, either in the config or in the current org file, org_todo keymap triggers fast access mode to select a keyword
• org_todo_prev behaves like S-RIGHT in Emacs Orgmode

Falling back to fast access mode when multiple sets are defined is a bit of a shortcut to get a first version of this feature out of the door. Emacs Orgmode defines some additional keybindings to switch between keyword sets. This is a bit more elaborated and could be implemented in a further PR.

Checklist

I confirm that I have:

• Followed the
  Conventional Commits
  specification (e.g., feat: add new feature, fix: correct bug,
  docs: update documentation).
• My PR title also follows the conventional commits specification.
• Updated relevant documentation, if necessary.
• Thoroughly tested my changes.
• Added tests (if applicable) and verified existing tests pass with
  make test.
• Checked for breaking changes and documented them, if any.

[seflue]

@kristijanhusak It seems, that the indentation test is a bit flaky (those are the both failing test). It also failed occasionally locally on my machine, but that is unrelated to my changes.

[kristijanhusak]

I left few comments around the code, some around code styling changes (mostly around avoiding else when there's early return), and some comments around the logic.

I think we should approach this in a slightly different , and potentially simpler way:

1. Always store the todo keywords as sequences. You already did that here more-less, but there's no need have a separate logic like parse_single_sequence or parse_multiple_sequence. When TodoKeywords get's org_todo_keywords value, just check if it's a string[] or string[][]. If it's former, just convert it to string[][] and handle it accordingly.
2. Instead of keeping the sequence index on the TodoKeyword, and sequences on the TodoKeywords, we can just search things on the fly. These things are used only when mutating the document, so it's not that necessary to do these optimizations. Lua is fast enough to handle this, and I doubt users have a lot of todo sequences.

Another approach could be to keep the TodoKeywords as they are, which is basically as single sequence, and have a layer above that will know to figure out which of the sequence we need at the given point, and just return it and use it where necessary.
This might complicate some other things so it might not be the best idea, but I wanted to point it out.

Let me know what you think.

[kristijanhusak]

We can just return directly here, method returns void anyway. Same for the if below.

Suggested change

	self:_parse_single_sequence(self.org_todo_keywords)
	return
	return self:_parse_single_sequence(self.org_todo_keywords)

[kristijanhusak]

There's no need for else block when if block returns. It removes one level of indentation.

[kristijanhusak]

Having multiple sequences doesn't necessarily mean we use fast access. When there is no fast access defined in the config of the todo keywords, Emacs just cycles through the sequence it figured out that is being used.

There's a catch though. Emacs somehow keeps in memory which was the last sequence used. For example, if you have these keywords:

(setq org-todo-keywords
      '((sequence "TODO" "|" "DONE")
        (sequence "REPORT" "BUG" "TESTING" "|" "FIXED")))

And you have a headline with * REPORT foo, cycling without the fast access will go REPORT -> BUG -> TESTING -> FIXED -> {EMPTY} -> REPORT -> etc.. So it keeps in memory that the last sequence is 2nd one. Now, if you switch to an empty headline without todo keyword, restart emacs, and try switching the todo state, it will use the first sequence. So it's only in memory while the emacs is open.

I'm not sure what's the best way to access that issue, but I wanted to bring it up in case you have some ideas.

[seflue]

@kristijanhusak Thanks for the feedback! I've implemented most of your suggestions:

Simplified parsing and code style:

• Always store todo keywords as sequences (string[][]) - normalized in constructor
• Removed separate parsing methods, single unified _parse() path
• Fixed unnecessary else blocks after early returns
• Cleaned up TodoState constructor

Regarding the sequence index approach:
I'd prefer to keep the current approach here. The sequence_index isn't just for performance - it's needed for proper cycling behavior. According to the Emacs orgmode manual, C-c C-t should cycle only within the current sequence. So a TODO in:

["TODO", "|", "DONE"]

cycles TODO → DONE → empty → TODO, while a REPORT in:

["REPORT", "BUG", "|", "FIXED"]

stays within that sequence.

Without sequence_index, we can't determine which sequence a keyword belongs to, especially when keywords are duplicated across sequences (like having "TODO" in both bug and feature workflows).

The next step would be implementing proper cycling behavior instead of jumping to fast access mode in a separate PR, which is where this becomes important.

What do you think?

[kristijanhusak]

Hey @seflue , sorry for the delay! I didn't see any feedback on the PR comments and I thought you are still working on it.

Can you just answer this comment: https://github.com/nvim-orgmode/orgmode/pull/974/files#r2083571890

Regarding this:

The next step would be implementing proper cycling behavior instead of jumping to fast access mode in a separate PR, which is where this becomes important.

Just to confirm. Is this an answer to #974 (comment)?

[seflue]

Hey @kristijanhusak , yes my comment was an answer to your review. Sorry that I didn't directly react to your code comments, it was a small amount of time I had to continue on this PR. I was pretty busy lately and still am, so I am not sure when I will find the time to continue on the multilevel cycling. Do you think, we can already merge this as a first step?
Sure, users currently need to define unambiguous shorthands for their keywords, if they want to use the feature (I actually do), on the other hand it does not break anything, users can still use the original cycling workflow if they define only one sequence.

[kristijanhusak]

Yes, I will give it a final test and it's probably good to go, but I want to reduce the amount of changes if possible. If we can just revert that refactoring that was done for the repeating task it should be good to go.
Are you ok with me taking over and cleaning up these things ?

[seflue]

@kristijanhusak Sorry for the long delay, I just didn't found the time to get back to this PR in the last month.

I reverted the refactoring as you requested, hopefully it is now ready to merge.

[kristijanhusak]

I think this is good to go now. I'll do some minor changes around building the TodoKeywords, but nothing major.
Next up we should remove the fast access if not declared, and document this.

Thanks for the PR and the patience!