12.14.2 Applying Connection Local Variables

When writing connection-aware code, you’ll need to collect, and possibly apply, any connection-local variables. There are several ways to do this, as described below.

Function: hack-connection-local-variables criteria ¶

This function collects applicable connection-local variables associated with criteria in connection-local-variables-alist, without applying them. Example:

(hack-connection-local-variables
  '(:application tramp :protocol "ssh" :machine "localhost"))

connection-local-variables-alist
     ⇒ ((null-device . "/dev/null")
        (shell-login-switch . "-l")
        (shell-interactive-switch . "-i")
        (shell-command-switch . "-c")
        (shell-file-name . "/bin/bash"))

Function: hack-connection-local-variables-apply criteria ¶

This function looks for connection-local variables according to criteria, and immediately applies them in the current buffer.

Macro: with-connection-local-application-variables application &rest body ¶

Apply all connection-local variables for application, which are specified by default-directory.

After that, body is executed, and the connection-local variables are unwound. Example:

(connection-local-set-profile-variables
  'my-remote-perl
  '((perl-command-name . "/usr/local/bin/perl5")
    (perl-command-switch . "-e %s")))

(connection-local-set-profiles
  '(:application my-app :protocol "ssh" :machine "remotehost")
  'my-remote-perl)

(let ((default-directory "/ssh:remotehost:/working/dir/"))
  (with-connection-local-application-variables 'my-app
    do something useful))

Variable: connection-local-default-application ¶

The default application, a symbol, to be applied in with-connection-local-variables, connection-local-p and connection-local-value. It defaults to tramp, but you can let-bind it to change the application temporarily (see Local Variables).

This variable must not be changed globally.

Macro: with-connection-local-variables &rest body ¶

This is equivalent to with-connection-local-application-variables, but uses connection-local-default-application for the application.

Macro: setq-connection-local [symbol form]… ¶

This macro sets each symbol connection-locally to the result of evaluating the corresponding form, using the connection-local profile specified in connection-local-profile-name-for-setq; if the profile name is nil, this macro will just set the variables normally, as with setq (see Setting Variable Values).

For example, you can use this macro in combination with with-connection-local-variables or with-connection-local-application-variables to lazily initialize connection-local settings:

(defvar my-app-variable nil)

(connection-local-set-profile-variables
 'my-app-connection-default-profile
 '((my-app-variable . nil)))

(connection-local-set-profiles
 '(:application my-app)
 'my-app-connection-default-profile)

(defun my-app-get-variable ()
  (with-connection-local-application-variables 'my-app
    (or my-app-variable
        (setq-connection-local my-app-variable
                               do something useful))))

Variable: connection-local-profile-name-for-setq ¶

The connection-local profile name, a symbol, to use when setting variables via setq-connection-local. This is let-bound in the body of with-connection-local-variables, but you can also let-bind it yourself if you’d like to set variables on a different profile.

This variable must not be changed globally.

Macro: connection-local-p symbol &optional application ¶

This macro returns non-nil if symbol has a connection-local binding for application. If application is nil, the value of connection-local-default-application is used.

Macro: connection-local-value symbol &optional application ¶

This macro returns the connection-local value of symbol for application. If application is nil, the value of connection-local-default-application is used.

If symbol does not have a connection-local binding, the value is the default binding of the variable.

Variable: enable-connection-local-variables ¶

If nil, connection-local variables are ignored. This variable shall be changed temporarily only in special modes.