Function: tramp-dissect-file-name

tramp-dissect-file-name is an autoloaded and byte-compiled function defined in tramp.el.gz.

Signature

(tramp-dissect-file-name NAME &optional NODEFAULT)

Documentation

Return a tramp-file-name structure of NAME, a remote file name.

The structure consists of method, user, domain, host, port, localname (file name on remote host), and hop.

Unless NODEFAULT is non-nil, method, user and host are expanded to their default values. For the other file name parts, no default values are used.

Probably introduced at or before Emacs version 29.1.

Source Code

;; Defined in /usr/src/emacs/lisp/net/tramp.el.gz
;;;###tramp-autoload
(defun tramp-dissect-file-name (name &optional nodefault)
  "Return a `tramp-file-name' structure of NAME, a remote file name.
The structure consists of method, user, domain, host, port,
localname (file name on remote host), and hop.

Unless NODEFAULT is non-nil, method, user and host are expanded
to their default values.  For the other file name parts, no
default values are used."
  ;; (declare (tramp-suppress-trace t))
  (save-match-data
    (unless (tramp-tramp-file-p name)
      (tramp-user-error nil "Not a Tramp file name: \"%s\"" name))
    (if (not (string-match (nth 0 tramp-file-name-structure) name))
        (error "`tramp-file-name-structure' didn't match!")
      (let ((method    (match-string (nth 1 tramp-file-name-structure) name))
	    (user      (match-string (nth 2 tramp-file-name-structure) name))
	    (host      (match-string (nth 3 tramp-file-name-structure) name))
	    (localname (match-string (nth 4 tramp-file-name-structure) name))
	    (hop       (match-string (nth 5 tramp-file-name-structure) name))
	    domain port v)
	(when user
	  (when (string-match tramp-user-with-domain-regexp user)
	    (setq domain (match-string 2 user)
		  user (match-string 1 user))))

	(when host
	  (when (string-match tramp-host-with-port-regexp host)
	    (setq port (match-string 2 host)
		  host (match-string 1 host)))
	  (when (string-match tramp-prefix-ipv6-regexp host)
	    (setq host (replace-match "" nil t host)))
	  (when (string-match tramp-postfix-ipv6-regexp host)
	    (setq host (replace-match "" nil t host))))

	(unless nodefault
	  (when hop
	    (setq v (tramp-dissect-hop-name hop)
		  hop (and hop (tramp-make-tramp-hop-name v))))
	  (let ((tramp-default-host
		 (or (and v (not (tramp-compat-string-search
				  "%h" (tramp-file-name-host v)))
			  (tramp-file-name-host v))
		     tramp-default-host)))
	    (setq method (tramp-find-method method user host)
		  user (tramp-find-user method user host)
		  host (tramp-find-host method user host)
		  hop
		  (and hop
		       (format-spec hop (format-spec-make ?h host ?u user))))))

	;; Return result.
	(prog1
	    (setq v (make-tramp-file-name
		     :method method :user user :domain domain :host host
		     :port port :localname localname :hop hop))
	  ;; The method must be known.
	  (unless (or nodefault non-essential
		      (assoc method tramp-methods))
	    (tramp-user-error
	     v "Method `%s' is not known" method))
	  ;; Only some methods from tramp-sh.el do support multi-hops.
	  (unless (or (null hop) nodefault non-essential (tramp-multi-hop-p v))
	    (tramp-user-error
	     v "Method `%s' is not supported for multi-hops" method))
	  (let (connection-local-variables-alist)
	    (hack-connection-local-variables
	     (tramp-get-connection-local-criteria v))
	    (let ((allow-double-percent
		   (alist-get
		    'tramp-allow-double-percent
		    connection-local-variables-alist
		    tramp-allow-double-percent)))
	      ;; User name could be invalid after expansion of
	      ;; environment variables, or contain a literal
	      ;; environment variable.
	      (unless (tramp-string-empty-or-nil-p user)
		(when (or (not (string-match-p tramp-user-regexp user))
			  (string-match-p
			   (rx "$") (tramp-file-name-user-domain v))
			  (and (not allow-double-percent)
			       (string-match-p
				(rx "%" (* nonl) "%")
				(tramp-file-name-user-domain v))))
		  (tramp-user-error
		   v "Not a valid user name: \"%s\""
		   (tramp-file-name-user-domain v))))
	      ;; Host name could contain a literal environment variable.
	      (unless (tramp-string-empty-or-nil-p host)
		(when (or (not (string-match-p tramp-host-regexp host))
			  (string-match-p (rx "$") host)
			  (and (not allow-double-percent)
			       (string-match-p (rx "%" (* nonl) "%") host)))
		  (tramp-user-error
		   v "Not a valid host name: \"%s\"" host))))))))))