Re: Should "org-element-parse-buffer" check whether the buffer's major mode is org mode?

[Ihor Radchenko]

Antonio Romano <n58r@pm.me> writes:

> What I did was simply parse out a buffer, change all headlines's TODO
> keyword in its AST to "DONE", interpret the resulting AST and finally
> print out the resulting document to a new buffer. The issue I had
> encountered was that an headline like "* TODO Hello" would wrongly
> become "* DONE TODO Hello" instead of "* DONE Hello".

That might happen, yes. The behavior in non-Org buffers is currently
undefined. Sometimes, you may also get errors.

> A kind user pointed out that the issue was that I called "org-element-
> parse-buffer" in a fundamental-mode buffer and, in fact, turning on
> org-mode beforehand solved the issue. As the user suggested, I'm here
> to ask you if this is the intended behavior or if it would be better
> limiting the usage of the function to org-mode (and derived) buffers
> only. Thank you in advance.

If you look into the docstring, it says

    ...
    This function assumes that current major mode is `org-mode'.

Should we complain when current buffer is not in Org mode? It is not
easy to answer. In Org 9.7 (before the release), we modified
`org-element-at-point' to do exactly this - complain when current major
mode is not Org mode. Soon, a number of people reported that
`org-element-at-point' is, in fact, misused by a number of packages and
does get called in non-Org buffers. At the end, I had to change
`org-element-at-point' to throw a warning rather than an error as some
packages simply _rely_ upon such misuse.

The current tentative plan for this is the following:

1. Slowly update the parser so that using it in non-Org buffers becomes
   less unreliable. (It mostly involves computing some variables that
   Org mode normally initializes dynamically)

2. Allow the parser to be used on arbitrary text.


So, you should be able to use `org-element-parse-buffer' in non-Org
buffers in the long run. For now, a note in the docstring is what we
have. I may also add a warning, but I am not sure - a number of people
are confused enough by the warning from `org-element-at-point' (caused
by packages abusing it in non-Org buffers); to the point that I am
thinking to remove it as well.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>