Next: , Up: Defining Prefix and Suffix Commands   [Contents]

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

Next: , Up: Defining Prefix and Suffix Commands   [Contents]