diff options
Diffstat (limited to 'elpa/with-editor-3.4.3')
21 files changed, 2595 insertions, 0 deletions
diff --git a/elpa/with-editor-3.4.3/.github/ISSUE_TEMPLATE/bug_report.md b/elpa/with-editor-3.4.3/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..56a0c95 --- /dev/null +++ b/elpa/with-editor-3.4.3/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,20 @@ +--- +title: +name: 𪳠Bug report +about: Report a defect. Do not use this for support requests and feature suggestions. +--- + +Please explain + (1) what behavior you expected + (2) what behavior you observed + (3) and how we can reproduce the issue. + +You don't have to quote the above lines to do that. + +Please include a backtrace in your report. In most cases doing: + + M-x toggle-debug-on-error RET + +and then going through the steps again should result in a backtrace. + +---- now delete this line and everything above ---- diff --git a/elpa/with-editor-3.4.3/.github/ISSUE_TEMPLATE/config.yml b/elpa/with-editor-3.4.3/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..6cf96bc --- /dev/null +++ b/elpa/with-editor-3.4.3/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,17 @@ +blank_issues_enabled: false +contact_links: + - name: "đĄ Suggest a feature" + url: https://github.com/magit/with-editor/discussions + about: Start a discussion suggest an improvement or a new feature. + - name: "đ Ask the community for support" + url: https://www.reddit.com/r/emacs + about: Please also consider supporting others. + - name: "đ Ask the maintainers for support" + url: https://github.com/magit/with-editor/discussions + about: Please keep in mind that our bandwidth is limited. + - name: "đ˘ \"I am unable to commit with Magit\"" + url: https://magit.vc/manual/with-editor/Debugging.html + about: Others might have had the same question before. + - name: "âšď¸ With-Editor Manual" + url: https://magit.vc/manual/with-editor/#Top + about: The fine manual may also be of use. diff --git a/elpa/with-editor-3.4.3/.github/workflows/compile.yml b/elpa/with-editor-3.4.3/.github/workflows/compile.yml new file mode 100644 index 0000000..2c1a987 --- /dev/null +++ b/elpa/with-editor-3.4.3/.github/workflows/compile.yml @@ -0,0 +1,6 @@ +name: Compile +on: [push, pull_request] +jobs: + compile: + name: Compile + uses: emacscollective/workflows/.github/workflows/compile.yml@main diff --git a/elpa/with-editor-3.4.3/.github/workflows/manual.yml b/elpa/with-editor-3.4.3/.github/workflows/manual.yml new file mode 100644 index 0000000..3b02f40 --- /dev/null +++ b/elpa/with-editor-3.4.3/.github/workflows/manual.yml @@ -0,0 +1,12 @@ +name: Manual +on: + push: + branches: main + tags: "v[0-9]+.[0-9]+.[0-9]+" +jobs: + manual: + name: Manual + uses: emacscollective/workflows/.github/workflows/manual.yml@main + secrets: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} diff --git a/elpa/with-editor-3.4.3/.github/workflows/stats.yml b/elpa/with-editor-3.4.3/.github/workflows/stats.yml new file mode 100644 index 0000000..e941fb9 --- /dev/null +++ b/elpa/with-editor-3.4.3/.github/workflows/stats.yml @@ -0,0 +1,13 @@ +name: Statistics +on: + push: + branches: main + schedule: + - cron: '3 13 * * 1' +jobs: + stats: + name: Statistics + uses: emacscollective/workflows/.github/workflows/stats.yml@main + secrets: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} diff --git a/elpa/with-editor-3.4.3/CHANGELOG b/elpa/with-editor-3.4.3/CHANGELOG new file mode 100644 index 0000000..3b9809c --- /dev/null +++ b/elpa/with-editor-3.4.3/CHANGELOG @@ -0,0 +1,13 @@ +# -*- mode: org -*- +* v3.4.3 2024-12-01 + +- Added new variable ~with-editor-emacsclient-program-suffixes~. #132 + +* v3.4.2 2024-09-01 + +- Fixed ~shell-command-with-editor-mode~ for remote processes. #129 + +- ~with-editor-export-editor~ now waits longer for the terminal to get + ready. #130 + +- Updated tooling. diff --git a/elpa/with-editor-3.4.3/Makefile b/elpa/with-editor-3.4.3/Makefile new file mode 100644 index 0000000..eb41ee3 --- /dev/null +++ b/elpa/with-editor-3.4.3/Makefile @@ -0,0 +1,36 @@ +-include ../config.mk +include ../default.mk + +lisp: $(ELCS) loaddefs check-declare + +loaddefs: $(PKG)-autoloads.el + +%.elc: %.el + @printf "Compiling $<\n" + @$(EMACS) -Q --batch $(EMACS_ARGS) $(LOAD_PATH) -f batch-byte-compile $< + +check-declare: + @printf " Checking function declarations\n" + @$(EMACS) -Q --batch $(EMACS_ARGS) $(LOAD_PATH) \ + --eval "(check-declare-directory default-directory)" + +CLEAN = $(ELCS) $(PKG)-autoloads.el + +clean: + @printf " Cleaning lisp/*...\n" + @rm -rf $(CLEAN) + +$(PKG)-autoloads.el: $(ELS) + @printf " Creating $@\n" + @$(EMACS) -Q --batch -l autoload -l cl-lib --eval "\ +(let ((file (expand-file-name \"$@\"))\ + (autoload-timestamps nil) \ + (backup-inhibited t)\ + (version-control 'never)\ + (coding-system-for-write 'utf-8-emacs-unix))\ + (write-region (autoload-rubric file \"package\" nil) nil file nil 'silent)\ + (cl-letf (((symbol-function 'progress-reporter-do-update) (lambda (&rest _)))\ + ((symbol-function 'progress-reporter-done) (lambda (_))))\ + (let ((generated-autoload-file file))\ + (update-directory-autoloads default-directory))))" \ + 2>&1 | sed "/^Package autoload is deprecated$$/d" diff --git a/elpa/with-editor-3.4.3/README-elpa b/elpa/with-editor-3.4.3/README-elpa new file mode 100644 index 0000000..1824daa --- /dev/null +++ b/elpa/with-editor-3.4.3/README-elpa @@ -0,0 +1,55 @@ +1 With-Editor +âââââââââââââ + + This library makes it possible to reliably use the Emacsclient as the + `$EDITOR' of child processes. It makes sure that they know how to + call home. For remote processes a substitute is provided, which + communicates with Emacs on standard output/input instead of using a + socket as the Emacsclient does. + + It provides the commands `with-editor-async-shell-command' and + `with-editor-shell-command', which are intended as replacements for + `async-shell-command' and `shell-command'. They automatically export + `$EDITOR' making sure the executed command uses the current Emacs + instance as "the editor". With a prefix argument these commands + prompt for an alternative environment variable such as `$GIT_EDITOR'. + To always use these variants add this to your init file: + + âââââ + â (keymap-global-set "<remap> <async-shell-command>" + â #'with-editor-async-shell-command) + â (keymap-global-set "<remap> <shell-command>" + â #'with-editor-shell-command) + âââââ + + Alternatively use the global `shell-command-with-editor-mode', which + always sets `$EDITOR' for all Emacs commands which ultimately use + `shell-command' to asynchronously run some shell command. + + The command `with-editor-export-editor' exports `$EDITOR' or another + such environment variable in `shell-mode', `eshell-mode', `term-mode' + and `vterm-mode' buffers. Use this Emacs command before executing a + shell command which needs the editor set, or always arrange for the + current Emacs instance to be used as editor by adding it to the + appropriate mode hooks: + + âââââ + â (add-hook 'shell-mode-hook 'with-editor-export-editor) + â (add-hook 'eshell-mode-hook 'with-editor-export-editor) + â (add-hook 'term-exec-hook 'with-editor-export-editor) + â (add-hook 'vterm-mode-hook 'with-editor-export-editor) + âââââ + + Some variants of this function exist, these two forms are equivalent: + + âââââ + â (add-hook 'shell-mode-hook + â (apply-partially 'with-editor-export-editor "GIT_EDITOR")) + â (add-hook 'shell-mode-hook 'with-editor-export-git-editor) + âââââ + + This library can also be used by other packages which need to use the + current Emacs instance as editor. In fact this library was written + for Magit and its `git-commit-mode' and `git-rebase-mode'. Consult + `git-rebase.el' and the related code in `magit-sequence.el' for a + simple example. diff --git a/elpa/with-editor-3.4.3/README.org b/elpa/with-editor-3.4.3/README.org new file mode 100644 index 0000000..aea30cc --- /dev/null +++ b/elpa/with-editor-3.4.3/README.org @@ -0,0 +1,63 @@ +* With-Editor + +This library makes it possible to reliably use the Emacsclient as +the ~$EDITOR~ of child processes. It makes sure that they know how +to call home. For remote processes a substitute is provided, which +communicates with Emacs on standard output/input instead of using a +socket as the Emacsclient does. + +It provides the commands ~with-editor-async-shell-command~ and +~with-editor-shell-command~, which are intended as replacements +for ~async-shell-command~ and ~shell-command~. They automatically +export ~$EDITOR~ making sure the executed command uses the current +Emacs instance as "the editor". With a prefix argument these +commands prompt for an alternative environment variable such as +~$GIT_EDITOR~. To always use these variants add this to your init +file: + +#+begin_src emacs-lisp + (keymap-global-set "<remap> <async-shell-command>" + #'with-editor-async-shell-command) + (keymap-global-set "<remap> <shell-command>" + #'with-editor-shell-command) +#+end_src + +Alternatively use the global ~shell-command-with-editor-mode~, +which always sets ~$EDITOR~ for all Emacs commands which ultimately +use ~shell-command~ to asynchronously run some shell command. + +The command ~with-editor-export-editor~ exports ~$EDITOR~ or +another such environment variable in ~shell-mode~, ~eshell-mode~, +~term-mode~ and ~vterm-mode~ buffers. Use this Emacs command +before executing a shell command which needs the editor set, or +always arrange for the current Emacs instance to be used as editor +by adding it to the appropriate mode hooks: + +#+begin_src emacs-lisp + (add-hook 'shell-mode-hook 'with-editor-export-editor) + (add-hook 'eshell-mode-hook 'with-editor-export-editor) + (add-hook 'term-exec-hook 'with-editor-export-editor) + (add-hook 'vterm-mode-hook 'with-editor-export-editor) +#+end_src + +Some variants of this function exist, these two forms are +equivalent: + +#+begin_src emacs-lisp + (add-hook 'shell-mode-hook + (apply-partially 'with-editor-export-editor "GIT_EDITOR")) + (add-hook 'shell-mode-hook 'with-editor-export-git-editor) +#+end_src + +This library can also be used by other packages which need to use +the current Emacs instance as editor. In fact this library was +written for Magit and its ~git-commit-mode~ and ~git-rebase-mode~. +Consult ~git-rebase.el~ and the related code in ~magit-sequence.el~ +for a simple example. + +#+html: <br><br> +#+html: <a href="https://github.com/magit/with-editor/actions/workflows/compile.yml"><img alt="Compile" src="https://github.com/magit/with-editor/actions/workflows/compile.yml/badge.svg"/></a> +#+html: <a href="https://github.com/magit/with-editor/actions/workflows/manual.yml"><img alt="Manual" src="https://github.com/magit/with-editor/actions/workflows/manual.yml/badge.svg"/></a> +#+html: <a href="https://elpa.nongnu.org/nongnu/with-editor.html"><img alt="NonGNU ELPA" src="https://emacsair.me/assets/badges/nongnu-elpa.svg"/></a> +#+html: <a href="https://stable.melpa.org/#/with-editor"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/with-editor-badge.svg"/></a> +#+html: <a href="https://melpa.org/#/with-editor"><img alt="MELPA" src="https://melpa.org/packages/with-editor-badge.svg"/></a> diff --git a/elpa/with-editor-3.4.3/default.mk b/elpa/with-editor-3.4.3/default.mk new file mode 100644 index 0000000..0577715 --- /dev/null +++ b/elpa/with-editor-3.4.3/default.mk @@ -0,0 +1,34 @@ +TOP := $(dir $(lastword $(MAKEFILE_LIST))) + +PKG = with-editor + +ELS = $(PKG).el +ELCS = $(ELS:.el=.elc) + +DEPS = compat +DEPS += vterm + +DOMAIN ?= magit.vc +CFRONT_DIST ?= E2LUHBKU1FBV02 + +VERSION ?= $(shell test -e $(TOP).git && git describe --tags --abbrev=0 | cut -c2-) +REVDESC := $(shell test -e $(TOP).git && git describe --tags) + +EMACS ?= emacs +EMACS_ARGS ?= +EMACS_ARGS += --eval '(setq with-editor-emacsclient-executable nil)' + +LOAD_PATH ?= $(addprefix -L ../../,$(DEPS)) +LOAD_PATH += -L . + +ifndef ORG_LOAD_PATH +ORG_LOAD_PATH = -L ../../org/lisp +endif + +INSTALL_INFO ?= $(shell command -v ginstall-info || printf install-info) +MAKEINFO ?= makeinfo +MANUAL_HTML_ARGS ?= --css-ref /assets/page.css + +GITSTATS ?= gitstats +GITSTATS_DIR ?= $(TOP)docs/stats +GITSTATS_ARGS ?= -c style=https://magit.vc/assets/stats.css -c max_authors=999 diff --git a/elpa/with-editor-3.4.3/dir b/elpa/with-editor-3.4.3/dir new file mode 100644 index 0000000..c5810e0 --- /dev/null +++ b/elpa/with-editor-3.4.3/dir @@ -0,0 +1,18 @@ +This is the file .../info/dir, which contains the +topmost node of the Info hierarchy, called (dir)Top. +The first time you invoke Info you start off looking at this node. + +File: dir, Node: Top This is the top of the INFO tree + + This (the Directory node) gives a menu of major topics. + Typing "q" exits, "H" lists all Info commands, "d" returns here, + "h" gives a primer for first-timers, + "mEmacs<Return>" visits the Emacs manual, etc. + + In Emacs, you can click mouse button 2 on a menu item or cross reference + to select it. + +* Menu: + +Emacs +* With-Editor: (with-editor). Using the Emacsclient as $EDITOR. diff --git a/elpa/with-editor-3.4.3/docs/.orgconfig b/elpa/with-editor-3.4.3/docs/.orgconfig new file mode 100644 index 0000000..bdaba4a --- /dev/null +++ b/elpa/with-editor-3.4.3/docs/.orgconfig @@ -0,0 +1,18 @@ +# -*- mode:org -*- +# Copyright (C) 2021-2024 Jonas Bernoulli +# SPDX-License-Identifier: GPL-3.0-or-later +# URL: https://github.com/emacscollective/org-macros +# Visit that to see these macros in a human-readable format. + +#+language: en + +#+options: H:4 num:3 toc:2 compact-itemx:t +#+property: header-args :eval never + +#+macro: year (eval (format-time-string "%Y")) +#+macro: version (eval (if-let ((tag (ignore-errors (car (process-lines "git" "describe" "--exact-match"))))) (concat "version " (substring tag 1)) (or (ignore-errors (car (process-lines "git" "describe"))) (concat "version " (or $1 "<unknown>"))))) +#+macro: kbd (eval (format "@@texinfo:@kbd{@@%s@@texinfo:}@@" (let (case-fold-search) (replace-regexp-in-string (regexp-opt '("BS" "TAB" "RET" "ESC" "SPC" "DEL" "LFD" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt" "Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN") 'words) "@@texinfo:@key{@@\\&@@texinfo:}@@" $1 t)))) +#+macro: kbdvar (eval (format "@@texinfo:@kbd{@@%s@@texinfo:}@@" (let (case-fold-search) (replace-regexp-in-string "<\\([a-zA-Z-]+\\)>" "@@texinfo:@var{@@\\1@@texinfo:}@@" (replace-regexp-in-string (regexp-opt '("BS" "TAB" "RET" "ESC" "SPC" "DEL" "LFD" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt" "Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN") 'words) "@@texinfo:@key{@@\\&@@texinfo:}@@" $1 t) t)))) +#+macro: codevar (eval (format "@@texinfo:@code{@@%s@@texinfo:}@@" (let (case-fold-search) (replace-regexp-in-string "\\([A-Z][A-Z-]+\\)" "@@texinfo:@var{@@\\&@@texinfo:}@@" $1 t)))) +#+macro: var @@texinfo:@var{@@$1@@texinfo:}@@ +#+macro: dfn @@texinfo:@dfn{@@$1@@texinfo:}@@ diff --git a/elpa/with-editor-3.4.3/docs/Makefile b/elpa/with-editor-3.4.3/docs/Makefile new file mode 100644 index 0000000..0eaf142 --- /dev/null +++ b/elpa/with-editor-3.4.3/docs/Makefile @@ -0,0 +1,110 @@ +-include ../config.mk +include ../default.mk + +docs: texi info html html-dir pdf + +texi: $(PKG).texi +info: $(PKG).info dir +html: $(PKG).html +html-dir: $(PKG)/index.html +pdf: $(PKG).pdf + +ORG_ARGS = --batch -Q $(ORG_LOAD_PATH) +ORG_EVAL += --eval "(setq indent-tabs-mode nil)" +ORG_EVAL += --eval "(setq org-src-preserve-indentation nil)" +ORG_EVAL += --funcall org-texinfo-export-to-texinfo + +redo-docs: + @touch $(PKG).org + @make docs + +.revdesc: ; +_ := $(shell test "$(REVDESC)" = "$$(cat .revdesc 2> /dev/null)" ||\ + echo "$(REVDESC)" > .revdesc) + +%.texi: %.org .orgconfig .revdesc + @printf "Generating $@\n" + @$(EMACS) $(ORG_ARGS) $< $(ORG_EVAL) + +%.info: %.texi + @printf "Generating $@\n" + @$(MAKEINFO) --no-split $< -o $@ + +dir: $(PKG).info + @printf "Generating $@\n" + @printf "%s" $^ | xargs -n 1 $(INSTALL_INFO) --dir=$@ + +HTML_FIXUP_CSS = '/<link rel="stylesheet" type="text\/css" href="\/assets\/page.css">/a\ +<link rel="icon" href="/assets/magit_alt1.ico">\ +\n<link class="s-css-s--style" rel="stylesheet" title="Default" href="/assets/themes/default.css">\ +\n<link class="s-css-s--style" rel="stylesheet alternate" title="Default high contrast" href="/assets/themes/default-high-contrast.css">\ +\n<link class="s-css-s--style" rel="stylesheet alternate" title="Solarized dark xterm" href="/assets/themes/solarized-dark-xterm.css">\ +\n<link class="s-css-s--style" rel="stylesheet alternate" title="Black on white" href="/assets/themes/black-on-white.css">\ +\n<script src="/assets/js/simple-css-switch.js"></script>' +HTML_FIXUP_ONLOAD = 's/<body lang="en">/<body lang="en" onload="simpleCssSwitch()">/' +HTML_FIXUP_MENU = '/<\/body>/i<div id="s-css-s--menu"><\/div>' + +%.html: %.texi + @printf "Generating $@\n" + @$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) $< + @sed -i -e $(HTML_FIXUP_CSS) -e $(HTML_FIXUP_ONLOAD) -e $(HTML_FIXUP_MENU) $@ + +%/index.html: %.texi + @printf "Generating $(PKG)/*.html\n" + @rm -rf $(PKG) + @$(MAKEINFO) --html -o $(PKG)/ $(MANUAL_HTML_ARGS) $< + @for f in $$(find $(PKG) -name '*.html') ; do \ + sed -i -e $(HTML_FIXUP_CSS) -e $(HTML_FIXUP_ONLOAD) -e $(HTML_FIXUP_MENU) $$f ; \ + done + +%.pdf: %.texi + @printf "Generating $@\n" + @texi2pdf --clean $< > /dev/null + +PUBLISH_PATH ?= /manual/ +RELEASE_PATH ?= /manual/$(VERSION)/ +S3_BUCKET ?= s3://$(DOMAIN) +PUBLISH_TARGET = $(S3_BUCKET)$(PUBLISH_PATH) +RELEASE_TARGET = $(S3_BUCKET)$(RELEASE_PATH) +CFRONT_PATHS = $(PKG).html $(PKG).pdf $(PKG)/* + +comma := , +empty := +space := $(empty) $(empty) + +publish: redo-docs + @aws s3 cp $(PKG).html $(PUBLISH_TARGET) + @aws s3 cp $(PKG).pdf $(PUBLISH_TARGET) + @aws s3 sync $(PKG) $(PUBLISH_TARGET)$(PKG)/ + @printf "Generating CDN invalidation\n" + @aws cloudfront create-invalidation --distribution-id $(CFRONT_DIST) --paths \ + "$(subst $(space),$(comma),$(addprefix $(PUBLISH_PATH),$(CFRONT_PATHS)))" > /dev/null + +release: redo-docs + @aws s3 cp $(PKG).html $(RELEASE_TARGET) + @aws s3 cp $(PKG).pdf $(RELEASE_TARGET) + @aws s3 sync $(PKG) $(RELEASE_TARGET)$(PKG)/ + @aws s3 cp $(PUBLISH_TARGET)dir.html $(RELEASE_TARGET)dir.html + @aws s3 cp $(PUBLISH_TARGET)dir/index.html $(RELEASE_TARGET)dir/index.html + @printf "Generating CDN invalidation\n" + @aws cloudfront create-invalidation --distribution-id $(CFRONT_DIST) --paths \ + "$(subst $(space),$(comma),$(addprefix $(RELEASE_PATH),$(CFRONT_PATHS)))" > /dev/null + +.PHONY: stats +stats: + @printf "Generating statistics\n" + @$(GITSTATS) $(GITSTATS_ARGS) $(TOP) $(GITSTATS_DIR) + +stats-upload: + @printf "Uploading statistics...\n" + @aws s3 sync $(GITSTATS_DIR) $(S3_BUCKET)/stats/$(PKG) + @printf "Uploaded to $(S3_BUCKET)/stats/$(PKG)\n" + @printf "Generating CDN invalidation\n" + @aws cloudfront create-invalidation \ + --distribution-id $(CFRONT_DIST) --paths "/stats/*" > /dev/null + +CLEAN = $(PKG).info dir $(PKG) $(PKG).html $(PKG).pdf + +clean: + @printf " Cleaning docs/*...\n" + @rm -rf $(CLEAN) diff --git a/elpa/with-editor-3.4.3/docs/htmlxref.cnf b/elpa/with-editor-3.4.3/docs/htmlxref.cnf new file mode 100644 index 0000000..54c3421 --- /dev/null +++ b/elpa/with-editor-3.4.3/docs/htmlxref.cnf @@ -0,0 +1,42 @@ +# https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Configuration.html + +EMACS = https://www.gnu.org/software/emacs/manual + +auth mono ${EMACS}/html_mono/auth.html +auth node ${EMACS}/html_node/auth/ + +ediff mono ${EMACS}/html_mono/ediff.html +ediff node ${EMACS}/html_node/ediff/ + +elisp mono ${EMACS}/html_mono/elisp.html +elisp node ${EMACS}/html_node/elisp/ + +emacs mono ${EMACS}/html_mono/emacs.html +emacs node ${EMACS}/html_node/emacs/ + + +MAGIT = https://magit.vc/manual + +forge mono ${MAGIT}/forge.html +forge node ${MAGIT}/forge/ + +ghub mono ${MAGIT}/ghub.html +ghub node ${MAGIT}/ghub/ + +magit mono ${MAGIT}/magit.html +magit node ${MAGIT}/magit/ + +transient mono ${MAGIT}/transient.html +transient node ${MAGIT}/transient/ + +with-editor mono ${MAGIT}/with-editor.html +with-editor node ${MAGIT}/with-editor/ + + +MIRROR = https://emacsmirror.net/manual + +borg mono ${MAGIT}/borg.html +borg node ${MAGIT}/borg/ + +epkg mono ${MAGIT}/epkg.html +epkg node ${MAGIT}/epkg/ diff --git a/elpa/with-editor-3.4.3/docs/with-editor.org b/elpa/with-editor-3.4.3/docs/with-editor.org new file mode 100644 index 0000000..00352d3 --- /dev/null +++ b/elpa/with-editor-3.4.3/docs/with-editor.org @@ -0,0 +1,311 @@ +#+title: With-Editor User Manual +:PREAMBLE: +#+author: Jonas Bernoulli +#+email: emacs.with-editor@jonas.bernoulli.dev +#+date: 2015-{{{year}}} + +#+texinfo_dir_category: Emacs +#+texinfo_dir_title: With-Editor: (with-editor). +#+texinfo_dir_desc: Using the Emacsclient as $EDITOR +#+subtitle: for version 3.4.3 + +#+setupfile: .orgconfig + +The library ~with-editor~ makes it easy to use the Emacsclient as the +~$EDITOR~ of child processes, making sure they know how to call home. +For remote processes a substitute is provided, which communicates with +Emacs on standard output instead of using a socket as the Emacsclient +does. + +This library was written because Magit has to be able to do the above +to allow the user to edit commit messages gracefully and to edit +rebase sequences, which wouldn't be possible at all otherwise. + +Because other packages can benefit from such functionality, this +library is made available as a separate package. It also defines some +additional functionality which makes it useful even for end-users, who +don't use Magit or another package which uses it internally. + +#+texinfo: @noindent +This manual is for With-Editor version 3.4.3. + +#+texinfo: @insertcopying +:END: +* Using the With-Editor package + +The ~With-Editor~ package is used internally by Magit when editing +commit messages and rebase sequences. It also provides some commands +and features which are useful by themselves, even if you don't use +Magit. + +For information about using this library in your own package, see +[[*Using With-Editor as a library]]. + +** Configuring With-Editor + +With-Editor tries very hard to locate a suitable ~emacsclient~ +executable, so ideally you should never have to customize the option +~with-editor-emacsclient-executable~. When it fails to do so, then the +most likely reason is that someone found yet another way to package +Emacs (most likely on macOS) without putting the executable on ~$PATH~, +and we have to add another kludge to find it anyway. + +- User Option: with-editor-emacsclient-executable :: + + The ~emacsclient~ executable used as the editor by child processes of + this Emacs instance. By using this executable, child processes can + call home to their parent process. + + This option is automatically set at startup by looking in ~exec-path~, + and other places where the executable could be installed, to find + the ~emacsclient~ executable most suitable for the current Emacs + instance. + + You should *not* customize this option permanently. If you have to do + it, then you should consider that a temporary kludge and inform the + Magit maintainer as described in [[*Debugging][Debugging]]. + + If With-Editor fails to find a suitable ~emacsclient~ on your system, + then this should be fixed for all users at once, by teaching + ~with-editor-locate-emacsclient~ how to do so on your system and + systems like yours. Doing it this way has the advantage, that you + won't have do it again every time you update Emacs, and that other + users who have installed Emacs the same way as you have, won't have + to go through the same trouble. + + Note that there also is a nuclear option; setting this variable to + ~nil~ causes the "sleeping editor" described below to be used even for + local child processes. Obviously we don't recommend that you use + this except in "emergencies", i.e., before we had a change to add a + kludge appropriate for your setup. + +- Function: with-editor-locate-emacsclient :: + + The function used to set the initial value of the option + ~with-editor-emacsclient-executable~. There's a lot of voodoo here. + +The ~emacsclient~ cannot be used when using Tramp to run a process on a +remote machine. (Theoretically it could, but that would be hard to +setup, very fragile, and rather insecure). + +With-Editor provides an alternative "editor" which can be used by +remote processes in much the same way as local processes use an +~emacsclient~ executable. This alternative is known as the "sleeping +editor" because it is implemented as a shell script which sleeps until +it receives a signal. + +- User Option: with-editor-sleeping-editor :: + + The sleeping editor is a shell script used as the editor of child + processes when the ~emacsclient~ executable cannot be used. + + This fallback is used for asynchronous processes started inside the + macro ~with-editor~, when the process runs on a remote machine or for + local processes when ~with-editor-emacsclient-executable~ is ~nil~. + + Where the latter uses a socket to communicate with Emacs' server, + this substitute prints edit requests to its standard output on + which a process filter listens for such requests. As such it is + not a complete substitute for a proper ~emacsclient~, it can only + be used as ~$EDITOR~ of child process of the current Emacs instance. + + Some shells do not execute traps immediately when waiting for a + child process, but by default we do use such a blocking child + process. + + If you use such a shell (e.g., ~csh~ on FreeBSD, but not Debian), then + you have to edit this option. You can either replace ~sh~ with ~bash~ + (and install that), or you can use the older, less performant + implementation: + + #+BEGIN_SRC emacs-lisp + "sh -c '\ + echo \"WITH-EDITOR: $$ OPEN $0 $1 IN $(pwd)\"; \ + trap \"exit 0\" USR1; \ + trap \"exit 1\" USR2; \ + while true; do sleep 1; done'" + #+END_SRC + + Note that the unit separator character ( ) right after the file + name ($0) is required. + + Also note that using this alternative implementation leads to a + delay of up to a second. The delay can be shortened by replacing + ~sleep 1~ with ~sleep 0.01~, or if your implementation does not support + floats, then by using ~nanosleep~ instead. + +** Using With-Editor commands + +This section describes how to use the ~with-editor~ library /outside/ of +Magit. You don't need to know any of this just to create commits +using Magit. + +The commands ~with-editor-async-shell-command~ and +~with-editor-shell-command~ are intended as drop in replacements for +~async-shell-command~ and ~shell-command~. They automatically export +~$EDITOR~ making sure the executed command uses the current Emacs +instance as "the editor". With a prefix argument these commands +prompt for an alternative environment variable such as ~$GIT_EDITOR~. + +- Command: with-editor-async-shell-command :: + + This command is like ~async-shell-command~, but it runs the shell + command with the current Emacs instance exported as ~$EDITOR~. + +- Command: with-editor-shell-command :: + + This command is like ~shell-command~, but if the shell command ends + with ~&~ and is therefore run asynchronously, then the current Emacs + instance is exported as ~$EDITOR~. + +To always use these variants add this to your init file: + +#+begin_src emacs-lisp + (keymap-global-set "<remap> <async-shell-command>" + #'with-editor-async-shell-command) + (keymap-global-set "<remap> <shell-command>" + #'with-editor-shell-command) +#+end_src + +Alternatively use the global ~shell-command-with-editor-mode~. + +- Variable: shell-command-with-editor-mode :: + + When this mode is active, then ~$EDITOR~ is exported whenever + ultimately ~shell-command~ is called to asynchronously run some shell + command. This affects most variants of that command, whether they + are defined in Emacs or in some third-party package. + +The command ~with-editor-export-editor~ exports ~$EDITOR~ or another +such environment variable in ~shell-mode~, ~eshell-mode~, ~term-mode~ and +~vterm-mode~ buffers. Use this Emacs command before executing a shell +command which needs the editor set, or always arrange for the current +Emacs instance to be used as editor by adding it to the appropriate +mode hooks: + +#+begin_src emacs-lisp + (add-hook 'shell-mode-hook 'with-editor-export-editor) + (add-hook 'eshell-mode-hook 'with-editor-export-editor) + (add-hook 'term-exec-hook 'with-editor-export-editor) + (add-hook 'vterm-mode-hook 'with-editor-export-editor) +#+end_src + +Some variants of this function exist; these two forms are equivalent: + +#+begin_src emacs-lisp + (add-hook 'shell-mode-hook + (apply-partially 'with-editor-export-editor "GIT_EDITOR")) + (add-hook 'shell-mode-hook 'with-editor-export-git-editor) +#+end_src + +- Command: with-editor-export-editor :: + + When invoked in a ~shell-mode~, ~eshell-mode~, ~term-mode~ or ~vterm-mode~ + buffer, this command teaches shell commands to use the current Emacs + instance as the editor, by exporting ~$EDITOR~. + +- Command: with-editor-export-git-editor :: + + This command is like ~with-editor-export-editor~ but exports + ~$GIT_EDITOR~. + +- Command: with-editor-export-hg-editor :: + + This command is like ~with-editor-export-editor~ but exports + ~$HG_EDITOR~. + +* Using With-Editor as a library + +This section describes how to use the ~with-editor~ library /outside/ of +Magit to teach another package how to have its child processes call +home, just like Magit does. You don't need to know any of this just +to create commits using Magit. You can also ignore this if you use +~with-editor~ outside of Magit, but only as an end-user. + +For information about interactive use and options that affect both +interactive and non-interactive use, see [[*Using the With-Editor +package]]. + +- Macro: with-editor &rest body :: + + This macro arranges for the ~emacsclient~ or the sleeping editor to be + used as the editor of child processes, effectively teaching them to + call home to the current Emacs instance when they require that the + user edits a file. + + This is done by establishing a local binding for ~process-environment~ + and changing the value of the ~EDITOR~ environment variable in that + scope. This affects all (asynchronous) processes started by forms + (dynamically) inside BODY. + + If BODY begins with a literal string, then that variable is set + instead of ~EDITOR~. + +- Macro: with-editor* envvar &rest body :: + + This macro is like ~with-editor~, except that the ENVVAR argument is + required and that it is evaluated at run-time. + +- Function: with-editor-set-process-filter process filter :: + + This function is like ~set-process-filter~ but ensures that adding the + new FILTER does not remove the ~with-editor-process-filter~. This is + done by wrapping the two filter functions using a lambda, which + becomes the actual filter. It calls FILTER first, which may or + may not insert the text into the PROCESS's buffer. Then it calls + ~with-editor-process-filter~, passing ~t~ as NO-STANDARD-FILTER. + +* Debugging + +With-Editor tries very hard to locate a suitable ~emacsclient~ +executable, and then sets option ~with-editor-emacsclient-executable~ +accordingly. In very rare cases this fails. When it does fail, then +the most likely reason is that someone found yet another way to +package Emacs (most likely on macOS) without putting the executable on +~$PATH~, and we have to add another kludge to find it anyway. + +If you are having problems using ~with-editor~, e.g., you cannot commit +in Magit, then please open a new issue at +https://github.com/magit/with-editor/issues and provide information +about your Emacs installation. Most importantly how did you install +Emacs and what is the output of ~M-x with-editor-debug RET~. + +* Function and Command Index +:PROPERTIES: +:APPENDIX: t +:INDEX: fn +:END: +* Variable Index +:PROPERTIES: +:APPENDIX: t +:INDEX: vr +:END: +* Copying +:PROPERTIES: +:COPYING: t +:END: + +#+begin_quote +Copyright (C) 2015-{{{year}}} Jonas Bernoulli <emacs.with-editor@jonas.bernoulli.dev> + +You can redistribute this document 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 document 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. +#+end_quote + +# LocalWords: LocalWords +# LocalWords: Magit Emacs emacsclient FreeBSD macOS texinfo +# LocalWords: async eval hg init performant rebase startup + +# IMPORTANT: Also update ORG_ARGS and ORG_EVAL in the Makefile. +# Local Variables: +# eval: (require 'magit-utils nil t) +# indent-tabs-mode: nil +# org-src-preserve-indentation: nil +# End: diff --git a/elpa/with-editor-3.4.3/docs/with-editor.texi b/elpa/with-editor-3.4.3/docs/with-editor.texi new file mode 100644 index 0000000..0cdf62c --- /dev/null +++ b/elpa/with-editor-3.4.3/docs/with-editor.texi @@ -0,0 +1,344 @@ +\input texinfo @c -*- texinfo -*- +@c %**start of header +@setfilename with-editor.info +@settitle With-Editor User Manual +@documentencoding UTF-8 +@documentlanguage en +@c %**end of header + +@copying +@quotation +Copyright (C) 2015-2024 Jonas Bernoulli <emacs.with-editor@@jonas.bernoulli.dev> + +You can redistribute this document 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 document 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. + +@end quotation +@end copying + +@dircategory Emacs +@direntry +* With-Editor: (with-editor). Using the Emacsclient as $EDITOR. +@end direntry + +@finalout +@titlepage +@title With-Editor User Manual +@subtitle for version 3.4.3 +@author Jonas Bernoulli +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top With-Editor User Manual + +The library @code{with-editor} makes it easy to use the Emacsclient as the +@code{$EDITOR} of child processes, making sure they know how to call home. +For remote processes a substitute is provided, which communicates with +Emacs on standard output instead of using a socket as the Emacsclient +does. + +This library was written because Magit has to be able to do the above +to allow the user to edit commit messages gracefully and to edit +rebase sequences, which wouldn't be possible at all otherwise. + +Because other packages can benefit from such functionality, this +library is made available as a separate package. It also defines some +additional functionality which makes it useful even for end-users, who +don't use Magit or another package which uses it internally. + +@noindent +This manual is for With-Editor version 3.4.3. + +@insertcopying +@end ifnottex + +@menu +* Using the With-Editor package:: +* Using With-Editor as a library:: +* Debugging:: +* Function and Command Index:: +* Variable Index:: + +@detailmenu +--- The Detailed Node Listing --- + +Using the With-Editor package + +* Configuring With-Editor:: +* Using With-Editor commands:: + +@end detailmenu +@end menu + +@node Using the With-Editor package +@chapter Using the With-Editor package + +The @code{With-Editor} package is used internally by Magit when editing +commit messages and rebase sequences. It also provides some commands +and features which are useful by themselves, even if you don't use +Magit. + +For information about using this library in your own package, see +@ref{Using With-Editor as a library}. + +@menu +* Configuring With-Editor:: +* Using With-Editor commands:: +@end menu + +@node Configuring With-Editor +@section Configuring With-Editor + +With-Editor tries very hard to locate a suitable @code{emacsclient} +executable, so ideally you should never have to customize the option +@code{with-editor-emacsclient-executable}. When it fails to do so, then the +most likely reason is that someone found yet another way to package +Emacs (most likely on macOS) without putting the executable on @code{$PATH}, +and we have to add another kludge to find it anyway. + +@defopt with-editor-emacsclient-executable +The @code{emacsclient} executable used as the editor by child processes of +this Emacs instance. By using this executable, child processes can +call home to their parent process. + +This option is automatically set at startup by looking in @code{exec-path}, +and other places where the executable could be installed, to find +the @code{emacsclient} executable most suitable for the current Emacs +instance. + +You should @strong{not} customize this option permanently. If you have to do +it, then you should consider that a temporary kludge and inform the +Magit maintainer as described in @ref{Debugging, , Debugging}. + +If With-Editor fails to find a suitable @code{emacsclient} on your system, +then this should be fixed for all users at once, by teaching +@code{with-editor-locate-emacsclient} how to do so on your system and +systems like yours. Doing it this way has the advantage, that you +won't have do it again every time you update Emacs, and that other +users who have installed Emacs the same way as you have, won't have +to go through the same trouble. + +Note that there also is a nuclear option; setting this variable to +@code{nil} causes the "sleeping editor" described below to be used even for +local child processes. Obviously we don't recommend that you use +this except in "emergencies", i.e., before we had a change to add a +kludge appropriate for your setup. +@end defopt + +@defun with-editor-locate-emacsclient +The function used to set the initial value of the option +@code{with-editor-emacsclient-executable}. There's a lot of voodoo here. +@end defun + +The @code{emacsclient} cannot be used when using Tramp to run a process on a +remote machine. (Theoretically it could, but that would be hard to +setup, very fragile, and rather insecure). + +With-Editor provides an alternative "editor" which can be used by +remote processes in much the same way as local processes use an +@code{emacsclient} executable. This alternative is known as the "sleeping +editor" because it is implemented as a shell script which sleeps until +it receives a signal. + +@defopt with-editor-sleeping-editor +The sleeping editor is a shell script used as the editor of child +processes when the @code{emacsclient} executable cannot be used. + +This fallback is used for asynchronous processes started inside the +macro @code{with-editor}, when the process runs on a remote machine or for +local processes when @code{with-editor-emacsclient-executable} is @code{nil}. + +Where the latter uses a socket to communicate with Emacs' server, +this substitute prints edit requests to its standard output on +which a process filter listens for such requests. As such it is +not a complete substitute for a proper @code{emacsclient}, it can only +be used as @code{$EDITOR} of child process of the current Emacs instance. + +Some shells do not execute traps immediately when waiting for a +child process, but by default we do use such a blocking child +process. + +If you use such a shell (e.g., @code{csh} on FreeBSD, but not Debian), then +you have to edit this option. You can either replace @code{sh} with @code{bash} +(and install that), or you can use the older, less performant +implementation: + +@lisp +"sh -c '\ +echo \"WITH-EDITOR: $$ OPEN $0 $1 IN $(pwd)\"; \ +trap \"exit 0\" USR1; \ +trap \"exit 1\" USR2; \ +while true; do sleep 1; done'" +@end lisp + +Note that the unit separator character ( ) right after the file +name ($0) is required. + +Also note that using this alternative implementation leads to a +delay of up to a second. The delay can be shortened by replacing +@code{sleep 1} with @code{sleep 0.01}, or if your implementation does not support +floats, then by using @code{nanosleep} instead. +@end defopt + +@node Using With-Editor commands +@section Using With-Editor commands + +This section describes how to use the @code{with-editor} library @emph{outside} of +Magit. You don't need to know any of this just to create commits +using Magit. + +The commands @code{with-editor-async-shell-command} and +@code{with-editor-shell-command} are intended as drop in replacements for +@code{async-shell-command} and @code{shell-command}. They automatically export +@code{$EDITOR} making sure the executed command uses the current Emacs +instance as "the editor". With a prefix argument these commands +prompt for an alternative environment variable such as @code{$GIT_EDITOR}. + +@deffn Command with-editor-async-shell-command +This command is like @code{async-shell-command}, but it runs the shell +command with the current Emacs instance exported as @code{$EDITOR}. +@end deffn + +@deffn Command with-editor-shell-command +This command is like @code{shell-command}, but if the shell command ends +with @code{&} and is therefore run asynchronously, then the current Emacs +instance is exported as @code{$EDITOR}. +@end deffn + +To always use these variants add this to your init file: + +@lisp +(keymap-global-set "<remap> <async-shell-command>" + #'with-editor-async-shell-command) +(keymap-global-set "<remap> <shell-command>" + #'with-editor-shell-command) +@end lisp + +Alternatively use the global @code{shell-command-with-editor-mode}. + +@defvar shell-command-with-editor-mode +When this mode is active, then @code{$EDITOR} is exported whenever +ultimately @code{shell-command} is called to asynchronously run some shell +command. This affects most variants of that command, whether they +are defined in Emacs or in some third-party package. +@end defvar + +The command @code{with-editor-export-editor} exports @code{$EDITOR} or another +such environment variable in @code{shell-mode}, @code{eshell-mode}, @code{term-mode} and +@code{vterm-mode} buffers. Use this Emacs command before executing a shell +command which needs the editor set, or always arrange for the current +Emacs instance to be used as editor by adding it to the appropriate +mode hooks: + +@lisp +(add-hook 'shell-mode-hook 'with-editor-export-editor) +(add-hook 'eshell-mode-hook 'with-editor-export-editor) +(add-hook 'term-exec-hook 'with-editor-export-editor) +(add-hook 'vterm-mode-hook 'with-editor-export-editor) +@end lisp + +Some variants of this function exist; these two forms are equivalent: + +@lisp +(add-hook 'shell-mode-hook + (apply-partially 'with-editor-export-editor "GIT_EDITOR")) +(add-hook 'shell-mode-hook 'with-editor-export-git-editor) +@end lisp + +@deffn Command with-editor-export-editor +When invoked in a @code{shell-mode}, @code{eshell-mode}, @code{term-mode} or @code{vterm-mode} +buffer, this command teaches shell commands to use the current Emacs +instance as the editor, by exporting @code{$EDITOR}. +@end deffn + +@deffn Command with-editor-export-git-editor +This command is like @code{with-editor-export-editor} but exports +@code{$GIT_EDITOR}. +@end deffn + +@deffn Command with-editor-export-hg-editor +This command is like @code{with-editor-export-editor} but exports +@code{$HG_EDITOR}. +@end deffn + +@node Using With-Editor as a library +@chapter Using With-Editor as a library + +This section describes how to use the @code{with-editor} library @emph{outside} of +Magit to teach another package how to have its child processes call +home, just like Magit does. You don't need to know any of this just +to create commits using Magit. You can also ignore this if you use +@code{with-editor} outside of Magit, but only as an end-user. + +For information about interactive use and options that affect both +interactive and non-interactive use, see @ref{Using the With-Editor package}. + +@defmac with-editor &rest body +This macro arranges for the @code{emacsclient} or the sleeping editor to be +used as the editor of child processes, effectively teaching them to +call home to the current Emacs instance when they require that the +user edits a file. + +This is done by establishing a local binding for @code{process-environment} +and changing the value of the @code{EDITOR} environment variable in that +scope. This affects all (asynchronous) processes started by forms +(dynamically) inside BODY@. + +If BODY begins with a literal string, then that variable is set +instead of @code{EDITOR}. +@end defmac + +@defmac with-editor* envvar &rest body +This macro is like @code{with-editor}, except that the ENVVAR argument is +required and that it is evaluated at run-time. +@end defmac + +@defun with-editor-set-process-filter process filter +This function is like @code{set-process-filter} but ensures that adding the +new FILTER does not remove the @code{with-editor-process-filter}. This is +done by wrapping the two filter functions using a lambda, which +becomes the actual filter. It calls FILTER first, which may or +may not insert the text into the PROCESS's buffer. Then it calls +@code{with-editor-process-filter}, passing @code{t} as NO-STANDARD-FILTER@. +@end defun + +@node Debugging +@chapter Debugging + +With-Editor tries very hard to locate a suitable @code{emacsclient} +executable, and then sets option @code{with-editor-emacsclient-executable} +accordingly. In very rare cases this fails. When it does fail, then +the most likely reason is that someone found yet another way to +package Emacs (most likely on macOS) without putting the executable on +@code{$PATH}, and we have to add another kludge to find it anyway. + +If you are having problems using @code{with-editor}, e.g., you cannot commit +in Magit, then please open a new issue at +@uref{https://github.com/magit/with-editor/issues} and provide information +about your Emacs installation. Most importantly how did you install +Emacs and what is the output of @code{M-x with-editor-debug RET}. + +@node Function and Command Index +@appendix Function and Command Index + +@printindex fn + +@node Variable Index +@appendix Variable Index + +@printindex vr + +@bye diff --git a/elpa/with-editor-3.4.3/with-editor-autoloads.el b/elpa/with-editor-3.4.3/with-editor-autoloads.el new file mode 100644 index 0000000..fe538d4 --- /dev/null +++ b/elpa/with-editor-3.4.3/with-editor-autoloads.el @@ -0,0 +1,105 @@ +;;; with-editor-autoloads.el --- automatically extracted autoloads (do not edit) -*- lexical-binding: t -*- +;; Generated by the `loaddefs-generate' function. + +;; This file is part of GNU Emacs. + +;;; Code: + +(add-to-list 'load-path (or (and load-file-name (directory-file-name (file-name-directory load-file-name))) (car load-path))) + + + +;;; Generated autoloads from with-editor.el + +(autoload 'with-editor-export-editor "with-editor" "\ +Teach subsequent commands to use current Emacs instance as editor. + +Set and export the environment variable ENVVAR, by default +\"EDITOR\". The value is automatically generated to teach +commands to use the current Emacs instance as \"the editor\". + +This works in `shell-mode', `term-mode', `eshell-mode' and +`vterm'. + +(fn &optional (ENVVAR \"EDITOR\"))" t) +(autoload 'with-editor-export-git-editor "with-editor" "\ +Like `with-editor-export-editor' but always set `$GIT_EDITOR'." t) +(autoload 'with-editor-export-hg-editor "with-editor" "\ +Like `with-editor-export-editor' but always set `$HG_EDITOR'." t) +(defvar shell-command-with-editor-mode nil "\ +Non-nil if Shell-Command-With-Editor mode is enabled. +See the `shell-command-with-editor-mode' command +for a description of this minor mode.") +(custom-autoload 'shell-command-with-editor-mode "with-editor" nil) +(autoload 'shell-command-with-editor-mode "with-editor" "\ +Teach `shell-command' to use current Emacs instance as editor. + +Teach `shell-command', and all commands that ultimately call that +command, to use the current Emacs instance as editor by executing +\"EDITOR=CLIENT COMMAND&\" instead of just \"COMMAND&\". + +CLIENT is automatically generated; EDITOR=CLIENT instructs +COMMAND to use to the current Emacs instance as \"the editor\", +assuming no other variable overrides the effect of \"$EDITOR\". +CLIENT may be the path to an appropriate emacsclient executable +with arguments, or a script which also works over Tramp. + +Alternatively you can use the `with-editor-async-shell-command', +which also allows the use of another variable instead of +\"EDITOR\". + +This is a global minor mode. If called interactively, toggle the +`Shell-Command-With-Editor mode' mode. If the prefix argument is +positive, enable the mode, and if it is zero or negative, disable the +mode. + +If called from Lisp, toggle the mode if ARG is `toggle'. Enable the +mode if ARG is nil, omitted, or is a positive number. Disable the mode +if ARG is a negative number. + +To check whether the minor mode is enabled in the current buffer, +evaluate `(default-value \\='shell-command-with-editor-mode)'. + +The mode's hook is called both when the mode is enabled and when it is +disabled. + +(fn &optional ARG)" t) +(autoload 'with-editor-async-shell-command "with-editor" "\ +Like `async-shell-command' but with `$EDITOR' set. + +Execute string \"ENVVAR=CLIENT COMMAND\" in an inferior shell; +display output, if any. With a prefix argument prompt for an +environment variable, otherwise the default \"EDITOR\" variable +is used. With a negative prefix argument additionally insert +the COMMAND's output at point. + +CLIENT is automatically generated; ENVVAR=CLIENT instructs +COMMAND to use to the current Emacs instance as \"the editor\", +assuming it respects ENVVAR as an \"EDITOR\"-like variable. +CLIENT may be the path to an appropriate emacsclient executable +with arguments, or a script which also works over Tramp. + +Also see `async-shell-command' and `shell-command'. + +(fn COMMAND &optional OUTPUT-BUFFER ERROR-BUFFER ENVVAR)" t) +(autoload 'with-editor-shell-command "with-editor" "\ +Like `shell-command' or `with-editor-async-shell-command'. +If COMMAND ends with \"&\" behave like the latter, +else like the former. + +(fn COMMAND &optional OUTPUT-BUFFER ERROR-BUFFER ENVVAR)" t) +(register-definition-prefixes "with-editor" '("server-" "shell-command" "start-file-process" "with-editor")) + +;;; End of scraped data + +(provide 'with-editor-autoloads) + +;; Local Variables: +;; version-control: never +;; no-byte-compile: t +;; no-update-autoloads: t +;; no-native-compile: t +;; coding: utf-8-emacs-unix +;; End: + +;;; with-editor-autoloads.el ends here diff --git a/elpa/with-editor-3.4.3/with-editor-pkg.el b/elpa/with-editor-3.4.3/with-editor-pkg.el new file mode 100644 index 0000000..6bd429a --- /dev/null +++ b/elpa/with-editor-3.4.3/with-editor-pkg.el @@ -0,0 +1,2 @@ +;; Generated package description from with-editor.el -*- no-byte-compile: t -*- +(define-package "with-editor" "3.4.3" "Use the Emacsclient as $EDITOR" '((emacs "26.1") (compat "30.0.0.0")) :commit "ca902ae02972bdd6919a902be2593d8cb6bd991b" :authors '(("Jonas Bernoulli" . "emacs.with-editor@jonas.bernoulli.dev")) :maintainer '("Jonas Bernoulli" . "emacs.with-editor@jonas.bernoulli.dev") :keywords '("processes" "terminals") :url "https://github.com/magit/with-editor") diff --git a/elpa/with-editor-3.4.3/with-editor.el b/elpa/with-editor-3.4.3/with-editor.el new file mode 100644 index 0000000..3c971f3 --- /dev/null +++ b/elpa/with-editor-3.4.3/with-editor.el @@ -0,0 +1,992 @@ +;;; with-editor.el --- Use the Emacsclient as $EDITOR -*- lexical-binding:t -*- + +;; Copyright (C) 2014-2024 The Magit Project Contributors + +;; Author: Jonas Bernoulli <emacs.with-editor@jonas.bernoulli.dev> +;; Homepage: https://github.com/magit/with-editor +;; Keywords: processes terminals + +;; Package-Version: 3.4.3 +;; Package-Requires: ((emacs "26.1") (compat "30.0.0.0")) + +;; SPDX-License-Identifier: GPL-3.0-or-later + +;; This file 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 file 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 file. If not, see <https://www.gnu.org/licenses/>. + +;;; Commentary: + +;; This library makes it possible to reliably use the Emacsclient as +;; the `$EDITOR' of child processes. It makes sure that they know how +;; to call home. For remote processes a substitute is provided, which +;; communicates with Emacs on standard output/input instead of using a +;; socket as the Emacsclient does. + +;; It provides the commands `with-editor-async-shell-command' and +;; `with-editor-shell-command', which are intended as replacements +;; for `async-shell-command' and `shell-command'. They automatically +;; export `$EDITOR' making sure the executed command uses the current +;; Emacs instance as "the editor". With a prefix argument these +;; commands prompt for an alternative environment variable such as +;; `$GIT_EDITOR'. To always use these variants add this to your init +;; file: +;; +;; (keymap-global-set "<remap> <async-shell-command>" +;; #'with-editor-async-shell-command) +;; (keymap-global-set "<remap> <shell-command>" +;; #'with-editor-shell-command) + +;; Alternatively use the global `shell-command-with-editor-mode', +;; which always sets `$EDITOR' for all Emacs commands which ultimately +;; use `shell-command' to asynchronously run some shell command. + +;; The command `with-editor-export-editor' exports `$EDITOR' or +;; another such environment variable in `shell-mode', `eshell-mode', +;; `term-mode' and `vterm-mode' buffers. Use this Emacs command +;; before executing a shell command which needs the editor set, or +;; always arrange for the current Emacs instance to be used as editor +;; by adding it to the appropriate mode hooks: +;; +;; (add-hook 'shell-mode-hook #'with-editor-export-editor) +;; (add-hook 'eshell-mode-hook #'with-editor-export-editor) +;; (add-hook 'term-exec-hook #'with-editor-export-editor) +;; (add-hook 'vterm-mode-hook #'with-editor-export-editor) + +;; Some variants of this function exist, these two forms are +;; equivalent: +;; +;; (add-hook 'shell-mode-hook +;; (apply-partially #'with-editor-export-editor "GIT_EDITOR")) +;; (add-hook 'shell-mode-hook #'with-editor-export-git-editor) + +;; This library can also be used by other packages which need to use +;; the current Emacs instance as editor. In fact this library was +;; written for Magit and its `git-commit-mode' and `git-rebase-mode'. +;; Consult `git-rebase.el' and the related code in `magit-sequence.el' +;; for a simple example. + +;;; Code: + +(require 'cl-lib) +(require 'compat) +(require 'server) +(require 'shell) +(eval-when-compile (require 'subr-x)) + +(declare-function dired-get-filename "dired" + (&optional localp no-error-if-not-filep)) +(declare-function term-emulate-terminal "term" (proc str)) +(defvar eshell-preoutput-filter-functions) +(defvar git-commit-post-finish-hook) +(defvar vterm--process) +(defvar warning-minimum-level) +(defvar warning-minimum-log-level) + +;;; Options + +(defgroup with-editor nil + "Use the Emacsclient as $EDITOR." + :group 'external + :group 'server) + +(defun with-editor-locate-emacsclient () + "Search for a suitable Emacsclient executable." + (or (with-editor-locate-emacsclient-1 + (with-editor-emacsclient-path) + (length (split-string emacs-version "\\."))) + (prog1 nil (display-warning 'with-editor "\ +Cannot determine a suitable Emacsclient + +Determining an Emacsclient executable suitable for the +current Emacs instance failed. For more information +please see https://github.com/magit/magit/wiki/Emacsclient.")))) + +(defvar with-editor-emacsclient-program-suffixes + (list "-snapshot" ".emacs-snapshot") + "Suffixes to append to append when looking for a Emacsclient executables.") + +(defun with-editor-locate-emacsclient-1 (path depth) + (let* ((version-lst (cl-subseq (split-string emacs-version "\\.") 0 depth)) + (version-reg (concat "^" (string-join version-lst "\\.")))) + (or (locate-file + (cond ((equal (downcase invocation-name) "remacs") + "remacsclient") + ((bound-and-true-p emacsclient-program-name)) + ("emacsclient")) + path + (mapcan (lambda (v) (cl-mapcar (lambda (e) (concat v e)) exec-suffixes)) + (nconc (and (boundp 'debian-emacs-flavor) + (list (format ".%s" debian-emacs-flavor))) + (cl-mapcon (lambda (v) + (setq v (string-join (reverse v) ".")) + (list v + (concat "-" v) + (concat ".emacs" v))) + (reverse version-lst)) + (cons "" with-editor-emacsclient-program-suffixes))) + (lambda (exec) + (ignore-errors + (string-match-p version-reg + (with-editor-emacsclient-version exec))))) + (and (> depth 1) + (with-editor-locate-emacsclient-1 path (1- depth)))))) + +(defun with-editor-emacsclient-version (exec) + (let ((default-directory (file-name-directory exec))) + (ignore-errors + (cadr (split-string (car (process-lines exec "--version"))))))) + +(defun with-editor-emacsclient-path () + (let ((path exec-path)) + (when invocation-directory + (push (directory-file-name invocation-directory) path) + (let* ((linkname (expand-file-name invocation-name invocation-directory)) + (truename (file-chase-links linkname))) + (unless (equal truename linkname) + (push (directory-file-name (file-name-directory truename)) path))) + (when (eq system-type 'darwin) + (let ((dir (expand-file-name "bin" invocation-directory))) + (when (file-directory-p dir) + (push dir path))) + (when (string-search "Cellar" invocation-directory) + (let ((dir (expand-file-name "../../../bin" invocation-directory))) + (when (file-directory-p dir) + (push dir path)))))) + (cl-remove-duplicates path :test #'equal))) + +(defcustom with-editor-emacsclient-executable (with-editor-locate-emacsclient) + "The Emacsclient executable used by the `with-editor' macro." + :group 'with-editor + :type '(choice (string :tag "Executable") + (const :tag "Don't use Emacsclient" nil))) + +(defcustom with-editor-sleeping-editor "\ +sh -c '\ +printf \"\\nWITH-EDITOR: $$ OPEN $0\\037$1\\037 IN $(pwd)\\n\"; \ +sleep 604800 & sleep=$!; \ +trap \"kill $sleep; exit 0\" USR1; \ +trap \"kill $sleep; exit 1\" USR2; \ +wait $sleep'" + "The sleeping editor, used when the Emacsclient cannot be used. + +This fallback is used for asynchronous processes started inside +the macro `with-editor', when the process runs on a remote machine +or for local processes when `with-editor-emacsclient-executable' +is nil (i.e., when no suitable Emacsclient was found, or the user +decided not to use it). + +Where the latter uses a socket to communicate with Emacs' server, +this substitute prints edit requests to its standard output on +which a process filter listens for such requests. As such it is +not a complete substitute for a proper Emacsclient, it can only +be used as $EDITOR of child process of the current Emacs instance. + +Some shells do not execute traps immediately when waiting for a +child process, but by default we do use such a blocking child +process. + +If you use such a shell (e.g., `csh' on FreeBSD, but not Debian), +then you have to edit this option. You can either replace \"sh\" +with \"bash\" (and install that), or you can use the older, less +performant implementation: + + \"sh -c '\\ + echo -e \\\"\\nWITH-EDITOR: $$ OPEN $0 $1 IN $(pwd)\\n\\\"; \\ + trap \\\"exit 0\\\" USR1; \\ + trap \\\"exit 1\" USR2; \\ + while true; do sleep 1; done'\" + +Note that the two unit separator characters ( ) right after $0 +and $1 are required. Normally $0 is the file name and $1 is +missing or else gets ignored. But if $0 has the form \"+N[:N]\", +then it is treated as a position in the file and $1 is expected +to be the file. + +Also note that using this alternative implementation leads to a +delay of up to a second. The delay can be shortened by replacing +\"sleep 1\" with \"sleep 0.01\", or if your implementation does +not support floats, then by using \"nanosleep\" instead." + :package-version '(with-editor . "2.8.0") + :group 'with-editor + :type 'string) + +(defcustom with-editor-finish-query-functions nil + "List of functions called to query before finishing session. + +The buffer in question is current while the functions are called. +If any of them returns nil, then the session is not finished and +the buffer is not killed. The user should then fix the issue and +try again. The functions are called with one argument. If it is +non-nil then that indicates that the user used a prefix argument +to force finishing the session despite issues. Functions should +usually honor that and return non-nil." + :group 'with-editor + :type 'hook) +(put 'with-editor-finish-query-functions 'permanent-local t) + +(defcustom with-editor-cancel-query-functions nil + "List of functions called to query before canceling session. + +The buffer in question is current while the functions are called. +If any of them returns nil, then the session is not canceled and +the buffer is not killed. The user should then fix the issue and +try again. The functions are called with one argument. If it is +non-nil then that indicates that the user used a prefix argument +to force canceling the session despite issues. Functions should +usually honor that and return non-nil." + :group 'with-editor + :type 'hook) +(put 'with-editor-cancel-query-functions 'permanent-local t) + +(defcustom with-editor-mode-lighter " WE" + "The mode-line lighter of the With-Editor mode." + :group 'with-editor + :type '(choice (const :tag "No lighter" "") string)) + +(defvar with-editor-server-window-alist nil + "Alist of filename patterns vs corresponding `server-window'. + +Each element looks like (REGEXP . FUNCTION). Files matching +REGEXP are selected using FUNCTION instead of the default in +`server-window'. + +Note that when a package adds an entry here then it probably +has a reason to disrespect `server-window' and it likely is +not a good idea to change such entries.") + +(defvar with-editor-file-name-history-exclude nil + "List of regexps for filenames `server-visit' should not remember. +When a filename matches any of the regexps, then `server-visit' +does not add it to the variable `file-name-history', which is +used when reading a filename in the minibuffer.") + +(defcustom with-editor-shell-command-use-emacsclient t + "Whether to use the emacsclient when running shell commands. + +This affects `with-editor-async-shell-command' and, if the input +ends with \"&\" `with-editor-shell-command' . + +If `shell-command-with-editor-mode' is enabled, then it also +affects `shell-command-async' and, if the input ends with \"&\" +`shell-command'. + +This is a temporary kludge that lets you choose between two +possible defects, the ones described in the issues #23 and #40. + +When t, then use the emacsclient. This has the disadvantage that +`with-editor-mode' won't be enabled because we don't know whether +this package was involved at all in the call to the emacsclient, +and when it is not, then we really should. The problem is that +the emacsclient doesn't pass along any environment variables to +the server. This will hopefully be fixed in Emacs eventually. + +When nil, then use the sleeping editor. Because in this case we +know that this package is involved, we can enable the mode. But +this makes it necessary that you invoke $EDITOR in shell scripts +like so: + + eval \"$EDITOR\" file + +And some tools that do not handle $EDITOR properly also break." + :package-version '(with-editor . "2.7.1") + :group 'with-editor + :type 'boolean) + +;;; Mode Commands + +(defvar with-editor-pre-finish-hook nil) +(defvar with-editor-pre-cancel-hook nil) +(defvar with-editor-post-finish-hook nil) +(defvar with-editor-post-finish-hook-1 nil) +(defvar with-editor-post-cancel-hook nil) +(defvar with-editor-post-cancel-hook-1 nil) +(defvar with-editor-cancel-alist nil) +(put 'with-editor-pre-finish-hook 'permanent-local t) +(put 'with-editor-pre-cancel-hook 'permanent-local t) +(put 'with-editor-post-finish-hook 'permanent-local t) +(put 'with-editor-post-cancel-hook 'permanent-local t) + +(defvar-local with-editor-show-usage t) +(defvar-local with-editor-cancel-message nil) +(defvar-local with-editor-previous-winconf nil) +(put 'with-editor-cancel-message 'permanent-local t) +(put 'with-editor-previous-winconf 'permanent-local t) + +(defvar-local with-editor--pid nil "For internal use.") +(put 'with-editor--pid 'permanent-local t) + +(defun with-editor-finish (force) + "Finish the current edit session." + (interactive "P") + (when (run-hook-with-args-until-failure + 'with-editor-finish-query-functions force) + (let ((post-finish-hook with-editor-post-finish-hook) + (post-commit-hook (bound-and-true-p git-commit-post-finish-hook)) + (dir default-directory)) + (run-hooks 'with-editor-pre-finish-hook) + (with-editor-return nil) + (accept-process-output nil 0.1) + (with-temp-buffer + (setq default-directory dir) + (setq-local with-editor-post-finish-hook post-finish-hook) + (when post-commit-hook + (setq-local git-commit-post-finish-hook post-commit-hook)) + (run-hooks 'with-editor-post-finish-hook))))) + +(defun with-editor-cancel (force) + "Cancel the current edit session." + (interactive "P") + (when (run-hook-with-args-until-failure + 'with-editor-cancel-query-functions force) + (let ((message with-editor-cancel-message)) + (when (functionp message) + (setq message (funcall message))) + (let ((post-cancel-hook with-editor-post-cancel-hook) + (with-editor-cancel-alist nil) + (dir default-directory)) + (run-hooks 'with-editor-pre-cancel-hook) + (with-editor-return t) + (accept-process-output nil 0.1) + (with-temp-buffer + (setq default-directory dir) + (setq-local with-editor-post-cancel-hook post-cancel-hook) + (run-hooks 'with-editor-post-cancel-hook))) + (message (or message "Canceled by user"))))) + +(defun with-editor-return (cancel) + (let ((winconf with-editor-previous-winconf) + (clients server-buffer-clients) + (dir default-directory) + (pid with-editor--pid)) + (remove-hook 'kill-buffer-query-functions + #'with-editor-kill-buffer-noop t) + (cond (cancel + (save-buffer) + (if clients + (let ((buf (current-buffer))) + (dolist (client clients) + (message "client %S" client) + (ignore-errors + (server-send-string client "-error Canceled by user")) + (delete-process client)) + (when (buffer-live-p buf) + (kill-buffer buf))) + ;; Fallback for when emacs was used as $EDITOR + ;; instead of emacsclient or the sleeping editor. + ;; See https://github.com/magit/magit/issues/2258. + (ignore-errors (delete-file buffer-file-name)) + (kill-buffer))) + (t + (save-buffer) + (if clients + ;; Don't use `server-edit' because we do not want to + ;; show another buffer belonging to another client. + ;; See https://github.com/magit/magit/issues/2197. + (server-done) + (kill-buffer)))) + (when pid + (let ((default-directory dir)) + (process-file "kill" nil nil nil + "-s" (if cancel "USR2" "USR1") pid))) + (when (and winconf (eq (window-configuration-frame winconf) + (selected-frame))) + (set-window-configuration winconf)))) + +;;; Mode + +(defvar-keymap with-editor-mode-map + "C-c C-c" #'with-editor-finish + "<remap> <server-edit>" #'with-editor-finish + "<remap> <evil-save-and-close>" #'with-editor-finish + "<remap> <evil-save-modified-and-close>" #'with-editor-finish + "C-c C-k" #'with-editor-cancel + "<remap> <kill-buffer>" #'with-editor-cancel + "<remap> <ido-kill-buffer>" #'with-editor-cancel + "<remap> <iswitchb-kill-buffer>" #'with-editor-cancel + "<remap> <evil-quit>" #'with-editor-cancel) + +(define-minor-mode with-editor-mode + "Edit a file as the $EDITOR of an external process." + :lighter with-editor-mode-lighter + ;; Protect the user from enabling or disabling the mode interactively. + ;; Manually enabling the mode is dangerous because canceling the buffer + ;; deletes the visited file. The mode must not be disabled manually, + ;; either `with-editor-finish' or `with-editor-cancel' must be used. + :interactive nil ; >= 28.1 + (when (called-interactively-p 'any) ; < 28.1 + (setq with-editor-mode (not with-editor-mode)) + (user-error "With-Editor mode is not intended for interactive use")) + ;; The buffer must also not be killed using regular kill commands. + (add-hook 'kill-buffer-query-functions + #'with-editor-kill-buffer-noop nil t) + ;; `server-execute' displays a message which is not + ;; correct when using this mode. + (when with-editor-show-usage + (with-editor-usage-message))) + +(put 'with-editor-mode 'permanent-local t) + +(defun with-editor-kill-buffer-noop () + ;; We started doing this in response to #64, but it is not safe + ;; to do so, because the client has already been killed, causing + ;; `with-editor-return' (called by `with-editor-cancel') to delete + ;; the file, see #66. The reason we delete the file in the first + ;; place are https://github.com/magit/magit/issues/2258 and + ;; https://github.com/magit/magit/issues/2248. + ;; (if (memq this-command '(save-buffers-kill-terminal + ;; save-buffers-kill-emacs)) + ;; (let ((with-editor-cancel-query-functions nil)) + ;; (with-editor-cancel nil) + ;; t) + ;; ...) + ;; So go back to always doing this instead: + (user-error (substitute-command-keys (format "\ +Don't kill this buffer %S. Instead cancel using \\[with-editor-cancel]" + (current-buffer))))) + +(defvar-local with-editor-usage-message "\ +Type \\[with-editor-finish] to finish, \ +or \\[with-editor-cancel] to cancel") + +(defun with-editor-usage-message () + ;; Run after `server-execute', which is run using + ;; a timer which starts immediately. + (let ((buffer (current-buffer))) + (run-with-timer + 0.05 nil + (lambda () + (with-current-buffer buffer + (message (substitute-command-keys with-editor-usage-message))))))) + +;;; Wrappers + +(defvar with-editor--envvar nil "For internal use.") + +(defmacro with-editor (&rest body) + "Use the Emacsclient as $EDITOR while evaluating BODY. +Modify the `process-environment' for processes started in BODY, +instructing them to use the Emacsclient as $EDITOR. If optional +ENVVAR is a literal string then bind that environment variable +instead. +\n(fn [ENVVAR] BODY...)" + (declare (indent defun) (debug (body))) + `(let ((with-editor--envvar ,(if (stringp (car body)) + (pop body) + '(or with-editor--envvar "EDITOR"))) + (process-environment process-environment)) + (with-editor--setup) + ,@body)) + +(defmacro with-editor* (envvar &rest body) + "Use the Emacsclient as the editor while evaluating BODY. +Modify the `process-environment' for processes started in BODY, +instructing them to use the Emacsclient as editor. ENVVAR is the +environment variable that is exported to do so, it is evaluated +at run-time. +\n(fn ENVVAR BODY...)" + (declare (indent defun) (debug (sexp body))) + `(let ((with-editor--envvar ,envvar) + (process-environment process-environment)) + (with-editor--setup) + ,@body)) + +(defun with-editor--setup () + (if (or (not with-editor-emacsclient-executable) + (file-remote-p default-directory)) + (push (concat with-editor--envvar "=" with-editor-sleeping-editor) + process-environment) + ;; Make sure server-use-tcp's value is valid. + (unless (featurep 'make-network-process '(:family local)) + (setq server-use-tcp t)) + ;; Make sure the server is running. + (unless (process-live-p server-process) + (when (server-running-p server-name) + (setq server-name (format "server%s" (emacs-pid))) + (when (server-running-p server-name) + (server-force-delete server-name))) + (server-start)) + ;; Tell $EDITOR to use the Emacsclient. + (push (concat with-editor--envvar "=" + ;; Quoting is the right thing to do. Applications that + ;; fail because of that, are the ones that need fixing, + ;; e.g., by using 'eval "$EDITOR" file'. See #121. + (shell-quote-argument + ;; If users set the executable manually, they might + ;; begin the path with "~", which would get quoted. + (if (string-prefix-p "~" with-editor-emacsclient-executable) + (concat (expand-file-name "~") + (substring with-editor-emacsclient-executable 1)) + with-editor-emacsclient-executable)) + ;; Tell the process where the server file is. + (and (not server-use-tcp) + (concat " --socket-name=" + (shell-quote-argument + (expand-file-name server-name + server-socket-dir))))) + process-environment) + (when server-use-tcp + (push (concat "EMACS_SERVER_FILE=" + (expand-file-name server-name server-auth-dir)) + process-environment)) + ;; As last resort fallback to the sleeping editor. + (push (concat "ALTERNATE_EDITOR=" with-editor-sleeping-editor) + process-environment))) + +(defun with-editor-server-window () + (or (and buffer-file-name + (cdr (cl-find-if (lambda (cons) + (string-match-p (car cons) buffer-file-name)) + with-editor-server-window-alist))) + server-window)) + +(define-advice server-switch-buffer + (:around (fn &optional next-buffer &rest args) + with-editor-server-window-alist) + "Honor `with-editor-server-window-alist' (which see)." + (let ((server-window (with-current-buffer + (or next-buffer (current-buffer)) + (when with-editor-mode + (setq with-editor-previous-winconf + (current-window-configuration))) + (with-editor-server-window)))) + (apply fn next-buffer args))) + +(define-advice start-file-process + (:around (fn name buffer program &rest program-args) + with-editor-process-filter) + "When called inside a `with-editor' form and the Emacsclient +cannot be used, then give the process the filter function +`with-editor-process-filter'. To avoid overriding the filter +being added here you should use `with-editor-set-process-filter' +instead of `set-process-filter' inside `with-editor' forms. + +When the `default-directory' is located on a remote machine, +then also manipulate PROGRAM and PROGRAM-ARGS in order to set +the appropriate editor environment variable." + (if (not with-editor--envvar) + (apply fn name buffer program program-args) + (when (file-remote-p default-directory) + (unless (equal program "env") + (push program program-args) + (setq program "env")) + (push (concat with-editor--envvar "=" with-editor-sleeping-editor) + program-args)) + (let ((process (apply fn name buffer program program-args))) + (set-process-filter process #'with-editor-process-filter) + (process-put process 'default-dir default-directory) + process))) + +(advice-add #'make-process :around + #'make-process@with-editor-process-filter) +(cl-defun make-process@with-editor-process-filter + (fn &rest keys &key name buffer command coding noquery stop + connection-type filter sentinel stderr file-handler + &allow-other-keys) + "When called inside a `with-editor' form and the Emacsclient +cannot be used, then give the process the filter function +`with-editor-process-filter'. To avoid overriding the filter +being added here you should use `with-editor-set-process-filter' +instead of `set-process-filter' inside `with-editor' forms. + +When the `default-directory' is located on a remote machine and +FILE-HANDLER is non-nil, then also manipulate COMMAND in order +to set the appropriate editor environment variable." + (if (or (not file-handler) (not with-editor--envvar)) + (apply fn keys) + (when (file-remote-p default-directory) + (unless (equal (car command) "env") + (push "env" command)) + (push (concat with-editor--envvar "=" with-editor-sleeping-editor) + (cdr command))) + (let* ((filter (if filter + (lambda (process output) + (funcall filter process output) + (with-editor-process-filter process output t)) + #'with-editor-process-filter)) + (process (funcall fn + :name name + :buffer buffer + :command command + :coding coding + :noquery noquery + :stop stop + :connection-type connection-type + :filter filter + :sentinel sentinel + :stderr stderr + :file-handler file-handler))) + (process-put process 'default-dir default-directory) + process))) + +(defun with-editor-set-process-filter (process filter) + "Like `set-process-filter' but keep `with-editor-process-filter'. +Give PROCESS the new FILTER but keep `with-editor-process-filter' +if that was added earlier by the advised `start-file-process'. + +Do so by wrapping the two filter functions using a lambda, which +becomes the actual filter. It calls FILTER first, which may or +may not insert the text into the PROCESS's buffer. Then it calls +`with-editor-process-filter', passing t as NO-STANDARD-FILTER." + (set-process-filter + process + (if (eq (process-filter process) 'with-editor-process-filter) + `(lambda (proc str) + (,filter proc str) + (with-editor-process-filter proc str t)) + filter))) + +(defvar with-editor-filter-visit-hook nil) + +(defconst with-editor-sleeping-editor-regexp "^\ +WITH-EDITOR: \\([0-9]+\\) \ +OPEN \\([^ ]+?\\)\ +\\(?: \\([^ ]*\\)\\)?\ +\\(?: IN \\([^\r]+?\\)\\)?\r?$") + +(defvar with-editor--max-incomplete-length 1000) + +(defun with-editor-sleeping-editor-filter (process string) + (when-let ((incomplete (and process (process-get process 'incomplete)))) + (setq string (concat incomplete string))) + (save-match-data + (cond + ((and process (not (string-suffix-p "\n" string))) + (let ((length (length string))) + (when (> length with-editor--max-incomplete-length) + (setq string + (substring string + (- length with-editor--max-incomplete-length))))) + (process-put process 'incomplete string) + nil) + ((string-match with-editor-sleeping-editor-regexp string) + (when process + (process-put process 'incomplete nil)) + (let ((pid (match-string 1 string)) + (arg0 (match-string 2 string)) + (arg1 (match-string 3 string)) + (dir (match-string 4 string)) + file line column) + (cond ((string-match "\\`\\+\\([0-9]+\\)\\(?::\\([0-9]+\\)\\)?\\'" arg0) + (setq file arg1) + (setq line (string-to-number (match-string 1 arg0))) + (setq column (match-string 2 arg0)) + (setq column (and column (string-to-number column)))) + ((setq file arg0))) + (unless (file-name-absolute-p file) + (setq file (expand-file-name file dir))) + (when default-directory + (setq file (concat (file-remote-p default-directory) file))) + (with-current-buffer (find-file-noselect file) + (with-editor-mode 1) + (setq with-editor--pid pid) + (setq with-editor-previous-winconf + (current-window-configuration)) + (when line + (let ((pos (save-excursion + (save-restriction + (goto-char (point-min)) + (forward-line (1- line)) + (when column + (move-to-column column)) + (point))))) + (when (and (buffer-narrowed-p) + widen-automatically + (not (<= (point-min) pos (point-max)))) + (widen)) + (goto-char pos))) + (run-hooks 'with-editor-filter-visit-hook) + (funcall (or (with-editor-server-window) #'switch-to-buffer) + (current-buffer)) + (kill-local-variable 'server-window))) + nil) + (t string)))) + +(defun with-editor-process-filter + (process string &optional no-default-filter) + "Listen for edit requests by child processes." + (let ((default-directory (process-get process 'default-dir))) + (with-editor-sleeping-editor-filter process string)) + (unless no-default-filter + (internal-default-process-filter process string))) + +(define-advice server-visit-files + (:after (files _proc &optional _nowait) + with-editor-file-name-history-exclude) + "Prevent certain files from being added to `file-name-history'. +Files matching a regexp in `with-editor-file-name-history-exclude' +are prevented from being added to that list." + (pcase-dolist (`(,file . ,_) files) + (when (cl-find-if (lambda (regexp) + (string-match-p regexp file)) + with-editor-file-name-history-exclude) + (setq file-name-history + (delete (abbreviate-file-name file) file-name-history))))) + +;;; Augmentations + +;;;###autoload +(cl-defun with-editor-export-editor (&optional (envvar "EDITOR")) + "Teach subsequent commands to use current Emacs instance as editor. + +Set and export the environment variable ENVVAR, by default +\"EDITOR\". The value is automatically generated to teach +commands to use the current Emacs instance as \"the editor\". + +This works in `shell-mode', `term-mode', `eshell-mode' and +`vterm'." + (interactive (list (with-editor-read-envvar))) + (cond + ((derived-mode-p 'comint-mode 'term-mode) + (when-let ((process (get-buffer-process (current-buffer)))) + (goto-char (process-mark process)) + (process-send-string + process (format " export %s=%s\n" envvar + (shell-quote-argument with-editor-sleeping-editor))) + (while (accept-process-output process 1 nil t)) + (if (derived-mode-p 'term-mode) + (with-editor-set-process-filter process #'with-editor-emulate-terminal) + (add-hook 'comint-output-filter-functions #'with-editor-output-filter + nil t)))) + ((derived-mode-p 'eshell-mode) + (add-to-list 'eshell-preoutput-filter-functions + #'with-editor-output-filter) + (setenv envvar with-editor-sleeping-editor)) + ((and (derived-mode-p 'vterm-mode) + (fboundp 'vterm-send-return) + (fboundp 'vterm-send-string)) + (if with-editor-emacsclient-executable + (let ((with-editor--envvar envvar) + (process-environment process-environment)) + (with-editor--setup) + (while (accept-process-output vterm--process 1 nil t)) + (when-let ((v (getenv envvar))) + (vterm-send-string (format " export %s=%S" envvar v)) + (vterm-send-return)) + (when-let ((v (getenv "EMACS_SERVER_FILE"))) + (vterm-send-string (format " export EMACS_SERVER_FILE=%S" v)) + (vterm-send-return)) + (vterm-send-string "clear") + (vterm-send-return)) + (error "Cannot use sleeping editor in this buffer"))) + (t + (error "Cannot export environment variables in this buffer"))) + (message "Successfully exported %s" envvar)) + +;;;###autoload +(defun with-editor-export-git-editor () + "Like `with-editor-export-editor' but always set `$GIT_EDITOR'." + (interactive) + (with-editor-export-editor "GIT_EDITOR")) + +;;;###autoload +(defun with-editor-export-hg-editor () + "Like `with-editor-export-editor' but always set `$HG_EDITOR'." + (interactive) + (with-editor-export-editor "HG_EDITOR")) + +(defun with-editor-output-filter (string) + "Handle edit requests on behalf of `comint-mode' and `eshell-mode'." + (with-editor-sleeping-editor-filter nil string)) + +(defun with-editor-emulate-terminal (process string) + "Like `term-emulate-terminal' but also handle edit requests." + (let ((with-editor-sleeping-editor-regexp + (substring with-editor-sleeping-editor-regexp 1))) + (with-editor-sleeping-editor-filter process string)) + (term-emulate-terminal process string)) + +(defvar with-editor-envvars '("EDITOR" "GIT_EDITOR" "HG_EDITOR")) + +(cl-defun with-editor-read-envvar + (&optional (prompt "Set environment variable") + (default "EDITOR")) + (let ((reply (completing-read (if default + (format "%s (%s): " prompt default) + (concat prompt ": ")) + with-editor-envvars nil nil nil nil default))) + (if (string= reply "") (user-error "Nothing selected") reply))) + +;;;###autoload +(define-minor-mode shell-command-with-editor-mode + "Teach `shell-command' to use current Emacs instance as editor. + +Teach `shell-command', and all commands that ultimately call that +command, to use the current Emacs instance as editor by executing +\"EDITOR=CLIENT COMMAND&\" instead of just \"COMMAND&\". + +CLIENT is automatically generated; EDITOR=CLIENT instructs +COMMAND to use to the current Emacs instance as \"the editor\", +assuming no other variable overrides the effect of \"$EDITOR\". +CLIENT may be the path to an appropriate emacsclient executable +with arguments, or a script which also works over Tramp. + +Alternatively you can use the `with-editor-async-shell-command', +which also allows the use of another variable instead of +\"EDITOR\"." + :global t) + +;;;###autoload +(defun with-editor-async-shell-command + (command &optional output-buffer error-buffer envvar) + "Like `async-shell-command' but with `$EDITOR' set. + +Execute string \"ENVVAR=CLIENT COMMAND\" in an inferior shell; +display output, if any. With a prefix argument prompt for an +environment variable, otherwise the default \"EDITOR\" variable +is used. With a negative prefix argument additionally insert +the COMMAND's output at point. + +CLIENT is automatically generated; ENVVAR=CLIENT instructs +COMMAND to use to the current Emacs instance as \"the editor\", +assuming it respects ENVVAR as an \"EDITOR\"-like variable. +CLIENT may be the path to an appropriate emacsclient executable +with arguments, or a script which also works over Tramp. + +Also see `async-shell-command' and `shell-command'." + (interactive (with-editor-shell-command-read-args "Async shell command: " t)) + (let ((with-editor--envvar envvar)) + (with-editor + (async-shell-command command output-buffer error-buffer)))) + +;;;###autoload +(defun with-editor-shell-command + (command &optional output-buffer error-buffer envvar) + "Like `shell-command' or `with-editor-async-shell-command'. +If COMMAND ends with \"&\" behave like the latter, +else like the former." + (interactive (with-editor-shell-command-read-args "Shell command: ")) + (if (string-match "&[ \t]*\\'" command) + (with-editor-async-shell-command + command output-buffer error-buffer envvar) + (shell-command command output-buffer error-buffer))) + +(defun with-editor-shell-command-read-args (prompt &optional async) + (let ((command (read-shell-command + prompt nil nil + (let ((filename (or buffer-file-name + (and (eq major-mode 'dired-mode) + (dired-get-filename nil t))))) + (and filename (file-relative-name filename)))))) + (list command + (if (or async (setq async (string-match-p "&[ \t]*\\'" command))) + (< (prefix-numeric-value current-prefix-arg) 0) + current-prefix-arg) + shell-command-default-error-buffer + (and async current-prefix-arg (with-editor-read-envvar))))) + +(define-advice shell-command + (:around (fn command &optional output-buffer error-buffer) + shell-command-with-editor-mode) + "Set editor envvar, if `shell-command-with-editor-mode' is enabled. +Also take care of that for `with-editor-[async-]shell-command'." + ;; `shell-mode' and its hook are intended for buffers in which an + ;; interactive shell is running, but `shell-command' also turns on + ;; that mode, even though it only runs the shell to run a single + ;; command. The `with-editor-export-editor' hook function is only + ;; intended to be used in buffers in which an interactive shell is + ;; running, so it has to be removed here. + (let ((shell-mode-hook (remove 'with-editor-export-editor shell-mode-hook))) + (cond + ;; If `with-editor-async-shell-command' was used, then `with-editor' + ;; was used, and `with-editor--envvar'. `with-editor-shell-command' + ;; only goes down that path if the command ends with "&". We might + ;; still have to use `with-editor' here, for `async-shell-command' + ;; or `shell-command', if the mode is enabled. + ((and (string-suffix-p "&" command) + (or with-editor--envvar + shell-command-with-editor-mode)) + (if with-editor--envvar + (funcall fn command output-buffer error-buffer) + (with-editor (funcall fn command output-buffer error-buffer))) + ;; The comint filter was overridden with our filter. Use both. + (and-let* ((process (get-buffer-process + (or output-buffer + (get-buffer "*Async Shell Command*"))))) + (prog1 process + (set-process-filter process + (lambda (proc str) + (comint-output-filter proc str) + (with-editor-process-filter proc str t)))))) + ((funcall fn command output-buffer error-buffer))))) + +;;; _ + +(defun with-editor-debug () + "Debug configuration issues. +See info node `(with-editor)Debugging' for instructions." + (interactive) + (require 'warnings) + (with-current-buffer (get-buffer-create "*with-editor-debug*") + (pop-to-buffer (current-buffer)) + (erase-buffer) + (ignore-errors (with-editor)) + (insert + (format "with-editor: %s\n" (locate-library "with-editor.el")) + (format "emacs: %s (%s)\n" + (expand-file-name invocation-name invocation-directory) + emacs-version) + "system:\n" + (format " system-type: %s\n" system-type) + (format " system-configuration: %s\n" system-configuration) + (format " system-configuration-options: %s\n" system-configuration-options) + "server:\n" + (format " server-running-p: %s\n" (server-running-p)) + (format " server-process: %S\n" server-process) + (format " server-use-tcp: %s\n" server-use-tcp) + (format " server-name: %s\n" server-name) + (format " server-socket-dir: %s\n" server-socket-dir)) + (if (and server-socket-dir (file-accessible-directory-p server-socket-dir)) + (dolist (file (directory-files server-socket-dir nil "^[^.]")) + (insert (format " %s\n" file))) + (insert (format " %s: not an accessible directory\n" + (if server-use-tcp "WARNING" "ERROR")))) + (insert (format " server-auth-dir: %s\n" server-auth-dir)) + (if (file-accessible-directory-p server-auth-dir) + (dolist (file (directory-files server-auth-dir nil "^[^.]")) + (insert (format " %s\n" file))) + (insert (format " %s: not an accessible directory\n" + (if server-use-tcp "ERROR" "WARNING")))) + (let ((val with-editor-emacsclient-executable) + (def (default-value 'with-editor-emacsclient-executable)) + (fun (let ((warning-minimum-level :error) + (warning-minimum-log-level :error)) + (with-editor-locate-emacsclient)))) + (insert "with-editor-emacsclient-executable:\n" + (format " value: %s (%s)\n" val + (and val (with-editor-emacsclient-version val))) + (format " default: %s (%s)\n" def + (and def (with-editor-emacsclient-version def))) + (format " funcall: %s (%s)\n" fun + (and fun (with-editor-emacsclient-version fun))))) + (insert "path:\n" + (format " $PATH: %s\n" (split-string (getenv "PATH") ":")) + (format " exec-path: %s\n" exec-path)) + (insert (format " with-editor-emacsclient-path:\n")) + (dolist (dir (with-editor-emacsclient-path)) + (insert (format " %s (%s)\n" dir (car (file-attributes dir)))) + (when (file-directory-p dir) + ;; Don't match emacsclientw.exe, it makes popup windows. + (dolist (exec (directory-files dir t "emacsclient\\(?:[^w]\\|\\'\\)")) + (insert (format " %s (%s)\n" exec + (with-editor-emacsclient-version exec)))))))) + +(defconst with-editor-font-lock-keywords + '(("(\\(with-\\(?:git-\\)?editor\\)\\_>" (1 'font-lock-keyword-face)))) +(font-lock-add-keywords 'emacs-lisp-mode with-editor-font-lock-keywords) + +(provide 'with-editor) +;; Local Variables: +;; indent-tabs-mode: nil +;; byte-compile-warnings: (not docstrings-control-chars) +;; End: +;;; with-editor.el ends here diff --git a/elpa/with-editor-3.4.3/with-editor.elc b/elpa/with-editor-3.4.3/with-editor.elc Binary files differnew file mode 100644 index 0000000..8b65ea8 --- /dev/null +++ b/elpa/with-editor-3.4.3/with-editor.elc diff --git a/elpa/with-editor-3.4.3/with-editor.info b/elpa/with-editor-3.4.3/with-editor.info new file mode 100644 index 0000000..bdd6dfa --- /dev/null +++ b/elpa/with-editor-3.4.3/with-editor.info @@ -0,0 +1,384 @@ +This is docua7I5P.info, produced by makeinfo version 6.8 from +with-editor.texi. + + Copyright (C) 2015-2024 Jonas Bernoulli + <emacs.with-editor@jonas.bernoulli.dev> + + You can redistribute this document 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 document 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. + +INFO-DIR-SECTION Emacs +START-INFO-DIR-ENTRY +* With-Editor: (with-editor). Using the Emacsclient as $EDITOR. +END-INFO-DIR-ENTRY + + +File: docua7I5P.info, Node: Top, Next: Using the With-Editor package, Up: (dir) + +With-Editor User Manual +*********************** + +The library âwith-editorâ makes it easy to use the Emacsclient as the +â$EDITORâ of child processes, making sure they know how to call home. +For remote processes a substitute is provided, which communicates with +Emacs on standard output instead of using a socket as the Emacsclient +does. + + This library was written because Magit has to be able to do the above +to allow the user to edit commit messages gracefully and to edit rebase +sequences, which wouldnât be possible at all otherwise. + + Because other packages can benefit from such functionality, this +library is made available as a separate package. It also defines some +additional functionality which makes it useful even for end-users, who +donât use Magit or another package which uses it internally. + +This manual is for With-Editor version 3.4.3. + + Copyright (C) 2015-2024 Jonas Bernoulli + <emacs.with-editor@jonas.bernoulli.dev> + + You can redistribute this document 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 document 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. + +* Menu: + +* Using the With-Editor package:: +* Using With-Editor as a library:: +* Debugging:: +* Function and Command Index:: +* Variable Index:: + +â The Detailed Node Listing â + +Using the With-Editor package + +* Configuring With-Editor:: +* Using With-Editor commands:: + + + +File: docua7I5P.info, Node: Using the With-Editor package, Next: Using With-Editor as a library, Prev: Top, Up: Top + +1 Using the With-Editor package +******************************* + +The âWith-Editorâ package is used internally by Magit when editing +commit messages and rebase sequences. It also provides some commands +and features which are useful by themselves, even if you donât use +Magit. + + For information about using this library in your own package, see +*note Using With-Editor as a library::. + +* Menu: + +* Configuring With-Editor:: +* Using With-Editor commands:: + + +File: docua7I5P.info, Node: Configuring With-Editor, Next: Using With-Editor commands, Up: Using the With-Editor package + +1.1 Configuring With-Editor +=========================== + +With-Editor tries very hard to locate a suitable âemacsclientâ +executable, so ideally you should never have to customize the option +âwith-editor-emacsclient-executableâ. When it fails to do so, then the +most likely reason is that someone found yet another way to package +Emacs (most likely on macOS) without putting the executable on â$PATHâ, +and we have to add another kludge to find it anyway. + + -- User Option: with-editor-emacsclient-executable + The âemacsclientâ executable used as the editor by child processes + of this Emacs instance. By using this executable, child processes + can call home to their parent process. + + This option is automatically set at startup by looking in + âexec-pathâ, and other places where the executable could be + installed, to find the âemacsclientâ executable most suitable for + the current Emacs instance. + + You should *not* customize this option permanently. If you have to + do it, then you should consider that a temporary kludge and inform + the Magit maintainer as described in *note Debugging: Debugging. + + If With-Editor fails to find a suitable âemacsclientâ on your + system, then this should be fixed for all users at once, by + teaching âwith-editor-locate-emacsclientâ how to do so on your + system and systems like yours. Doing it this way has the + advantage, that you wonât have do it again every time you update + Emacs, and that other users who have installed Emacs the same way + as you have, wonât have to go through the same trouble. + + Note that there also is a nuclear option; setting this variable to + ânilâ causes the "sleeping editor" described below to be used even + for local child processes. Obviously we donât recommend that you + use this except in "emergencies", i.e., before we had a change to + add a kludge appropriate for your setup. + + -- Function: with-editor-locate-emacsclient + The function used to set the initial value of the option + âwith-editor-emacsclient-executableâ. Thereâs a lot of voodoo + here. + + The âemacsclientâ cannot be used when using Tramp to run a process on +a remote machine. (Theoretically it could, but that would be hard to +setup, very fragile, and rather insecure). + + With-Editor provides an alternative "editor" which can be used by +remote processes in much the same way as local processes use an +âemacsclientâ executable. This alternative is known as the "sleeping +editor" because it is implemented as a shell script which sleeps until +it receives a signal. + + -- User Option: with-editor-sleeping-editor + The sleeping editor is a shell script used as the editor of child + processes when the âemacsclientâ executable cannot be used. + + This fallback is used for asynchronous processes started inside the + macro âwith-editorâ, when the process runs on a remote machine or + for local processes when âwith-editor-emacsclient-executableâ is + ânilâ. + + Where the latter uses a socket to communicate with Emacsâ server, + this substitute prints edit requests to its standard output on + which a process filter listens for such requests. As such it is + not a complete substitute for a proper âemacsclientâ, it can only + be used as â$EDITORâ of child process of the current Emacs + instance. + + Some shells do not execute traps immediately when waiting for a + child process, but by default we do use such a blocking child + process. + + If you use such a shell (e.g., âcshâ on FreeBSD, but not Debian), + then you have to edit this option. You can either replace âshâ + with âbashâ (and install that), or you can use the older, less + performant implementation: + + "sh -c '\ + echo \"WITH-EDITOR: $$ OPEN $0 $1 IN $(pwd)\"; \ + trap \"exit 0\" USR1; \ + trap \"exit 1\" USR2; \ + while true; do sleep 1; done'" + + Note that the unit separator character ( ) right after the file name + ($0) is required. + + Also note that using this alternative implementation leads to a + delay of up to a second. The delay can be shortened by replacing + âsleep 1â with âsleep 0.01â, or if your implementation does not + support floats, then by using ânanosleepâ instead. + + +File: docua7I5P.info, Node: Using With-Editor commands, Prev: Configuring With-Editor, Up: Using the With-Editor package + +1.2 Using With-Editor commands +============================== + +This section describes how to use the âwith-editorâ library _outside_ of +Magit. You donât need to know any of this just to create commits using +Magit. + + The commands âwith-editor-async-shell-commandâ and +âwith-editor-shell-commandâ are intended as drop in replacements for +âasync-shell-commandâ and âshell-commandâ. They automatically export +â$EDITORâ making sure the executed command uses the current Emacs +instance as "the editor". With a prefix argument these commands prompt +for an alternative environment variable such as â$GIT_EDITORâ. + + -- Command: with-editor-async-shell-command + This command is like âasync-shell-commandâ, but it runs the shell + command with the current Emacs instance exported as â$EDITORâ. + + -- Command: with-editor-shell-command + This command is like âshell-commandâ, but if the shell command ends + with â&â and is therefore run asynchronously, then the current + Emacs instance is exported as â$EDITORâ. + + To always use these variants add this to your init file: + + (keymap-global-set "<remap> <async-shell-command>" + #'with-editor-async-shell-command) + (keymap-global-set "<remap> <shell-command>" + #'with-editor-shell-command) + + Alternatively use the global âshell-command-with-editor-modeâ. + + -- Variable: shell-command-with-editor-mode + When this mode is active, then â$EDITORâ is exported whenever + ultimately âshell-commandâ is called to asynchronously run some + shell command. This affects most variants of that command, whether + they are defined in Emacs or in some third-party package. + + The command âwith-editor-export-editorâ exports â$EDITORâ or another +such environment variable in âshell-modeâ, âeshell-modeâ, âterm-modeâ +and âvterm-modeâ buffers. Use this Emacs command before executing a +shell command which needs the editor set, or always arrange for the +current Emacs instance to be used as editor by adding it to the +appropriate mode hooks: + + (add-hook 'shell-mode-hook 'with-editor-export-editor) + (add-hook 'eshell-mode-hook 'with-editor-export-editor) + (add-hook 'term-exec-hook 'with-editor-export-editor) + (add-hook 'vterm-mode-hook 'with-editor-export-editor) + + Some variants of this function exist; these two forms are equivalent: + + (add-hook 'shell-mode-hook + (apply-partially 'with-editor-export-editor "GIT_EDITOR")) + (add-hook 'shell-mode-hook 'with-editor-export-git-editor) + + -- Command: with-editor-export-editor + When invoked in a âshell-modeâ, âeshell-modeâ, âterm-modeâ or + âvterm-modeâ buffer, this command teaches shell commands to use the + current Emacs instance as the editor, by exporting â$EDITORâ. + + -- Command: with-editor-export-git-editor + This command is like âwith-editor-export-editorâ but exports + â$GIT_EDITORâ. + + -- Command: with-editor-export-hg-editor + This command is like âwith-editor-export-editorâ but exports + â$HG_EDITORâ. + + +File: docua7I5P.info, Node: Using With-Editor as a library, Next: Debugging, Prev: Using the With-Editor package, Up: Top + +2 Using With-Editor as a library +******************************** + +This section describes how to use the âwith-editorâ library _outside_ of +Magit to teach another package how to have its child processes call +home, just like Magit does. You donât need to know any of this just to +create commits using Magit. You can also ignore this if you use +âwith-editorâ outside of Magit, but only as an end-user. + + For information about interactive use and options that affect both +interactive and non-interactive use, see *note Using the With-Editor +package::. + + -- Macro: with-editor &rest body + This macro arranges for the âemacsclientâ or the sleeping editor to + be used as the editor of child processes, effectively teaching them + to call home to the current Emacs instance when they require that + the user edits a file. + + This is done by establishing a local binding for + âprocess-environmentâ and changing the value of the âEDITORâ + environment variable in that scope. This affects all + (asynchronous) processes started by forms (dynamically) inside + BODY. + + If BODY begins with a literal string, then that variable is set + instead of âEDITORâ. + + -- Macro: with-editor* envvar &rest body + This macro is like âwith-editorâ, except that the ENVVAR argument + is required and that it is evaluated at run-time. + + -- Function: with-editor-set-process-filter process filter + This function is like âset-process-filterâ but ensures that adding + the new FILTER does not remove the âwith-editor-process-filterâ. + This is done by wrapping the two filter functions using a lambda, + which becomes the actual filter. It calls FILTER first, which may + or may not insert the text into the PROCESSâs buffer. Then it + calls âwith-editor-process-filterâ, passing âtâ as + NO-STANDARD-FILTER. + + +File: docua7I5P.info, Node: Debugging, Next: Function and Command Index, Prev: Using With-Editor as a library, Up: Top + +3 Debugging +*********** + +With-Editor tries very hard to locate a suitable âemacsclientâ +executable, and then sets option âwith-editor-emacsclient-executableâ +accordingly. In very rare cases this fails. When it does fail, then +the most likely reason is that someone found yet another way to package +Emacs (most likely on macOS) without putting the executable on â$PATHâ, +and we have to add another kludge to find it anyway. + + If you are having problems using âwith-editorâ, e.g., you cannot +commit in Magit, then please open a new issue at +<https://github.com/magit/with-editor/issues> and provide information +about your Emacs installation. Most importantly how did you install +Emacs and what is the output of âM-x with-editor-debug RETâ. + + +File: docua7I5P.info, Node: Function and Command Index, Next: Variable Index, Prev: Debugging, Up: Top + +Appendix A Function and Command Index +************************************* + + +* Menu: + +* with-editor: Using With-Editor as a library. + (line 16) +* with-editor*: Using With-Editor as a library. + (line 31) +* with-editor-async-shell-command: Using With-Editor commands. + (line 17) +* with-editor-export-editor: Using With-Editor commands. + (line 59) +* with-editor-export-git-editor: Using With-Editor commands. + (line 64) +* with-editor-export-hg-editor: Using With-Editor commands. + (line 68) +* with-editor-locate-emacsclient: Configuring With-Editor. + (line 41) +* with-editor-set-process-filter: Using With-Editor as a library. + (line 35) +* with-editor-shell-command: Using With-Editor commands. + (line 21) + + +File: docua7I5P.info, Node: Variable Index, Prev: Function and Command Index, Up: Top + +Appendix B Variable Index +************************* + + +* Menu: + +* shell-command-with-editor-mode: Using With-Editor commands. + (line 35) +* with-editor-emacsclient-executable: Configuring With-Editor. + (line 13) +* with-editor-sleeping-editor: Configuring With-Editor. + (line 56) + + + +Tag Table: +Node: Top797 +Node: Using the With-Editor package2611 +Node: Configuring With-Editor3196 +Node: Using With-Editor commands7759 +Node: Using With-Editor as a library11059 +Node: Debugging13089 +Node: Function and Command Index13979 +Node: Variable Index15475 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: |