Add new Tramp method "flatpak"

* doc/misc/tramp.texi (Inline methods): Add flatpak.

* etc/NEWS: Add new Tramp method "flatpak".  Fix typos.

* lisp/net/tramp-container.el (tramp-flatpak-program): New defcustom.
(tramp-flatpak-method): New defconst.
(tramp-flatpak--completion-function): New defun.  Set it for "flatpak".
(tramp-methods) <flatpak>: Add.
(tramp-container-connection-local-default-flatpak-variables):
New defconst.  Set respective connection-local variables.

4 files changed, 106 insertions, 17 deletions

diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 65892f8621e..247d718b59a 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -938,6 +938,16 @@ be used.
 
 This method does not support user names.
 
+@item @option{flatpak}
+@cindex method @option{flatpak}
+@cindex @option{flatpak} method
+
+Integration of Flatpak sandboxes.  The host name may be either an
+application ID, a sandbox instance ID, or a PID, as returned by
+@samp{flatpak ps}.
+
+This method does not support user names.
+
 @end table
 
 
diff --git a/etc/NEWS b/etc/NEWS
index 1d5f2b13958..ca529be7aa1 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -67,9 +67,10 @@ This is used for displaying the time and date components of
 'display-time-mode'.
 
 ---
-** New icon images for general use
-Several symbolic icons are added to etc/images/symbols, including
+** New icon images for general use.
+Several symbolic icons are added to "etc/images/symbols", including
 plus, minus, check-mark, start, etc.
+
 
 * Editing Changes in Emacs 30.1
 
