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

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

[Antonio Romano]

Hi all,

yesterday I've sent a question on Emacs StackExchange 
(https://emacs.stackexchange.com/questions/82063) where I described a
small issue I had encountered while using Org Element API. 

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".

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.

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>

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

[Antonio Romano]

Ouch, that part of the docstring totally slipped my eye. 

The situation is a bit more complex than I imagined and am not
experienced enough to have a strong opinion on the matter. If things
are to stay as they are right now, I guess emphasizing even more in the
docstring that this function may have undefined behavior in different
modes can only do good. 

Thank you for clarifying.