+++ /dev/null
-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.
-\1f
-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
-* Magit-Popup: (magit-popup). Infix arguments with feedback.
+++ /dev/null
-;;; magit-popup-autoloads.el --- automatically extracted autoloads
-;;
-;;; Code:
-
-(add-to-list 'load-path (directory-file-name
- (or (file-name-directory #$) (car load-path))))
-
-\f
-;;;### (autoloads nil "magit-popup" "magit-popup.el" (0 0 0 0))
-;;; Generated autoloads from magit-popup.el
-
-(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "magit-popup" '("magit-")))
-
-;;;***
-\f
-;;;### (autoloads nil nil ("magit-popup-pkg.el") (0 0 0 0))
-
-;;;***
-\f
-;; Local Variables:
-;; version-control: never
-;; no-byte-compile: t
-;; no-update-autoloads: t
-;; coding: utf-8
-;; End:
-;;; magit-popup-autoloads.el ends here
+++ /dev/null
-(define-package "magit-popup" "20190223.2234" "Define prefix-infix-suffix command combos"
- '((emacs "24.4")
- (async "1.9.2")
- (dash "2.13.0"))
- :keywords
- '("bindings")
- :authors
- '(("Jonas Bernoulli" . "jonasNOSPAMbernoul.li"))
- :maintainer
- '("Jonas Bernoulli" . "jonasNOSPAMbernoul.li")
- :url "https://github.com/magit/magit-popup")
-;; Local Variables:
-;; no-byte-compile: t
-;; End:
+++ /dev/null
-;;; magit-popup.el --- Define prefix-infix-suffix command combos -*- lexical-binding: t -*-
-
-;; Copyright (C) 2010-2019 The Magit Project Contributors
-;;
-;; You should have received a copy of the AUTHORS.md file which
-;; lists all contributors. If not, see http://magit.vc/authors.
-
-;; This library was inspired by and replaces library `magit-key-mode',
-;; which was written by Phil Jackson <philNOSPAMshellarchive.co.uk> and is
-;; distributed under the GNU General Public License version 3 or later.
-
-;; Author: Jonas Bernoulli <jonasNOSPAMbernoul.li>
-;; Maintainer: Jonas Bernoulli <jonasNOSPAMbernoul.li>
-
-;; Package-Requires: ((emacs "24.4") (async "1.9.2") (dash "2.13.0"))
-;; Keywords: bindings
-;; Homepage: https://github.com/magit/magit-popup
-
-;; Magit-Popup 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, or (at your option)
-;; any later version.
-;;
-;; Magit-Popup 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 Magit-Popup. If not, see http://www.gnu.org/licenses.
-
-;;; Commentary:
-
-;; This package implements a generic interface for toggling switches
-;; and setting options and then invoking an Emacs command that does
-;; something with these arguments. Usually the command calls an
-;; external process with the specified arguments.
-
-;; This package has been superseded by Transient. No new features
-;; will be added but bugs will be fixes.
-
-;;; Code:
-
-(require 'button)
-(require 'cl-lib)
-(require 'dash)
-(require 'format-spec)
-(eval-when-compile (require 'subr-x))
-
-(and (require 'async-bytecomp nil t)
- (cl-intersection '(all magit)
- (bound-and-true-p async-bytecomp-allowed-packages))
- (fboundp 'async-bytecomp-package-mode)
- (async-bytecomp-package-mode 1))
-
-(declare-function info 'info)
-(declare-function Man-find-section 'man)
-(declare-function Man-next-section 'man)
-
-;; For branch actions.
-(declare-function magit-branch-set-face 'magit-git)
-
-;;; Settings
-;;;; Custom Groups
-
-(defgroup magit-popup nil
- "Infix arguments with a popup as feedback."
- :link '(info-link "(magit-popup)")
- :group 'bindings)
-
-(defgroup magit-popup-faces nil
- "Faces used by Magit-Popup."
- :group 'magit-popup)
-
-;;;; Custom Options
-
-(defcustom magit-popup-display-buffer-action '((display-buffer-below-selected))
- "The action used to display a popup buffer.
-
-Popup buffers are displayed using `display-buffer' with the value
-of this option as ACTION argument. You can also set this to nil
-and instead add an entry to `display-buffer-alist'."
- :package-version '(magit-popup . "2.4.0")
- :group 'magit-popup
- :type 'sexp)
-
-(defcustom magit-popup-manpage-package
- (if (memq system-type '(windows-nt ms-dos)) 'woman 'man)
- "The package used to display manpages.
-One of `man' or `woman'."
- :group 'magit-popup
- :type '(choice (const man) (const woman)))
-
-(defcustom magit-popup-show-help-echo t
- "Show usage information in the echo area."
- :group 'magit-popup
- :type 'boolean)
-
-(defcustom magit-popup-show-common-commands nil
- "Whether to initially show section with commands common to all popups.
-This section can also be toggled temporarily using \
-\\<magit-popup-mode-map>\\[magit-popup-toggle-show-common-commands]."
- :package-version '(magit-popup . "2.9.0")
- :group 'magit-popup
- :type 'boolean)
-
-(defcustom magit-popup-use-prefix-argument 'default
- "Control how prefix arguments affect infix argument popups.
-
-This option controls the effect that the use of a prefix argument
-before entering a popup has.
-
-`default' With a prefix argument directly invoke the popup's
- default action (an Emacs command), instead of bringing
- up the popup.
-
-`popup' With a prefix argument bring up the popup, otherwise
- directly invoke the popup's default action.
-
-`nil' Ignore prefix arguments."
- :group 'magit-popup
- :type '(choice
- (const :tag "Call default action instead of showing popup" default)
- (const :tag "Show popup instead of calling default action" popup)
- (const :tag "Ignore prefix argument" nil)))
-
-;;;; Custom Faces
-
-(defface magit-popup-heading
- '((t :inherit font-lock-keyword-face))
- "Face for key mode header lines."
- :group 'magit-popup-faces)
-
-(defface magit-popup-key
- '((t :inherit font-lock-builtin-face))
- "Face for key mode buttons."
- :group 'magit-popup-faces)
-
-(defface magit-popup-argument
- '((t :inherit font-lock-warning-face))
- "Face used to display enabled arguments in popups."
- :group 'magit-popup-faces)
-
-(defface magit-popup-disabled-argument
- '((t :inherit shadow))
- "Face used to display disabled arguments in popups."
- :group 'magit-popup-faces)
-
-(defface magit-popup-option-value
- '((t :inherit font-lock-string-face))
- "Face used to display option values in popups."
- :group 'magit-popup-faces)
-
-;;;; Keymap
-
-(defvar magit-popup-mode-map
- (let ((map (make-sparse-keymap)))
- (define-key map [remap self-insert-command] 'magit-invoke-popup-action)
- (define-key map (kbd "- <t>") 'magit-invoke-popup-switch)
- (define-key map (kbd "= <t>") 'magit-invoke-popup-option)
- (define-key map (kbd "C-g") 'magit-popup-quit)
- (define-key map (kbd "?") 'magit-popup-help)
- (define-key map (kbd "C-h k") 'magit-popup-help)
- (define-key map (kbd "C-h i") 'magit-popup-info)
- (define-key map (kbd "C-t") 'magit-popup-toggle-show-common-commands)
- (define-key map (kbd "C-c C-c") 'magit-popup-set-default-arguments)
- (define-key map (kbd "C-x C-s") 'magit-popup-save-default-arguments)
- (cond ((featurep 'jkl)
- (define-key map (kbd "C-p") 'universal-argument)
- (define-key map [return] 'push-button)
- (define-key map (kbd "C-i") 'backward-button)
- (define-key map (kbd "C-k") 'forward-button))
- (t
- (define-key map (kbd "C-m") 'push-button)
- (define-key map (kbd "DEL") 'backward-button)
- (define-key map (kbd "C-p") 'backward-button)
- (define-key map (kbd "C-i") 'forward-button)
- (define-key map (kbd "C-n") 'forward-button)))
- map)
- "Keymap for `magit-popup-mode'.
-
-\\<magit-popup-mode-map>\
-This keymap contains bindings common to all popups. A section
-listing these commands can be shown or hidden using \
-\\[magit-popup-toggle-show-common-commands].
-
-The prefix used to toggle any switch can be changed by binding
-another key to `magit-invoke-popup-switch'. Likewise binding
-another key to `magit-invoke-popup-option' changes the prefixed
-used to set any option. The two prefixes have to be different.
-If you change these bindings, you should also change the `prefix'
-property of the button types `magit-popup-switch-button' and
-`magit-popup-option-button'.
-
-If you change any other binding, then you might have to also edit
-`magit-popup-common-commands' for things to align correctly in
-the section listing these commands.
-
-Never bind an alphabetic character in this keymap or you might
-make it impossible to invoke certain actions.")
-
-(defvar magit-popup-common-commands
- '(("Set defaults" magit-popup-set-default-arguments)
- ("View popup manual" magit-popup-info)
- ("Toggle this section" magit-popup-toggle-show-common-commands)
- ("Save defaults" magit-popup-save-default-arguments)
- (" Popup help prefix" magit-popup-help)
- ("Abort" magit-popup-quit)))
-
-;;;; Buttons
-
-(define-button-type 'magit-popup-button
- 'face nil
- 'action (lambda (button)
- (funcall (button-get button 'function)
- (button-get button 'event))))
-
-(define-button-type 'magit-popup-switch-button
- 'supertype 'magit-popup-button
- 'function 'magit-invoke-popup-switch
- 'property :switches
- 'heading "Switches\n"
- 'formatter 'magit-popup-format-argument-button
- 'format " %k %d (%a)"
- 'prefix ?-
- 'maxcols 1)
-
-(define-button-type 'magit-popup-option-button
- 'supertype 'magit-popup-button
- 'function 'magit-invoke-popup-option
- 'property :options
- 'heading "Options\n"
- 'formatter 'magit-popup-format-argument-button
- 'format " %k %d (%a%v)"
- 'prefix ?=
- 'maxcols 1)
-
-(define-button-type 'magit-popup-variable-button
- 'supertype 'magit-popup-button
- 'function 'magit-invoke-popup-action
- 'property :variables
- 'heading "Variables\n"
- 'formatter 'magit-popup-format-variable-button
- 'format " %k %d"
- 'prefix nil
- 'maxcols 1)
-
-(define-button-type 'magit-popup-action-button
- 'supertype 'magit-popup-button
- 'function 'magit-invoke-popup-action
- 'property :actions
- 'heading "Actions\n"
- 'formatter 'magit-popup-format-action-button
- 'format " %k %d"
- 'prefix nil
- 'maxcols :max-action-columns)
-
-(define-button-type 'magit-popup-command-button
- 'supertype 'magit-popup-action-button
- 'formatter 'magit-popup-format-command-button
- 'action (lambda (button)
- (let ((command (button-get button 'function)))
- (unless (eq command 'push-button)
- (call-interactively command)))))
-
-(define-button-type 'magit-popup-internal-command-button
- 'supertype 'magit-popup-command-button
- 'heading "Common Commands\n"
- 'maxcols 3)
-
-;;; Events
-
-(defvar-local magit-this-popup nil
- "The popup which is currently active.
-This is intended for internal use only.
-Don't confuse this with `magit-current-popup'.")
-
-(defvar-local magit-this-popup-events nil
- "The events known to the active popup.
-This is intended for internal use only.
-Don't confuse this with `magit-current-popup-args'.")
-
-(defvar-local magit-previous-popup nil)
-
-(defvar-local magit-pre-popup-buffer nil
- "The buffer that was current before invoking the active popup.")
-
-(defun magit-popup-get (prop)
- "While a popup is active, get the value of PROP."
- (if (memq prop '(:switches :options :variables :actions))
- (plist-get magit-this-popup-events prop)
- (plist-get (symbol-value magit-this-popup) prop)))
-
-(defun magit-popup-put (prop val)
- "While a popup is active, set the value of PROP to VAL."
- (if (memq prop '(:switches :options :variables :actions))
- (setq magit-this-popup-events
- (plist-put magit-this-popup-events prop val))
- (error "Property %s isn't supported" prop)))
-
-(defvar magit-current-popup nil
- "The popup from which this editing command was invoked.
-
-Use this inside the `interactive' form of a popup aware command
-to determine whether it was invoked from a popup and if so from
-which popup. If the current command was invoked without the use
-of a popup, then this is nil.")
-
-(defvar magit-current-popup-action nil
- "The popup action now being executed.")
-
-(defvar magit-current-popup-args nil
- "The value of the popup arguments for this editing command.
-
-If the current command was invoked from a popup, then this is
-a list of strings of all the set switches and options. This
-includes arguments which are set by default not only those
-explicitly set during this invocation.
-
-When the value is nil, then that can be because no argument is
-set, or because the current command wasn't invoked from a popup;
-consult `magit-current-popup' to tell the difference.
-
-Generally it is better to use `NAME-arguments', which is created
-by `magit-define-popup', instead of this variable or the function
-by the same name, because `NAME-argument' uses the default value
-for the arguments when the editing command is invoked directly
-instead of from a popup. When the command is bound in several
-popups that might not be feasible though.")
-
-(defun magit-current-popup-args (&rest filter)
- "Return the value of the popup arguments for this editing command.
-
-The value is the same as that of the variable by the same name
-\(which see), except that FILTER is applied. FILTER is a list
-of regexps; only arguments that match one of them are returned.
-The first element of FILTER may also be `:not' in which case
-only arguments that don't match any of the regexps are returned,
-or `:only' which doesn't change the behaviour."
- (let ((-compare-fn (lambda (a b) (magit-popup-arg-match b a))))
- (-filter (if (eq (car filter) :not)
- (lambda (arg) (not (-contains-p (cdr filter) arg)))
- (when (eq (car filter) :only)
- (pop filter))
- (lambda (arg) (-contains-p filter arg)))
- magit-current-popup-args)))
-
-(defvar magit-current-pre-popup-buffer nil
- "The buffer that was current before invoking the active popup.
-This is bound when invoking an action or variable.")
-
-(defmacro magit-with-pre-popup-buffer (&rest body)
- "Execute the forms in BODY in the buffer that current before the popup.
-If `magit-current-pre-popup-buffer' is non-nil use that, else if
-`magit-pre-popup-buffer' is non-nil use that, otherwise (when no
-popup is involved) execute the forms in the current buffer."
- (declare (indent 0))
- `(--if-let (or magit-current-pre-popup-buffer magit-pre-popup-buffer)
- (with-current-buffer it ,@body)
- ,@body))
-
-(defun magit-popup-arg-match (pattern string)
- (if (or (string-match-p "=$" pattern)
- (string-match-p "^-[A-Z]$" pattern))
- (string-match (format "^%s\\(.*\\)$" pattern) string)
- (string-equal string pattern)))
-
-(cl-defstruct magit-popup-event key dsc arg fun use val)
-
-(defun magit-popup-event-keydsc (ev)
- (let ((key (magit-popup-event-key ev)))
- (key-description (if (vectorp key) key (vector key)))))
-
-(defun magit-popup-lookup (event type)
- (--first (equal (magit-popup-event-key it) event)
- (-filter 'magit-popup-event-p (magit-popup-get type))))
-
-(defun magit-popup-get-args ()
- (--mapcat (when (and (magit-popup-event-p it)
- (magit-popup-event-use it))
- (list (format "%s%s"
- (magit-popup-event-arg it)
- (or (magit-popup-event-val it) ""))))
- (append (magit-popup-get :switches)
- (magit-popup-get :options))))
-
-(defmacro magit-popup-convert-events (def form)
- (declare (indent 1) (debug (form form)))
- `(--map (if (or (null it) (stringp it) (functionp it)) it ,form) ,def))
-
-(defun magit-popup-convert-switches (val def)
- (magit-popup-convert-events def
- (let ((a (nth 2 it)))
- (make-magit-popup-event
- :key (car it) :dsc (cadr it) :arg a
- :use (and (member a val) t)
- ;; For arguments implemented in lisp, this function's
- ;; doc-string is used by `magit-popup-help'. That is
- ;; the only thing it is used for.
- :fun (and (string-prefix-p "\+\+" a) (nth 3 it))))))
-
-(defun magit-popup-convert-options (val def)
- (magit-popup-convert-events def
- (let* ((a (nth 2 it))
- (r (format "^%s\\(.*\\)" a))
- (v (--first (string-match r it) val)))
- (make-magit-popup-event
- :key (car it) :dsc (cadr it) :arg a
- :use (and v t) :val (and v (match-string 1 v))
- :fun (or (nth 3 it) 'read-from-minibuffer)))))
-
-(defun magit-popup-convert-variables (_val def)
- (magit-popup-convert-events def
- (make-magit-popup-event
- :key (car it) :dsc (cadr it) :fun (nth 2 it) :arg (nth 3 it))))
-
-(defun magit-popup-convert-actions (_val def)
- (magit-popup-convert-events def
- (make-magit-popup-event
- :key (car it) :dsc (cadr it) :fun (nth 2 it))))
-
-;;; Define
-
-(defmacro magit-define-popup (name doc &rest args)
- "Define a popup command named NAME.
-
-NAME should begin with the package prefix and by convention end
-with `-popup'. That name is used for the actual command as well
-as for a variable used internally. DOC is used as the doc-string
-of that command.
-
-Also define an option and a function named `SHORTNAME-arguments',
-where SHORTNAME is NAME with the trailing `-popup' removed. The
-name of this option and this function can be overwritten using
-the optional argument OPTION, but that is rarely advisable. As a
-special case if OPTION is specified but nil, do not define this
-option and this function at all.
-
-The option `SHORTNAME-arguments' holds the default value for the
-popup arguments. It can be customized from within the popup or
-using the Custom interface.
-
-The function `SHORTNAME-arguments' is a wrapper around the
-variable `magit-current-popup-args', both of which are intended
-to be used inside the `interactive' form of commands commonly
-invoked from the popup `NAME'. When such a command is invoked
-from that popup, then the function `SHORTNAME-arguments' returns
-the value of the variable `magit-current-popup-args'; however
-when the command is invoked directly, then it returns the default
-value of the variable `SHORTNAME-arguments'.
-
-Optional argument GROUP specifies the Custom group into which the
-option is placed. If omitted, then the option is placed into some
-group the same way it is done when directly using `defcustom' and
-omitting the group, except when NAME begins with \"magit-\", in
-which case the group `magit-git-arguments' is used.
-
-Optional argument MODE is deprecated, instead use the keyword
-arguments `:setup-function' and/or `:refresh-function'. If MODE
-is non-nil, then it specifies the mode used by the popup buffer,
-instead of the default, which is `magit-popup-mode'.
-
-The remaining arguments should have the form
-
- [KEYWORD VALUE]...
-
-The following keywords are meaningful (and by convention are
-usually specified in that order):
-
-`:actions'
- The actions which can be invoked from the popup. VALUE is a
- list whose members have the form (KEY DESC COMMAND), see
- `magit-define-popup-action' for details.
-
- Actions are regular Emacs commands, which usually have an
- `interactive' form setup to consume the values of the popup
- `:switches' and `:options' when invoked from the corresponding
- popup, else when invoked as the default action or directly
- without using the popup, the default value of the variable
- `SHORTNAME-arguments'. This is usually done by calling the
- function `SHORTNAME-arguments'.
-
- Members of VALUE may also be strings and functions, assuming
- the first member is a string or function. In that case the
- members are split into sections and these special elements are
- used as headings. If such an element is a function then it is
- called with no arguments and must return either a string, which
- is used as the heading, or nil, in which case the section is
- not inserted.
-
- Members of VALUE may also be nil. This should only be used
- together with `:max-action-columns' and allows having gaps in
- the action grid, which can help arranging actions sensibly.
-
-`:default-action'
- The default action of the popup which is used directly instead
- of displaying the popup buffer, when the popup is invoked with
- a prefix argument. Also see `magit-popup-use-prefix-argument'
- and `:use-prefix', which can be used to inverse the meaning of
- the prefix argument.
-
-`:use-prefix'
- Controls when to display the popup buffer and when to invoke
- the default action (if any) directly. This overrides the
- global default set using `magit-popup-use-prefix-argument'.
- The value, if specified, should be one of `default' or `popup',
- or a function that is called with no arguments and returns one
- of these symbols.
-
-`:max-action-columns'
- The maximum number of actions to display on a single line, a
- number or a function that returns a number and takes the name
- of the section currently being inserted as argument. If there
- isn't enough room to display as many columns as specified here,
- then fewer are used.
-
-`:switches'
- The popup arguments which can be toggled on and off. VALUE
- is a list whose members have the form (KEY DESC SWITCH), see
- `magit-define-popup-switch' for details.
-
- Members of VALUE may also be strings and functions, assuming
- the first member is a string or function. In that case the
- members are split into sections and these special elements are
- used as headings. If such an element is a function then it is
- called with no arguments and must return either a string, which
- is used as the heading, or nil, in which case the section is
- not inserted.
-
-`:options'
- The popup arguments which take a value, as in \"--opt=OPTVAL\".
- VALUE is a list whose members have the form (KEY DESC OPTION
- READER), see `magit-define-popup-option' for details.
-
- Members of VALUE may also be strings and functions, assuming
- the first member is a string or function. In that case the
- members are split into sections and these special elements are
- used as headings. If such an element is a function then it is
- called with no arguments and must return either a string, which
- is used as the heading, or nil, in which case the section is
- not inserted.
-
-`:default-arguments'
- The default arguments, a list of switches (which are then
- enabled by default) and options with there default values, as
- in \"--OPT=OPTVAL\".
-
-`:variables'
-
- Variables which can be set from the popup. VALUE is a list
- whose members have the form (KEY DESC COMMAND FORMATTER), see
- `magit-define-popup-variable' for details.
-
- Members of VALUE may also be strings and functions, assuming
- the first member is a string or function. In that case the
- members are split into sections and these special elements are
- used as headings. If such an element is a function then it is
- called with no arguments and must return either a string, which
- is used as the heading, or nil, in which case the section is
- not inserted.
-
- Members of VALUE may also be actions as described above for
- `:actions'.
-
- VALUE may also be a function that returns a list as describe
- above.
-
-`:sequence-predicate'
- When this function returns non-nil, then the popup uses
- `:sequence-actions' instead of `:actions', and does not show
- the `:switches' and `:options'.
-
-`:sequence-actions'
- The actions which can be invoked from the popup, when
- `:sequence-predicate' returns non-nil.
-
-`:setup-function'
- When this function is specified, then it is used instead of
- `magit-popup-default-setup'.
-
-`:refresh-function'
- When this function is specified, then it is used instead of
- calling `magit-popup-insert-section' three times with symbols
- `magit-popup-switch-button', `magit-popup-option-button', and
- finally `magit-popup-action-button' as argument.
-
-`:man-page'
- The name of the manpage to be displayed when the user requests
- help for a switch or argument.
-
-\(fn NAME DOC [GROUP [MODE [OPTION]]] :KEYWORD VALUE...)"
- (declare (indent defun) (doc-string 2))
- (let* ((str (symbol-name name))
- (grp (if (keywordp (car args))
- (and (string-prefix-p "magit-" str) ''magit-git-arguments)
- (pop args)))
- (mode (and (not (keywordp (car args))) (pop args)))
- (opt (if (keywordp (car args))
- (intern (concat (if (string-suffix-p "-popup" str)
- (substring str 0 -6)
- str)
- "-arguments"))
- (eval (pop args)))))
- `(progn
- (defun ,name (&optional arg) ,doc
- (interactive "P")
- (magit-invoke-popup ',name ,mode arg))
- (defvar ,name
- (list :variable ',opt ,@args))
- (magit-define-popup-keys-deferred ',name)
- ,@(when opt
- `((defcustom ,opt (plist-get ,name :default-arguments)
- ""
- ,@(and grp (list :group grp))
- :type '(repeat (string :tag "Argument")))
- (defun ,opt ()
- (if (eq magit-current-popup ',name)
- magit-current-popup-args
- ,opt))
- (put ',opt 'definition-name ',name))))))
-
-(defun magit-define-popup-switch (popup key desc switch
- &optional enable at prepend)
- "In POPUP, define KEY as SWITCH.
-
-POPUP is a popup command defined using `magit-define-popup'.
-SWITCH is a string representing an argument that takes no value.
-KEY is a character representing the second event in the sequence
-of keystrokes used to toggle the argument. (The first event, the
-prefix, is shared among all switches, defaults to -, and can be
-changed in `magit-popup-mode-keymap').
-
-DESC is a string describing the purpose of the argument, it is
-displayed in the popup.
-
-If optional ENABLE is non-nil, then the switch is on by default.
-
-SWITCH is inserted after all other switches already defined for
-POPUP, unless optional PREPEND is non-nil, in which case it is
-placed first. If optional AT is non-nil, then it should be the
-KEY of another switch already defined for POPUP, the argument
-is then placed before or after AT, depending on PREPEND."
- (declare (indent defun))
- (magit-define-popup-key popup :switches key
- (list desc switch enable) at prepend))
-
-(defun magit-define-popup-option (popup key desc option
- &optional reader value at prepend)
- "In POPUP, define KEY as OPTION.
-
-POPUP is a popup command defined using `magit-define-popup'.
-OPTION is a string representing an argument that takes a value.
-KEY is a character representing the second event in the sequence
-of keystrokes used to set the argument's value. (The first
-event, the prefix, is shared among all options, defaults to =,
-and can be changed in `magit-popup-mode-keymap').
-
-DESC is a string describing the purpose of the argument, it is
-displayed in the popup.
-
-If optional VALUE is non-nil then the option is on by default,
-and VALUE is its default value.
-
-READER is used to read a value from the user when the option is
-invoked and does not currently have a value. (When the option
-has a value, then invoking the option causes it to be unset.)
-This function must take two arguments but may choose to ignore
-them. The first argument is the name of the option (with \": \"
-appended, unless it ends with \"=\") and can be used as the
-prompt. The second argument is nil or the value that was in
-effect before the option was unset, which may be suitable as
-initial completion input. If no reader is specified, then
-`read-from-minibuffer' is used.
-
-OPTION is inserted after all other options already defined for
-POPUP, unless optional PREPEND is non-nil, in which case it is
-placed first. If optional AT is non-nil, then it should be the
-KEY of another option already defined for POPUP, the argument
-is then placed before or after AT, depending on PREPEND."
- (declare (indent defun))
- (magit-define-popup-key popup :options key
- (list desc option reader value) at prepend))
-
-(defun magit-define-popup-variable (popup key desc command formatter
- &optional at prepend)
- "In POPUP, define KEY as COMMAND.
-
-POPUP is a popup command defined using `magit-define-popup'.
-COMMAND is a command which calls `magit-popup-set-variable'.
-FORMATTER is a function which calls `magit-popup-format-variable'.
-These two functions have to be called with the same arguments.
-
-KEY is a character representing the event used interactively call
-the COMMAND.
-
-DESC is the variable or a representation thereof. It's not
-actually used for anything.
-
-COMMAND is inserted after all other commands already defined for
-POPUP, unless optional PREPEND is non-nil, in which case it is
-placed first. If optional AT is non-nil, then it should be the
-KEY of another command already defined for POPUP, the command
-is then placed before or after AT, depending on PREPEND."
- (declare (indent defun))
- (magit-define-popup-key popup :variables key
- (list desc command formatter) at prepend))
-
-(defun magit-define-popup-action (popup key desc command
- &optional at prepend)
- "In POPUP, define KEY as COMMAND.
-
-POPUP is a popup command defined using `magit-define-popup'.
-COMMAND can be any command but should usually consume the popup
-arguments in its `interactive' form.
-KEY is a character representing the event used invoke the action,
-i.e. to interactively call the COMMAND.
-
-DESC is a string describing the purpose of the action, it is
-displayed in the popup.
-
-COMMAND is inserted after all other commands already defined for
-POPUP, unless optional PREPEND is non-nil, in which case it is
-placed first. If optional AT is non-nil, then it should be the
-KEY of another command already defined for POPUP, the command
-is then placed before or after AT, depending on PREPEND."
- (declare (indent defun))
- (magit-define-popup-key popup :actions key
- (list desc command) at prepend))
-
-(defun magit-define-popup-sequence-action
- (popup key desc command &optional at prepend)
- "Like `magit-define-popup-action' but for `:sequence-action'."
- (declare (indent defun))
- (magit-define-popup-key popup :sequence-actions key
- (list desc command) at prepend))
-
-(defconst magit-popup-type-plural-alist
- '((:switch . :switches)
- (:option . :options)
- (:variable . :variables)
- (:action . :actions)
- (:sequence-action . :sequence-actions)))
-
-(defun magit-popup-pluralize-type (type)
- (or (cdr (assq type magit-popup-type-plural-alist))
- type))
-
-(defun magit-define-popup-key
- (popup type key def &optional at prepend)
- "In POPUP, define KEY as an action, switch, or option.
-It's better to use one of the specialized functions
- `magit-define-popup-action',
- `magit-define-popup-sequence-action',
- `magit-define-popup-switch',
- `magit-define-popup-option', or
- `magit-define-popup-variable'."
- (declare (indent defun))
- (setq type (magit-popup-pluralize-type type))
- (if (memq type '(:switches :options :variables :actions :sequence-actions))
- (if (boundp popup)
- (let* ((plist (symbol-value popup))
- (value (plist-get plist type))
- (elt (assoc key value)))
- (if elt
- (setcdr elt def)
- (setq elt (cons key def)))
- (if at
- (when (setq at (cl-member at value :key 'car-safe :test 'equal))
- (setq value (cl-delete key value :key 'car-safe :test 'equal))
- (if prepend
- (progn (push (car at) (cdr at))
- (setcar at elt))
- (push elt (cdr at))))
- (setq value (cl-delete key value :key 'car-safe :test 'equal)))
- (unless (assoc key value)
- (setq value (if prepend
- (cons elt value)
- (append value (list elt)))))
- (set popup (plist-put plist type value)))
- (push (list type key def at prepend)
- (get popup 'magit-popup-deferred)))
- (error "Unknown popup event type: %s" type)))
-
-(defun magit-define-popup-keys-deferred (popup)
- (dolist (args (get popup 'magit-popup-deferred))
- (condition-case err
- (apply #'magit-define-popup-key popup args)
- ((debug error)
- (display-warning 'magit (error-message-string err) :error))))
- (put popup 'magit-popup-deferred nil))
-
-(defun magit-change-popup-key (popup type from to)
- "In POPUP, bind TO to what FROM was bound to.
-TYPE is one of `:action', `:sequence-action', `:switch', or
-`:option'. Bind TO and unbind FROM, both are characters."
- (--if-let (assoc from (plist-get (symbol-value popup)
- (magit-popup-pluralize-type type)))
- (setcar it to)
- (message "magit-change-popup-key: FROM key %c is unbound" from)))
-
-(defun magit-remove-popup-key (popup type key)
- "In POPUP, remove KEY's binding of TYPE.
-POPUP is a popup command defined using `magit-define-popup'.
-TYPE is one of `:action', `:sequence-action', `:switch', or
-`:option'. KEY is the character which is to be unbound."
- (setq type (magit-popup-pluralize-type type))
- (let* ((plist (symbol-value popup))
- (alist (plist-get plist type))
- (value (assoc key alist)))
- (set popup (plist-put plist type (delete value alist)))))
-
-;;; Invoke
-
-(defvar-local magit-popup-previous-winconf nil)
-
-(defun magit-invoke-popup (popup mode arg)
- (let* ((def (symbol-value popup))
- (val (symbol-value (plist-get def :variable)))
- (default (plist-get def :default-action))
- (local (plist-get def :use-prefix))
- (local (if (functionp local)
- (funcall local)
- local))
- (use-prefix (or local magit-popup-use-prefix-argument)))
- (cond
- ((or (and (eq use-prefix 'default) arg)
- (and (eq use-prefix 'popup) (not arg)))
- (if default
- (let ((magit-current-popup (list popup 'default))
- (magit-current-popup-args
- (let ((magit-this-popup popup)
- (magit-this-popup-events nil))
- (magit-popup-default-setup val def)
- (magit-popup-get-args))))
- (when (and arg (listp arg))
- (setq current-prefix-arg (and (not (= (car arg) 4))
- (list (/ (car arg) 4)))))
- (call-interactively default))
- (message "%s has no default action; showing popup instead." popup)
- (magit-popup-mode-setup popup mode)))
- ((memq use-prefix '(default popup nil))
- (magit-popup-mode-setup popup mode)
- (when magit-popup-show-help-echo
- (let ((message-log-max nil))
- (message
- (format
- "[%s] show common commands, [%s] describe events, [%s] show manual"
- (propertize "C-t" 'face 'magit-popup-key)
- (propertize "?" 'face 'magit-popup-key)
- (propertize "C-h i" 'face 'magit-popup-key))))))
- (local
- (error "Invalid :use-prefix popup property value: %s" use-prefix))
- (t
- (error "Invalid magit-popup-use-prefix-argument value: %s" use-prefix)))))
-
-(defun magit-invoke-popup-switch (event)
- (interactive (list last-command-event))
- (--if-let (magit-popup-lookup event :switches)
- (progn
- (setf (magit-popup-event-use it)
- (not (magit-popup-event-use it)))
- (magit-refresh-popup-buffer))
- (user-error "%c isn't bound to any switch" event)))
-
-(defun magit-invoke-popup-option (event)
- (interactive (list last-command-event))
- (--if-let (magit-popup-lookup event :options)
- (progn
- (if (magit-popup-event-use it)
- (setf (magit-popup-event-use it) nil)
- (let* ((arg (magit-popup-event-arg it))
- (val (funcall
- (magit-popup-event-fun it)
- (concat arg (unless (string-match-p "=$" arg) ": "))
- (magit-popup-event-val it))))
- (setf (magit-popup-event-use it) t)
- (setf (magit-popup-event-val it) val)))
- (magit-refresh-popup-buffer))
- (user-error "%c isn't bound to any option" event)))
-
-(defun magit-invoke-popup-action (event)
- (interactive (list last-command-event))
- (let ((action (magit-popup-lookup event :actions))
- (variable (magit-popup-lookup event :variables)))
- (when (and variable (not (magit-popup-event-arg variable)))
- (setq action variable)
- (setq variable nil))
- (cond ((or action variable)
- (let* ((magit-current-popup magit-this-popup)
- (magit-current-popup-args (magit-popup-get-args))
- (magit-current-pre-popup-buffer magit-pre-popup-buffer)
- (command (magit-popup-event-fun (or action variable)))
- (magit-current-popup-action command))
- (when action
- (magit-popup-quit))
- (setq this-command command)
- (call-interactively command)
- (unless action
- (magit-refresh-popup-buffer))))
- ((eq event ?q)
- (magit-popup-quit)
- (when magit-previous-popup
- (magit-popup-mode-setup magit-previous-popup nil)))
- (t
- (user-error "%c isn't bound to any action" event)))))
-
-(defun magit-popup-quit ()
- "Quit the current popup command without invoking an action."
- (interactive)
- (let ((winconf magit-popup-previous-winconf))
- (if (derived-mode-p 'magit-popup-mode)
- (kill-buffer)
- (magit-popup-help-mode -1)
- (kill-local-variable 'magit-popup-previous-winconf))
- (when winconf
- (set-window-configuration winconf))))
-
-(defun magit-popup-read-number (prompt &optional default)
- "Like `read-number' but DEFAULT may be a numeric string."
- (read-number prompt (if (stringp default)
- (string-to-number default)
- default)))
-
-;;; Save
-
-(defun magit-popup-set-default-arguments (arg)
- "Set default value for the arguments for the current popup.
-Then close the popup without invoking an action; unless a prefix
-argument is used in which case the popup remains open.
-
-For a popup named `NAME-popup' that usually means setting the
-value of the custom option `NAME-arguments'."
- (interactive "P")
- (-if-let (var (magit-popup-get :variable))
- (progn (customize-set-variable var (magit-popup-get-args))
- (unless arg (magit-popup-quit)))
- (user-error "Nothing to set")))
-
-(defun magit-popup-save-default-arguments (arg)
- "Save default value for the arguments for the current popup.
-Then close the popup without invoking an action; unless a prefix
-argument is used in which case the popup remains open.
-
-For a popup named `NAME-popup' that usually means saving the
-value of the custom option `NAME-arguments'."
- (interactive "P")
- (-if-let (var (magit-popup-get :variable))
- (progn (customize-save-variable var (magit-popup-get-args))
- (unless arg (magit-popup-quit)))
- (user-error "Nothing to save")))
-
-;;; Help
-
-(defun magit-popup-toggle-show-common-commands ()
- "Show or hide an additional section with common commands.
-The commands listed in this section are common to all popups
-and are defined in `magit-popup-mode-map' (which see)."
- (interactive)
- (setq magit-popup-show-common-commands
- (not magit-popup-show-common-commands))
- (magit-refresh-popup-buffer)
- (fit-window-to-buffer))
-
-(defun magit-popup-help ()
- "Show help for the argument or action at point."
- (interactive)
- (let* ((man (magit-popup-get :man-page))
- (key (read-key-sequence
- (concat "Describe key" (and man " (? for manpage)") ": ")))
- (int (aref key (1- (length key))))
- (def (or (lookup-key (current-local-map) key t)
- (lookup-key (current-global-map) key))))
- (pcase def
- (`magit-invoke-popup-switch
- (--if-let (magit-popup-lookup int :switches)
- (if (and (string-prefix-p "++" (magit-popup-event-arg it))
- (magit-popup-event-fun it))
- (magit-popup-describe-function (magit-popup-event-fun it))
- (magit-popup-manpage man it))
- (user-error "%c isn't bound to any switch" int)))
- (`magit-invoke-popup-option
- (--if-let (magit-popup-lookup int :options)
- (if (and (string-prefix-p "++" (magit-popup-event-arg it))
- (magit-popup-event-fun it))
- (magit-popup-describe-function (magit-popup-event-fun it))
- (magit-popup-manpage man it))
- (user-error "%c isn't bound to any option" int)))
- (`magit-popup-help
- (magit-popup-manpage man nil))
- ((or `self-insert-command
- `magit-invoke-popup-action)
- (setq def (or (magit-popup-lookup int :actions)
- (magit-popup-lookup int :variables)))
- (if def
- (magit-popup-describe-function (magit-popup-event-fun def))
- (ding)
- (message nil)))
- (`nil (ding)
- (message nil))
- (_ (magit-popup-describe-function def)))))
-
-(defun magit-popup-manpage (topic arg)
- (unless topic
- (user-error "No man page associated with %s"
- (magit-popup-get :man-page)))
- (when arg
- (setq arg (magit-popup-event-arg arg))
- (when (string-prefix-p "--" arg)
- ;; handle '--' option and the '--[no-]' shorthand
- (setq arg (cond ((string= "-- " arg)
- "\\(?:\\[--\\] \\)?<[^[:space:]]+>\\.\\.\\.")
- ((string-prefix-p "--no-" arg)
- (concat "--"
- "\\[?no-\\]?"
- (substring arg 5)))
- (t
- (concat "--"
- "\\(?:\\[no-\\]\\)?"
- (substring arg 2)))))))
- (let ((winconf (current-window-configuration)) buffer)
- (pcase magit-popup-manpage-package
- (`woman (delete-other-windows)
- (split-window-below)
- (with-no-warnings ; display-buffer-function is obsolete
- (let ((display-buffer-alist nil)
- (display-buffer-function nil)
- (display-buffer-overriding-action nil))
- (woman topic)))
- (setq buffer (current-buffer)))
- (`man (cl-letf (((symbol-function #'fboundp) (lambda (_) nil)))
- (setq buffer (man topic)))
- (delete-other-windows)
- (split-window-below)
- (set-window-buffer (selected-window) buffer)))
- (with-current-buffer buffer
- (setq magit-popup-previous-winconf winconf)
- (magit-popup-help-mode)
- (fit-window-to-buffer (next-window))
- (if (and arg
- (Man-find-section "OPTIONS")
- (let ((case-fold-search nil)
- ;; This matches preceding/proceeding options.
- ;; Options such as '-a', '-S[<keyid>]', and
- ;; '--grep=<pattern>' are matched by this regex
- ;; without the shy group. The '. ' in the shy
- ;; group is for options such as '-m
- ;; parent-number', and the '-[^[:space:]]+ ' is
- ;; for options such as '--mainline parent-number'
- (others "-\\(?:. \\|-[^[:space:]]+ \\)?[^[:space:]]+"))
- (re-search-forward
- ;; should start with whitespace, and may have any
- ;; number of options before/after
- (format "^[\t\s]+\\(?:%s, \\)*?\\(?1:%s\\)%s\\(?:, %s\\)*$"
- others
- ;; options don't necessarily end in an '='
- ;; (e.g., '--gpg-sign[=<keyid>]')
- (string-remove-suffix "=" arg)
- ;; Simple options don't end in an '='.
- ;; Splitting this into 2 cases should make
- ;; getting false positives less likely.
- (if (string-suffix-p "=" arg)
- ;; [^[:space:]]*[^.[:space:]] matches
- ;; the option value, which is usually
- ;; after the option name and either '='
- ;; or '[='. The value can't end in a
- ;; period, as that means it's being used
- ;; at the end of a sentence. The space
- ;; is for options such as '--mainline
- ;; parent-number'.
- "\\(?: \\|\\[?=\\)[^[:space:]]*[^.[:space:]]"
- ;; Either this doesn't match anything
- ;; (e.g., '-a'), or the option is followed
- ;; by a value delimited by a '[', '<', or
- ;; ':'. A space might appear before this
- ;; value, as in '-f <file>'. The space
- ;; alternative is for options such as '-m
- ;; parent-number'.
- "\\(?:\\(?: \\| ?[\\[<:]\\)[^[:space:]]*[^.[:space:]]\\)?")
- others)
- nil
- t)))
- (goto-char (match-beginning 1))
- (goto-char (point-min))))))
-
-(defun magit-popup-describe-function (function)
- (let ((winconf (current-window-configuration)))
- (delete-other-windows)
- (split-window-below)
- (other-window 1)
- (with-no-warnings ; display-buffer-function is obsolete
- (let ((display-buffer-alist '(("" display-buffer-use-some-window)))
- (display-buffer-function nil)
- (display-buffer-overriding-action nil)
- (help-window-select nil))
- (describe-function function)))
- (fit-window-to-buffer)
- (other-window 1)
- (setq magit-popup-previous-winconf winconf)
- (magit-popup-help-mode)))
-
-(defun magit-popup-info ()
- "Show the popup manual."
- (interactive)
- (let ((winconf (current-window-configuration)))
- (delete-other-windows)
- (split-window-below)
- (info "(magit-popup.info)Usage")
- (magit-popup-help-mode)
- (setq magit-popup-previous-winconf winconf))
- (magit-popup-help-mode)
- (fit-window-to-buffer (next-window)))
-
-(define-minor-mode magit-popup-help-mode
- "Auxiliary minor mode used to restore previous window configuration.
-When some sort of help buffer is created from within a popup,
-then this minor mode is turned on in that buffer, so that when
-the user quits it, the previous window configuration is also
-restored."
- :keymap '(([remap Man-quit] . magit-popup-quit)
- ([remap Info-exit] . magit-popup-quit)
- ([remap quit-window] . magit-popup-quit)))
-
-;;; Modes
-
-(define-derived-mode magit-popup-mode fundamental-mode "MagitPopup"
- "Major mode for infix argument popups."
- :mode 'magit-popup
- (setq truncate-lines t)
- (setq buffer-read-only t)
- (setq-local scroll-margin 0)
- (setq-local magit-popup-show-common-commands magit-popup-show-common-commands)
- (hack-dir-local-variables-non-file-buffer))
-
-(put 'magit-popup-mode 'mode-class 'special)
-
-(defun magit-popup-default-setup (val def)
- (if (--when-let (magit-popup-get :sequence-predicate)
- (funcall it))
- (magit-popup-put :actions (magit-popup-convert-actions
- val (magit-popup-get :sequence-actions)))
- (let ((vars (plist-get def :variables)))
- (when (functionp vars)
- (setq vars (funcall vars)))
- (when vars
- (magit-popup-put :variables (magit-popup-convert-variables val vars))))
- (magit-popup-put :switches (magit-popup-convert-switches
- val (plist-get def :switches)))
- (magit-popup-put :options (magit-popup-convert-options
- val (plist-get def :options)))
- (magit-popup-put :actions (magit-popup-convert-actions
- val (plist-get def :actions)))))
-
-(defun magit-popup-mode-setup (popup mode)
- (setq magit-previous-popup magit-current-popup)
- (let ((val (symbol-value (plist-get (symbol-value popup) :variable)))
- (def (symbol-value popup))
- (buf (current-buffer)))
- (magit-popup-mode-display-buffer (get-buffer-create
- (format "*%s*" popup))
- (or mode 'magit-popup-mode))
- (setq magit-this-popup popup)
- (setq magit-pre-popup-buffer buf)
- (if (bound-and-true-p magit-popup-setup-hook) ; obsolete
- (run-hook-with-args 'magit-popup-setup-hook val def)
- (funcall (or (magit-popup-get :setup-function)
- 'magit-popup-default-setup)
- val def)))
- (magit-refresh-popup-buffer)
- (fit-window-to-buffer nil nil (line-number-at-pos (point-max))))
-
-(defun magit-popup-mode-display-buffer (buffer mode)
- (let ((winconf (current-window-configuration)))
- (select-window (display-buffer buffer magit-popup-display-buffer-action))
- (funcall mode)
- (setq magit-popup-previous-winconf winconf)))
-
-(defvar magit-refresh-popup-buffer-hook nil
- "Hook run by `magit-refresh-popup-buffer'.
-
-The hook is run right after inserting the representation of the
-popup events but before optionally inserting the representation
-of events shared by all popups and before point is adjusted.")
-
-(defun magit-refresh-popup-buffer ()
- (let* ((inhibit-read-only t)
- (button (button-at (point)))
- (prefix (and button (button-get button 'prefix)))
- (event (and button (button-get button 'event))))
- (erase-buffer)
- (save-excursion
- (--if-let (magit-popup-get :refresh-function)
- (funcall it)
- (magit-popup-insert-section 'magit-popup-variable-button)
- (magit-popup-insert-section 'magit-popup-switch-button)
- (magit-popup-insert-section 'magit-popup-option-button)
- (magit-popup-insert-section 'magit-popup-action-button))
- (run-hooks 'magit-refresh-popup-buffer-hook)
- (when magit-popup-show-common-commands
- (magit-popup-insert-command-section
- 'magit-popup-internal-command-button
- magit-popup-common-commands)))
- (set-buffer-modified-p nil)
- (when event
- (while (and (ignore-errors (forward-button 1))
- (let ((b (button-at (point))))
- (or (not (equal (button-get b 'prefix) prefix))
- (not (equal (button-get b 'event) event)))))))))
-
-;;; Draw
-
-(defvar magit-popup-min-padding 3
- "Minimal amount of whitespace between columns in popup buffers.")
-
-(defun magit-popup-insert-section (type &optional spec heading)
- (if (not spec)
- (progn (setq spec (magit-popup-get (button-type-get type 'property)))
- (when spec
- (if (or (stringp (car spec))
- (functionp (car spec)))
- (--each (--partition-by-header
- (or (stringp it) (functionp it))
- spec)
- (magit-popup-insert-section type (cdr it) (car it)))
- (magit-popup-insert-section type spec))))
- (let* ((formatter (button-type-get type 'formatter))
- (items (mapcar (lambda (ev)
- (and ev (or (funcall formatter type ev) '(""))))
- (or spec (magit-popup-get
- (button-type-get type 'property)))))
- (maxcols (button-type-get type 'maxcols))
- (pred (magit-popup-get :sequence-predicate)))
- (when items
- (if (functionp heading)
- (when (setq heading (funcall heading))
- (insert heading ?\n))
- (unless heading
- (setq heading (button-type-get type 'heading)))
- (insert (propertize heading 'face 'magit-popup-heading))
- (unless (string-match "\n$" heading)
- (insert "\n")))
- (if (and pred (funcall pred))
- (setq maxcols nil)
- (cl-typecase maxcols
- (keyword (setq maxcols (magit-popup-get maxcols)))
- (symbol (setq maxcols (symbol-value maxcols)))))
- (when (functionp maxcols)
- (setq maxcols (funcall maxcols heading)))
- (when heading
- (let ((colwidth
- (+ (apply 'max (mapcar (lambda (e) (length (car e))) items))
- magit-popup-min-padding)))
- (dolist (item items)
- (unless (bolp)
- (let ((padding (- colwidth (% (current-column) colwidth))))
- (if (and (< (+ (current-column) padding colwidth)
- (window-width))
- (< (ceiling (/ (current-column) (* colwidth 1.0)))
- (or maxcols 1000)))
- (insert (make-string padding ?\s))
- (insert "\n"))))
- (unless (equal item '(""))
- (if item
- (apply 'insert-button item)
- (insert ?\s)))))
- (insert (if (= (char-before) ?\n) "\n" "\n\n")))))))
-
-(defun magit-popup-format-argument-button (type ev)
- (list (format-spec
- (button-type-get type 'format)
- `((?k . ,(propertize (concat
- (--when-let (button-type-get type 'prefix)
- (char-to-string it))
- (magit-popup-event-keydsc ev))
- 'face 'magit-popup-key))
- (?d . ,(magit-popup-event-dsc ev))
- (?a . ,(propertize (magit-popup-event-arg ev)
- 'face (if (magit-popup-event-use ev)
- 'magit-popup-argument
- 'magit-popup-disabled-argument)))
- (?v . ,(let ((val (magit-popup-event-val ev)))
- (if (and (magit-popup-event-use ev)
- (not (equal val "")))
- (propertize (format "\"%s\"" val)
- 'face 'magit-popup-option-value)
- "")))))
- 'type type 'event (magit-popup-event-key ev)))
-
-(defun magit-popup-format-variable-button (type ev)
- (if (not (magit-popup-event-arg ev))
- (magit-popup-format-action-button 'magit-popup-action-button ev)
- (list (format-spec
- (button-type-get type 'format)
- `((?k . ,(propertize (magit-popup-event-keydsc ev)
- 'face 'magit-popup-key))
- (?d . ,(funcall (magit-popup-event-arg ev)))))
- 'type type 'event (magit-popup-event-key ev))))
-
-(defun magit-popup-format-action-button (type ev)
- (let* ((cmd (magit-popup-event-fun ev))
- (dsc (magit-popup-event-dsc ev))
- (fun (and (functionp dsc) dsc)))
- (unless (and disabled-command-function
- (symbolp cmd)
- (get cmd 'disabled))
- (when fun
- (setq dsc
- (-when-let (branch (funcall fun))
- (if (text-property-not-all 0 (length branch) 'face nil branch)
- branch
- (magit-branch-set-face branch)))))
- (when dsc
- (list (format-spec
- (button-type-get type 'format)
- `((?k . ,(propertize (magit-popup-event-keydsc ev)
- 'face 'magit-popup-key))
- (?d . ,dsc)
- (?D . ,(if (and (not fun)
- (eq cmd (magit-popup-get :default-action)))
- (propertize dsc 'face 'bold)
- dsc))))
- 'type type 'event (magit-popup-event-key ev))))))
-
-(defun magit-popup-insert-command-section (type spec)
- (magit-popup-insert-section
- type (mapcar (lambda (elt)
- (list (car (where-is-internal (cadr elt)
- (current-local-map)))
- (car elt)))
- spec)))
-
-(defun magit-popup-format-command-button (type elt)
- (nconc (magit-popup-format-action-button
- type (make-magit-popup-event :key (car elt)
- :dsc (cadr elt)))
- (list 'function (lookup-key (current-local-map) (car elt)))))
-
-;;; Utilities
-
-(defun magit-popup-import-file-args (args files)
- (if files
- (cons (concat "-- " (mapconcat #'identity files ",")) args)
- args))
-
-(defun magit-popup-export-file-args (args)
- (let ((files (--first (string-prefix-p "-- " it) args)))
- (when files
- (setq args (remove files args))
- (setq files (split-string (substring files 3) ",")))
- (list args files)))
-
-(defconst magit-popup-font-lock-keywords
- (eval-when-compile
- `((,(concat "(\\(magit-define-popup\\)\\_>"
- "[ \t'\(]*"
- "\\(\\(?:\\sw\\|\\s_\\)+\\)?")
- (1 'font-lock-keyword-face)
- (2 'font-lock-function-name-face nil t)))))
-
-(font-lock-add-keywords 'emacs-lisp-mode magit-popup-font-lock-keywords)
-
-;;; _
-(provide 'magit-popup)
-;; Local Variables:
-;; indent-tabs-mode: nil
-;; End:
-;;; magit-popup.el ends here
+++ /dev/null
-This is magit-popup.info, produced by makeinfo version 6.5 from
-magit-popup.texi.
-
- Copyright (C) 2015-2019 Jonas Bernoulli <jonasNOSPAMbernoul.li>
-
- 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
-* Magit-Popup: (magit-popup). Infix arguments with feedback.
-END-INFO-DIR-ENTRY
-
-\1f
-File: magit-popup.info, Node: Top, Next: Introduction, Up: (dir)
-
-Magit-Popup User Manual
-***********************
-
-This package implements a generic interface for toggling switches and
-setting options and then invoking an Emacs command that does something
-with these arguments. Usually the command calls an external process
-with the specified arguments.
-
- This package has been superseded by Transient (*note
-(transient)Top::). No new features will be added but bugs will be
-fixes.
-
-This manual is for Magit-Popup version 2.13.0.
-
- Copyright (C) 2015-2019 Jonas Bernoulli <jonasNOSPAMbernoul.li>
-
- 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:
-
-* Introduction::
-* Usage::
-* Defining Prefix and Suffix Commands::
-
-— The Detailed Node Listing —
-
-Usage
-
-* Customizing Existing Popups::
-* Other Options::
-
-Defining Prefix and Suffix Commands
-
-* Defining Prefix Commands::
-* Defining Suffix Commands::
-
-
-\1f
-File: magit-popup.info, Node: Introduction, Next: Usage, Prev: Top, Up: Top
-
-1 Introduction
-**************
-
-Taking inspiration from regular prefix commands and prefix arguments,
-this library implements a similar abstraction; a new kind of prefix
-command that is associated with a specific set of infix arguments and
-suffix commands.
-
- Invoking such a prefix command displays a popup buffer which lists
-the associated infix arguments and suffix commands. In that buffer each
-argument is prefixed with the key sequence that can be used to toggle it
-or change its value. Likewise each suffix command is prefixed with the
-key used to invoke it. Such a popup buffer might look like this:
-
- ,-----------------------------------------
- |Switches
- | -l Show graph (--graph)
- | -d Show refnames (--decorate)
- |
- |Options
- | =m Search messages (--grep="popup")
- | =p Search patches (-G)
- |
- |Action
- | l Show log for current branch
- | o Show log for another branch
- '-----------------------------------------
-
- The user could then for example type ‘-l’ to toggle the ‘--graph’
-*switch* (when it is on then it is shown in green, otherwise in gray),
-or ‘=m’ to change the value of the *option* ‘--grep’.
-
- Once all arguments are as desired one invokes a suffix command, which
-causes the popup buffer to disappear. The suffix command should then
-retrieve the infix arguments in its ‘interactive’ form like this is done
-for prefix arguments.
-
- While such "prefix-infix-suffix" combos were inspired by regular
-prefix commands and prefix arguments, they are also quite different.
-This should illustrate the most basic differences:
-
- • A regular prefix command
-
- /- command1
- prefix --- command2
- \- command3
-
- • Prefix arguments
-
- /- command1
- C-u ... --- command2
- \- well any command
-
- • A Prefix-Infix-Suffix combo
-
- /- argument1 -\ /- suffix1
- prefix----- argument2 --+-- suffix2
- ^ \- argument3 -/
- | |
- '--------'
- (refresh buffer)
-
- This package has been superseded by Transient (*note
-(transient)Top::). No new features will be added but bugs will be
-fixes.
-
-\1f
-File: magit-popup.info, Node: Usage, Next: Defining Prefix and Suffix Commands, Prev: Introduction, Up: Top
-
-2 Usage
-*******
-
-Every popup buffers created with a prefix command contains a section
-named "Actions" listing the available suffix commands. Most buffers
-also contain a "Switches" and/or an "Options" section which list the two
-types of infix arguments separately.
-
- Switches are arguments that can be toggled on or off. When a switch
-is active then it is shown in color, when it is off then it is shown in
-gray (of course the details depend on the color theme in use).
-
- Options are arguments that have a value. When an option has a value
-then that is shown after the option itself. Because for some options
-the empty string is a valid value, options are additionally colorized
-like switches to indicate whether they are active or not.
-
- The events bound to suffix commands are always single alphabetic
-characters. The bindings for arguments are always two events long. For
-switches the first key is always ‘-’, for options it is always ‘=’. The
-second key is always an alphabetic character.
-
- By default popup buffers also feature a section listing commands
-common to all popups. To avoid conflicts with suffix commands, the
-bindings of these common commands are not alphabetic characters. This
-section is shown by default so that documentation-resistant users get a
-chance to notice them.
-
- -- User Option: magit-popup-show-common-commands
-
- This option controls whether the section that lists the commands
- that are common to all popups is initially shown.
-
- By default this is not the case, but note that you can temporarily
- show this section using ‘C-t’, which therefore is the only common
- command you actually have to memorize.
-
-‘C-t’ (‘magit-popup-toggle-show-common-commands’)
-
- Show or hide the section listing the commands shared by all popups.
-
-‘C-g’ (‘magit-popup-quit’)
-
- Quit popup buffer without invoking a suffix command.
-
- Without further action, setting arguments only affects the next
-suffix command. Invoking the same prefix command again resets the
-arguments to their default value, but the defaults can be changed
-directly from the popup buffer itself. For a prefix command named
-‘NAME-popup’ the default values are stored as the value of the custom
-option named ‘NAME-arguments’. While this option can be customized
-using the Custom interface, it is better to do so directly from the
-popup buffer.
-
-‘C-c C-c’ (‘magit-popup-set-default-arguments’)
-
- This sets the default value for the arguments for the current
- popup.
-
- Then the popup buffer is closed without invoking a suffix command;
- unless a prefix argument is used in which case the popup remains
- open.
-
-‘C-x C-s’ (‘magit-popup-save-default-arguments’)
-
- This sets the default value for the arguments for the current popup
- and saves it for future Emacs sessions.
-
- Then the popup buffer is closed without invoking an action; unless
- a prefix argument is used in which case the popup remains open.
-
- It is also possible to add additional arguments and commands to an
-existing popup, but that cannot be done directly from the popup (or the
-Custom interface). See *note Customizing Existing Popups::.
-
- Documentation about a popup’s arguments and commands can be shown
-directly from the popup.
-
-‘C-h i’ (‘magit-popup-info’)
-
- Show this manual.
-
-‘?’ (‘magit-popup-help’)
-
- This command reads a key sequence and then shows the documentation
- of the argument or command that sequence is bound to. In other
- words type the same keys that you would use to invoke the argument
- or command, but prefix the sequence with ‘?’.
-
- For suffix commands this shows the doc-string. For arguments this
- command can only show something for popups that have an associated
- man-page. If the man-page is set, then this command displays it in
- a separate buffer and puts point on the entry about the argument in
- question.
-
- The buffer which is used to display the documentation is selected.
- Simply press ‘q’ to leave that buffer and restore the old window
- configuration.
-
- While it isn’t very useful, it is possible to move around in a popup
-buffer using ‘C-p’ and ‘C-n’, and to invoke the argument or command at
-point using ‘RET’. But it is much more efficient to use the dedicated
-key bindings instead, so these commands are not listed in popup buffers
-along with the other common commands.
-
-* Menu:
-
-* Customizing Existing Popups::
-* Other Options::
-
-\1f
-File: magit-popup.info, Node: Customizing Existing Popups, Next: Other Options, Up: Usage
-
-2.1 Customizing Existing Popups
-===============================
-
-It is possible to define additional infix arguments and suffix commands
-to an existing popup using the following functions.
-
- You can find some examples which use the below commands at
-<https://github.com/magit/magit/wiki/Additional-proposed-infix-arguments-and-suffix-commands>.
-
- -- Function: magit-define-popup-switch popup key desc switch &optional
- enable at prepend
-
- In POPUP, define KEY as SWITCH.
-
- POPUP is a popup command defined using ‘magit-define-popup’.
- SWITCH is a string representing an argument that takes no value.
- KEY is a character representing the second event in the sequence of
- keystrokes used to toggle the argument. (The first event, the
- prefix, is shared among all switches, defaults to ‘-’, and can be
- changed in ‘magit-popup-mode-keymap’).
-
- DESC is a string describing the purpose of the argument, it is
- displayed in the popup.
-
- If optional ENABLE is non-nil then the switch is on by default.
-
- SWITCH is inserted after all other switches already defined for
- POPUP, unless optional PREPEND is non-nil, in which case it is
- placed first. If optional AT is non-nil then it should be the KEY
- of another switch already defined for POPUP, the argument is then
- placed before or after AT, depending on PREPEND.
-
- -- Function: magit-define-popup-option popup key desc option &optional
- reader value at prepend
-
- In POPUP, define KEY as OPTION.
-
- POPUP is a popup command defined using ‘magit-define-popup’.
- OPTION is a string representing an argument that takes a value.
- KEY is a character representing the second event in the sequence of
- keystrokes used to set the argument’s value. (The first event, the
- prefix, is shared among all options, defaults to ‘=’, and can be
- changed in ‘magit-popup-mode-keymap’).
-
- DESC is a string describing the purpose of the argument, it is
- displayed in the popup.
-
- If optional VALUE is non-nil then the option is on by default, and
- VALUE is its default value.
-
- READER is used to read a value from the user when the option is
- invoked and does not currently have a value. (When the option has
- a value, then invoking the option causes it to be unset.) This
- function must take two arguments but may choose to ignore them.
- The first argument is the name of the option (with ": \" appended,
- unless it ends with "=") and can be used as the prompt. The second
- argument is nil or the value that was in effect before the option
- was unset, which may be suitable as initial completion input. If
- no reader is specified, then ‘read-from-minibuffer’ is used.
-
- OPTION is inserted after all other options already defined for
- POPUP, unless optional PREPEND is non-nil, in which case it is
- placed first. If optional AT is non-nil then it should be the KEY
- of another option already defined for POPUP, the argument is then
- placed before or after AT, depending on PREPEND.
-
- -- Function: magit-define-popup-action popup key desc command &optional
- at prepend
-
- In POPUP, define KEY as COMMAND.
-
- POPUP is a popup command defined using ‘magit-define-popup’.
- COMMAND can be any command but should usually consume the popup
- arguments in its ‘interactive’ form. KEY is a character
- representing the event used invoke the action, i.e. to
- interactively call the COMMAND.
-
- DESC is a string describing the purpose of the action, it is
- displayed in the popup.
-
- COMMAND is inserted after all other commands already defined for
- POPUP, unless optional PREPEND is non-nil, in which case it is
- placed first. If optional AT is non-nil then it should be the KEY
- of another command already defined for POPUP, the command is then
- placed before or after AT, depending on PREPEND.
-
- -- Function: magit-define-popup-sequence-action popup key desc command
- &optional at prepend
-
- Like ‘magit-define-popup-action’, but modifies the value of the
- ‘:sequence-actions’ property instead of ‘:actions’.
-
- -- Function: magit-define-popup-variable popup key desc command
- formatter &optional at prepend
-
- In POPUP, define KEY as COMMAND.
-
- POPUP is a popup command defined using ‘magit-define-popup’.
- COMMAND is a command which calls ‘magit-popup-set-variable’.
- FORMATTER is a function which calls ‘magit-popup-format-variable’.
- These two functions have to be called with the same arguments.
-
- KEY is a character representing the event used interactively call
- the COMMAND.
-
- DESC is the variable or a representation thereof. It’s not
- actually used for anything.
-
- COMMAND is inserted after all other commands already defined for
- POPUP, unless optional PREPEND is non-nil, in which case it is
- placed first. If optional AT is non-nil then it should be the KEY
- of another command already defined for POPUP, the command is then
- placed before or after AT, depending on PREPEND."
-
- -- Function: magit-change-popup-key popup type from to
-
- In POPUP, bind TO to what FROM was bound to. TYPE is one of
- ‘:action’, ‘:sequence-action’, ‘:switch’, or ‘:option’. Bind TO
- and unbind FROM, both are characters.
-
- -- Function: magit-remove-popup-key popup type key
-
- In POPUP, remove KEY’s binding of TYPE. POPUP is a popup command
- defined using ‘magit-define-popup’. TYPE is one of ‘:action’,
- ‘:sequence-action’, ‘:switch’, or ‘:option’. KEY is the character
- which is to be unbound.
-
- It is also possible to change other aspects of a popup by setting a
-property using ‘plist-put’. See *note Defining Prefix Commands:: for
-valid properties. The most likely change Magit users might want to make
-is:
-
- (plist-put magit-show-refs-popup :use-prefix nil)
-
-\1f
-File: magit-popup.info, Node: Other Options, Prev: Customizing Existing Popups, Up: Usage
-
-2.2 Other Options
-=================
-
- -- User Option: magit-popup-use-prefix-argument
-
- This option controls the effect that the use of a prefix argument
- before entering a popup has.
-
- • ‘default’
-
- With a prefix argument directly invoke the popup’s default
- action (an Emacs command), instead of bringing up the popup.
-
- • ‘popup’
-
- With a prefix argument bring up the popup, otherwise directly
- invoke the popup’s default action.
-
- • ‘nil’
-
- Ignore prefix arguments.
-
- This option can be overridden for individual popups.
- ‘magit-show-refs-popup’ for example defaults to invoking the
- default action directly. It only shows the popup buffer when a
- prefix argument is used. See *note Customizing Existing Popups::.
-
- -- User Option: magit-popup-manpage-package
-
- The Emacs package used to display man-pages, one of ‘man’ or
- ‘woman’.
-
- -- User Option: magit-popup-display-buffer-action
-
- The option controls how the window used to display a popup buffer
- is created. Popup buffers are displayed using ‘display-buffer’
- with the value of this option as ACTION argument. You can also set
- this to nil and instead add an entry to ‘display-buffer-alist’.
-
- To emphasize the default action by making it bold use this:
-
- (button-type-put 'magit-popup-action-button 'format " %k %D")
-
-\1f
-File: magit-popup.info, Node: Defining Prefix and Suffix Commands, Prev: Usage, Up: Top
-
-3 Defining Prefix and Suffix Commands
-*************************************
-
-If you write an extension for Magit then you should use this library now
-and later when ‘transient’ is released port to that.
-
- If you are considering using this library to define popups for
-packages not related to Magit, then keep in mind that it will be
-superseded eventually. Once ‘transient’ has been released I will only
-fix bugs in ‘magit-popup’ but not implement any new features.
-
- Also consider using ‘hydra’ instead. To some extend ‘magit-popup’
-and ‘hydra’ are similar but have a different focus. The main purpose of
-‘magit-popup’ is to pass infix arguments to suffix commands. If all you
-need is a command dispatcher then you are better of using ‘hydra’. Of
-course ‘hydra’ may also be a better fit not only because of the features
-it lacks, but also because of the features it provides, which are in
-turn missing from ‘magit-popup’.
-
- Here is an example of how one defines a prefix command along with its
-infix arguments, and then also one of its suffix commands.
-
- ;;;###autoload (autoload 'magit-tag-popup "magit" nil t)
- (magit-define-popup magit-tag-popup
- "Show popup buffer featuring tagging commands."
- 'magit-commands
- :man-page "git-tag"
- :switches '((?a "Annotate" "--annotate")
- (?s "Sign" "--sign")
- (?f "Force" "--force"))
- :actions '((?t "Create" magit-tag)
- (?k "Delete" magit-tag-delete)
- (?p "Prune" magit-tag-prune))
- :default-action 'magit-tag)
-
- ;;;###autoload
- (defun magit-tag (name rev &optional args)
- "Create a new tag with the given NAME at REV."
- (interactive (list (magit-read-tag "Tag name")
- (magit-read-branch-or-commit "Place tag on")
- (magit-tag-arguments)))
- (magit-run-git-with-editor "tag" args name rev))
-
-* Menu:
-
-* Defining Prefix Commands::
-* Defining Suffix Commands::
-
-\1f
-File: magit-popup.info, Node: Defining Prefix Commands, Next: Defining Suffix Commands, Up: Defining Prefix and Suffix Commands
-
-3.1 Defining Prefix Commands
-============================
-
-Prefix commands and their infix arguments are defined using the macro
-‘magit-define-popup’. The key bindings and descriptions of suffix
-commands are also defined using that macro, but the actual interactive
-commands have to be defined separately using plain ‘defun’.
-
- -- Macro: magit-define-popup name doc [group [mode [option]]] :keyword
- value...
-
- This macro defines a popup named NAME. The NAME should begin with
- the package prefix and by convention end with ‘-popup’, it is used
- as the name of the command which shows the popup and for an
- internal variable (whose value is used to store information about
- the popup and should not be accessed directly). DOC is the
- doc-string of the popup command.
-
- This macro also defines an option and a function both named
- ‘SHORTNAME-arguments’, where SHORTNAME is NAME with the trailing
- ‘-popup’ removed. The name of this option and this function can be
- overwritten using the optional argument OPTION, but that is rarely
- advisable. As a special case if OPTION is specified but ‘nil’,
- then this option and this function are not defined at all, which is
- useful for popups that are used as simple dispatchers that offer no
- arguments.
-
- The option ‘SHORTNAME-arguments’ holds the value for the popup
- arguments. It can be customized from within the popup or using the
- Custom interface. It can also have a buffer local value in any
- non-popup buffer. The local value for the buffer from which the
- popup command was invoked, can be set from within the popup buffer.
-
- The function ‘SHORTNAME-arguments’ returns the currently effective
- value of the variable by the same name. See below for more
- information.
-
- Optional argument GROUP specifies the Custom group into which the
- option is placed. If omitted then the option is placed into some
- group the same way it is done when directly using ‘defcustom’ and
- omitting the group, except when NAME begins with "magit-", in which
- case the group ‘magit-git-arguments’ is used.
-
- The optional argument MODE specifies the mode used by the popup
- buffer. If it is omitted or ‘nil’ then ‘magit-popup-mode’ is used.
-
- The remaining arguments should have the form ‘[KEYWORD VALUE]...’.
-
- The following keywords are meaningful (and by convention are
- usually specified in that order):
-
- • ‘:actions’
-
- The actions which can be invoked from the popup. VALUE is a
- list whose members have the form (KEY DESC COMMAND), see
- ‘magit-define-popup-action’ for details.
-
- Actions are regular Emacs commands, which usually have an
- ‘interactive’ form setup to consume the values of the popup
- ‘:switches’ and ‘:options’ when invoked from the corresponding
- popup, else when invoked as the default action or directly
- without using the popup, the default value of the variable
- ‘SHORTNAME-arguments’. This is usually done by calling the
- function ‘SHORTNAME-arguments’.
-
- Members of VALUE may also be strings and functions, assuming
- the first member is a string or function. In that case the
- members are split into sections and these special elements are
- used as headings. If such an element is a function then it is
- called with no arguments and must return either a string,
- which is used as the heading, or nil, in which case the
- section is not inserted.
-
- Members of VALUE may also be nil. This should only be used
- together with ‘:max-action-columns’ and allows having gaps in
- the action grit, which can help arranging actions sensibly.
-
- • ‘:default-action’
-
- The default action of the popup which is used directly instead
- of displaying the popup buffer, when the popup is invoked with
- a prefix argument. Also see ‘magit-popup-use-prefix-argument’
- and ‘:use-prefix’, which can be used to inverse the meaning of
- the prefix argument.
-
- • ‘:use-prefix’
-
- Controls when to display the popup buffer and when to invoke
- the default action (if any) directly. This overrides the
- global default set using ‘magit-popup-use-prefix-argument’.
- The value, if specified, should be one of ‘default’ or
- ‘prefix’, or a function that is called with no arguments and
- returns one of these symbols.
-
- • ‘:max-action-columns’
-
- The maximum number of actions to display on a single line, a
- number or a function that return a number and takes the name
- of the section currently being inserted as argument. If there
- isn’t enough room to display as many columns as specified
- here, then fewer are used.
-
- • ‘:switches’
-
- The popup arguments which can be toggled on and off. VALUE is
- a list whose members have the form ‘(KEY DESC SWITCH)’, see
- ‘magit-define-popup-switch’ for details.
-
- Members of VALUE may also be strings and functions, assuming
- the first member is a string or function. In that case the
- members are split into sections and these special elements are
- used as headings. If such an element is a function then it is
- called with no arguments and must return either a string,
- which is used as the heading, or nil, in which case the
- section is not inserted.
-
- • ‘:options’
-
- The popup arguments which take a value, as in "–opt~OPTVAL".
- VALUE is a list whose members have the form ‘(KEY DESC OPTION
- READER)’, see ‘magit-define-popup-option’ for details.
-
- Members of VALUE may also be strings and functions, assuming
- the first member is a string or function. In that case the
- members are split into sections and these special elements are
- used as headings. If such an element is a function then it is
- called with no arguments and must return either a string,
- which is used as the heading, or nil, in which case the
- section is not inserted.
-
- • ‘:default-arguments’
-
- The default arguments, a list of switches (which are then
- enabled by default) and options with there default values, as
- in ‘"--OPT=OPTVAL"’.
-
- • ‘:variables’
-
- Variables which can be set from the popup. VALUE is a list
- whose members have the form ‘(KEY DESC COMMAND FORMATTER)’,
- see ‘magit-define-popup-variable’ for details.
-
- Members of VALUE may also be strings and functions, assuming
- the first member is a string or function. In that case the
- members are split into sections and these special elements are
- used as headings. If such an element is a function then it is
- called with no arguments and must return either a string,
- which is used as the heading, or nil, in which case the
- section is not inserted.
-
- Members of VALUE may also be actions as described above for
- ‘:actions’.
-
- VALUE may also be a function that returns a list as describe
- above.
-
- • ‘:sequence-predicate’
-
- When this function returns non-nil, then the popup uses
- ‘:sequence-actions’ instead of ‘:actions’, and does not show
- the ‘:switches’ and ‘:options’.
-
- • ‘:sequence-actions’
-
- The actions which can be invoked from the popup, when
- ‘:sequence-predicate’ returns non-nil.
-
- • ‘:setup-function’
-
- When this function is specified, then it is used instead of
- ‘magit-popup-default-setup’.
-
- • ‘:refresh-function’
-
- When this function is specified, then it is used instead of
- calling ‘magit-popup-insert-section’ three times with symbols
- ‘magit-popup-switch-button’, ‘magit-popup-option-button’, and
- finally ‘magit-popup-action-button’ as argument.
-
- • ‘:man-page’
-
- The name of the manpage to be displayed when the user requests
- help for an argument.
-
-\1f
-File: magit-popup.info, Node: Defining Suffix Commands, Prev: Defining Prefix Commands, Up: Defining Prefix and Suffix Commands
-
-3.2 Defining Suffix Commands
-============================
-
-Commands intended to be invoked from a particular popup should determine
-the currently effective arguments by calling the function
-‘SHORTNAME-arguments’ inside their ‘interactive’ form. This function is
-created by the ‘magit-define-popup’ macro. For a popup named
-‘prefix-foo-popup’ the name of this function is ‘prefix-foo-arguments’.
-
- When the command was invoked as an action in the respective popup,
-then this function returns the arguments that were set in the popup.
-Otherwise when the command was invoked as the default of the popup (by
-calling the popup command with a prefix argument), or without using the
-popup command at all, then this function returns the buffer-local or
-global value of the variable ‘SHORTNAME-arguments’.
-
- Internally arguments are handled as a list of strings. This might
-not be appropriate for the intended use inside commands, or it might be
-necessary to manipulate that list somehow, i.e. to split "–ARG=VAL"
-into "–ARG""VAL". This should be done by advising or redefining the
-function ‘SHORTNAME-arguments’.
-
- Internally ‘SHORNAME-arguments’ used following variables and
-function. Except when redefining the former, you should not use these
-directly.
-
- -- Variable: magit-current-popup
-
- The popup from which this editing command was invoked.
-
- -- Variable: magit-current-popup-args
-
- The value of the popup arguments for this editing command.
-
- If the current command was invoked from a popup, then this is a
- list of strings of all the set switches and options. This includes
- arguments which are set by default not only those explicitly set
- during this invocation.
-
- When the value is nil, then that can be because no argument is set,
- or because the current command wasn’t invoked from a popup at all.
-
- -- Function: magit-current-popup-args &rest args
-
- This function returns the value of the popup arguments for this
- editing command. The value is the same as that of the variable by
- the same name, except that FILTER is applied. FILTER is a list of
- regexps; only arguments that match one of them are returned. The
- first element of FILTER may also be ‘:not’ in which case only
- arguments that don’t match any of the regexps are returned, or
- ‘:only’ which doesn’t change the behavior.
-
-
-\1f
-Tag Table:
-Node: Top\7f770
-Node: Introduction\7f2139
-Node: Usage\7f4478
-Node: Customizing Existing Popups\7f9175
-Node: Other Options\7f15316
-Node: Defining Prefix and Suffix Commands\7f16859
-Node: Defining Prefix Commands\7f19011
-Node: Defining Suffix Commands\7f27706
-\1f
-End Tag Table
-
-\1f
-Local Variables:
-coding: utf-8
-End:
--- /dev/null
+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.
+\1f
+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
+* Magit-Popup: (magit-popup). Infix arguments with feedback.
--- /dev/null
+;;; magit-popup-autoloads.el --- automatically extracted autoloads
+;;
+;;; Code:
+
+(add-to-list 'load-path (directory-file-name
+ (or (file-name-directory #$) (car load-path))))
+
+\f
+;;;### (autoloads nil "magit-popup" "magit-popup.el" (0 0 0 0))
+;;; Generated autoloads from magit-popup.el
+
+(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "magit-popup" '("magit-")))
+
+;;;***
+\f
+;;;### (autoloads nil nil ("magit-popup-pkg.el") (0 0 0 0))
+
+;;;***
+\f
+;; Local Variables:
+;; version-control: never
+;; no-byte-compile: t
+;; no-update-autoloads: t
+;; coding: utf-8
+;; End:
+;;; magit-popup-autoloads.el ends here
--- /dev/null
+(define-package "magit-popup" "20200102.1811" "Define prefix-infix-suffix command combos"
+ '((emacs "24.4")
+ (dash "2.13.0"))
+ :keywords
+ '("bindings")
+ :authors
+ '(("Jonas Bernoulli" . "jonasNOSPAMbernoul.li"))
+ :maintainer
+ '("Jonas Bernoulli" . "jonasNOSPAMbernoul.li")
+ :url "https://github.com/magit/magit-popup")
+;; Local Variables:
+;; no-byte-compile: t
+;; End:
--- /dev/null
+;;; magit-popup.el --- Define prefix-infix-suffix command combos -*- lexical-binding: t -*-
+
+;; Copyright (C) 2010-2020 The Magit Project Contributors
+;;
+;; You should have received a copy of the AUTHORS.md file which
+;; lists all contributors. If not, see http://magit.vc/authors.
+
+;; This library was inspired by and replaces library `magit-key-mode',
+;; which was written by Phil Jackson <philNOSPAMshellarchive.co.uk> and is
+;; distributed under the GNU General Public License version 3 or later.
+
+;; Author: Jonas Bernoulli <jonasNOSPAMbernoul.li>
+;; Maintainer: Jonas Bernoulli <jonasNOSPAMbernoul.li>
+
+;; Package-Requires: ((emacs "24.4") (dash "2.13.0"))
+;; Keywords: bindings
+;; Homepage: https://github.com/magit/magit-popup
+
+;; Magit-Popup 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, or (at your option)
+;; any later version.
+;;
+;; Magit-Popup 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 Magit-Popup. If not, see http://www.gnu.org/licenses.
+
+;;; Commentary:
+
+;; This package implements a generic interface for toggling switches
+;; and setting options and then invoking an Emacs command that does
+;; something with these arguments. Usually the command calls an
+;; external process with the specified arguments.
+
+;; This package has been superseded by Transient. No new features
+;; will be added but bugs will be fixes.
+
+;;; Code:
+
+(require 'button)
+(require 'cl-lib)
+(require 'dash)
+(require 'format-spec)
+(eval-when-compile (require 'subr-x))
+
+(declare-function info 'info)
+(declare-function Man-find-section 'man)
+(declare-function Man-next-section 'man)
+
+;; For branch actions.
+(declare-function magit-branch-set-face 'magit-git)
+
+;;; Settings
+;;;; Custom Groups
+
+(defgroup magit-popup nil
+ "Infix arguments with a popup as feedback."
+ :link '(info-link "(magit-popup)")
+ :group 'bindings)
+
+(defgroup magit-popup-faces nil
+ "Faces used by Magit-Popup."
+ :group 'magit-popup)
+
+;;;; Custom Options
+
+(defcustom magit-popup-display-buffer-action '((display-buffer-below-selected))
+ "The action used to display a popup buffer.
+
+Popup buffers are displayed using `display-buffer' with the value
+of this option as ACTION argument. You can also set this to nil
+and instead add an entry to `display-buffer-alist'."
+ :package-version '(magit-popup . "2.4.0")
+ :group 'magit-popup
+ :type 'sexp)
+
+(defcustom magit-popup-manpage-package
+ (if (memq system-type '(windows-nt ms-dos)) 'woman 'man)
+ "The package used to display manpages.
+One of `man' or `woman'."
+ :group 'magit-popup
+ :type '(choice (const man) (const woman)))
+
+(defcustom magit-popup-show-help-echo t
+ "Show usage information in the echo area."
+ :group 'magit-popup
+ :type 'boolean)
+
+(defcustom magit-popup-show-common-commands nil
+ "Whether to initially show section with commands common to all popups.
+This section can also be toggled temporarily using \
+\\<magit-popup-mode-map>\\[magit-popup-toggle-show-common-commands]."
+ :package-version '(magit-popup . "2.9.0")
+ :group 'magit-popup
+ :type 'boolean)
+
+(defcustom magit-popup-use-prefix-argument 'default
+ "Control how prefix arguments affect infix argument popups.
+
+This option controls the effect that the use of a prefix argument
+before entering a popup has.
+
+`default' With a prefix argument directly invoke the popup's
+ default action (an Emacs command), instead of bringing
+ up the popup.
+
+`popup' With a prefix argument bring up the popup, otherwise
+ directly invoke the popup's default action.
+
+`nil' Ignore prefix arguments."
+ :group 'magit-popup
+ :type '(choice
+ (const :tag "Call default action instead of showing popup" default)
+ (const :tag "Show popup instead of calling default action" popup)
+ (const :tag "Ignore prefix argument" nil)))
+
+;;;; Custom Faces
+
+(defface magit-popup-heading
+ '((t :inherit font-lock-keyword-face))
+ "Face for key mode header lines."
+ :group 'magit-popup-faces)
+
+(defface magit-popup-key
+ '((t :inherit font-lock-builtin-face))
+ "Face for key mode buttons."
+ :group 'magit-popup-faces)
+
+(defface magit-popup-argument
+ '((t :inherit font-lock-warning-face))
+ "Face used to display enabled arguments in popups."
+ :group 'magit-popup-faces)
+
+(defface magit-popup-disabled-argument
+ '((t :inherit shadow))
+ "Face used to display disabled arguments in popups."
+ :group 'magit-popup-faces)
+
+(defface magit-popup-option-value
+ '((t :inherit font-lock-string-face))
+ "Face used to display option values in popups."
+ :group 'magit-popup-faces)
+
+;;;; Keymap
+
+(defvar magit-popup-mode-map
+ (let ((map (make-sparse-keymap)))
+ (define-key map [remap self-insert-command] 'magit-invoke-popup-action)
+ (define-key map (kbd "- <t>") 'magit-invoke-popup-switch)
+ (define-key map (kbd "= <t>") 'magit-invoke-popup-option)
+ (define-key map (kbd "C-g") 'magit-popup-quit)
+ (define-key map (kbd "?") 'magit-popup-help)
+ (define-key map (kbd "C-h k") 'magit-popup-help)
+ (define-key map (kbd "C-h i") 'magit-popup-info)
+ (define-key map (kbd "C-t") 'magit-popup-toggle-show-common-commands)
+ (define-key map (kbd "C-c C-c") 'magit-popup-set-default-arguments)
+ (define-key map (kbd "C-x C-s") 'magit-popup-save-default-arguments)
+ (cond ((featurep 'jkl)
+ (define-key map (kbd "C-p") 'universal-argument)
+ (define-key map [return] 'push-button)
+ (define-key map (kbd "C-i") 'backward-button)
+ (define-key map (kbd "C-k") 'forward-button))
+ (t
+ (define-key map (kbd "C-m") 'push-button)
+ (define-key map (kbd "DEL") 'backward-button)
+ (define-key map (kbd "C-p") 'backward-button)
+ (define-key map (kbd "C-i") 'forward-button)
+ (define-key map (kbd "C-n") 'forward-button)))
+ map)
+ "Keymap for `magit-popup-mode'.
+
+\\<magit-popup-mode-map>\
+This keymap contains bindings common to all popups. A section
+listing these commands can be shown or hidden using \
+\\[magit-popup-toggle-show-common-commands].
+
+The prefix used to toggle any switch can be changed by binding
+another key to `magit-invoke-popup-switch'. Likewise binding
+another key to `magit-invoke-popup-option' changes the prefixed
+used to set any option. The two prefixes have to be different.
+If you change these bindings, you should also change the `prefix'
+property of the button types `magit-popup-switch-button' and
+`magit-popup-option-button'.
+
+If you change any other binding, then you might have to also edit
+`magit-popup-common-commands' for things to align correctly in
+the section listing these commands.
+
+Never bind an alphabetic character in this keymap or you might
+make it impossible to invoke certain actions.")
+
+(defvar magit-popup-common-commands
+ '(("Set defaults" magit-popup-set-default-arguments)
+ ("View popup manual" magit-popup-info)
+ ("Toggle this section" magit-popup-toggle-show-common-commands)
+ ("Save defaults" magit-popup-save-default-arguments)
+ (" Popup help prefix" magit-popup-help)
+ ("Abort" magit-popup-quit)))
+
+;;;; Buttons
+
+(define-button-type 'magit-popup-button
+ 'face nil
+ 'action (lambda (button)
+ (funcall (button-get button 'function)
+ (button-get button 'event))))
+
+(define-button-type 'magit-popup-switch-button
+ 'supertype 'magit-popup-button
+ 'function 'magit-invoke-popup-switch
+ 'property :switches
+ 'heading "Switches\n"
+ 'formatter 'magit-popup-format-argument-button
+ 'format " %k %d (%a)"
+ 'prefix ?-
+ 'maxcols 1)
+
+(define-button-type 'magit-popup-option-button
+ 'supertype 'magit-popup-button
+ 'function 'magit-invoke-popup-option
+ 'property :options
+ 'heading "Options\n"
+ 'formatter 'magit-popup-format-argument-button
+ 'format " %k %d (%a%v)"
+ 'prefix ?=
+ 'maxcols 1)
+
+(define-button-type 'magit-popup-variable-button
+ 'supertype 'magit-popup-button
+ 'function 'magit-invoke-popup-action
+ 'property :variables
+ 'heading "Variables\n"
+ 'formatter 'magit-popup-format-variable-button
+ 'format " %k %d"
+ 'prefix nil
+ 'maxcols 1)
+
+(define-button-type 'magit-popup-action-button
+ 'supertype 'magit-popup-button
+ 'function 'magit-invoke-popup-action
+ 'property :actions
+ 'heading "Actions\n"
+ 'formatter 'magit-popup-format-action-button
+ 'format " %k %d"
+ 'prefix nil
+ 'maxcols :max-action-columns)
+
+(define-button-type 'magit-popup-command-button
+ 'supertype 'magit-popup-action-button
+ 'formatter 'magit-popup-format-command-button
+ 'action (lambda (button)
+ (let ((command (button-get button 'function)))
+ (unless (eq command 'push-button)
+ (call-interactively command)))))
+
+(define-button-type 'magit-popup-internal-command-button
+ 'supertype 'magit-popup-command-button
+ 'heading "Common Commands\n"
+ 'maxcols 3)
+
+;;; Events
+
+(defvar-local magit-this-popup nil
+ "The popup which is currently active.
+This is intended for internal use only.
+Don't confuse this with `magit-current-popup'.")
+
+(defvar-local magit-this-popup-events nil
+ "The events known to the active popup.
+This is intended for internal use only.
+Don't confuse this with `magit-current-popup-args'.")
+
+(defvar-local magit-previous-popup nil)
+
+(defvar-local magit-pre-popup-buffer nil
+ "The buffer that was current before invoking the active popup.")
+
+(defun magit-popup-get (prop)
+ "While a popup is active, get the value of PROP."
+ (if (memq prop '(:switches :options :variables :actions))
+ (plist-get magit-this-popup-events prop)
+ (plist-get (symbol-value magit-this-popup) prop)))
+
+(defun magit-popup-put (prop val)
+ "While a popup is active, set the value of PROP to VAL."
+ (if (memq prop '(:switches :options :variables :actions))
+ (setq magit-this-popup-events
+ (plist-put magit-this-popup-events prop val))
+ (error "Property %s isn't supported" prop)))
+
+(defvar magit-current-popup nil
+ "The popup from which this editing command was invoked.
+
+Use this inside the `interactive' form of a popup aware command
+to determine whether it was invoked from a popup and if so from
+which popup. If the current command was invoked without the use
+of a popup, then this is nil.")
+
+(defvar magit-current-popup-action nil
+ "The popup action now being executed.")
+
+(defvar magit-current-popup-args nil
+ "The value of the popup arguments for this editing command.
+
+If the current command was invoked from a popup, then this is
+a list of strings of all the set switches and options. This
+includes arguments which are set by default not only those
+explicitly set during this invocation.
+
+When the value is nil, then that can be because no argument is
+set, or because the current command wasn't invoked from a popup;
+consult `magit-current-popup' to tell the difference.
+
+Generally it is better to use `NAME-arguments', which is created
+by `magit-define-popup', instead of this variable or the function
+by the same name, because `NAME-argument' uses the default value
+for the arguments when the editing command is invoked directly
+instead of from a popup. When the command is bound in several
+popups that might not be feasible though.")
+
+(defun magit-current-popup-args (&rest filter)
+ "Return the value of the popup arguments for this editing command.
+
+The value is the same as that of the variable by the same name
+\(which see), except that FILTER is applied. FILTER is a list
+of regexps; only arguments that match one of them are returned.
+The first element of FILTER may also be `:not' in which case
+only arguments that don't match any of the regexps are returned,
+or `:only' which doesn't change the behaviour."
+ (let ((-compare-fn (lambda (a b) (magit-popup-arg-match b a))))
+ (-filter (if (eq (car filter) :not)
+ (lambda (arg) (not (-contains-p (cdr filter) arg)))
+ (when (eq (car filter) :only)
+ (pop filter))
+ (lambda (arg) (-contains-p filter arg)))
+ magit-current-popup-args)))
+
+(defvar magit-current-pre-popup-buffer nil
+ "The buffer that was current before invoking the active popup.
+This is bound when invoking an action or variable.")
+
+(defmacro magit-with-pre-popup-buffer (&rest body)
+ "Execute the forms in BODY in the buffer that current before the popup.
+If `magit-current-pre-popup-buffer' is non-nil use that, else if
+`magit-pre-popup-buffer' is non-nil use that, otherwise (when no
+popup is involved) execute the forms in the current buffer."
+ (declare (indent 0))
+ `(--if-let (or magit-current-pre-popup-buffer magit-pre-popup-buffer)
+ (with-current-buffer it ,@body)
+ ,@body))
+
+(defun magit-popup-arg-match (pattern string)
+ (if (or (string-match-p "=$" pattern)
+ (string-match-p "^-[A-Z]$" pattern))
+ (string-match (format "^%s\\(.*\\)$" pattern) string)
+ (string-equal string pattern)))
+
+(cl-defstruct magit-popup-event key dsc arg fun use val)
+
+(defun magit-popup-event-keydsc (ev)
+ (let ((key (magit-popup-event-key ev)))
+ (key-description (if (vectorp key) key (vector key)))))
+
+(defun magit-popup-lookup (event type)
+ (--first (equal (magit-popup-event-key it) event)
+ (-filter 'magit-popup-event-p (magit-popup-get type))))
+
+(defun magit-popup-get-args ()
+ (--mapcat (when (and (magit-popup-event-p it)
+ (magit-popup-event-use it))
+ (list (format "%s%s"
+ (magit-popup-event-arg it)
+ (or (magit-popup-event-val it) ""))))
+ (append (magit-popup-get :switches)
+ (magit-popup-get :options))))
+
+(defmacro magit-popup-convert-events (def form)
+ (declare (indent 1) (debug (form form)))
+ `(--map (if (or (null it) (stringp it) (functionp it)) it ,form) ,def))
+
+(defun magit-popup-convert-switches (val def)
+ (magit-popup-convert-events def
+ (let ((a (nth 2 it)))
+ (make-magit-popup-event
+ :key (car it) :dsc (cadr it) :arg a
+ :use (and (member a val) t)
+ ;; For arguments implemented in lisp, this function's
+ ;; doc-string is used by `magit-popup-help'. That is
+ ;; the only thing it is used for.
+ :fun (and (string-prefix-p "\+\+" a) (nth 3 it))))))
+
+(defun magit-popup-convert-options (val def)
+ (magit-popup-convert-events def
+ (let* ((a (nth 2 it))
+ (r (format "^%s\\(.*\\)" a))
+ (v (--first (string-match r it) val)))
+ (make-magit-popup-event
+ :key (car it) :dsc (cadr it) :arg a
+ :use (and v t) :val (and v (match-string 1 v))
+ :fun (or (nth 3 it) 'read-from-minibuffer)))))
+
+(defun magit-popup-convert-variables (_val def)
+ (magit-popup-convert-events def
+ (make-magit-popup-event
+ :key (car it) :dsc (cadr it) :fun (nth 2 it) :arg (nth 3 it))))
+
+(defun magit-popup-convert-actions (_val def)
+ (magit-popup-convert-events def
+ (make-magit-popup-event
+ :key (car it) :dsc (cadr it) :fun (nth 2 it))))
+
+;;; Define
+
+(defmacro magit-define-popup (name doc &rest args)
+ "Define a popup command named NAME.
+
+NAME should begin with the package prefix and by convention end
+with `-popup'. That name is used for the actual command as well
+as for a variable used internally. DOC is used as the doc-string
+of that command.
+
+Also define an option and a function named `SHORTNAME-arguments',
+where SHORTNAME is NAME with the trailing `-popup' removed. The
+name of this option and this function can be overwritten using
+the optional argument OPTION, but that is rarely advisable. As a
+special case if OPTION is specified but nil, do not define this
+option and this function at all.
+
+The option `SHORTNAME-arguments' holds the default value for the
+popup arguments. It can be customized from within the popup or
+using the Custom interface.
+
+The function `SHORTNAME-arguments' is a wrapper around the
+variable `magit-current-popup-args', both of which are intended
+to be used inside the `interactive' form of commands commonly
+invoked from the popup `NAME'. When such a command is invoked
+from that popup, then the function `SHORTNAME-arguments' returns
+the value of the variable `magit-current-popup-args'; however
+when the command is invoked directly, then it returns the default
+value of the variable `SHORTNAME-arguments'.
+
+Optional argument GROUP specifies the Custom group into which the
+option is placed. If omitted, then the option is placed into some
+group the same way it is done when directly using `defcustom' and
+omitting the group, except when NAME begins with \"magit-\", in
+which case the group `magit-git-arguments' is used.
+
+Optional argument MODE is deprecated, instead use the keyword
+arguments `:setup-function' and/or `:refresh-function'. If MODE
+is non-nil, then it specifies the mode used by the popup buffer,
+instead of the default, which is `magit-popup-mode'.
+
+The remaining arguments should have the form
+
+ [KEYWORD VALUE]...
+
+The following keywords are meaningful (and by convention are
+usually specified in that order):
+
+`:actions'
+ The actions which can be invoked from the popup. VALUE is a
+ list whose members have the form (KEY DESC COMMAND), see
+ `magit-define-popup-action' for details.
+
+ Actions are regular Emacs commands, which usually have an
+ `interactive' form setup to consume the values of the popup
+ `:switches' and `:options' when invoked from the corresponding
+ popup, else when invoked as the default action or directly
+ without using the popup, the default value of the variable
+ `SHORTNAME-arguments'. This is usually done by calling the
+ function `SHORTNAME-arguments'.
+
+ Members of VALUE may also be strings and functions, assuming
+ the first member is a string or function. In that case the
+ members are split into sections and these special elements are
+ used as headings. If such an element is a function then it is
+ called with no arguments and must return either a string, which
+ is used as the heading, or nil, in which case the section is
+ not inserted.
+
+ Members of VALUE may also be nil. This should only be used
+ together with `:max-action-columns' and allows having gaps in
+ the action grid, which can help arranging actions sensibly.
+
+`:default-action'
+ The default action of the popup which is used directly instead
+ of displaying the popup buffer, when the popup is invoked with
+ a prefix argument. Also see `magit-popup-use-prefix-argument'
+ and `:use-prefix', which can be used to inverse the meaning of
+ the prefix argument.
+
+`:use-prefix'
+ Controls when to display the popup buffer and when to invoke
+ the default action (if any) directly. This overrides the
+ global default set using `magit-popup-use-prefix-argument'.
+ The value, if specified, should be one of `default' or `popup',
+ or a function that is called with no arguments and returns one
+ of these symbols.
+
+`:max-action-columns'
+ The maximum number of actions to display on a single line, a
+ number or a function that returns a number and takes the name
+ of the section currently being inserted as argument. If there
+ isn't enough room to display as many columns as specified here,
+ then fewer are used.
+
+`:switches'
+ The popup arguments which can be toggled on and off. VALUE
+ is a list whose members have the form (KEY DESC SWITCH), see
+ `magit-define-popup-switch' for details.
+
+ Members of VALUE may also be strings and functions, assuming
+ the first member is a string or function. In that case the
+ members are split into sections and these special elements are
+ used as headings. If such an element is a function then it is
+ called with no arguments and must return either a string, which
+ is used as the heading, or nil, in which case the section is
+ not inserted.
+
+`:options'
+ The popup arguments which take a value, as in \"--opt=OPTVAL\".
+ VALUE is a list whose members have the form (KEY DESC OPTION
+ READER), see `magit-define-popup-option' for details.
+
+ Members of VALUE may also be strings and functions, assuming
+ the first member is a string or function. In that case the
+ members are split into sections and these special elements are
+ used as headings. If such an element is a function then it is
+ called with no arguments and must return either a string, which
+ is used as the heading, or nil, in which case the section is
+ not inserted.
+
+`:default-arguments'
+ The default arguments, a list of switches (which are then
+ enabled by default) and options with there default values, as
+ in \"--OPT=OPTVAL\".
+
+`:variables'
+
+ Variables which can be set from the popup. VALUE is a list
+ whose members have the form (KEY DESC COMMAND FORMATTER), see
+ `magit-define-popup-variable' for details.
+
+ Members of VALUE may also be strings and functions, assuming
+ the first member is a string or function. In that case the
+ members are split into sections and these special elements are
+ used as headings. If such an element is a function then it is
+ called with no arguments and must return either a string, which
+ is used as the heading, or nil, in which case the section is
+ not inserted.
+
+ Members of VALUE may also be actions as described above for
+ `:actions'.
+
+ VALUE may also be a function that returns a list as describe
+ above.
+
+`:sequence-predicate'
+ When this function returns non-nil, then the popup uses
+ `:sequence-actions' instead of `:actions', and does not show
+ the `:switches' and `:options'.
+
+`:sequence-actions'
+ The actions which can be invoked from the popup, when
+ `:sequence-predicate' returns non-nil.
+
+`:setup-function'
+ When this function is specified, then it is used instead of
+ `magit-popup-default-setup'.
+
+`:refresh-function'
+ When this function is specified, then it is used instead of
+ calling `magit-popup-insert-section' three times with symbols
+ `magit-popup-switch-button', `magit-popup-option-button', and
+ finally `magit-popup-action-button' as argument.
+
+`:man-page'
+ The name of the manpage to be displayed when the user requests
+ help for a switch or argument.
+
+\(fn NAME DOC [GROUP [MODE [OPTION]]] :KEYWORD VALUE...)"
+ (declare (indent defun) (doc-string 2))
+ (let* ((str (symbol-name name))
+ (grp (if (keywordp (car args))
+ (and (string-prefix-p "magit-" str) ''magit-git-arguments)
+ (pop args)))
+ (mode (and (not (keywordp (car args))) (pop args)))
+ (opt (if (keywordp (car args))
+ (intern (concat (if (string-suffix-p "-popup" str)
+ (substring str 0 -6)
+ str)
+ "-arguments"))
+ (eval (pop args)))))
+ `(progn
+ (defun ,name (&optional arg) ,doc
+ (interactive "P")
+ (magit-invoke-popup ',name ,mode arg))
+ (defvar ,name
+ (list :variable ',opt ,@args))
+ (magit-define-popup-keys-deferred ',name)
+ ,@(when opt
+ `((defcustom ,opt (plist-get ,name :default-arguments)
+ ""
+ ,@(and grp (list :group grp))
+ :type '(repeat (string :tag "Argument")))
+ (defun ,opt ()
+ (if (eq magit-current-popup ',name)
+ magit-current-popup-args
+ ,opt))
+ (put ',opt 'definition-name ',name))))))
+
+(defun magit-define-popup-switch (popup key desc switch
+ &optional enable at prepend)
+ "In POPUP, define KEY as SWITCH.
+
+POPUP is a popup command defined using `magit-define-popup'.
+SWITCH is a string representing an argument that takes no value.
+KEY is a character representing the second event in the sequence
+of keystrokes used to toggle the argument. (The first event, the
+prefix, is shared among all switches, defaults to -, and can be
+changed in `magit-popup-mode-keymap').
+
+DESC is a string describing the purpose of the argument, it is
+displayed in the popup.
+
+If optional ENABLE is non-nil, then the switch is on by default.
+
+SWITCH is inserted after all other switches already defined for
+POPUP, unless optional PREPEND is non-nil, in which case it is
+placed first. If optional AT is non-nil, then it should be the
+KEY of another switch already defined for POPUP, the argument
+is then placed before or after AT, depending on PREPEND."
+ (declare (indent defun))
+ (magit-define-popup-key popup :switches key
+ (list desc switch enable) at prepend))
+
+(defun magit-define-popup-option (popup key desc option
+ &optional reader value at prepend)
+ "In POPUP, define KEY as OPTION.
+
+POPUP is a popup command defined using `magit-define-popup'.
+OPTION is a string representing an argument that takes a value.
+KEY is a character representing the second event in the sequence
+of keystrokes used to set the argument's value. (The first
+event, the prefix, is shared among all options, defaults to =,
+and can be changed in `magit-popup-mode-keymap').
+
+DESC is a string describing the purpose of the argument, it is
+displayed in the popup.
+
+If optional VALUE is non-nil then the option is on by default,
+and VALUE is its default value.
+
+READER is used to read a value from the user when the option is
+invoked and does not currently have a value. (When the option
+has a value, then invoking the option causes it to be unset.)
+This function must take two arguments but may choose to ignore
+them. The first argument is the name of the option (with \": \"
+appended, unless it ends with \"=\") and can be used as the
+prompt. The second argument is nil or the value that was in
+effect before the option was unset, which may be suitable as
+initial completion input. If no reader is specified, then
+`read-from-minibuffer' is used.
+
+OPTION is inserted after all other options already defined for
+POPUP, unless optional PREPEND is non-nil, in which case it is
+placed first. If optional AT is non-nil, then it should be the
+KEY of another option already defined for POPUP, the argument
+is then placed before or after AT, depending on PREPEND."
+ (declare (indent defun))
+ (magit-define-popup-key popup :options key
+ (list desc option reader value) at prepend))
+
+(defun magit-define-popup-variable (popup key desc command formatter
+ &optional at prepend)
+ "In POPUP, define KEY as COMMAND.
+
+POPUP is a popup command defined using `magit-define-popup'.
+COMMAND is a command which calls `magit-popup-set-variable'.
+FORMATTER is a function which calls `magit-popup-format-variable'.
+These two functions have to be called with the same arguments.
+
+KEY is a character representing the event used interactively call
+the COMMAND.
+
+DESC is the variable or a representation thereof. It's not
+actually used for anything.
+
+COMMAND is inserted after all other commands already defined for
+POPUP, unless optional PREPEND is non-nil, in which case it is
+placed first. If optional AT is non-nil, then it should be the
+KEY of another command already defined for POPUP, the command
+is then placed before or after AT, depending on PREPEND."
+ (declare (indent defun))
+ (magit-define-popup-key popup :variables key
+ (list desc command formatter) at prepend))
+
+(defun magit-define-popup-action (popup key desc command
+ &optional at prepend)
+ "In POPUP, define KEY as COMMAND.
+
+POPUP is a popup command defined using `magit-define-popup'.
+COMMAND can be any command but should usually consume the popup
+arguments in its `interactive' form.
+KEY is a character representing the event used invoke the action,
+i.e. to interactively call the COMMAND.
+
+DESC is a string describing the purpose of the action, it is
+displayed in the popup.
+
+COMMAND is inserted after all other commands already defined for
+POPUP, unless optional PREPEND is non-nil, in which case it is
+placed first. If optional AT is non-nil, then it should be the
+KEY of another command already defined for POPUP, the command
+is then placed before or after AT, depending on PREPEND."
+ (declare (indent defun))
+ (magit-define-popup-key popup :actions key
+ (list desc command) at prepend))
+
+(defun magit-define-popup-sequence-action
+ (popup key desc command &optional at prepend)
+ "Like `magit-define-popup-action' but for `:sequence-action'."
+ (declare (indent defun))
+ (magit-define-popup-key popup :sequence-actions key
+ (list desc command) at prepend))
+
+(defconst magit-popup-type-plural-alist
+ '((:switch . :switches)
+ (:option . :options)
+ (:variable . :variables)
+ (:action . :actions)
+ (:sequence-action . :sequence-actions)))
+
+(defun magit-popup-pluralize-type (type)
+ (or (cdr (assq type magit-popup-type-plural-alist))
+ type))
+
+(defun magit-define-popup-key
+ (popup type key def &optional at prepend)
+ "In POPUP, define KEY as an action, switch, or option.
+It's better to use one of the specialized functions
+ `magit-define-popup-action',
+ `magit-define-popup-sequence-action',
+ `magit-define-popup-switch',
+ `magit-define-popup-option', or
+ `magit-define-popup-variable'."
+ (declare (indent defun))
+ (setq type (magit-popup-pluralize-type type))
+ (if (memq type '(:switches :options :variables :actions :sequence-actions))
+ (if (boundp popup)
+ (let* ((plist (symbol-value popup))
+ (value (plist-get plist type))
+ (elt (assoc key value)))
+ (if elt
+ (setcdr elt def)
+ (setq elt (cons key def)))
+ (if at
+ (when (setq at (cl-member at value :key 'car-safe :test 'equal))
+ (setq value (cl-delete key value :key 'car-safe :test 'equal))
+ (if prepend
+ (progn (push (car at) (cdr at))
+ (setcar at elt))
+ (push elt (cdr at))))
+ (setq value (cl-delete key value :key 'car-safe :test 'equal)))
+ (unless (assoc key value)
+ (setq value (if prepend
+ (cons elt value)
+ (append value (list elt)))))
+ (set popup (plist-put plist type value)))
+ (push (list type key def at prepend)
+ (get popup 'magit-popup-deferred)))
+ (error "Unknown popup event type: %s" type)))
+
+(defun magit-define-popup-keys-deferred (popup)
+ (dolist (args (get popup 'magit-popup-deferred))
+ (condition-case err
+ (apply #'magit-define-popup-key popup args)
+ ((debug error)
+ (display-warning 'magit (error-message-string err) :error))))
+ (put popup 'magit-popup-deferred nil))
+
+(defun magit-change-popup-key (popup type from to)
+ "In POPUP, bind TO to what FROM was bound to.
+TYPE is one of `:action', `:sequence-action', `:switch', or
+`:option'. Bind TO and unbind FROM, both are characters."
+ (--if-let (assoc from (plist-get (symbol-value popup)
+ (magit-popup-pluralize-type type)))
+ (setcar it to)
+ (message "magit-change-popup-key: FROM key %c is unbound" from)))
+
+(defun magit-remove-popup-key (popup type key)
+ "In POPUP, remove KEY's binding of TYPE.
+POPUP is a popup command defined using `magit-define-popup'.
+TYPE is one of `:action', `:sequence-action', `:switch', or
+`:option'. KEY is the character which is to be unbound."
+ (setq type (magit-popup-pluralize-type type))
+ (let* ((plist (symbol-value popup))
+ (alist (plist-get plist type))
+ (value (assoc key alist)))
+ (set popup (plist-put plist type (delete value alist)))))
+
+;;; Invoke
+
+(defvar-local magit-popup-previous-winconf nil)
+
+(defun magit-invoke-popup (popup mode arg)
+ (let* ((def (symbol-value popup))
+ (val (symbol-value (plist-get def :variable)))
+ (default (plist-get def :default-action))
+ (local (plist-get def :use-prefix))
+ (local (if (functionp local)
+ (funcall local)
+ local))
+ (use-prefix (or local magit-popup-use-prefix-argument)))
+ (cond
+ ((or (and (eq use-prefix 'default) arg)
+ (and (eq use-prefix 'popup) (not arg)))
+ (if default
+ (let ((magit-current-popup (list popup 'default))
+ (magit-current-popup-args
+ (let ((magit-this-popup popup)
+ (magit-this-popup-events nil))
+ (magit-popup-default-setup val def)
+ (magit-popup-get-args))))
+ (when (and arg (listp arg))
+ (setq current-prefix-arg (and (not (= (car arg) 4))
+ (list (/ (car arg) 4)))))
+ (call-interactively default))
+ (message "%s has no default action; showing popup instead." popup)
+ (magit-popup-mode-setup popup mode)))
+ ((memq use-prefix '(default popup nil))
+ (magit-popup-mode-setup popup mode)
+ (when magit-popup-show-help-echo
+ (let ((message-log-max nil))
+ (message
+ (format
+ "[%s] show common commands, [%s] describe events, [%s] show manual"
+ (propertize "C-t" 'face 'magit-popup-key)
+ (propertize "?" 'face 'magit-popup-key)
+ (propertize "C-h i" 'face 'magit-popup-key))))))
+ (local
+ (error "Invalid :use-prefix popup property value: %s" use-prefix))
+ (t
+ (error "Invalid magit-popup-use-prefix-argument value: %s" use-prefix)))))
+
+(defun magit-invoke-popup-switch (event)
+ (interactive (list last-command-event))
+ (--if-let (magit-popup-lookup event :switches)
+ (progn
+ (setf (magit-popup-event-use it)
+ (not (magit-popup-event-use it)))
+ (magit-refresh-popup-buffer))
+ (user-error "%c isn't bound to any switch" event)))
+
+(defun magit-invoke-popup-option (event)
+ (interactive (list last-command-event))
+ (--if-let (magit-popup-lookup event :options)
+ (progn
+ (if (magit-popup-event-use it)
+ (setf (magit-popup-event-use it) nil)
+ (let* ((arg (magit-popup-event-arg it))
+ (val (funcall
+ (magit-popup-event-fun it)
+ (concat arg (unless (string-match-p "=$" arg) ": "))
+ (magit-popup-event-val it))))
+ (setf (magit-popup-event-use it) t)
+ (setf (magit-popup-event-val it) val)))
+ (magit-refresh-popup-buffer))
+ (user-error "%c isn't bound to any option" event)))
+
+(defun magit-invoke-popup-action (event)
+ (interactive (list last-command-event))
+ (let ((action (magit-popup-lookup event :actions))
+ (variable (magit-popup-lookup event :variables)))
+ (when (and variable (not (magit-popup-event-arg variable)))
+ (setq action variable)
+ (setq variable nil))
+ (cond ((or action variable)
+ (let* ((magit-current-popup magit-this-popup)
+ (magit-current-popup-args (magit-popup-get-args))
+ (magit-current-pre-popup-buffer magit-pre-popup-buffer)
+ (command (magit-popup-event-fun (or action variable)))
+ (magit-current-popup-action command))
+ (when action
+ (magit-popup-quit))
+ (setq this-command command)
+ (call-interactively command)
+ (unless action
+ (magit-refresh-popup-buffer))))
+ ((eq event ?q)
+ (magit-popup-quit)
+ (when magit-previous-popup
+ (magit-popup-mode-setup magit-previous-popup nil)))
+ (t
+ (user-error "%c isn't bound to any action" event)))))
+
+(defun magit-popup-quit ()
+ "Quit the current popup command without invoking an action."
+ (interactive)
+ (let ((winconf magit-popup-previous-winconf))
+ (if (derived-mode-p 'magit-popup-mode)
+ (kill-buffer)
+ (magit-popup-help-mode -1)
+ (kill-local-variable 'magit-popup-previous-winconf))
+ (when winconf
+ (set-window-configuration winconf))))
+
+(defun magit-popup-read-number (prompt &optional default)
+ "Like `read-number' but DEFAULT may be a numeric string."
+ (read-number prompt (if (stringp default)
+ (string-to-number default)
+ default)))
+
+;;; Save
+
+(defun magit-popup-set-default-arguments (arg)
+ "Set default value for the arguments for the current popup.
+Then close the popup without invoking an action; unless a prefix
+argument is used in which case the popup remains open.
+
+For a popup named `NAME-popup' that usually means setting the
+value of the custom option `NAME-arguments'."
+ (interactive "P")
+ (-if-let (var (magit-popup-get :variable))
+ (progn (customize-set-variable var (magit-popup-get-args))
+ (unless arg (magit-popup-quit)))
+ (user-error "Nothing to set")))
+
+(defun magit-popup-save-default-arguments (arg)
+ "Save default value for the arguments for the current popup.
+Then close the popup without invoking an action; unless a prefix
+argument is used in which case the popup remains open.
+
+For a popup named `NAME-popup' that usually means saving the
+value of the custom option `NAME-arguments'."
+ (interactive "P")
+ (-if-let (var (magit-popup-get :variable))
+ (progn (customize-save-variable var (magit-popup-get-args))
+ (unless arg (magit-popup-quit)))
+ (user-error "Nothing to save")))
+
+;;; Help
+
+(defun magit-popup-toggle-show-common-commands ()
+ "Show or hide an additional section with common commands.
+The commands listed in this section are common to all popups
+and are defined in `magit-popup-mode-map' (which see)."
+ (interactive)
+ (setq magit-popup-show-common-commands
+ (not magit-popup-show-common-commands))
+ (magit-refresh-popup-buffer)
+ (fit-window-to-buffer))
+
+(defun magit-popup-help ()
+ "Show help for the argument or action at point."
+ (interactive)
+ (let* ((man (magit-popup-get :man-page))
+ (key (read-key-sequence
+ (concat "Describe key" (and man " (? for manpage)") ": ")))
+ (int (aref key (1- (length key))))
+ (def (or (lookup-key (current-local-map) key t)
+ (lookup-key (current-global-map) key))))
+ (pcase def
+ (`magit-invoke-popup-switch
+ (--if-let (magit-popup-lookup int :switches)
+ (if (and (string-prefix-p "++" (magit-popup-event-arg it))
+ (magit-popup-event-fun it))
+ (magit-popup-describe-function (magit-popup-event-fun it))
+ (magit-popup-manpage man it))
+ (user-error "%c isn't bound to any switch" int)))
+ (`magit-invoke-popup-option
+ (--if-let (magit-popup-lookup int :options)
+ (if (and (string-prefix-p "++" (magit-popup-event-arg it))
+ (magit-popup-event-fun it))
+ (magit-popup-describe-function (magit-popup-event-fun it))
+ (magit-popup-manpage man it))
+ (user-error "%c isn't bound to any option" int)))
+ (`magit-popup-help
+ (magit-popup-manpage man nil))
+ ((or `self-insert-command
+ `magit-invoke-popup-action)
+ (setq def (or (magit-popup-lookup int :actions)
+ (magit-popup-lookup int :variables)))
+ (if def
+ (magit-popup-describe-function (magit-popup-event-fun def))
+ (ding)
+ (message nil)))
+ (`nil (ding)
+ (message nil))
+ (_ (magit-popup-describe-function def)))))
+
+(defun magit-popup-manpage (topic arg)
+ (unless topic
+ (user-error "No man page associated with %s"
+ (magit-popup-get :man-page)))
+ (when arg
+ (setq arg (magit-popup-event-arg arg))
+ (when (string-prefix-p "--" arg)
+ ;; handle '--' option and the '--[no-]' shorthand
+ (setq arg (cond ((string= "-- " arg)
+ "\\(?:\\[--\\] \\)?<[^[:space:]]+>\\.\\.\\.")
+ ((string-prefix-p "--no-" arg)
+ (concat "--"
+ "\\[?no-\\]?"
+ (substring arg 5)))
+ (t
+ (concat "--"
+ "\\(?:\\[no-\\]\\)?"
+ (substring arg 2)))))))
+ (let ((winconf (current-window-configuration)) buffer)
+ (pcase magit-popup-manpage-package
+ (`woman (delete-other-windows)
+ (split-window-below)
+ (with-no-warnings ; display-buffer-function is obsolete
+ (let ((display-buffer-alist nil)
+ (display-buffer-function nil)
+ (display-buffer-overriding-action nil))
+ (woman topic)))
+ (setq buffer (current-buffer)))
+ (`man (cl-letf (((symbol-function #'fboundp) (lambda (_) nil)))
+ (setq buffer (man topic)))
+ (delete-other-windows)
+ (split-window-below)
+ (set-window-buffer (selected-window) buffer)))
+ (with-current-buffer buffer
+ (setq magit-popup-previous-winconf winconf)
+ (magit-popup-help-mode)
+ (fit-window-to-buffer (next-window))
+ (if (and arg
+ (Man-find-section "OPTIONS")
+ (let ((case-fold-search nil)
+ ;; This matches preceding/proceeding options.
+ ;; Options such as '-a', '-S[<keyid>]', and
+ ;; '--grep=<pattern>' are matched by this regex
+ ;; without the shy group. The '. ' in the shy
+ ;; group is for options such as '-m
+ ;; parent-number', and the '-[^[:space:]]+ ' is
+ ;; for options such as '--mainline parent-number'
+ (others "-\\(?:. \\|-[^[:space:]]+ \\)?[^[:space:]]+"))
+ (re-search-forward
+ ;; should start with whitespace, and may have any
+ ;; number of options before/after
+ (format "^[\t\s]+\\(?:%s, \\)*?\\(?1:%s\\)%s\\(?:, %s\\)*$"
+ others
+ ;; options don't necessarily end in an '='
+ ;; (e.g., '--gpg-sign[=<keyid>]')
+ (string-remove-suffix "=" arg)
+ ;; Simple options don't end in an '='.
+ ;; Splitting this into 2 cases should make
+ ;; getting false positives less likely.
+ (if (string-suffix-p "=" arg)
+ ;; [^[:space:]]*[^.[:space:]] matches
+ ;; the option value, which is usually
+ ;; after the option name and either '='
+ ;; or '[='. The value can't end in a
+ ;; period, as that means it's being used
+ ;; at the end of a sentence. The space
+ ;; is for options such as '--mainline
+ ;; parent-number'.
+ "\\(?: \\|\\[?=\\)[^[:space:]]*[^.[:space:]]"
+ ;; Either this doesn't match anything
+ ;; (e.g., '-a'), or the option is followed
+ ;; by a value delimited by a '[', '<', or
+ ;; ':'. A space might appear before this
+ ;; value, as in '-f <file>'. The space
+ ;; alternative is for options such as '-m
+ ;; parent-number'.
+ "\\(?:\\(?: \\| ?[\\[<:]\\)[^[:space:]]*[^.[:space:]]\\)?")
+ others)
+ nil
+ t)))
+ (goto-char (match-beginning 1))
+ (goto-char (point-min))))))
+
+(defun magit-popup-describe-function (function)
+ (let ((winconf (current-window-configuration)))
+ (delete-other-windows)
+ (split-window-below)
+ (other-window 1)
+ (with-no-warnings ; display-buffer-function is obsolete
+ (let ((display-buffer-alist '(("" display-buffer-use-some-window)))
+ (display-buffer-function nil)
+ (display-buffer-overriding-action nil)
+ (help-window-select nil))
+ (describe-function function)))
+ (fit-window-to-buffer)
+ (other-window 1)
+ (setq magit-popup-previous-winconf winconf)
+ (magit-popup-help-mode)))
+
+(defun magit-popup-info ()
+ "Show the popup manual."
+ (interactive)
+ (let ((winconf (current-window-configuration)))
+ (delete-other-windows)
+ (split-window-below)
+ (info "(magit-popup.info)Usage")
+ (magit-popup-help-mode)
+ (setq magit-popup-previous-winconf winconf))
+ (magit-popup-help-mode)
+ (fit-window-to-buffer (next-window)))
+
+(define-minor-mode magit-popup-help-mode
+ "Auxiliary minor mode used to restore previous window configuration.
+When some sort of help buffer is created from within a popup,
+then this minor mode is turned on in that buffer, so that when
+the user quits it, the previous window configuration is also
+restored."
+ :keymap '(([remap Man-quit] . magit-popup-quit)
+ ([remap Info-exit] . magit-popup-quit)
+ ([remap quit-window] . magit-popup-quit)))
+
+;;; Modes
+
+(define-derived-mode magit-popup-mode fundamental-mode "MagitPopup"
+ "Major mode for infix argument popups."
+ :mode 'magit-popup
+ (setq truncate-lines t)
+ (setq buffer-read-only t)
+ (setq-local scroll-margin 0)
+ (setq-local magit-popup-show-common-commands magit-popup-show-common-commands)
+ (hack-dir-local-variables-non-file-buffer))
+
+(put 'magit-popup-mode 'mode-class 'special)
+
+(defun magit-popup-default-setup (val def)
+ (if (--when-let (magit-popup-get :sequence-predicate)
+ (funcall it))
+ (magit-popup-put :actions (magit-popup-convert-actions
+ val (magit-popup-get :sequence-actions)))
+ (let ((vars (plist-get def :variables)))
+ (when (functionp vars)
+ (setq vars (funcall vars)))
+ (when vars
+ (magit-popup-put :variables (magit-popup-convert-variables val vars))))
+ (magit-popup-put :switches (magit-popup-convert-switches
+ val (plist-get def :switches)))
+ (magit-popup-put :options (magit-popup-convert-options
+ val (plist-get def :options)))
+ (magit-popup-put :actions (magit-popup-convert-actions
+ val (plist-get def :actions)))))
+
+(defun magit-popup-mode-setup (popup mode)
+ (setq magit-previous-popup magit-current-popup)
+ (let ((val (symbol-value (plist-get (symbol-value popup) :variable)))
+ (def (symbol-value popup))
+ (buf (current-buffer)))
+ (magit-popup-mode-display-buffer (get-buffer-create
+ (format "*%s*" popup))
+ (or mode 'magit-popup-mode))
+ (setq magit-this-popup popup)
+ (setq magit-pre-popup-buffer buf)
+ (if (bound-and-true-p magit-popup-setup-hook) ; obsolete
+ (run-hook-with-args 'magit-popup-setup-hook val def)
+ (funcall (or (magit-popup-get :setup-function)
+ 'magit-popup-default-setup)
+ val def)))
+ (magit-refresh-popup-buffer)
+ (fit-window-to-buffer nil nil (line-number-at-pos (point-max))))
+
+(defun magit-popup-mode-display-buffer (buffer mode)
+ (let ((winconf (current-window-configuration)))
+ (select-window (display-buffer buffer magit-popup-display-buffer-action))
+ (funcall mode)
+ (setq magit-popup-previous-winconf winconf)))
+
+(defvar magit-refresh-popup-buffer-hook nil
+ "Hook run by `magit-refresh-popup-buffer'.
+
+The hook is run right after inserting the representation of the
+popup events but before optionally inserting the representation
+of events shared by all popups and before point is adjusted.")
+
+(defun magit-refresh-popup-buffer ()
+ (let* ((inhibit-read-only t)
+ (button (button-at (point)))
+ (prefix (and button (button-get button 'prefix)))
+ (event (and button (button-get button 'event))))
+ (erase-buffer)
+ (save-excursion
+ (--if-let (magit-popup-get :refresh-function)
+ (funcall it)
+ (magit-popup-insert-section 'magit-popup-variable-button)
+ (magit-popup-insert-section 'magit-popup-switch-button)
+ (magit-popup-insert-section 'magit-popup-option-button)
+ (magit-popup-insert-section 'magit-popup-action-button))
+ (run-hooks 'magit-refresh-popup-buffer-hook)
+ (when magit-popup-show-common-commands
+ (magit-popup-insert-command-section
+ 'magit-popup-internal-command-button
+ magit-popup-common-commands)))
+ (set-buffer-modified-p nil)
+ (when event
+ (while (and (ignore-errors (forward-button 1))
+ (let ((b (button-at (point))))
+ (or (not (equal (button-get b 'prefix) prefix))
+ (not (equal (button-get b 'event) event)))))))))
+
+;;; Draw
+
+(defvar magit-popup-min-padding 3
+ "Minimal amount of whitespace between columns in popup buffers.")
+
+(defun magit-popup-insert-section (type &optional spec heading)
+ (if (not spec)
+ (progn (setq spec (magit-popup-get (button-type-get type 'property)))
+ (when spec
+ (if (or (stringp (car spec))
+ (functionp (car spec)))
+ (--each (--partition-by-header
+ (or (stringp it) (functionp it))
+ spec)
+ (magit-popup-insert-section type (cdr it) (car it)))
+ (magit-popup-insert-section type spec))))
+ (let* ((formatter (button-type-get type 'formatter))
+ (items (mapcar (lambda (ev)
+ (and ev (or (funcall formatter type ev) '(""))))
+ (or spec (magit-popup-get
+ (button-type-get type 'property)))))
+ (maxcols (button-type-get type 'maxcols))
+ (pred (magit-popup-get :sequence-predicate)))
+ (when items
+ (if (functionp heading)
+ (when (setq heading (funcall heading))
+ (insert heading ?\n))
+ (unless heading
+ (setq heading (button-type-get type 'heading)))
+ (insert (propertize heading 'face 'magit-popup-heading))
+ (unless (string-match "\n$" heading)
+ (insert "\n")))
+ (if (and pred (funcall pred))
+ (setq maxcols nil)
+ (cl-typecase maxcols
+ (keyword (setq maxcols (magit-popup-get maxcols)))
+ (symbol (setq maxcols (symbol-value maxcols)))))
+ (when (functionp maxcols)
+ (setq maxcols (funcall maxcols heading)))
+ (when heading
+ (let ((colwidth
+ (+ (apply 'max (mapcar (lambda (e) (length (car e))) items))
+ magit-popup-min-padding)))
+ (dolist (item items)
+ (unless (bolp)
+ (let ((padding (- colwidth (% (current-column) colwidth))))
+ (if (and (< (+ (current-column) padding colwidth)
+ (window-width))
+ (< (ceiling (/ (current-column) (* colwidth 1.0)))
+ (or maxcols 1000)))
+ (insert (make-string padding ?\s))
+ (insert "\n"))))
+ (unless (equal item '(""))
+ (if item
+ (apply 'insert-button item)
+ (insert ?\s)))))
+ (insert (if (= (char-before) ?\n) "\n" "\n\n")))))))
+
+(defun magit-popup-format-argument-button (type ev)
+ (list (format-spec
+ (button-type-get type 'format)
+ `((?k . ,(propertize (concat
+ (--when-let (button-type-get type 'prefix)
+ (char-to-string it))
+ (magit-popup-event-keydsc ev))
+ 'face 'magit-popup-key))
+ (?d . ,(magit-popup-event-dsc ev))
+ (?a . ,(propertize (magit-popup-event-arg ev)
+ 'face (if (magit-popup-event-use ev)
+ 'magit-popup-argument
+ 'magit-popup-disabled-argument)))
+ (?v . ,(let ((val (magit-popup-event-val ev)))
+ (if (and (magit-popup-event-use ev)
+ (not (equal val "")))
+ (propertize (format "\"%s\"" val)
+ 'face 'magit-popup-option-value)
+ "")))))
+ 'type type 'event (magit-popup-event-key ev)))
+
+(defun magit-popup-format-variable-button (type ev)
+ (if (not (magit-popup-event-arg ev))
+ (magit-popup-format-action-button 'magit-popup-action-button ev)
+ (list (format-spec
+ (button-type-get type 'format)
+ `((?k . ,(propertize (magit-popup-event-keydsc ev)
+ 'face 'magit-popup-key))
+ (?d . ,(funcall (magit-popup-event-arg ev)))))
+ 'type type 'event (magit-popup-event-key ev))))
+
+(defun magit-popup-format-action-button (type ev)
+ (let* ((cmd (magit-popup-event-fun ev))
+ (dsc (magit-popup-event-dsc ev))
+ (fun (and (functionp dsc) dsc)))
+ (unless (and disabled-command-function
+ (symbolp cmd)
+ (get cmd 'disabled))
+ (when fun
+ (setq dsc
+ (-when-let (branch (funcall fun))
+ (if (text-property-not-all 0 (length branch) 'face nil branch)
+ branch
+ (magit-branch-set-face branch)))))
+ (when dsc
+ (list (format-spec
+ (button-type-get type 'format)
+ `((?k . ,(propertize (magit-popup-event-keydsc ev)
+ 'face 'magit-popup-key))
+ (?d . ,dsc)
+ (?D . ,(if (and (not fun)
+ (eq cmd (magit-popup-get :default-action)))
+ (propertize dsc 'face 'bold)
+ dsc))))
+ 'type type 'event (magit-popup-event-key ev))))))
+
+(defun magit-popup-insert-command-section (type spec)
+ (magit-popup-insert-section
+ type (mapcar (lambda (elt)
+ (list (car (where-is-internal (cadr elt)
+ (current-local-map)))
+ (car elt)))
+ spec)))
+
+(defun magit-popup-format-command-button (type elt)
+ (nconc (magit-popup-format-action-button
+ type (make-magit-popup-event :key (car elt)
+ :dsc (cadr elt)))
+ (list 'function (lookup-key (current-local-map) (car elt)))))
+
+;;; Utilities
+
+(defun magit-popup-import-file-args (args files)
+ (if files
+ (cons (concat "-- " (mapconcat #'identity files ",")) args)
+ args))
+
+(defun magit-popup-export-file-args (args)
+ (let ((files (--first (string-prefix-p "-- " it) args)))
+ (when files
+ (setq args (remove files args))
+ (setq files (split-string (substring files 3) ",")))
+ (list args files)))
+
+(defconst magit-popup-font-lock-keywords
+ (eval-when-compile
+ `((,(concat "(\\(magit-define-popup\\)\\_>"
+ "[ \t'\(]*"
+ "\\(\\(?:\\sw\\|\\s_\\)+\\)?")
+ (1 'font-lock-keyword-face)
+ (2 'font-lock-function-name-face nil t)))))
+
+(font-lock-add-keywords 'emacs-lisp-mode magit-popup-font-lock-keywords)
+
+;;; _
+(provide 'magit-popup)
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; End:
+;;; magit-popup.el ends here
--- /dev/null
+This is magit-popup.info, produced by makeinfo version 6.5 from
+magit-popup.texi.
+
+ Copyright (C) 2015-2020 Jonas Bernoulli <jonasNOSPAMbernoul.li>
+
+ 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
+* Magit-Popup: (magit-popup). Infix arguments with feedback.
+END-INFO-DIR-ENTRY
+
+\1f
+File: magit-popup.info, Node: Top, Next: Introduction, Up: (dir)
+
+Magit-Popup User Manual
+***********************
+
+This package implements a generic interface for toggling switches and
+setting options and then invoking an Emacs command that does something
+with these arguments. Usually the command calls an external process
+with the specified arguments.
+
+ This package has been superseded by Transient (*note
+(transient)Top::). No new features will be added but bugs will be
+fixes.
+
+This manual is for Magit-Popup version 2.13.2.
+
+ Copyright (C) 2015-2020 Jonas Bernoulli <jonasNOSPAMbernoul.li>
+
+ 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:
+
+* Introduction::
+* Usage::
+* Defining Prefix and Suffix Commands::
+
+— The Detailed Node Listing —
+
+Usage
+
+* Customizing Existing Popups::
+* Other Options::
+
+Defining Prefix and Suffix Commands
+
+* Defining Prefix Commands::
+* Defining Suffix Commands::
+
+
+\1f
+File: magit-popup.info, Node: Introduction, Next: Usage, Prev: Top, Up: Top
+
+1 Introduction
+**************
+
+Taking inspiration from regular prefix commands and prefix arguments,
+this library implements a similar abstraction; a new kind of prefix
+command that is associated with a specific set of infix arguments and
+suffix commands.
+
+ Invoking such a prefix command displays a popup buffer which lists
+the associated infix arguments and suffix commands. In that buffer each
+argument is prefixed with the key sequence that can be used to toggle it
+or change its value. Likewise each suffix command is prefixed with the
+key used to invoke it. Such a popup buffer might look like this:
+
+ ,-----------------------------------------
+ |Switches
+ | -l Show graph (--graph)
+ | -d Show refnames (--decorate)
+ |
+ |Options
+ | =m Search messages (--grep="popup")
+ | =p Search patches (-G)
+ |
+ |Action
+ | l Show log for current branch
+ | o Show log for another branch
+ '-----------------------------------------
+
+ The user could then for example type ‘-l’ to toggle the ‘--graph’
+*switch* (when it is on then it is shown in green, otherwise in gray),
+or ‘=m’ to change the value of the *option* ‘--grep’.
+
+ Once all arguments are as desired one invokes a suffix command, which
+causes the popup buffer to disappear. The suffix command should then
+retrieve the infix arguments in its ‘interactive’ form like this is done
+for prefix arguments.
+
+ While such "prefix-infix-suffix" combos were inspired by regular
+prefix commands and prefix arguments, they are also quite different.
+This should illustrate the most basic differences:
+
+ • A regular prefix command
+
+ /- command1
+ prefix --- command2
+ \- command3
+
+ • Prefix arguments
+
+ /- command1
+ C-u ... --- command2
+ \- well any command
+
+ • A Prefix-Infix-Suffix combo
+
+ /- argument1 -\ /- suffix1
+ prefix----- argument2 --+-- suffix2
+ ^ \- argument3 -/
+ | |
+ '--------'
+ (refresh buffer)
+
+ This package has been superseded by Transient (*note
+(transient)Top::). No new features will be added but bugs will be
+fixes.
+
+\1f
+File: magit-popup.info, Node: Usage, Next: Defining Prefix and Suffix Commands, Prev: Introduction, Up: Top
+
+2 Usage
+*******
+
+Every popup buffers created with a prefix command contains a section
+named "Actions" listing the available suffix commands. Most buffers
+also contain a "Switches" and/or an "Options" section which list the two
+types of infix arguments separately.
+
+ Switches are arguments that can be toggled on or off. When a switch
+is active then it is shown in color, when it is off then it is shown in
+gray (of course the details depend on the color theme in use).
+
+ Options are arguments that have a value. When an option has a value
+then that is shown after the option itself. Because for some options
+the empty string is a valid value, options are additionally colorized
+like switches to indicate whether they are active or not.
+
+ The events bound to suffix commands are always single alphabetic
+characters. The bindings for arguments are always two events long. For
+switches the first key is always ‘-’, for options it is always ‘=’. The
+second key is always an alphabetic character.
+
+ By default popup buffers also feature a section listing commands
+common to all popups. To avoid conflicts with suffix commands, the
+bindings of these common commands are not alphabetic characters. This
+section is shown by default so that documentation-resistant users get a
+chance to notice them.
+
+ -- User Option: magit-popup-show-common-commands
+
+ This option controls whether the section that lists the commands
+ that are common to all popups is initially shown.
+
+ By default this is not the case, but note that you can temporarily
+ show this section using ‘C-t’, which therefore is the only common
+ command you actually have to memorize.
+
+‘C-t’ (‘magit-popup-toggle-show-common-commands’)
+
+ Show or hide the section listing the commands shared by all popups.
+
+‘C-g’ (‘magit-popup-quit’)
+
+ Quit popup buffer without invoking a suffix command.
+
+ Without further action, setting arguments only affects the next
+suffix command. Invoking the same prefix command again resets the
+arguments to their default value, but the defaults can be changed
+directly from the popup buffer itself. For a prefix command named
+‘NAME-popup’ the default values are stored as the value of the custom
+option named ‘NAME-arguments’. While this option can be customized
+using the Custom interface, it is better to do so directly from the
+popup buffer.
+
+‘C-c C-c’ (‘magit-popup-set-default-arguments’)
+
+ This sets the default value for the arguments for the current
+ popup.
+
+ Then the popup buffer is closed without invoking a suffix command;
+ unless a prefix argument is used in which case the popup remains
+ open.
+
+‘C-x C-s’ (‘magit-popup-save-default-arguments’)
+
+ This sets the default value for the arguments for the current popup
+ and saves it for future Emacs sessions.
+
+ Then the popup buffer is closed without invoking an action; unless
+ a prefix argument is used in which case the popup remains open.
+
+ It is also possible to add additional arguments and commands to an
+existing popup, but that cannot be done directly from the popup (or the
+Custom interface). See *note Customizing Existing Popups::.
+
+ Documentation about a popup’s arguments and commands can be shown
+directly from the popup.
+
+‘C-h i’ (‘magit-popup-info’)
+
+ Show this manual.
+
+‘?’ (‘magit-popup-help’)
+
+ This command reads a key sequence and then shows the documentation
+ of the argument or command that sequence is bound to. In other
+ words type the same keys that you would use to invoke the argument
+ or command, but prefix the sequence with ‘?’.
+
+ For suffix commands this shows the doc-string. For arguments this
+ command can only show something for popups that have an associated
+ man-page. If the man-page is set, then this command displays it in
+ a separate buffer and puts point on the entry about the argument in
+ question.
+
+ The buffer which is used to display the documentation is selected.
+ Simply press ‘q’ to leave that buffer and restore the old window
+ configuration.
+
+ While it isn’t very useful, it is possible to move around in a popup
+buffer using ‘C-p’ and ‘C-n’, and to invoke the argument or command at
+point using ‘RET’. But it is much more efficient to use the dedicated
+key bindings instead, so these commands are not listed in popup buffers
+along with the other common commands.
+
+* Menu:
+
+* Customizing Existing Popups::
+* Other Options::
+
+\1f
+File: magit-popup.info, Node: Customizing Existing Popups, Next: Other Options, Up: Usage
+
+2.1 Customizing Existing Popups
+===============================
+
+It is possible to define additional infix arguments and suffix commands
+to an existing popup using the following functions.
+
+ You can find some examples which use the below commands at
+<https://github.com/magit/magit/wiki/Additional-proposed-infix-arguments-and-suffix-commands>.
+
+ -- Function: magit-define-popup-switch popup key desc switch &optional
+ enable at prepend
+
+ In POPUP, define KEY as SWITCH.
+
+ POPUP is a popup command defined using ‘magit-define-popup’.
+ SWITCH is a string representing an argument that takes no value.
+ KEY is a character representing the second event in the sequence of
+ keystrokes used to toggle the argument. (The first event, the
+ prefix, is shared among all switches, defaults to ‘-’, and can be
+ changed in ‘magit-popup-mode-keymap’).
+
+ DESC is a string describing the purpose of the argument, it is
+ displayed in the popup.
+
+ If optional ENABLE is non-nil then the switch is on by default.
+
+ SWITCH is inserted after all other switches already defined for
+ POPUP, unless optional PREPEND is non-nil, in which case it is
+ placed first. If optional AT is non-nil then it should be the KEY
+ of another switch already defined for POPUP, the argument is then
+ placed before or after AT, depending on PREPEND.
+
+ -- Function: magit-define-popup-option popup key desc option &optional
+ reader value at prepend
+
+ In POPUP, define KEY as OPTION.
+
+ POPUP is a popup command defined using ‘magit-define-popup’.
+ OPTION is a string representing an argument that takes a value.
+ KEY is a character representing the second event in the sequence of
+ keystrokes used to set the argument’s value. (The first event, the
+ prefix, is shared among all options, defaults to ‘=’, and can be
+ changed in ‘magit-popup-mode-keymap’).
+
+ DESC is a string describing the purpose of the argument, it is
+ displayed in the popup.
+
+ If optional VALUE is non-nil then the option is on by default, and
+ VALUE is its default value.
+
+ READER is used to read a value from the user when the option is
+ invoked and does not currently have a value. (When the option has
+ a value, then invoking the option causes it to be unset.) This
+ function must take two arguments but may choose to ignore them.
+ The first argument is the name of the option (with ": \" appended,
+ unless it ends with "=") and can be used as the prompt. The second
+ argument is nil or the value that was in effect before the option
+ was unset, which may be suitable as initial completion input. If
+ no reader is specified, then ‘read-from-minibuffer’ is used.
+
+ OPTION is inserted after all other options already defined for
+ POPUP, unless optional PREPEND is non-nil, in which case it is
+ placed first. If optional AT is non-nil then it should be the KEY
+ of another option already defined for POPUP, the argument is then
+ placed before or after AT, depending on PREPEND.
+
+ -- Function: magit-define-popup-action popup key desc command &optional
+ at prepend
+
+ In POPUP, define KEY as COMMAND.
+
+ POPUP is a popup command defined using ‘magit-define-popup’.
+ COMMAND can be any command but should usually consume the popup
+ arguments in its ‘interactive’ form. KEY is a character
+ representing the event used invoke the action, i.e. to
+ interactively call the COMMAND.
+
+ DESC is a string describing the purpose of the action, it is
+ displayed in the popup.
+
+ COMMAND is inserted after all other commands already defined for
+ POPUP, unless optional PREPEND is non-nil, in which case it is
+ placed first. If optional AT is non-nil then it should be the KEY
+ of another command already defined for POPUP, the command is then
+ placed before or after AT, depending on PREPEND.
+
+ -- Function: magit-define-popup-sequence-action popup key desc command
+ &optional at prepend
+
+ Like ‘magit-define-popup-action’, but modifies the value of the
+ ‘:sequence-actions’ property instead of ‘:actions’.
+
+ -- Function: magit-define-popup-variable popup key desc command
+ formatter &optional at prepend
+
+ In POPUP, define KEY as COMMAND.
+
+ POPUP is a popup command defined using ‘magit-define-popup’.
+ COMMAND is a command which calls ‘magit-popup-set-variable’.
+ FORMATTER is a function which calls ‘magit-popup-format-variable’.
+ These two functions have to be called with the same arguments.
+
+ KEY is a character representing the event used interactively call
+ the COMMAND.
+
+ DESC is the variable or a representation thereof. It’s not
+ actually used for anything.
+
+ COMMAND is inserted after all other commands already defined for
+ POPUP, unless optional PREPEND is non-nil, in which case it is
+ placed first. If optional AT is non-nil then it should be the KEY
+ of another command already defined for POPUP, the command is then
+ placed before or after AT, depending on PREPEND."
+
+ -- Function: magit-change-popup-key popup type from to
+
+ In POPUP, bind TO to what FROM was bound to. TYPE is one of
+ ‘:action’, ‘:sequence-action’, ‘:switch’, or ‘:option’. Bind TO
+ and unbind FROM, both are characters.
+
+ -- Function: magit-remove-popup-key popup type key
+
+ In POPUP, remove KEY’s binding of TYPE. POPUP is a popup command
+ defined using ‘magit-define-popup’. TYPE is one of ‘:action’,
+ ‘:sequence-action’, ‘:switch’, or ‘:option’. KEY is the character
+ which is to be unbound.
+
+ It is also possible to change other aspects of a popup by setting a
+property using ‘plist-put’. See *note Defining Prefix Commands:: for
+valid properties. The most likely change Magit users might want to make
+is:
+
+ (plist-put magit-show-refs-popup :use-prefix nil)
+
+\1f
+File: magit-popup.info, Node: Other Options, Prev: Customizing Existing Popups, Up: Usage
+
+2.2 Other Options
+=================
+
+ -- User Option: magit-popup-use-prefix-argument
+
+ This option controls the effect that the use of a prefix argument
+ before entering a popup has.
+
+ • ‘default’
+
+ With a prefix argument directly invoke the popup’s default
+ action (an Emacs command), instead of bringing up the popup.
+
+ • ‘popup’
+
+ With a prefix argument bring up the popup, otherwise directly
+ invoke the popup’s default action.
+
+ • ‘nil’
+
+ Ignore prefix arguments.
+
+ This option can be overridden for individual popups.
+ ‘magit-show-refs-popup’ for example defaults to invoking the
+ default action directly. It only shows the popup buffer when a
+ prefix argument is used. See *note Customizing Existing Popups::.
+
+ -- User Option: magit-popup-manpage-package
+
+ The Emacs package used to display man-pages, one of ‘man’ or
+ ‘woman’.
+
+ -- User Option: magit-popup-display-buffer-action
+
+ The option controls how the window used to display a popup buffer
+ is created. Popup buffers are displayed using ‘display-buffer’
+ with the value of this option as ACTION argument. You can also set
+ this to nil and instead add an entry to ‘display-buffer-alist’.
+
+ To emphasize the default action by making it bold use this:
+
+ (button-type-put 'magit-popup-action-button 'format " %k %D")
+
+\1f
+File: magit-popup.info, Node: Defining Prefix and Suffix Commands, Prev: Usage, Up: Top
+
+3 Defining Prefix and Suffix Commands
+*************************************
+
+If you write an extension for Magit then you should use this library now
+and later when ‘transient’ is released port to that.
+
+ If you are considering using this library to define popups for
+packages not related to Magit, then keep in mind that it will be
+superseded eventually. Once ‘transient’ has been released I will only
+fix bugs in ‘magit-popup’ but not implement any new features.
+
+ Also consider using ‘hydra’ instead. To some extend ‘magit-popup’
+and ‘hydra’ are similar but have a different focus. The main purpose of
+‘magit-popup’ is to pass infix arguments to suffix commands. If all you
+need is a command dispatcher then you are better of using ‘hydra’. Of
+course ‘hydra’ may also be a better fit not only because of the features
+it lacks, but also because of the features it provides, which are in
+turn missing from ‘magit-popup’.
+
+ Here is an example of how one defines a prefix command along with its
+infix arguments, and then also one of its suffix commands.
+
+ ;;;###autoload (autoload 'magit-tag-popup "magit" nil t)
+ (magit-define-popup magit-tag-popup
+ "Show popup buffer featuring tagging commands."
+ 'magit-commands
+ :man-page "git-tag"
+ :switches '((?a "Annotate" "--annotate")
+ (?s "Sign" "--sign")
+ (?f "Force" "--force"))
+ :actions '((?t "Create" magit-tag)
+ (?k "Delete" magit-tag-delete)
+ (?p "Prune" magit-tag-prune))
+ :default-action 'magit-tag)
+
+ ;;;###autoload
+ (defun magit-tag (name rev &optional args)
+ "Create a new tag with the given NAME at REV."
+ (interactive (list (magit-read-tag "Tag name")
+ (magit-read-branch-or-commit "Place tag on")
+ (magit-tag-arguments)))
+ (magit-run-git-with-editor "tag" args name rev))
+
+* Menu:
+
+* Defining Prefix Commands::
+* Defining Suffix Commands::
+
+\1f
+File: magit-popup.info, Node: Defining Prefix Commands, Next: Defining Suffix Commands, Up: Defining Prefix and Suffix Commands
+
+3.1 Defining Prefix Commands
+============================
+
+Prefix commands and their infix arguments are defined using the macro
+‘magit-define-popup’. The key bindings and descriptions of suffix
+commands are also defined using that macro, but the actual interactive
+commands have to be defined separately using plain ‘defun’.
+
+ -- Macro: magit-define-popup name doc [group [mode [option]]] :keyword
+ value...
+
+ This macro defines a popup named NAME. The NAME should begin with
+ the package prefix and by convention end with ‘-popup’, it is used
+ as the name of the command which shows the popup and for an
+ internal variable (whose value is used to store information about
+ the popup and should not be accessed directly). DOC is the
+ doc-string of the popup command.
+
+ This macro also defines an option and a function both named
+ ‘SHORTNAME-arguments’, where SHORTNAME is NAME with the trailing
+ ‘-popup’ removed. The name of this option and this function can be
+ overwritten using the optional argument OPTION, but that is rarely
+ advisable. As a special case if OPTION is specified but ‘nil’,
+ then this option and this function are not defined at all, which is
+ useful for popups that are used as simple dispatchers that offer no
+ arguments.
+
+ The option ‘SHORTNAME-arguments’ holds the value for the popup
+ arguments. It can be customized from within the popup or using the
+ Custom interface. It can also have a buffer local value in any
+ non-popup buffer. The local value for the buffer from which the
+ popup command was invoked, can be set from within the popup buffer.
+
+ The function ‘SHORTNAME-arguments’ returns the currently effective
+ value of the variable by the same name. See below for more
+ information.
+
+ Optional argument GROUP specifies the Custom group into which the
+ option is placed. If omitted then the option is placed into some
+ group the same way it is done when directly using ‘defcustom’ and
+ omitting the group, except when NAME begins with "magit-", in which
+ case the group ‘magit-git-arguments’ is used.
+
+ The optional argument MODE specifies the mode used by the popup
+ buffer. If it is omitted or ‘nil’ then ‘magit-popup-mode’ is used.
+
+ The remaining arguments should have the form ‘[KEYWORD VALUE]...’.
+
+ The following keywords are meaningful (and by convention are
+ usually specified in that order):
+
+ • ‘:actions’
+
+ The actions which can be invoked from the popup. VALUE is a
+ list whose members have the form (KEY DESC COMMAND), see
+ ‘magit-define-popup-action’ for details.
+
+ Actions are regular Emacs commands, which usually have an
+ ‘interactive’ form setup to consume the values of the popup
+ ‘:switches’ and ‘:options’ when invoked from the corresponding
+ popup, else when invoked as the default action or directly
+ without using the popup, the default value of the variable
+ ‘SHORTNAME-arguments’. This is usually done by calling the
+ function ‘SHORTNAME-arguments’.
+
+ Members of VALUE may also be strings and functions, assuming
+ the first member is a string or function. In that case the
+ members are split into sections and these special elements are
+ used as headings. If such an element is a function then it is
+ called with no arguments and must return either a string,
+ which is used as the heading, or nil, in which case the
+ section is not inserted.
+
+ Members of VALUE may also be nil. This should only be used
+ together with ‘:max-action-columns’ and allows having gaps in
+ the action grit, which can help arranging actions sensibly.
+
+ • ‘:default-action’
+
+ The default action of the popup which is used directly instead
+ of displaying the popup buffer, when the popup is invoked with
+ a prefix argument. Also see ‘magit-popup-use-prefix-argument’
+ and ‘:use-prefix’, which can be used to inverse the meaning of
+ the prefix argument.
+
+ • ‘:use-prefix’
+
+ Controls when to display the popup buffer and when to invoke
+ the default action (if any) directly. This overrides the
+ global default set using ‘magit-popup-use-prefix-argument’.
+ The value, if specified, should be one of ‘default’ or
+ ‘prefix’, or a function that is called with no arguments and
+ returns one of these symbols.
+
+ • ‘:max-action-columns’
+
+ The maximum number of actions to display on a single line, a
+ number or a function that return a number and takes the name
+ of the section currently being inserted as argument. If there
+ isn’t enough room to display as many columns as specified
+ here, then fewer are used.
+
+ • ‘:switches’
+
+ The popup arguments which can be toggled on and off. VALUE is
+ a list whose members have the form ‘(KEY DESC SWITCH)’, see
+ ‘magit-define-popup-switch’ for details.
+
+ Members of VALUE may also be strings and functions, assuming
+ the first member is a string or function. In that case the
+ members are split into sections and these special elements are
+ used as headings. If such an element is a function then it is
+ called with no arguments and must return either a string,
+ which is used as the heading, or nil, in which case the
+ section is not inserted.
+
+ • ‘:options’
+
+ The popup arguments which take a value, as in "–opt~OPTVAL".
+ VALUE is a list whose members have the form ‘(KEY DESC OPTION
+ READER)’, see ‘magit-define-popup-option’ for details.
+
+ Members of VALUE may also be strings and functions, assuming
+ the first member is a string or function. In that case the
+ members are split into sections and these special elements are
+ used as headings. If such an element is a function then it is
+ called with no arguments and must return either a string,
+ which is used as the heading, or nil, in which case the
+ section is not inserted.
+
+ • ‘:default-arguments’
+
+ The default arguments, a list of switches (which are then
+ enabled by default) and options with there default values, as
+ in ‘"--OPT=OPTVAL"’.
+
+ • ‘:variables’
+
+ Variables which can be set from the popup. VALUE is a list
+ whose members have the form ‘(KEY DESC COMMAND FORMATTER)’,
+ see ‘magit-define-popup-variable’ for details.
+
+ Members of VALUE may also be strings and functions, assuming
+ the first member is a string or function. In that case the
+ members are split into sections and these special elements are
+ used as headings. If such an element is a function then it is
+ called with no arguments and must return either a string,
+ which is used as the heading, or nil, in which case the
+ section is not inserted.
+
+ Members of VALUE may also be actions as described above for
+ ‘:actions’.
+
+ VALUE may also be a function that returns a list as describe
+ above.
+
+ • ‘:sequence-predicate’
+
+ When this function returns non-nil, then the popup uses
+ ‘:sequence-actions’ instead of ‘:actions’, and does not show
+ the ‘:switches’ and ‘:options’.
+
+ • ‘:sequence-actions’
+
+ The actions which can be invoked from the popup, when
+ ‘:sequence-predicate’ returns non-nil.
+
+ • ‘:setup-function’
+
+ When this function is specified, then it is used instead of
+ ‘magit-popup-default-setup’.
+
+ • ‘:refresh-function’
+
+ When this function is specified, then it is used instead of
+ calling ‘magit-popup-insert-section’ three times with symbols
+ ‘magit-popup-switch-button’, ‘magit-popup-option-button’, and
+ finally ‘magit-popup-action-button’ as argument.
+
+ • ‘:man-page’
+
+ The name of the manpage to be displayed when the user requests
+ help for an argument.
+
+\1f
+File: magit-popup.info, Node: Defining Suffix Commands, Prev: Defining Prefix Commands, Up: Defining Prefix and Suffix Commands
+
+3.2 Defining Suffix Commands
+============================
+
+Commands intended to be invoked from a particular popup should determine
+the currently effective arguments by calling the function
+‘SHORTNAME-arguments’ inside their ‘interactive’ form. This function is
+created by the ‘magit-define-popup’ macro. For a popup named
+‘prefix-foo-popup’ the name of this function is ‘prefix-foo-arguments’.
+
+ When the command was invoked as an action in the respective popup,
+then this function returns the arguments that were set in the popup.
+Otherwise when the command was invoked as the default of the popup (by
+calling the popup command with a prefix argument), or without using the
+popup command at all, then this function returns the buffer-local or
+global value of the variable ‘SHORTNAME-arguments’.
+
+ Internally arguments are handled as a list of strings. This might
+not be appropriate for the intended use inside commands, or it might be
+necessary to manipulate that list somehow, i.e. to split "–ARG=VAL"
+into "–ARG""VAL". This should be done by advising or redefining the
+function ‘SHORTNAME-arguments’.
+
+ Internally ‘SHORNAME-arguments’ used following variables and
+function. Except when redefining the former, you should not use these
+directly.
+
+ -- Variable: magit-current-popup
+
+ The popup from which this editing command was invoked.
+
+ -- Variable: magit-current-popup-args
+
+ The value of the popup arguments for this editing command.
+
+ If the current command was invoked from a popup, then this is a
+ list of strings of all the set switches and options. This includes
+ arguments which are set by default not only those explicitly set
+ during this invocation.
+
+ When the value is nil, then that can be because no argument is set,
+ or because the current command wasn’t invoked from a popup at all.
+
+ -- Function: magit-current-popup-args &rest args
+
+ This function returns the value of the popup arguments for this
+ editing command. The value is the same as that of the variable by
+ the same name, except that FILTER is applied. FILTER is a list of
+ regexps; only arguments that match one of them are returned. The
+ first element of FILTER may also be ‘:not’ in which case only
+ arguments that don’t match any of the regexps are returned, or
+ ‘:only’ which doesn’t change the behavior.
+
+
+\1f
+Tag Table:
+Node: Top\7f770
+Node: Introduction\7f2139
+Node: Usage\7f4478
+Node: Customizing Existing Popups\7f9175
+Node: Other Options\7f15316
+Node: Defining Prefix and Suffix Commands\7f16859
+Node: Defining Prefix Commands\7f19011
+Node: Defining Suffix Commands\7f27706
+\1f
+End Tag Table
+
+\1f
+Local Variables:
+coding: utf-8
+End:
projects / emacsconfig.git / commitdiff