[FR] Support headline as a function for file+headline target for org-capture-templates

[FR] Support headline as a function for file+headline target for org-capture-templates

[Nafiz Islam]

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

Right now, only the file name supports being either a string, symbol or
function, etc. Nonetheless, it would be nice if headline could be a
function that takes in as parameter a list of all headlines present in the
file so that we can dynamically pick a headline under which we want to add
an entry.  The function can also return a string to represent a
(potentially) new headline to insert.

My use case for that is I have an org file in which each headline is a
specific time, and I want to reuse a headline that is only within 5 minutes
behind the current time.

[-- Attachment #2: Type: text/html, Size: 631 bytes --]

Re: [FR] Support headline as a function for file+headline target for org-capture-templates

[Nafiz Islam]

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

Upon closer look at the `org-capture`, `org-capture-set-target-location`
and `org-capture-place-entry`, I'm starting to realize that "file+function"
can be used for what I'm looking for. I was just worried about the use of
`(org-capture-put :exact-position (point))`

On Sun, Apr 28, 2024 at 10:58 AM Nafiz Islam <nafiz.islam1001@gmail.com>
wrote:

> Right now, only the file name supports being either a string, symbol or
> function, etc. Nonetheless, it would be nice if headline could be a
> function that takes in as parameter a list of all headlines present in the
> file so that we can dynamically pick a headline under which we want to add
> an entry.  The function can also return a string to represent a
> (potentially) new headline to insert.
>
> My use case for that is I have an org file in which each headline is a
> specific time, and I want to reuse a headline that is only within 5 minutes
> behind the current time.
>
>

[-- Attachment #2: Type: text/html, Size: 1285 bytes --]

Re: [FR] Support headline as a function for file+headline target for org-capture-templates

[Nafiz Islam]

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

> Upon closer look at the `org-capture`, `org-capture-set-target-location`
and `org-capture-place-entry`, I'm starting to realize that "file+function"
can be used for what I'm looking for. I was just worried about the use of
`(org-capture-put :exact-position (point))`

My disappointing attempt at using file+function target to replicate my idea

(defun my/diary-capture-find-headline ()
    (let* ((entries (org-map-entries (lambda ()
      (list (org-element-property :title (org-element-at-point))
    (org-element-property :begin (org-element-at-point))))
    "LEVEL=1"))
  (final-pos)
  (final-pos
   (dolist (entry entries final-pos)
     (pcase-let ((`(,title ,begin) entry))
(let* ((diff-time (time-subtract (current-time) (org-time-string-to-time
title)))
      (diff-secs (nth 1 diff-time))
      (5-mins-in-secs (* 5 60)))
 (if (< diff-secs 5-mins-in-secs)
     (setq final-pos (goto-char begin))
   final-pos))))))
      (unless final-pos
(goto-char (point-max))
(unless (bolp) (insert "\n"))
(insert "\n* ")
(let ((current-prefix-arg '(16)))
 (call-interactively #'org-time-stamp-inactive))
(beginning-of-line))))

(setopt org-capture-templates
      '(("d" "Diary Template" entry
         (file (lambda () (expand-file-name
   (concat org-directory "Diary" "/" (format-time-string "%Y-%m-%d.org")))))
         "* %U\n%?"
:empty-lines 1)
("p" "Diary Item Capture Test" item
         (file+function (lambda () (expand-file-name
   (concat org-directory "Diary" "/" (format-time-string "%Y-%m-%d.org"))))
       my/diary-capture-find-headline)
"- %?"
:empty-lines 0)))

[-- Attachment #2: Type: text/html, Size: 2286 bytes --]

Re: [FR] Support headline as a function for file+headline target for org-capture-templates

[Ihor Radchenko]

Nafiz Islam <nafiz.islam1001@gmail.com> writes:

>> Upon closer look at the `org-capture`, `org-capture-set-target-location`
> and `org-capture-place-entry`, I'm starting to realize that "file+function"
> can be used for what I'm looking for. I was just worried about the use of
> `(org-capture-put :exact-position (point))`
>
> My disappointing attempt at using file+function target to replicate my idea

What is the problem with it?

-- 
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: [FR] Support headline as a function for file+headline target for org-capture-templates

[Ihor Radchenko]

Nafiz Islam <nafiz.islam1001@gmail.com> writes:

> Upon closer look at the `org-capture`, `org-capture-set-target-location`
> and `org-capture-place-entry`, I'm starting to realize that "file+function"
> can be used for what I'm looking for.

So, there is no feature to request.
Canceled.

-- 
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: [FR] Support headline as a function for file+headline target for org-capture-templates

[Nafiz Islam]

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

The problem with my implementation is that it modifies the org file before
prompting the user for item entry. As a result, if I cancel/abort my
org-capture, that modification will still be present. I've made another
attempt which is slightly more successful using advice.

(defun my/diary-capture-advice (oldfun r)
    (let ((org-capture-templates `(("d"
   "Diary Template"
   item
   (file+headline (lambda () (expand-file-name
      (concat org-directory "Diary" "/" (format-time-string "%Y-%m-%d.org
"))))
  ,(format-time-string (org-time-stamp-format t t) (current-time)))
   "- %?"
   :empty-lines 0))))
      (call-interactively oldfun)))
(advice-add #'org-capture :around #'my/diary-capture-advice)

On Tue, Apr 30, 2024 at 8:31 AM Ihor Radchenko <yantar92@posteo.net> wrote:

> Nafiz Islam <nafiz.islam1001@gmail.com> writes:
>
> >> Upon closer look at the `org-capture`, `org-capture-set-target-location`
> > and `org-capture-place-entry`, I'm starting to realize that
> "file+function"
> > can be used for what I'm looking for. I was just worried about the use of
> > `(org-capture-put :exact-position (point))`
> >
> > My disappointing attempt at using file+function target to replicate my
> idea
>
> What is the problem with it?
>
> --
> 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>
>

[-- Attachment #2: Type: text/html, Size: 2405 bytes --]

Re: [FR] Support headline as a function for file+headline target for org-capture-templates

[Ihor Radchenko]

Nafiz Islam <nafiz.islam1001@gmail.com> writes:

> The problem with my implementation is that it modifies the org file before
> prompting the user for item entry. As a result, if I cancel/abort my
> org-capture, that modification will still be present.

You can make use of `org-capture-put' and :hook capture property to mark
a custom region to be killed on abort via `org-capture-mark-kill-region'.

-- 
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: [FR] Support headline as a function for file+headline target for org-capture-templates

[Nafiz Islam]

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

> Aside from those workarounds, would that be a feature worth implementing?
I'd imagine it could borrow some logic from `org-capture-expand-file' for
the headline argument, and the function (for the headline) would take
headlines as a parameter and return a string.

Oops I forgot to CC the mailing list

[-- Attachment #2: Type: text/html, Size: 421 bytes --]

Re: [FR] Support headline as a function for file+headline target for org-capture-templates

[Ihor Radchenko]

Nafiz Islam <nafiz.islam1001@gmail.com> writes:

>> Aside from those workarounds, would that be a feature worth implementing?
> I'd imagine it could borrow some logic from `org-capture-expand-file' for
> the headline argument, and the function (for the headline) would take
> headlines as a parameter and return a string.

May you please describe what kind of feature you want to introduce and
explain why it is useful for other Org mode users?

-- 
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: [FR] Support headline as a function for file+headline target for org-capture-templates

[Nafiz Islam]

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

> May you please describe what kind of feature you want to introduce and
> explain why it is useful for other Org mode users?

The feature I want to introduce is to allow the headline parameter to be a
function for the `file+headline' target for the `org-capture-templates'.
The function would take a list of headlines as a parameter, and the user
would be able to pick a headline it wants to reuse or create a new one by
returning a string. This makes it possible, for example, to pick a headline
dynamically based on the current time (like in my case) to add an entry, or
the user could implement a function that prompts with existing headlines to
choose from.

[-- Attachment #2: Type: text/html, Size: 778 bytes --]

Re: [FR] Support headline as a function for file+headline target for org-capture-templates

[Ihor Radchenko]

Nafiz Islam <nafiz.islam1001@gmail.com> writes:

>> May you please describe what kind of feature you want to introduce and
>> explain why it is useful for other Org mode users?
>
> The feature I want to introduce is to allow the headline parameter to be a
> function for the `file+headline' target for the `org-capture-templates'.
> The function would take a list of headlines as a parameter, and the user
> would be able to pick a headline it wants to reuse or create a new one by
> returning a string. This makes it possible, for example, to pick a headline
> dynamically based on the current time (like in my case) to add an entry, or
> the user could implement a function that prompts with existing headlines to
> choose from.

Sounds reasonable.
Such a feature would require a new function similar to
`org-capture-expand-file', but for outlines.

Would you be interested to submit a patch?

-- 
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: [FR] Support headline as a function for file+headline target for org-capture-templates

[Nafiz Islam]

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

> > Would you be interested to submit a patch?
> If I finish writing a patch for it. Sure.

I again forgot to CC emacs-orgmode@gnu.org

[-- Attachment #2: Type: text/html, Size: 437 bytes --]

Re: [FR] Support headline as a function for file+headline target for org-capture-templates

[Ihor Radchenko]

Nafiz Islam <nafiz.islam1001@gmail.com> writes:

>> > Would you be interested to submit a patch?
>> If I finish writing a patch for it. Sure.

You may refer to https://orgmode.org/worg/org-contribute.html
And feel free to ask anything if you have questions.

-- 
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: [FR] Support headline as a function for file+headline target for org-capture-templates

[Nafiz Islam]

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

So far I have written this code...

(defun org-capture-expand-headline (headline)
  "Expand functions, symbols and strings for HEADLINE.


When HEADLINE is a function, call it.  When it is a form, evaluate


it.  When it is a variable, return its value.  When it is a string,


treat it as a headline title. When it is `t', select existing headline


title or enter a new one.  In any other case, raise an error."
  (let* ((headlines (org-map-entries (lambda ()
                                       (org-element-property :title
(org-element-at-point)))))
         (final-headline (cond ((stringp headline) headline)
                               ((functionp headline) (funcall headline
headlines))
                               ((eq headline t) (completing-read "Enter
headline: " headlines  nil 'confirm))
                               ((and (symbolp headline) (boundp headline))
(symbol-value headline))
                               (t nil))))
    (or (org-string-nw-p final-headline)
(error "Invalid headline: %S" headline))))

and I updated `org-capture-set-target-location' to use that function when
handling with target `file+headline'

What I am concerned about is the amount of tests I might have to write or
update for `org-capture'.

testing/lisp/test-org-capture.el


125:          `(("t" "Todo" entry (file+headline ,file "A") "** H1 %?"))))


144:             `(("t" "Todo" entry (file+headline ,file2 "A")


175:          `(("t" "Todo" entry (file+headline ,file "A") "** H1 %?"))))


221:          `(("t" "Todo" entry (file+headline ,file "A") "** H1 %?"))))


233:          `(("t" "Test" entry (file+headline ,file "A") "** H\nFoo"


243:         `(("t" "Test" entry (file+headline ,file "A") "** "


279:          `(("t" "Item" item (file+headline ,file "A") "- X"))))


312:          `(("t" "Item" item (file+headline ,file "A") "- X"))))


323:          `(("t" "Item" item (file+headline ,file "A") "- X"


337:          `(("t" "Item" item (file+headline ,file "A") "- X"


358:          `(("t" "Item" item (file+headline ,file "A") "- X"


371:          `(("t" "Item" item (file+headline ,file "A") "- X"))))


538:                `(("t" "Table" table-line (file+headline ,file "Inbox")


552:                `(("t" "Table" table-line (file+headline ,file "Inbox")


723:                `(("t" "Text" plain (file+headline ,file "A") "Foo"


733:                `(("t" "Text" plain (file+headline ,file "A") "Foo"

How do you think it should be tested if the headline can be 4 different
types?

Apology in advance if the formatting is off.

[-- Attachment #2: Type: text/html, Size: 7446 bytes --]

Re: [FR] Support headline as a function for file+headline target for org-capture-templates

[Ihor Radchenko]

Nafiz Islam <nafiz.islam1001@gmail.com> writes:

> So far I have written this code...
>
> (defun org-capture-expand-headline (headline)
>   "Expand functions, symbols and strings for HEADLINE.
>
>
> When HEADLINE is a function, call it.  When it is a form, evaluate
> it.  When it is a variable, return its value.  When it is a string,
> treat it as a headline title. When it is `t', select existing headline
> title or enter a new one.  In any other case, raise an error."

Let's not add "t" variant yet. It is going beyond what
`org-capture-expand-file' does.

>                                ((functionp headline) (funcall headline
> headlines))

Let's not over-complicate things. Just (funcall headline) will do,
making sure that it is called in the right context - current buffer
being selected according to file part of the capture target.

> What I am concerned about is the amount of tests I might have to write or
> update for `org-capture'.
>
> testing/lisp/test-org-capture.el
> ...
> 144:             `(("t" "Todo" entry (file+headline ,file2 "A")
> ...
> How do you think it should be tested if the headline can be 4 different
> types?

It is enough to make sure that basic entry type works correctly,
expanding the HEADLINE part of the template definition. Other tests you
listed are really not testing this; they are checking the logic of
inserting the right entry/item/table/etc.

Also, since we are adding more flexible HEADLINE expansion, may as well
allow functions for OLP in file+olp and file+olp+datetree.

-- 
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: [FR] Support headline as a function for file+headline target for org-capture-templates

[Nafiz Islam]

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

I see there are a lot of test cases for org-find-olp (which is the function
I believe processes the outline path argument).

testing/lisp/test-org.el
2861:(ert-deftest test-org/org-find-olp ()
2862:  "Test `org-find-olp' specifications."
2875:    (should (org-find-olp '("Headline") t))
2876:    (should-error (org-find-olp '("Headline" "Test") t))
2877:    (should-error (org-find-olp '("Headlinealksjd") t))
2878:    (should (org-find-olp '("Headline" "headline2") t))
2879:    (should (org-find-olp '("Headline" "headline3") t))
2880:    (should (org-find-olp '("Headline" "headline3" "headline4") t))
2881:    (should-error (org-find-olp '("Headline" "headline5") t))
2882:    (should (org-find-olp '("Headline" "headline6") t))
2883:    (should (org-find-olp '("Headline" "headline7") t))
2884:    (should (org-find-olp '("Headline" "headline8") t))

How should I go about testing different parameter types such as function
and symbol?

[-- Attachment #2: Type: text/html, Size: 1344 bytes --]

Re: [FR] Support headline as a function for file+headline target for org-capture-templates

[Ihor Radchenko]

Nafiz Islam <nafiz.islam1001@gmail.com> writes:

> I see there are a lot of test cases for org-find-olp (which is the function
> I believe processes the outline path argument).
>
> testing/lisp/test-org.el
> 2861:(ert-deftest test-org/org-find-olp ()
> 2862:  "Test `org-find-olp' specifications."
> 2875:    (should (org-find-olp '("Headline") t))
> 2876:    (should-error (org-find-olp '("Headline" "Test") t))
> 2877:    (should-error (org-find-olp '("Headlinealksjd") t))
> 2878:    (should (org-find-olp '("Headline" "headline2") t))
> 2879:    (should (org-find-olp '("Headline" "headline3") t))
> 2880:    (should (org-find-olp '("Headline" "headline3" "headline4") t))
> 2881:    (should-error (org-find-olp '("Headline" "headline5") t))
> 2882:    (should (org-find-olp '("Headline" "headline6") t))
> 2883:    (should (org-find-olp '("Headline" "headline7") t))
> 2884:    (should (org-find-olp '("Headline" "headline8") t))
>
> How should I go about testing different parameter types such as function
> and symbol?

I do not think that you need to modify `org-find-olp' itself.

Instead, do what is already done for resolving the file name:

(org-find-olp (cons (org-capture-expand-file path)
		    (org-capture-expand-olp outline-path)))

`org-capture-expand-olp' is the new function to be implemented.

Then, all you need in terms of tests is to add a test case into
`test-org-capture/entry' and, if you want, write a new test for
`org-capture-expand-olp'.

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