@@ -104,7 +105,7 @@ If you want to get back the old behavior, set the user option to the value
     (setopt gdb-locals-table-row-config
             `((type . 0) (name . 0) (value . ,gdb-locals-value-limit)))
 
-** Compile
+** Grep
 
 *** New user option 'grep-use-headings'.
 When non-nil, the output of Grep is split into sections, one for each
@@ -203,16 +204,18 @@ point is not in a comment or a string.  It is by default bound to
 ** Tramp
 
 +++
-*** New connection method "toolbox".
-This allows accessing system containers provided by Toolbox.
+*** New connection methods "toolbox" and "flatpak".
+They allow accessing system containers provided by Toolbox or
+sandboxes provided by Flatpak.
 
 +++
-*** Rename 'tramp-use-ssh-controlmaster-options' to 'tramp-use-connection-share.
-The old name still exists as defvaralias.  This user option controls
-now connection sharing for both ssh-based and plink-based methods.  It
-allows the values t, nil, and 'suppress'.  The latter suppresses
-also "ControlMaster" settings in the user's "~/.ssh/config" file,
-or connection share configuration in PuTTY sessions, respectively.
+*** Rename 'tramp-use-ssh-controlmaster-options' to 'tramp-use-connection-share'.
+The old name still exists as obsolete variable alias.  This user
+option controls now connection sharing for both ssh-based and
+plink-based methods.  It allows the values t, nil, and 'suppress'.
+The latter suppresses also "ControlMaster" settings in the user's
+"~/.ssh/config" file, or connection share configuration in PuTTY
+sessions, respectively.
 
 ** EWW
 
@@ -280,7 +283,7 @@ distracting and easily confused with actual code, or a significant
 early aid that relieves you from moving the buffer or reaching for the
 mouse to consult an error message.
 
-** Python mode
+** Python Mode
 
 ---
 *** New user option 'python-indent-block-paren-deeper'.
diff --git a/lisp/net/tramp-adb.el b/lisp/net/tramp-adb.el
index 14c63ba5834..3f3fb1ea6b3 100644
--- a/lisp/net/tramp-adb.el
+++ b/lisp/net/tramp-adb.el
@@ -1311,6 +1311,7 @@ connection if a previous connection has died for some reason."
             (tramp-set-connection-property p "connected" t)))))))
 
 ;;; Default connection-local variables for Tramp.
+
 (defconst tramp-adb-connection-local-default-shell-variables
   '((shell-file-name . "/system/bin/sh")
     (shell-command-switch . "-c"))
diff --git a/lisp/net/tramp-container.el b/lisp/net/tramp-container.el
index 5ae9ebaefb2..473cb1c54b8 100644
--- a/lisp/net/tramp-container.el
+++ b/lisp/net/tramp-container.el
@@ -47,9 +47,9 @@
 ;;     C-x C-f /kubernetes:POD:/path/to/file
 ;;
 ;; Where:
-;;     POD     is the pod to connect to.
-;;             By default, the first container in that pod will be
-;;             used.
+;;     POD      is the pod to connect to.
+;;              By default, the first container in that pod will be
+;;              used.
 ;;
 ;; Completion for POD and accessing it operate in the current
 ;; namespace, use this command to change it:
@@ -58,7 +58,7 @@
 ;;
 ;;
 ;;
-;; Open a file on an existing toolbox container via Toolbox:
+;; Open a file on an existing Toolbox container:
 ;;
 ;;     C-x C-f /toolbox:CONTAINER:/path/to/file
 ;;
@@ -67,6 +67,16 @@
 ;;
 ;; If the container is not running, it is started.  If no container is
 ;; specified, the default Toolbox container is used.
+;;
+;;
+;;
+;; Open a file on a running Flatpak sandbox:
+;;
+;;     C-x C-f /flatpak:SANDBOX:/path/to/file
+;;
+;; Where:
+;;     SANDBOX  is the running sandbox to connect to.
+;;              It could be an application ID, an instance ID, or a PID.
 
 ;;; Code:
 
@@ -105,6 +115,14 @@
                  (string)))
 
 ;;;###tramp-autoload
+(defcustom tramp-flatpak-program "flatpak"
+  "Name of the Flatpak client program."
+  :group 'tramp
+  :version "30.1"
+  :type '(choice (const "flatpak")
+                 (string)))
+
+;;;###tramp-autoload
 (defconst tramp-docker-method "docker"
   "Tramp method name to use to connect to Docker containers.")
 
@@ -121,6 +139,10 @@
   "Tramp method name to use to connect to Toolbox containers.")
 
 ;;;###tramp-autoload
+(defconst tramp-flatpak-method "flatpak"
+  "Tramp method name to use to connect to Flatpak sandboxes.")
+
+;;;###tramp-autoload
 (defun tramp-container--completion-function (program)
   "List running containers available for connection.
 PROGRAM is the program to be run for \"ps\", either
@@ -196,6 +218,30 @@ see its function help for a description of the format."
     (mapcar (lambda (name) (list nil name)) (delq nil names))))
 
 ;;;###tramp-autoload
+(defun tramp-flatpak--completion-function (&rest _args)
+  "List Flatpak sandboxes available for connection.
+It returns application IDs or, in case there is no application
+ID, instance IDs.
+
+This function is used by `tramp-set-completion-function', please
+see its function help for a description of the format."
+  (when-let ((default-directory tramp-compat-temporary-file-directory)
+             (raw-list
+              (shell-command-to-string
+               (concat tramp-flatpak-program
+                       " ps --columns=instance,application")))
+             (lines (split-string raw-list "\n" 'omit))
+             (names (mapcar
+                     (lambda (line)
+                       (when (string-match
+                              (rx bol (* space) (group (+ (not space)))
+                                  (? (+ space) (group (+ (not space)))) eol)
+                              line)
+                         (or (match-string 2 line) (match-string 1 line))))
+                     lines)))
+    (mapcar (lambda (name) (list nil name)) (delq nil names))))
+
+;;;###tramp-autoload
 (defvar tramp-default-remote-shell) ;; Silence byte compiler.
 
 ;;;###tramp-autoload
@@ -253,6 +299,17 @@ see its function help for a description of the format."
 
  (add-to-list 'tramp-default-host-alist `(,tramp-toolbox-method nil ""))
 
+ (add-to-list 'tramp-methods
+              `(,tramp-flatpak-method
+                (tramp-login-program ,tramp-flatpak-program)
+                (tramp-login-args (("enter")
+                                   ("%h")
+                                   ("%l")))
+                (tramp-direct-async (,tramp-default-remote-shell "-c"))
+                (tramp-remote-shell ,tramp-default-remote-shell)
+                (tramp-remote-shell-login ("-l"))
+                (tramp-remote-shell-args ("-c"))))
+
  (tramp-set-completion-function
   tramp-docker-method
   `((tramp-container--completion-function
@@ -269,7 +326,25 @@ see its function help for a description of the format."
 
  (tramp-set-completion-function
   tramp-toolbox-method
-  '((tramp-toolbox--completion-function ""))))
+  '((tramp-toolbox--completion-function "")))
+
+ (tramp-set-completion-function
+  tramp-flatpak-method
+  '((tramp-flatpak--completion-function "")))
+
+ ;; Default connection-local variables for Tramp.
+
+ (defconst tramp-container-connection-local-default-flatpak-variables
+   `((tramp-remote-path  . ,(cons "/app/bin" tramp-remote-path)))
+   "Default connection-local variables for remote flatpak connections.")
+
+ (connection-local-set-profile-variables
+  'tramp-container-connection-local-default-flatpak-profile
+  tramp-container-connection-local-default-flatpak-variables)
+
+ (connection-local-set-profiles
+  `(:application tramp :protocol ,tramp-flatpak-method)
+  'tramp-container-connection-local-default-flatpak-profile))
 
 (add-hook 'tramp-unload-hook
           (lambda ()