19.3 Obsolescence

Declarations of the forms

:- pragma obsolete(Name/Arity).
:- pragma obsolete(Name/Arity,
    [ReplName1/ReplArity1, ..., ReplNameN/ReplArityN]).

declare that the predicate(s) or function(s) with name Name and arity Arity are “obsolete”: they instruct the compiler to issue a warning whenever the named predicate(s) and/or function(s) are used. The second form tells the compiler to suggest the use of one of the listed possible replacements.

Declarations of the forms

:- pragma obsolete_proc(PredName(ArgMode1, ..., ArgModeN)).
:- pragma obsolete_proc(PredName(ArgMode1, ..., ArgModeN),
    [ReplName1/ReplArity1, ..., ReplNameN/ReplArityN]).
:- pragma obsolete_proc(FuncName(ArgMode1, ..., ArgModeN) = RetMode).
:- pragma obsolete_proc(FuncName(ArgMode1, ..., ArgModeN) = RetMode,
    [ReplName1/ReplArity1, ..., ReplNameN/ReplArityN]).

similarly declare that the predicate named PredName with arity N, or the function named FuncName with arity N, is obsolete when called in the specified mode. These forms also allow the specification of an optional list of possible replacements.

These declarations are intended for use by library developers, to allow gradual (rather than abrupt) evolution of library interfaces. If a library developer changes the interface of a library predicate or procedure, they should leave its old version in the library, but mark it as obsolete using one of these declarations, and document how library users should modify their code to suit the new interface. The users of the library will then get a warning if they use obsolete features, and can consult the library documentation to determine how to fix their code. Eventually, when the library developer believes that users have had sufficient warning, they can remove the old version entirely.