bug#7679: wishlist: add new library map-progress.el - mapping macros that report progress (Jonas Bernoulli)

[Jari Aalto]

Package: emacs
Version: 23.2+1-5.1
Severity: wishlist
X-debbugs-cc: Jonas Bernoulli <jonas@bernoul.li>

I would be nice if the progress indicator library map-progress.el by Jonas
Bernoulli. were included in Emacs

The code repository is at:

    https://github.com/emacsmirror/map-progress/blob/master/map-progress.el

Attached also below as of 2010-12-19 14:35 UTC:

    1f15042 2010-08-21  map-with-progress-reporter: fix names of internal 
variables

-- System Information
Debian Release: squeeze/sid
  APT Prefers testing
  APT policy: (990, testing) (500, unstable) (1, experimental)
Architecture: amd64
Kernel: Linux picasso 2.6.32-5-amd64 #1 SMP Fri Sep 17 21:50:19 UTC 2010 x86_64 
GNU/Linux
Locale: LANG=en_DK.UTF-8

-- Versions of packages `emacs depends on'.
Depends:
emacs23         23.2+1-5.1      GNU Emacs is the extensible self-documenting 
emacs23-lucid   23.2+1-5.1      GNU Emacs is the extensible self-documenting 
emacs23-nox     23.2+1-5.1      GNU Emacs is the extensible self-documenting 

;;; map-progress.el --- mapping macros that report progress

;; Copyright (C) 2010  Jonas Bernoulli

;; Author: Jonas Bernoulli <jonas@bernoul.li>
;; Created: 20100714
;; Updated: 20100810
;; Version: 0.2
;; Homepage: https://github.com/tarsius/map-progress/
;; Keywords: convenience

;; This file is not part of GNU Emacs.

;; This file 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, or (at your option)
;; any later version.

;; This file 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:

;; This library defines mapping macros that report progress.

;; For many of the standard and CL mapping functions like `mapc' macros
;; like `mapc-with-progress-reporter' are defined here.  The arguments
;; have the same meaning as the respective arguments of the respective
;; function and `make-progress-reporter', which ever has an argument by
;; the same name.

;; Even when the respective function supports multiple sequences the
;; macros defined here only support one.  One the other hand all of the
;; `make-progress-reporter' arguments except for MESSAGE are optional.
;; This includes the starting and final state argument.

;; Any mapping function with only exactly two mandatory arguments - a
;; function which is applied to a sequence - are supported by
;; `map-with-progress-reporter' which can be used when no specialized
;; macro corresponding to a particular function exists, but additional
;; arguments are not supported.

