[RFC] Sloppy `org-element-context'?

[Nicolas Goaziou <n.goaziou@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 2458 bytes --]

Hello,

As you may know, `org-element-context' returns the object under point,
according to Org Syntax. The questions are: should it be a little
sloppy, for convenience? And, if it should, what degree of sloppiness is
acceptable?

Note that, at the time being, the function is already somewhat sloppy,
because it will return an object right before point. In the following
example, "|" is point. Even though it is not on the bold object,
evaluating (org-element-context) there will give:

  "*bold*| text"  =>  (bold ...)

Should we go further? A recent discussion about opening links in node
properties suggests that some users expect to encounter Org syntax
there. I believe this is not generally desirable.

One reason is that contents of properties drawers are hidden most of the
time, and we may forget about them. So, for example, an entry could
appear in the agenda but the timestamp triggering it could be difficult
to find. This is why SCHEDULED and DEADLINE keywords were not turned
into node properties: they are always in sight.

Another reason is that properties can contain really anything, including
markup from other languages. For example, EXPORT_LATEX_HEADER property
contains LaTeX code. As such, they should be kept as general as
possible, that is as a pair of key and value, without any syntax
attached to value, much like keywords.

However, it is possible to still parse value of such properties, as
a convenience feature in `org-element-context', as the attached patch
does. Note that it has drawbacks. Let's consider the following idiomatic
example, meant to do something on every active timestamp below point in
the visible part of the buffer,

  (while (re-search-forward "<[0-9]\\{4\\}-" nil t)
    (let ((context (org-element-context)))
      (when (eq (org-element-type context) 'timestamp)
        ...)))

Used without care, it will be applied to non-existing timestamps (e.g.,
timestamps in a node property) and could lead to confusing behaviour,
like displaying an entry in the agenda because of an invisible
timestamp.

Anyway, here we are. I think it is important to define clearly what
belongs to the syntax (I think it is quite good at the moment), what can
be allowed for the sake of convenience, and what line should never be
crossed (I firmly believe, for example, that `org-element-context'
should never return objects in a comment, an example block, or
a fixed-width area).

Opinions?


Regards,

-- 
Nicolas Goaziou

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-element-Make-org-element-context-sloppy.patch --]
[-- Type: text/x-diff, Size: 2531 bytes --]

From ab72802ab90950d8edc2d415443f089a1208f5cc Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <n.goaziou@gmail.com>
Date: Thu, 27 Mar 2014 15:12:05 +0100
Subject: [PATCH] org-element: Make `org-element-context' sloppy

* lisp/org-element.el (org-element-context): Allow to parse node
  properties.
---
 lisp/org-element.el | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/lisp/org-element.el b/lisp/org-element.el
index d94243b..a774528 100644
--- a/lisp/org-element.el
+++ b/lisp/org-element.el
@@ -5598,7 +5598,9 @@ object type, but always include `:begin', `:end', `:parent' and
 `:post-blank'.
 
 As a special case, if point is right after an object and not at
-the beginning of any other object, return that object.
+the beginning of any other object, return that object.  Also,
+parse Org syntax and return objects in planning lines and node
+properties, for convenience.
 
 Optional argument ELEMENT, when non-nil, is the closest element
 containing point, as returned by `org-element-at-point'.
@@ -5668,8 +5670,12 @@ Providing it allows for quicker computation."
 	   (if (and (>= pos (point)) (< pos (line-end-position)))
 	       (narrow-to-region (point) (line-end-position))
 	     (throw 'objects-forbidden element))))
-	;; At a planning line, if point is at a timestamp, return it,
-	;; otherwise, return element.
+	;; Convenience features.
+	;;
+	;; - At a planning line, if point is at a timestamp, return
+	;;   it, otherwise, return element.
+	;;
+	;; - Return objects in node properties values.
 	((eq type 'planning)
 	 (dolist (p '(:closed :deadline :scheduled))
 	   (let ((timestamp (org-element-property p element)))
@@ -5677,8 +5683,16 @@ Providing it allows for quicker computation."
 			(<= (org-element-property :begin timestamp) pos)
 			(> (org-element-property :end timestamp) pos))
 	       (throw 'objects-forbidden timestamp))))
-	 ;; All other locations cannot contain objects: bail out.
 	 (throw 'objects-forbidden element))
+	((eq type 'node-property)
+	 (beginning-of-line)
+	 (search-forward ":" (line-end-position) t 2)
+	 (skip-chars-forward " \t")
+	 (if (> (point) pos) (throw 'objects-forbidden element)
+	   (narrow-to-region (point) (line-end-position))
+	   ;; Do not limit object types in a node property.
+	   (setq type 'paragraph)))
+	;; All other locations cannot contain objects: bail out.
 	(t (throw 'objects-forbidden element)))
        (goto-char (point-min))
        (let ((restriction (org-element-restriction type))
-- 
1.9.1