From: Matthias Meulien Date: Fri, 30 Sep 2022 20:46:35 +0000 (+0200) Subject: Rename osc.el to ansi-osc.el (bug#58200) X-Git-Tag: emacs-29.0.90~1856^2~108 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=abc955d017cc4e6ad33d06d61f8317bd2b6c380f;p=emacs.git Rename osc.el to ansi-osc.el (bug#58200) * lisp/osc.el: Move from here... * lisp/ansi-osc.el: ...to here. * test/lisp/osc-tests.el: Move from here... * test/lisp/ansi-osc-tests.el: ...to here. --- diff --git a/etc/NEWS b/etc/NEWS index b9c4ef62ceb..ec23f10b1fe 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -2577,12 +2577,12 @@ Enabling this minor mode turns on hiding header material, like 'elide-head' does; disabling it shows the header. The commands 'elide-head' and 'elide-head-show' are now obsolete. -*** New package osc.el. +*** New package ansi-osc.el. Support for OSC ("Operating System Command") escape sequences has been extracted from comint.el in order to provide interpretation of OSC sequences in compilation buffers. -Adding the new function 'osc-compilation-filter' to +Adding the new function 'ansi-osc-compilation-filter' to 'compilation-filter-hook' enables interpretation of OSC escape sequences in compilation buffers. By default, all sequences are filtered out. diff --git a/lisp/ansi-osc.el b/lisp/ansi-osc.el new file mode 100644 index 00000000000..67a85516281 --- /dev/null +++ b/lisp/ansi-osc.el @@ -0,0 +1,192 @@ +;;; ansi-osc.el --- Support for OSC escape sequences -*- lexical-binding: t; -*- + +;; Copyright (C) 2022 Free Software Foundation, Inc. + +;; Author: Augusto Stoffel +;; Matthias Meulien +;; Maintainer: emacs-devel@gnu.org +;; Keywords: processes, terminals, services + +;; This program is free software; you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published by +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; This program is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. + +;; You should have received a copy of the GNU General Public License +;; along with this program. If not, see . + +;;; Commentary: + +;; Interpretation of OSC (Operating System Commands) escape sequences. +;; Handlers for OSC 2, 7 and 8 (for window title, current directory +;; and hyperlinks respectively) are provided. + +;; The function `ansi-osc-compilation-filter' can be added to +;; `compilation-filter-hook' to collect OSC sequences in compilation +;; buffers. The variable `ansi-osc-for-compilation-buffer' tells what +;; to do with collected sequences. + +;;; Code: + +(defconst ansi-osc-control-seq-regexp + ;; See ECMA 48, section 8.3.89 "OSC - OPERATING SYSTEM COMMAND". + "\e\\][\x08-\x0D]*[\x20-\x7E]*\\(\a\\|\e\\\\\\)" + "Regexp matching an OSC control sequence.") + +(defun ansi-osc-filter-region (begin end) + "Filter out all OSC control sequences from region between BEGIN and END." + (save-excursion + (goto-char begin) + ;; Delete escape sequences. + (while (re-search-forward ansi-osc-control-seq-regexp end t) + (delete-region (match-beginning 0) (match-end 0))))) + +(defvar-local ansi-osc-handlers '(("2" . ansi-osc-window-title-handler) + ("7" . ansi-osc-directory-tracker) + ("8" . ansi-osc-hyperlink-handler)) + "Alist of handlers for OSC escape sequences. +See `ansi-osc-apply-on-region' for details.") + +(defvar-local ansi-osc--marker nil) +;; The function `ansi-osc-apply-on-region' can set `ansi-osc--marker' +;; to the start position of an escape sequence without termination. + +(defun ansi-osc-apply-on-region (begin end) + "Interpret OSC escape sequences in region between BEGIN and END. +This function searches for escape sequences of the forms + + ESC ] command ; text BEL + ESC ] command ; text ESC \\ + +Every occurrence of such escape sequences is removed from the +buffer. Then, if `command' is a key in the alist that is the +value of the local variable `ansi-osc-handlers', that key's +value, which should be a function, is called with `command' and +`text' as arguments, with point where the escape sequence was +located." + (save-excursion + (goto-char (or ansi-osc--marker begin)) + (when (eq (char-before) ?\e) (backward-char)) + (while (re-search-forward "\e]" end t) + (let ((pos0 (match-beginning 0)) + (code (and (re-search-forward "\\=\\([0-9A-Za-z]*\\);" end t) + (match-string 1))) + (pos1 (point))) + (if (re-search-forward "\a\\|\e\\\\" end t) + (let ((text (buffer-substring-no-properties + pos1 (match-beginning 0)))) + (setq ansi-osc--marker nil) + (delete-region pos0 (point)) + (when-let ((fun (cdr (assoc-string code ansi-osc-handlers)))) + (funcall fun code text))) + (put-text-property pos0 end 'invisible t) + (setq ansi-osc--marker (copy-marker pos0))))))) + +;; Window title handling (OSC 2) + +(defvar-local ansi-osc-window-title nil) +(defun ansi-osc-window-title-handler (_ text) + "Set value of `ansi-osc-window-title' from an OSC 2 escape sequence. +The variable `ansi-osc-window-title' can then be referenced in +`frame-title-format' to dynamically set the frame title. + +This function is intended to be included as an element of the +list that is the value of `ansi-osc-handlers'." + (setq ansi-osc-window-title text)) + +;; Current directory tracking (OSC 7) + +(declare-function url-host "url/url-parse.el") +(declare-function url-type "url/url-parse.el") +(declare-function url-filename "url/url-parse.el") +(defun ansi-osc-directory-tracker (_ text) + "Update `default-directory' from OSC 7 escape sequences. + +This function is intended to be included as an element of the +the list that is the value of `ansi-osc-handlers'. You should arrange +for your shell to print the appropriate escape sequence at each prompt, +such as with the following command: + + printf \"\\e]7;file://%s%s\\e\\\\\" \"$HOSTNAME\" \"$PWD\" + +This functionality serves as an alternative to `dirtrack-mode' +and `shell-dirtrack-mode'." + (let ((url (url-generic-parse-url text))) + (when (and (string= (url-type url) "file") + (or (null (url-host url)) + (string= (url-host url) (system-name)))) + (ignore-errors + (cd-absolute (url-unhex-string (url-filename url))))))) + +;; Hyperlink handling (OSC 8) + +(defvar ansi-osc-hyperlink-map + (let ((map (make-sparse-keymap))) + (define-key map "\C-c\r" 'browse-url-button-open) + (define-key map [mouse-2] 'browse-url-button-open) + (define-key map [follow-link] 'mouse-face) + map) + "Keymap used by OSC 8 hyperlink buttons.") + +(define-button-type 'ansi-osc-hyperlink + 'keymap ansi-osc-hyperlink-map + 'help-echo (lambda (_ buffer pos) + (when-let ((url (get-text-property pos 'browse-url-data buffer))) + (format "mouse-2, C-c RET: Open %s" url)))) + +(defvar-local ansi-osc-hyperlink--state nil) + +(defun ansi-osc-hyperlink-handler (_ text) + "Create a hyperlink from an OSC 8 escape sequence. +This function is intended to be included as an elemnt of the list +that is the value of `ansi-osc-handlers'." + (when ansi-osc-hyperlink--state + (let ((start (car ansi-osc-hyperlink--state)) + (url (cdr ansi-osc-hyperlink--state))) + (make-text-button start (point) + 'type 'ansi-osc-hyperlink + 'browse-url-data url))) + (setq ansi-osc-hyperlink--state + (and (string-match ";\\(.+\\)" text) + (cons (point-marker) (match-string-no-properties 1 text))))) + +(defcustom ansi-osc-for-compilation-buffer 'filter + "What to do with OSC escape sequences in compilation output. + +If nil, do nothing. + +If the symbol `filter', then filter out all OSC control sequences. + +If any other non-nil value, then collect OSC control sequences +and call the appropriate handlers as described in `ansi-osc-handlers'. + +In order for this to have any effect, `ansi-osc-compilation-filter' +must be in `compilation-filter-hook'." + :type '(choice (const :tag "Do nothing" nil) + (const :tag "Filter out OSC" filter) + (other :tag "Translate OSC" t)) + :group 'osc + :version "29.1") + +(defvar compilation-filter-start) + +;;;###autoload +(defun ansi-osc-compilation-filter () + "Maybe collect OSC control sequences. +This function depends on the variable `ansi-osc-for-compilation-buffer', +and is meant to be used in `compilation-filter-hook'." + (let ((inhibit-read-only t)) + (pcase ansi-osc-for-compilation-buffer + ('nil nil) + ('filter + (ansi-osc-filter-region compilation-filter-start (point))) + (_ + (ansi-osc-apply-on-region compilation-filter-start (point)))))) + +(provide 'ansi-osc) +;;; ansi-osc.el ends here diff --git a/lisp/comint.el b/lisp/comint.el index a70a75c6487..b1f3ad8259d 100644 --- a/lisp/comint.el +++ b/lisp/comint.el @@ -103,7 +103,7 @@ (require 'ring) (require 'ansi-color) -(require 'osc) +(require 'ansi-osc) (require 'regexp-opt) ;For regexp-opt-charset. (eval-when-compile (require 'subr-x)) @@ -3918,11 +3918,11 @@ REGEXP-GROUP is the regular expression group in REGEXP to use." ;; sequences. ;; Aliases defined for reverse compatibility -(defvaralias 'comint-osc-handlers 'osc-handlers) -(defalias 'comint-osc-directory-tracker 'osc-directory-tracker) -(defalias 'comint-osc-hyperlink-handler 'osc-hyperlink-handler) -(defalias 'comint-osc-hyperlink 'osc-hyperlink) -(defvaralias 'comint-osc-hyperlink-map 'osc-hyperlink-map) +(defvaralias 'comint-osc-handlers 'ansi-osc-handlers) +(defalias 'comint-osc-directory-tracker 'ansi-osc-directory-tracker) +(defalias 'comint-osc-hyperlink-handler 'ansi-osc-hyperlink-handler) +(defalias 'comint-osc-hyperlink 'ansi-osc-hyperlink) +(defvaralias 'comint-osc-hyperlink-map 'ansi-osc-hyperlink-map) (defun comint-osc-process-output (_) "Interpret OSC escape sequences in comint output. @@ -3941,7 +3941,7 @@ arguments, with point where the escape sequence was located." (let ((start (1- comint-last-output-start)) ;; Start one char before last output to catch a possibly stray ESC (bound (process-mark (get-buffer-process (current-buffer))))) - (osc-apply-on-region start bound))) + (ansi-osc-apply-on-region start bound))) ;;; Input fontification and indentation through an indirect buffer diff --git a/lisp/osc.el b/lisp/osc.el deleted file mode 100644 index 14f7fe6a4f3..00000000000 --- a/lisp/osc.el +++ /dev/null @@ -1,191 +0,0 @@ -;;; osc.el --- Support for OSC escape sequences -*- lexical-binding: t; -*- - -;; Copyright (C) 2022 Free Software Foundation, Inc. - -;; Author: Augusto Stoffel -;; Matthias Meulien -;; Maintainer: emacs-devel@gnu.org -;; Keywords: processes, terminals, services - -;; This program is free software; you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; This program is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with this program. If not, see . - -;;; Commentary: - -;; Interpretation of OSC (Operating System Commands) escape sequences. -;; Handlers for OSC 2, 7 and 8 (for window title, current directory -;; and hyperlinks respectively) are provided. - -;; The function `osc-compilation-filter' can be added to -;; `compilation-filter-hook' to collect OSC sequences in compilation -;; buffers. The variable `osc-for-compilation-buffer' tells what to -;; do with collected sequences. - -;;; Code: - -(defconst osc-control-seq-regexp - ;; See ECMA 48, section 8.3.89 "OSC - OPERATING SYSTEM COMMAND". - "\e\\][\x08-\x0D]*[\x20-\x7E]*\\(\a\\|\e\\\\\\)" - "Regexp matching an OSC control sequence.") - -(defun osc-filter-region (begin end) - "Filter out all OSC control sequences from region between BEGIN and END." - (save-excursion - (goto-char begin) - ;; Delete escape sequences. - (while (re-search-forward osc-control-seq-regexp end t) - (delete-region (match-beginning 0) (match-end 0))))) - -(defvar-local osc-handlers '(("2" . osc-window-title-handler) - ("7" . osc-directory-tracker) - ("8" . osc-hyperlink-handler)) - "Alist of handlers for OSC escape sequences. -See `osc-apply-on-region' for details.") - -(defvar-local osc--marker nil) -;; The function `osc-apply-on-region' can set `osc--marker' to the start -;; position of an escape sequence without termination. - -(defun osc-apply-on-region (begin end) - "Interpret OSC escape sequences in region between BEGIN and END. -This function searches for escape sequences of the forms - - ESC ] command ; text BEL - ESC ] command ; text ESC \\ - -Every occurrence of such escape sequences is removed from the -buffer. Then, if `command' is a key in the alist that is the value -of the local variable `osc-handlers', that key's value, which should -be a function, is called with `command' and `text' as arguments, with -point where the escape sequence was located." - (save-excursion - (goto-char (or osc--marker begin)) - (when (eq (char-before) ?\e) (backward-char)) - (while (re-search-forward "\e]" end t) - (let ((pos0 (match-beginning 0)) - (code (and (re-search-forward "\\=\\([0-9A-Za-z]*\\);" end t) - (match-string 1))) - (pos1 (point))) - (if (re-search-forward "\a\\|\e\\\\" end t) - (let ((text (buffer-substring-no-properties - pos1 (match-beginning 0)))) - (setq osc--marker nil) - (delete-region pos0 (point)) - (when-let ((fun (cdr (assoc-string code osc-handlers)))) - (funcall fun code text))) - (put-text-property pos0 end 'invisible t) - (setq osc--marker (copy-marker pos0))))))) - -;; Window title handling (OSC 2) - -(defvar-local osc-window-title nil) -(defun osc-window-title-handler (_ text) - "Set value of `osc-window-title' from an OSC 2 escape sequence. -The variable `osc-window-title' can then be referenced in -`frame-title-format' to dynamically set the frame title. - -This function is intended to be included as an element of the -list that is the value of `osc-handlers'." - (setq osc-window-title text)) - -;; Current directory tracking (OSC 7) - -(declare-function url-host "url/url-parse.el") -(declare-function url-type "url/url-parse.el") -(declare-function url-filename "url/url-parse.el") -(defun osc-directory-tracker (_ text) - "Update `default-directory' from OSC 7 escape sequences. - -This function is intended to be included as an element of the -the list that is the value of `osc-handlers'. You should arrange -for your shell to print the appropriate escape sequence at each prompt, -such as with the following command: - - printf \"\\e]7;file://%s%s\\e\\\\\" \"$HOSTNAME\" \"$PWD\" - -This functionality serves as an alternative to `dirtrack-mode' -and `shell-dirtrack-mode'." - (let ((url (url-generic-parse-url text))) - (when (and (string= (url-type url) "file") - (or (null (url-host url)) - (string= (url-host url) (system-name)))) - (ignore-errors - (cd-absolute (url-unhex-string (url-filename url))))))) - -;; Hyperlink handling (OSC 8) - -(defvar osc-hyperlink-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\r" 'browse-url-button-open) - (define-key map [mouse-2] 'browse-url-button-open) - (define-key map [follow-link] 'mouse-face) - map) - "Keymap used by OSC 8 hyperlink buttons.") - -(define-button-type 'osc-hyperlink - 'keymap osc-hyperlink-map - 'help-echo (lambda (_ buffer pos) - (when-let ((url (get-text-property pos 'browse-url-data buffer))) - (format "mouse-2, C-c RET: Open %s" url)))) - -(defvar-local osc-hyperlink--state nil) - -(defun osc-hyperlink-handler (_ text) - "Create a hyperlink from an OSC 8 escape sequence. -This function is intended to be included as an elemnt of the list -that is the value of `osc-handlers'." - (when osc-hyperlink--state - (let ((start (car osc-hyperlink--state)) - (url (cdr osc-hyperlink--state))) - (make-text-button start (point) - 'type 'osc-hyperlink - 'browse-url-data url))) - (setq osc-hyperlink--state - (and (string-match ";\\(.+\\)" text) - (cons (point-marker) (match-string-no-properties 1 text))))) - -(defcustom osc-for-compilation-buffer 'filter - "What to do with OSC escape sequences in compilation output. - -If nil, do nothing. - -If the symbol `filter', then filter out all OSC control sequences. - -If any other non-nil value, then collect OSC control sequences -and call the appropriate handlers as described in `osc-handlers'. - -In order for this to have any effect, `osc-compilation-filter' -must be in `compilation-filter-hook'." - :type '(choice (const :tag "Do nothing" nil) - (const :tag "Filter out OSC" filter) - (other :tag "Translate OSC" t)) - :group 'osc - :version "29.1") - -(defvar compilation-filter-start) - -;;;###autoload -(defun osc-compilation-filter () - "Maybe collect OSC control sequences. -This function depends on the variable `osc-for-compilation-buffer', -and is meant to be used in `compilation-filter-hook'." - (let ((inhibit-read-only t)) - (pcase osc-for-compilation-buffer - ('nil nil) - ('filter - (osc-filter-region compilation-filter-start (point))) - (_ - (osc-apply-on-region compilation-filter-start (point)))))) - -(provide 'osc) -;;; osc.el ends here diff --git a/test/lisp/ansi-osc-tests.el b/test/lisp/ansi-osc-tests.el new file mode 100644 index 00000000000..b3d66fb036c --- /dev/null +++ b/test/lisp/ansi-osc-tests.el @@ -0,0 +1,57 @@ +;;; osc-tests.el --- Tests for osc.el -*- lexical-binding: t; -*- + +;; Copyright (C) 2022 Free Software Foundation, Inc. + +;; Author: Matthias Meulien +;; Keywords: + +;; This file is part of GNU Emacs. + +;; GNU Emacs is free software: you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published by +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. + +;; You should have received a copy of the GNU General Public License +;; along with GNU Emacs. If not, see . + +;;; Commentary: + +;; + +;;; Code: + +(require 'ansi-osc) +(require 'ert) + +(defvar ansi-osc-tests--strings + `( + ("Hello World" "Hello World") + + ;; window title + ("Buffer \e]2;A window title\e\\content" "Buffer content") + + ;; window title + ("Unfinished \e]2;window title" "Unfinished \e]2;window title") + + ;; current directory + ("\e]7;file://127.0.0.1/tmp\e\\user@host$ " "user@host$ ") + + ;; hyperlink + ("\e]8;;http://example.com\e\\This is a link\e]8;;\e\\" "This is a link") + )) +;; Don't output those strings to stdout since they may have +;; side-effects on the environment + +(ert-deftest ansi-osc-tests-apply-region-no-handlers () + (let ((ansi-osc-handlers nil)) + (pcase-dolist (`(,input ,text) ansi-osc-tests--strings) + (with-temp-buffer + (insert input) + (ansi-osc-apply-on-region (point-min) (point-max)) + (should (equal (buffer-string) text)))))) diff --git a/test/lisp/osc-tests.el b/test/lisp/osc-tests.el deleted file mode 100644 index d53bab08d3d..00000000000 --- a/test/lisp/osc-tests.el +++ /dev/null @@ -1,57 +0,0 @@ -;;; osc-tests.el --- Tests for osc.el -*- lexical-binding: t; -*- - -;; Copyright (C) 2022 Free Software Foundation, Inc. - -;; Author: Matthias Meulien -;; Keywords: - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;; - -;;; Code: - -(require 'osc) -(require 'ert) - -(defvar osc-tests--strings - `( - ("Hello World" "Hello World") - - ;; window title - ("Buffer \e]2;A window title\e\\content" "Buffer content") - - ;; window title - ("Unfinished \e]2;window title" "Unfinished \e]2;window title") - - ;; current directory - ("\e]7;file://127.0.0.1/tmp\e\\user@host$ " "user@host$ ") - - ;; hyperlink - ("\e]8;;http://example.com\e\\This is a link\e]8;;\e\\" "This is a link") - )) -;; Don't output those strings to stdout since they may have -;; side-effects on the environment - -(ert-deftest osc-tests-apply-region-no-handlers () - (let ((osc-handlers nil)) - (pcase-dolist (`(,input ,text) osc-tests--strings) - (with-temp-buffer - (insert input) - (osc-apply-on-region (point-min) (point-max)) - (should (equal (buffer-string) text))))))