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 (guix diagnostics)
  22   #:autoload   (guix utils) (source-properties->location)
  23   #:export (define-deprecated
  24             define-deprecated/alias
  25             warn-about-deprecation))
  26
  27 ;;; Commentary:
  28 ;;;
  29 ;;; Provide a mechanism to mark bindings as deprecated.
  30 ;;;
  31 ;;; Code:
  32
  33 (define* (warn-about-deprecation variable properties
  34                                  #:key replacement)
  35   (let ((location (and properties (source-properties->location properties))))
  36     (if replacement
  37         (warning location (G_ "'~a' is deprecated, use '~a' instead~%")
  38                  variable replacement)
  39         (warning location (G_ "'~a' is deprecated~%")
  40                  variable))))
  41
  42 (define-syntax define-deprecated
  43   (lambda (s)
  44     "Define a deprecated variable or procedure, along these lines:
  45
  46   (define-deprecated foo bar 42)
  47   (define-deprecated (baz x y) qux (qux y x))
  48
  49 This will write a deprecation warning to GUIX-WARNING-PORT."
  50     (syntax-case s ()
  51       ((_ (proc formals ...) replacement body ...)
  52        #'(define-deprecated proc replacement
  53            (lambda* (formals ...) body ...)))
  54       ((_ variable replacement exp)
  55        (identifier? #'variable)
  56        (with-syntax ((real (datum->syntax
  57                             #'variable
  58                             (symbol-append '%
  59                                            (syntax->datum #'variable)
  60                                            '/deprecated))))
  61          #`(begin
  62              (define real
  63                (begin
  64                  (lambda () replacement)          ;just to ensure it's bound
  65                  exp))
  66
  67              (define-syntax variable
  68                (lambda (s)
  69                  (warn-about-deprecation 'variable (syntax-source s)
  70                                          #:replacement 'replacement)
  71                  (syntax-case s ()
  72                    ((_ args (... ...))
  73                     #'(real args (... ...)))
  74                    (id
  75                     (identifier? #'id)
  76                     #'real))))))))))
  77
  78 (define-syntax-rule (define-deprecated/alias deprecated replacement)
  79   "Define as an alias a deprecated variable, procedure, or macro, along
  80 these lines:
  81
  82   (define-deprecated/alias nix-server? store-connection?)
  83
  84 where 'nix-server?' is the deprecated name for 'store-connection?'.
  85
  86 This will write a deprecation warning to GUIX-WARNING-PORT."
  87   (define-syntax deprecated
  88     (lambda (s)
  89       (warn-about-deprecation 'deprecated (syntax-source s)
  90                               #:replacement 'replacement)
  91       (syntax-case s ()
  92         ((_ args (... ...))
  93          #'(replacement args (... ...)))
  94         (id
  95          (identifier? #'id)
  96          #'replacement)))))