gnu.org (original) (raw)

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 inconnection-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 tocriteria, 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 inwith-connection-local-variables, connection-local-p andconnection-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 towith-connection-local-application-variables, but usesconnection-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 withwith-connection-local-variables orwith-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 applicationis nil, the value ofconnection-local-default-application is used.

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

This macro returns the connection-local value of symbol forapplication. If application is nil, the value ofconnection-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.