;; Therefor at least the following functions are not supported: `map'.
;; However support for the following divergent mapping functions has
;; been implemented: .

;;; Code:

(eval-when-compile
  (require 'cl))

(defmacro map-with-progress-reporter (msg map fn seq &optional min max &rest 
rest)
  "Apply FUNCTION to each element of SEQUENCE using mapping function MAP.
Report progress in the echo.  Also see `make-progress-reporter'.
\(fn MESSAGE MAP FUNCTION SEQUENCE [MIN-VALUE MAX-VALUE CURRENT-VALUE 
MIN-CHANGE MIN-TIME])"
  (let ((idx (make-symbol "--map-with-progress-idx--"))
        (msm (make-symbol "--map-with-progress-msm--"))
        (lst (make-symbol "--map-with-progress-lst--"))
        (prg (make-symbol "--map-with-progress-prg--"))
        (elt (make-symbol "--map-with-progress-elt--")))
    `(let* ((,idx 0)
            (,msm ,msg)
            (,lst ,seq)
            (,prg (make-progress-reporter
                   ,msm (or ,min 0) (or ,max (length ,lst)) ,@rest)))
       (prog1 (funcall ,map (lambda (,elt)
                              (prog1 (funcall ,fn ,elt)
                                (progress-reporter-update ,prg (incf ,idx))))
                       ,lst)
         (progress-reporter-done ,prg)))))

(defmacro mapc-with-progress-reporter (msg fn seq &optional min max &rest rest)
  "Like `mapc' but report progress in the echo area.
Also see `make-progress-reporter'.
\(fn MESSAGE FUNCTION SEQUENCE [MIN-VALUE MAX-VALUE CURRENT-VALUE MIN-CHANGE 
MIN-TIME])"
  `(map-with-progress-reporter ,msg 'mapc ,fn ,seq ,min ,max ,@rest))

(defmacro mapcan-with-progress-reporter (msg fn seq &optional min max &rest 
rest)
  "Like `mapcan' but report progress in the echo area.
There may be only one SEQUENCE.  Also see `make-progress-reporter'.
\(fn MESSAGE FUNCTION SEQUENCE [MIN-VALUE MAX-VALUE CURRENT-VALUE MIN-CHANGE 
MIN-TIME])"
  `(map-with-progress-reporter ,msg 'mapcan ,fn ,seq ,min ,max ,@rest))

(defmacro mapcar-with-progress-reporter (msg fn seq &optional min max &rest 
rest)
  "Like `mapcar' but report progress in the echo area.
Also see `make-progress-reporter'.
\(fn MESSAGE FUNCTION SEQUENCE [MIN-VALUE MAX-VALUE CURRENT-VALUE MIN-CHANGE 
MIN-TIME])"
  `(map-with-progress-reporter ,msg 'mapcar ,fn ,seq ,min ,max ,@rest))

(defmacro mapcon-with-progress-reporter (msg fn seq &optional min max &rest 
rest)
  "Like `mapcon' but report progress in the echo area.
There may be only one SEQUENCE.  Also see `make-progress-reporter'.
\(fn MESSAGE FUNCTION SEQUENCE [MIN-VALUE MAX-VALUE CURRENT-VALUE MIN-CHANGE 
MIN-TIME])"
  `(map-with-progress-reporter ,msg 'mapcon ,fn ,seq ,min ,max ,@rest))

(defmacro mapl-with-progress-reporter (msg fn seq &optional min max &rest rest)
  "Like `mapl' but report progress in the echo area.
There may be only one SEQUENCE.  Also see `make-progress-reporter'.
\(fn MESSAGE FUNCTION SEQUENCE [MIN-VALUE MAX-VALUE CURRENT-VALUE MIN-CHANGE 
MIN-TIME])"
  `(map-with-progress-reporter ,msg 'mapl ,fn ,seq ,min ,max ,@rest))

(defmacro maplist-with-progress-reporter (msg fn seq &optional min max &rest 
rest)
  "Like `maplist' but report progress in the echo area.
There may be only one SEQUENCE.  Also see `make-progress-reporter'.
\(fn MESSAGE FUNCTION SEQUENCE [MIN-VALUE MAX-VALUE CURRENT-VALUE MIN-CHANGE 
MIN-TIME])"
  `(map-with-progress-reporter ,msg 'maplist ,fn ,seq ,min ,max ,@rest))

(defmacro mapatoms-with-progress-reporter (msg fn seq &optional min max &rest 
rest)
  "Like `mapatoms' but report progress in the echo area.
Also see `make-progress-reporter'.
\(fn MESSAGE FUNCTION [OBARRAY MIN-VALUE MAX-VALUE CURRENT-VALUE MIN-CHANGE 
MIN-TIME])"
  `(map-with-progress-reporter ,msg 'mapatoms ,fn ,seq ,min ,max ,@rest))

(defmacro maphash-with-progress-reporter (msg fn seq &optional min max &rest 
rest)
  "Like `maphash' but report progress in the echo area.
Also see `make-progress-reporter'.
\(fn MESSAGE FUNCTION HASH [MIN-VALUE MAX-VALUE CURRENT-VALUE MIN-CHANGE 
MIN-TIME])"
  `(map-with-progress-reporter ,msg 'maphash ,fn ,seq ,min ,max ,@rest))

(defmacro map-keymap-internal-with-progress-reporter (msg fn seq
                                                          &optional min max
                                                          &rest rest)
  "Like `map-keymap-internal' but report progress in the echo area.
Also see `make-progress-reporter'.
\(fn MESSAGE FUNCTION KEYMAP [MIN-VALUE MAX-VALUE CURRENT-VALUE MIN-CHANGE 
MIN-TIME])"
  `(map-with-progress-reporter ,msg 'map-keymap-internal ,fn ,seq ,min ,max 
,@rest))

(provide 'map-progress)
;;; map-progress.el ends here