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.

The difference to with-connection-local{-application}-variables is, that symbol is not set buffer-local. A typical usage pattern is to use only the the connection value of a variable if it exists, and not to use its default value otherwise (using my-app-variable initialized above):

(if (connection-local-p my-app-variable 'my-app)
    (connection-local-value my-app-variable 'my-app)
  ;; Something else.
  )

Variable: enable-connection-local-variables

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