my-emacs-d/elpa/magit-popup-20160606.1041/magit-popup.info

713 lines
28 KiB
Plaintext
Raw Normal View History

2016-02-24 22:06:01 +00:00
This is magit-popup.info, produced by makeinfo version 5.2 from
magit-popup.texi.
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.
Copyright (C) 2015-2016 Jonas Bernoulli <jonas@bernoul.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

File: magit-popup.info, Node: Top, Next: Introduction, Up: (dir)
Magit-Popup User Manual
***********************
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.
Copyright (C) 2015-2016 Jonas Bernoulli <jonas@bernoul.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 —
2016-04-21 21:27:19 +00:00
2016-02-24 22:06:01 +00:00
Usage
* Customizing existing popups::
* Other options::
2016-04-21 21:27:19 +00:00
2016-02-24 22:06:01 +00:00
Defining prefix and suffix commands
* Defining prefix commands::
* Defining suffix commands::

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 prefixes 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 disappears. 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 commands
/- 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 library was written as a replacement for magit-key-mode which
was used in Magit releases before 2.1.0. It is used to implement all
"popups" in the current Magit release but a future release will switch
to yet another implementation.
This library does not depend on any other Magit libraries and it is
distributed as a separate package, which makes it possible to use it in
packages that are not related to Magit. But keep in mind that it will
be deprecated eventually.

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
change to notice them.
-- User Option: magit-popup-show-common-commands
This option controls whether the section which lists the commands
that are common to all popups is initially show. We recommend you
set this to nil - after you have memorized that it can be shown
on demand using C-t.
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: Customizing
existing popups.
Documentation about a popups 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 isnt 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::

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 arguments 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.
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. Its 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 KEYs 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:
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)

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. The *intended* default is default,
but the *actual* default is disabled. This is necessary because
the old popup implementation did simply forward such a pre-popup
prefix argument to the suffix command invoked from the popup, and
changing that without users being aware of it could lead to tears.
disabled
Bring up a Custom option buffer so that the user reads this
and then makes an informed choice.
default
With a prefix argument directly invoke the popups default
action (an Emacs command), instead of bringing up the popup.
popup
With a prefix argument bring up the popup, otherwise directly
invoke the popups 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:
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")

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::

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.
The optional argument GROUP specifies the Custom group in which the
option is placed. If omitted then the option is placed in some
group the same way it is done when directly using defcustom and
omitting the group.
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.
How the actions are split into rows and columns currently
depends on the available space and :max-action-columns.
WARNING: This will likely be change to use a more explicit
format (((KEY DESC COMMAND)…)…) before the release.
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, assuming the first
member is also a string. Instead of just one action section
with the heading \"Actions\", multiple sections are then
inserted into the popup buffer, using these strings as
headings.
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.
: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.
: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.
:variables
Git 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.
: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\".
: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.

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 wasnt 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 dont match any of the regexps are returned, or
:only which doesnt change the behavior.

Tag Table:
Node: Top994
2016-04-21 21:27:19 +00:00
Node: Introduction2170
Node: Usage4747
Node: Customizing existing popups9404
Node: Other options14932
Node: Defining prefix and suffix commands16981
Node: Defining prefix commands19077
Node: Defining suffix commands25757
2016-02-24 22:06:01 +00:00

End Tag Table

Local Variables:
coding: utf-8
End: