14.15 Deprecation

► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

▼ | 14 | Reflection and Security

14.1 | Namespaces
14.2 | Evaluation and Compilation
14.3 | The racket/ load Language
14.4 | Module Names and Loading
14.5 | Impersonators and Chaperones
14.6 | Security Guards
14.7 | Custodians
14.8 | Thread Groups
14.9 | Structure Inspectors
14.10 | Code Inspectors
14.11 | Plumbers
14.12 | Sandboxed Evaluation
14.13 | The racket/ repl Library
14.14 | Linklets and the Core Compiler
14.15 | Deprecation

► | 14.15 | Deprecation

14.15.1 | Deprecated Aliases
14.15.2 | Deprecated Alias Transformers

On this page:

14.15.1 Deprecated Aliases
define-deprecated-alias
14.15.2 Deprecated Alias Transformers
deprecated-alias?
deprecated-alias
deprecated-alias-target

top contents ← prev up next →

### 14.15 Deprecation🔗ℹ

(require racket/deprecation) | package: base

The bindings documented in this section are provided by the racket/deprecation library, not racket/base or racket.

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.1 Deprecated Aliases🔗ℹ

> syntax (define-deprecated-alias alias-id target-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 provided 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 a 42)
> > (define-deprecated-alias legacy-a a)
> > legacy-a
> 42

#### 14.15.2 Deprecated Alias Transformers🔗ℹ

(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))))]
> #:with result (deprecated-alias? transformer)
> 'result)
> > (define-deprecated-alias bad-list list)
> > (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 provided 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 contents ← prev up next →