guix/deprecation.scm

   1 ;;; GNU Guix --- Functional package management for GNU
   2 ;;; Copyright © 2019 Ludovic Courtès <ludo@gnu.org>
   3 ;;;
   4 ;;; This file is part of GNU Guix.
   5 ;;;
   6 ;;; GNU Guix is free software; you can redistribute it and/or modify it
   7 ;;; under the terms of the GNU General Public License as published by
   8 ;;; the Free Software Foundation; either version 3 of the License, or (at
   9 ;;; your option) any later version.
  10 ;;;
  11 ;;; GNU Guix is distributed in the hope that it will be useful, but
  12 ;;; WITHOUT ANY WARRANTY; without even the implied warranty of
  13 ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 ;;; GNU General Public License for more details.
  15 ;;;
  16 ;;; You should have received a copy of the GNU General Public License
  17 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
  18
  19 (define-module (guix deprecation)
  20   #:use-module (guix i18n)
  21   #:use-module (ice-9 format)
  22   #:export (define-deprecated
  23             define-deprecated/alias
  24             deprecation-warning-port))
  25
  26 ;;; Commentary:
  27 ;;;
  28 ;;; Provide a mechanism to mark bindings as deprecated.
  29 ;;;
  30 ;;; We don't reuse (guix ui) mostly to avoid pulling in too many things.
  31 ;;;
  32 ;;; Code:
  33
  34 (define deprecation-warning-port
  35   ;; Port where deprecation warnings go.
  36   (make-parameter (current-error-port)))
  37
  38 (define (source-properties->location-string properties)
  39   "Return a human-friendly, GNU-standard representation of PROPERTIES, a
  40 source property alist."
  41   (let ((file   (assq-ref properties 'filename))
  42         (line   (assq-ref properties 'line))
  43         (column (assq-ref properties 'column)))
  44     (if (and file line column)
  45         (format #f "~a:~a:~a" file (+ 1 line) column)
  46         (G_ "<unknown location>"))))
  47
  48 (define* (warn-about-deprecation variable properties
  49                                  #:key replacement)
  50   (format (deprecation-warning-port)
  51           (G_ "~a: warning: '~a' is deprecated~@[, use '~a' instead~]~%")
  52           (source-properties->location-string properties)
  53           variable replacement))
  54
  55 (define-syntax define-deprecated
  56   (lambda (s)
  57     "Define a deprecated variable or procedure, along these lines:
  58
  59   (define-deprecated foo bar 42)
  60   (define-deprecated (baz x y) qux (qux y x))
  61
  62 This will write a deprecation warning to DEPRECATION-WARNING-PORT."
  63     (syntax-case s ()
  64       ((_ (proc formals ...) replacement body ...)
  65        #'(define-deprecated proc replacement
  66            (lambda* (formals ...) body ...)))
  67       ((_ variable replacement exp)
  68        (identifier? #'variable)
  69        (with-syntax ((real (datum->syntax
  70                             #'variable
  71                             (symbol-append '%
  72                                            (syntax->datum #'variable)
  73                                            '/deprecated))))
  74          #`(begin
  75              (define real
  76                (begin
  77                  (lambda () replacement)          ;just to ensure it's bound
  78                  exp))
  79
  80              (define-syntax variable
  81                (lambda (s)
  82                  (warn-about-deprecation 'variable (syntax-source s)
  83                                          #:replacement 'replacement)
  84                  (syntax-case s ()
  85                    ((_ args (... ...))
  86                     #'(real args (... ...)))
  87                    (id
  88                     (identifier? #'id)
  89                     #'real))))))))))
  90
  91 (define-syntax-rule (define-deprecated/alias deprecated replacement)
  92   "Define as an alias a deprecated variable, procedure, or macro, along
  93 these lines:
  94
  95   (define-deprecated/alias nix-server? store-connection?)
  96
  97 where 'nix-server?' is the deprecated name for 'store-connection?'.
  98
  99 This will write a deprecation warning to DEPRECATION-WARNING-PORT."
 100   (define-syntax deprecated
 101     (lambda (s)
 102       (warn-about-deprecation 'deprecated (syntax-source s)
 103                               #:replacement 'replacement)
 104       (syntax-case s ()
 105         ((_ args (... ...))
 106          #'(replacement args (... ...)))
 107         (id
 108          (identifier? #'id)
 109          #'replacement)))))