assess-call.el

;;; assess-call.el --- Call and Return -*- lexical-binding: t -*-

;;; Header:

;; This file is not part of Emacs

;; Author: Phillip Lord <phillip.lord@russet.org.uk>
;; Maintainer: Phillip Lord <phillip.lord@russet.org.uk>

;; The contents of this file are subject to the GPL License, Version 3.0.

;; Copyright (C) 2016-2022  Free Software Foundation, Inc.

;; This program is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <http://www.gnu.org/licenses/>.

;;; Commentary:

;; Capture calls to functions, checking parameters and return values.

;;; Code:

;; ** Call Capture

;; Here we provide a function for tracing calls to a particular function. This
;; can be a direct or indirect call; parameters and return values are available
;; for inspection afterwards. For example:

;; #+begin_src elisp
;;   (assess-call-capture
;;     '+
;;     (lambda()
;;       (+ 1 1)))
;;   ;; => (((1 1) . 2))
;; #+end_src

;; The return value is a list of cons cells, one for each invocation, of the
;; parameters and return values.


;; #+begin_src emacs-lisp
(defun assess-call--capture-lambda ()
  "Return function which captures args and returns of another.

The returned function takes FN the function to call, and any
number of ARGS to call the function with. In the special case,
that FN is equal to `:return`, then all previous args and return
values of FN are returned instead."
  (let ((capture-store nil))
    (lambda (fn &rest args)
      (if (eq fn :return)
          capture-store
        (let ((rtn (apply fn args)))
          (setq capture-store
                (cons (cons args rtn)
                      capture-store))
          rtn)))))

(defun assess-call-capture (sym-fn fn)
  "Trace all calls to SYM-FN when FN is called with no args.

The return value is a list of cons cells, with car being the
parameters of the calls, and the cdr being the return value."
  (let ((capture-lambda
         (assess-call--capture-lambda)))
    (unwind-protect
        (progn (advice-add sym-fn :around capture-lambda)
               (funcall fn)
               (funcall capture-lambda :return))
      (advice-remove sym-fn capture-lambda))))

(defun assess-call--hook-capture-lambda ()
  "Returns a function which captures all of its args.

The returned function takes any number of ARGS. In the special
case that the first arg is `:return` then it returns all previous
args."
  (let ((capture-store nil))
    (lambda (&rest args)
      (if (eq (car-safe args) :return)
          capture-store
        (setq capture-store
              (cons
               args
               capture-store))))))

(defun assess-call-capture-hook (hook-var fn &optional append local)
  "Trace all calls to HOOK-VAR when FN is called with no args.
APPEND and LOCAL are passed to `add-hook` and documented there."
  (let ((capture-lambda
         (assess-call--hook-capture-lambda)))
    (unwind-protect
        (progn
          (add-hook hook-var
                    capture-lambda
                    append local)
          (funcall fn)
          (funcall capture-lambda :return))
      (remove-hook hook-var
                   capture-lambda
                   local))))

(provide 'assess-call)
;;; assess-call.el ends here
;; #+end_src