Info Catalog elisp: Directory Local Variables elisp: Variables elisp: Variables with Restricted Values

elisp: Variable Aliases

 
 11.13 Variable Aliases
 ======================
 
 It is sometimes useful to make two variables synonyms, so that both
 variables always have the same value, and changing either one also
 changes the other.  Whenever you change the name of a variable—either
 because you realize its old name was not well chosen, or because its
 meaning has partly changed—it can be useful to keep the old name as an
 _alias_ of the new one for compatibility.  You can do this with
 ‘defvaralias’.
 
  -- Function: defvaralias new-alias base-variable &optional docstring
      This function defines the symbol NEW-ALIAS as a variable alias for
      symbol BASE-VARIABLE.  This means that retrieving the value of
      NEW-ALIAS returns the value of BASE-VARIABLE, and changing the
      value of NEW-ALIAS changes the value of BASE-VARIABLE.  The two
      aliased variable names always share the same value and the same
      bindings.
 
      If the DOCSTRING argument is non-‘nil’, it specifies the
      documentation for NEW-ALIAS; otherwise, the alias gets the same
      documentation as BASE-VARIABLE has, if any, unless BASE-VARIABLE is
      itself an alias, in which case NEW-ALIAS gets the documentation of
      the variable at the end of the chain of aliases.
 
      This function returns BASE-VARIABLE.
 
    Variable aliases are convenient for replacing an old name for a
 variable with a new name.  ‘make-obsolete-variable’ declares that the
 old name is obsolete and therefore that it may be removed at some stage
 in the future.
 
  -- Function: make-obsolete-variable obsolete-name current-name when
           &optional access-type
      This function makes the byte compiler warn that the variable
      OBSOLETE-NAME is obsolete.  If CURRENT-NAME is a symbol, it is the
      variable’s new name; then the warning message says to use
      CURRENT-NAME instead of OBSOLETE-NAME.  If CURRENT-NAME is a
      string, this is the message and there is no replacement variable.
      WHEN should be a string indicating when the variable was first made
      obsolete (usually a version number string).
 
      The optional argument ACCESS-TYPE, if non-‘nil’, should specify the
      kind of access that will trigger obsolescence warnings; it can be
      either ‘get’ or ‘set’.
 
    You can make two variables synonyms and declare one obsolete at the
 same time using the macro ‘define-obsolete-variable-alias’.
 
  -- Macro: define-obsolete-variable-alias obsolete-name current-name
           &optional when docstring
      This macro marks the variable OBSOLETE-NAME as obsolete and also
      makes it an alias for the variable CURRENT-NAME.  It is equivalent
      to the following:
 
           (defvaralias OBSOLETE-NAME CURRENT-NAME DOCSTRING)
           (make-obsolete-variable OBSOLETE-NAME CURRENT-NAME WHEN)
 
  -- Function: indirect-variable variable
      This function returns the variable at the end of the chain of
      aliases of VARIABLE.  If VARIABLE is not a symbol, or if VARIABLE
      is not defined as an alias, the function returns VARIABLE.
 
      This function signals a ‘cyclic-variable-indirection’ error if
      there is a loop in the chain of symbols.
 
      (defvaralias 'foo 'bar)
      (indirect-variable 'foo)
           ⇒ bar
      (indirect-variable 'bar)
           ⇒ bar
      (setq bar 2)
      bar
           ⇒ 2
      foo
           ⇒ 2
      (setq foo 0)
      bar
           ⇒ 0
      foo
           ⇒ 0
 

Info Catalog elisp: Directory Local Variables elisp: Variables elisp: Variables with Restricted Values