Ihor Radchenko <yanta...@posteo.net> writes:
> Bruno Barbier <brubar...@gmail.com> writes: > >>>> ;; (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'. Done. >>>> ;; (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. I've recycled the old function used by `org-pending-user-edit', improved it and made it the default :on-outcome handler: see `org-pending-on-outcome-replace'. I've simplified the example accordingly, removing the custom :on-outcome. I don't know any safe way to replace some text, but, I hope that will be a good enough default. >>> 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. :on-outcome now has a better default: `org-pending-on-outcome-replace' (see above). The predefined values for :before-kill-function and :user-cancel-function seem OK to me. We will see, when using org-pending, if some patterns need to be included in org-pending. >From the many examples provided in the branch, do you see any that should be included in the library as an other precooked-wrapper, that should be included in the section "Basic use of locks" ? I've added 'org-pending-shell-command-on-region' to my todo list. > > ;; ;; 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. I see. Good point! But note that the region is a "read-only constant" field; archiving/refiling live locks is forbidden. I modified the example to rely on the reglock when possible (as opposed to values kept from the creation time). > > ;; (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? If you cut out, from the example, the part where they differ, they do look the same indeed :) I'm apparently failing to explain and document this correctly, as it looks like a recurring topic, sorry. Yes, they need to be separate as they are two different operations. - cancel: The *user* may request a *cancel*; it's a polite way to tell org-pending that the user doesn't care anymore about the outcome. A valid implementation is to ignore the user request. The default implementation is to unlock the region (sending a cancel :failure using 'org-pending-send-update'): it unlocks the region, ignoring why it was locked.. - kill: *Emacs* may have to *kill* some locks, because Emacs is killed, or the lock buffer is killed. org-pending will intercept the operations of this kind, ask the user to confirm the destruction, and, if confirmed, it will give a chance to the lock to do some cleanup by calling the 'before-kill-function'. I've made some improvements about the kill behaviour and documentation. I've pushed my changes to my public branch. Bruno
