Function: pfuture-callback

pfuture-callback is a macro defined in pfuture.el.

Signature

(pfuture-callback COMMAND &key ON-SUCCESS ON-ERROR ON-STATUS-CHANGE DIRECTORY NAME CONNECTION-TYPE BUFFER FILTER)

Documentation

Pfuture variant that supports a callback-based workflow.

Internally based on make-process. Requires lexical scope.

The first - and only required - argument is COMMAND. It is an (unquoted) list of the command and the arguments for the process that should be started. A vector is likewise acceptable - the difference is purely cosmetic (this does not apply when command is passed as a variable, in this case it must be a list).

The rest of the argument list is made up of the following keyword arguments:

ON-SUCCESS is the code that will run once the process has finished with an exit code of 0. In its context, these variables are bound: process: The process object, as passed to the sentinel callback function. status: The string exit status, as passed to the sentinel callback function. pfuture-buffer: The buffer where the output of the process is collected, including both stdin and stdout. You can use pfuture-callback-output to quickly grab the buffer's content.

ON-SUCCESS may take one of 3 forms: an unquoted sexp, a quoted function or an unquoted function. In the former two cases the passed fuction will be called with process, status and buffer as its arguments.

ON-ERROR is the inverse to ON-SUCCESS; it will only run if the process has finished with a non-zero exit code. Otherwise the same conditions apply as for ON-SUCCESS.

ON-STATUS-CHANGE will run on every status change, even if the process remains running. It is meant for debugging and has access to the same variables as ON-SUCCESS and ON-ERROR, including the (potentially incomplete) process output buffer. Otherwise the same conditions as for ON-SUCCESS and ON-ERROR apply.

DIRECTORY is the value given to default-directory for the context of the process. If not given it will fall back the current value of default-directory.

NAME will be passed to the :name property of make-process. If not given it will fall back to "Pfuture Callback [$COMMAND]".

CONNECTION-TYPE will be passed to the :connection-process property of make-process. If not given it will fall back to 'pipe.

BUFFER is the buffer that will be used by the process to collect its output, quickly collectible with pfuture-output-from-buffer. Providing a buffer outside of specific use-cases is not necessary, as by default pfuture will assign every launched command its own unique buffer and kill it after ON-SUCCESS or ON-ERROR have finished running. However, no such cleanup will take place if a custom buffer is provided.

FILTER is a process filter-function (quoted function reference) that can be used to overwrite pfuture's own filter. By default pfuture uses its filter function to collect the launched process' output in its buffer, thus when providing a custom filter output needs to be gathered another way. Note that the process' buffer is stored in its buffer property and is therefore accessible via
(process-get process 'buffer).

Source Code

;; Defined in ~/.emacs.d/elpa/pfuture-20220913.1401/pfuture.el
(cl-defmacro pfuture-callback
    (command &key
             on-success
             on-error
             on-status-change
             directory
             name
             connection-type
             buffer
             filter)
  "Pfuture variant that supports a callback-based workflow.
Internally based on `make-process'.  Requires lexical scope.

The first - and only required - argument is COMMAND.  It is an (unquoted) list
of the command and the arguments for the process that should be started.  A
vector is likewise acceptable - the difference is purely cosmetic (this does not
apply when command is passed as a variable, in this case it must be a list).

The rest of the argument list is made up of the following keyword arguments:

ON-SUCCESS is the code that will run once the process has finished with an exit
code of 0. In its context, these variables are bound: `process': The process
object, as passed to the sentinel callback function.  `status': The string exit
status, as passed to the sentinel callback function.  `pfuture-buffer': The
buffer where the output of the process is collected, including both stdin and
stdout.  You can use `pfuture-callback-output' to quickly grab the buffer's
content.

ON-SUCCESS may take one of 3 forms: an unquoted sexp, a quoted function or an
unquoted function.  In the former two cases the passed fuction will be called
with `process', `status' and `buffer' as its arguments.

ON-ERROR is the inverse to ON-SUCCESS; it will only run if the process has
finished with a non-zero exit code.  Otherwise the same conditions apply as for
ON-SUCCESS.

ON-STATUS-CHANGE will run on every status change, even if the process remains
running.  It is meant for debugging and has access to the same variables as
ON-SUCCESS and ON-ERROR, including the (potentially incomplete) process output
buffer.  Otherwise the same conditions as for ON-SUCCESS and ON-ERROR apply.

DIRECTORY is the value given to `default-directory' for the context of the
process.  If not given it will fall back the current value of
`default-directory'.

NAME will be passed to the :name property of `make-process'.  If not given it
will fall back to \"Pfuture Callback [$COMMAND]\".

CONNECTION-TYPE will be passed to the :connection-process property of
`make-process'. If not given it will fall back to \\='pipe.

BUFFER is the buffer that will be used by the process to collect its output,
quickly collectible with `pfuture-output-from-buffer'.
Providing a buffer outside of specific use-cases is not necessary, as by default
pfuture will assign every launched command its own unique buffer and kill it
after ON-SUCCESS or ON-ERROR have finished running. However, no such cleanup
will take place if a custom buffer is provided.

FILTER is a process filter-function (quoted function reference) that can be used
to overwrite pfuture's own filter. By default pfuture uses its filter function
to collect the launched process' output in its buffer, thus when providing a
custom filter output needs to be gathered another way. Note that the process'
buffer is stored in its `buffer' property and is therefore accessible via
\(process-get process \\='buffer\)."
  (declare (indent 1))
  (let* ((command (if (vectorp command)
                      `(quote ,(cl-map 'list #'identity command))
                    command))
         (connection-type (or connection-type (quote 'pipe)))
         (directory (or directory default-directory)))
    (unless (or on-success on-error)
      (setq on-success '(function ignore)))
    `(let* ((default-directory ,directory)
            (name (or ,name (format " Pfuture-Callback %s" ,command)))
            ;; pfuture's buffers are internal implementation details
            ;; nobody should care if a new one is created
            (pfuture-buffer (or ,buffer (let (buffer-list-update-hook) (generate-new-buffer name))))
            (process
             (make-process
              :name name
              :command ,command
              :connection-type ,connection-type
              :filter ,(or filter '(function pfuture--append-output-to-buffer))
              :sentinel (lambda (process status)
                          (ignore status)
                          ,@(when on-status-change
                              `((pfuture--decompose-fn-form ,on-status-change
                                  process status pfuture-buffer)))
                          (unless (process-live-p process)
                            (if (= 0 (process-exit-status process))
                                (pfuture--decompose-fn-form ,on-success
                                  process status pfuture-buffer)
                              (pfuture--decompose-fn-form ,on-error
                                process status pfuture-buffer))
                            ,(unless buffer
                               `(kill-buffer (process-get process 'buffer))))))))
       (process-put process 'buffer pfuture-buffer)
       process)))