14.15 Deprecation

A deprecated function, macro, or other API element is one that’s been formally declared obsolete, typically with an intended replacement that users should migrate to. The racket/deprecation library provides a standardized mechanism for declaring deprecations in a machine-processable manner. These declarations can allow tools such as resyntax to automate migrating code away from deprecated APIs. Note that a dependency on the racket/deprecation library does not imply a dependency on any such tools.

14.15.1Deprecated Aliases🔗 i

syntax
( define-deprecated-alias alias-idtarget-id)

Binds alias-id as an alias of target-id with the intent that users of alias-id should prefer to use target-id instead. The given alias-id is bound as a deprecated alias transformer, which is a kind of rename transformer. The given target-id may be bound to a function, macro, or any other kind of binding.

Note that although alias-id is an alias of target-id, it is not considered the same binding as target-id and is not free-identifier=? . This is because the alias binding must be inspectable at compile-time with deprecated-alias? and deprecated-alias-target , and it must remain inspectable even if the alias is provide d by a module. This requires a module providing the alias and the target to provide them as two distinct bindings: one which is bound to a deprecated alias transformer and one which isn’t.

Examples:

> (require racket/deprecation)
> (define a42)
> (define-deprecated-alias legacy-aa)
> legacy-a

42

14.15.2Deprecated Alias Transformers🔗 i

(require racket/deprecation/transformer ) package: base

The racket/deprecation/transformer module provides compile-time supporting code for the racket/deprecation library, primarily for use in tools that wish to reflect on deprecated code.

A deprecated alias transformer is a kind of rename transformer which signals that the transformer binding is a deprecated alias of the target identifier. This signal is intended for consumption in tools such as editors (which may wish to display a warning when deprecated aliases are used) and automated refactoring systems (which may wish to replace deprecated aliases with their target identifiers automatically).

procedure
( deprecated-alias? v)→boolean?
v:any/c

Returns true if v is a deprecated alias transformer and returns false otherwise. Implies rename-transformer? . To determine if an identifier is bound to a deprecated alias transformer, use syntax-local-value/immediate and then use deprecated-alias? on the transformer value.

Examples:

> (require (for-syntax racket/base
racket/deprecation/transformer)
racket/deprecation
syntax/parse/define)

> (define-syntax-parse-rule (is-deprecated?id:id)
#:do[(define-values (transformer_ )
(syntax-local-value/immediate #'id (λ ()(values #false#false))))]
#:withresult(deprecated-alias? transformer)
'result)
> (define-deprecated-alias bad-listlist )
> (is-deprecated?list )

#f
> (is-deprecated?bad-list)

#t

procedure
( deprecated-alias target)→deprecated-alias?
target:identifier?

Constructs a deprecated alias transformer which expands to target when used. The returned alias is a rename transformer and is thus suitable for use with define-syntax . When expanding, the usage of target is annotated with the 'not-free-identifier=? syntax property to ensure that the alias and the target are treated as distinct bindings, even when provide d by a module.

This constructor is not intended for direct use by users who just want to declare a deprecated alias. Such users should prefer the define-deprecated-alias form instead.

procedure
( deprecated-alias-target alias)→identifier?
alias:deprecated-alias?

Returns the target identifier that alias expands to.

top ← prev up next →