Re: Pending contents in org documents (Re: Asynchronous blocks for everything (was Re: ...))

[Ihor Radchenko <yantar92@posteo.net>]

Bruno Barbier <brubar.cs@gmail.com> writes:

> ... I'm now using using a fully working example.

Thanks!
I will first reply to you email inline and then common further on your
changes from the branch.

>>> ;;        (org-pending-send-update my-rlock  (list :progress "Not ready yet."))
>>> ;;        (org-pending-send-update my-rlock  (list :progress "Coming soon."))
>>
>> Should the progress message always be a string?
>
> No.  It may currently be any data.  org-pending will format it as a
> string that fits on one line.

Please say this in the docstring of `org-pending-send-update'.

>>> ;;        (org-pending-send-update my-rlock (list :success 1))
>>
>> What will org-pending do with :success 1? Will it replace region with
>> "1" or will it do something else?
>
> That's the job on ON-OUTCOME to convert/format/append/prepend/replace
> some content if needed, on :success and/or on :failure.

Fair. Although, it feels like a common use case to replace the region
with :success value. Maybe the library should provide some ready-to-use
functions that can be used as the value of :on-outcome.

>> It would be nice to have an example that will also send a signal to
>> process, as it is probably the most commonly used way to utilize
>> org-pending.
>
> For my many use cases, that would always be a mistake to kill the
> process: an OS process is always in charge of many locks.
>
> More importantly, to find a self-contained working readable example
> might be a challenge.
>
> We could add a function 'org-pending-shell-command-on-region' in
> org-pending, that could be used as an implementation example, like
> `org-pending-user-edit', `org-babel-execute-src-block', etc.

Yes, having pre-cooked wrappers for `org-pending' or pre-defined values
for :on-outcome/:befire-kill-function/:user-cancel-function/etc would be useful.

;;     ;; We lock the 'region', defining how to update it when the
;;     ;; outcome is available.
;;     (setq my-lock (org-pending
;;                    region
;;                    :on-outcome
;;                    (lambda (_rl outcome)
;;                      (pcase outcome
;;                        (`(:success ,value)
;;                         ;; On :success, we replace the region with the
;;                         ;; value.
;;                         (let ((tmp-end (cdr region)))
;;                           (goto-char tmp-end)
;;                           (insert (format "%s\n" value))
;;                           (setcdr region (point))
;;                           (delete-region (car region) tmp-end)))
;; ...

This example has a major problem if user edits the buffer text _before_
locked region before the outcome is available.
(car region) and (cdr region) will no longer be accurate, and your code
will replace text in places you do not expect.

I believe that it will be better to query region-lock object about the
region location where we need to replace text:

(setq region (org-pending-reglock-region rl))

Same for reglock buffer in other examples.

Then, we will keep the possibility open for org-pending to handle cases
like killing/yanking text containing reglocks (org-refile) - org-pending
may in future keep track of them.

;;     (setf (org-pending-reglock-user-cancel-function my-lock)
;;           (let ((this-timer my-timer))
;;             (lambda (_rl)
;;               (cancel-timer this-timer)
;; ...

;;     (setf (org-pending-reglock-before-kill-function my-lock)
;;           (let ((this-timer my-timer))
;;             (lambda (_rl)
;;               (message "Killing %s" this-timer)
;;               (cancel-timer this-timer))))

What is the difference between "canceling" and "killing" the reglock?
Do they need to be separate?

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