EmacsWiki: Prefix Argument (original) (raw)
The prefix argument is a pseudo-argument that is automatically available for each Emacs command.
When you use a command, its behavior might differ, depending on the value of the prefix argument. You can use ‘C-u’ to set the prefix argument value to use, and thus affect the command’s behavior. ‘C-u’ is bound to command ‘universal-argument’, the universal argument command.
When you define a command, you can have it examine the current prefix argument and act differently, depending on its value.
Raw vs Numerical Prefix Arg
The prefix argument can have several kinds of value. It can be a list with a single integer element, ‘nil’, the symbol ‘-’, or an integer. The prefix argument is also called the raw prefix argument.
Whatever the raw value, the prefix argument is also said to have a numeric value that is derived from its raw value. This is also called the numeric prefix argument. The numeric prefix argument is 1 when the raw prefix argument is ‘nil’. It is -1 when the raw prefix argument is ‘-’. It is the integer list element when the raw prefix argument is a cons. Otherwise, it is the same integer as the raw prefix value.
If the user calls a command without using ‘C-u’, ‘C--’, ‘M--’, or ‘C-’’N , where N is a positive or negative integer, then the raw prefix argument is ‘nil’, and we also speak of there being no prefix argument.
For more information, see the EmacsLisp manual, node Prefix Command Arguments. That node also describes which prefix argument is passed to a command when user calls the command in different ways (e.g. ‘C-u’, ‘C-u 3’).
Overloading Commands Using the Prefix Argument
When you define a command, you might want it to produce two or more different results, depending on what the user wants. In a sense, this is overloading the command name, giving the command two or more alternative behaviors.
A conventional way to do this is to make the behavior depend on the prefix argument. You could, for example, write a command that normally kills a buffer only if it has no unsaved changes, but kills a buffer even if it has unsaved changes when the user provides a ‘C-u’ prefix.
There are various ways that a command definition can examine the raw and numeric prefix arguments, but a typical way is to use ‘P’ for raw or ‘p’ for numeric in the command’s ‘interactive’ spec.
This command definition, for instance, binds the argument ‘arg’ to the raw prefix argument value. It prints the argument value.
(defun foo (arg)
"Print the current raw prefix argument value."
(interactive "P")
(message "raw prefix arg is %S" arg))Try it:
‘M-x foo’ calls ‘foo’ with ‘arg’ bound to nil
‘C-u M-x foo’ calls ‘foo’ with ‘arg’ bound to (4)
‘C-u C-u M-x foo’ calls ‘foo’ with ‘arg’ bound to (16)
‘C-u 3 M-x foo’ calls ‘foo’ with ‘arg’ bound to 3
‘M-- M-x foo’ calls ‘foo’ with ‘arg’ bound to -
Multiple-Digit Numeric Prefix Argument
You can use ‘C-u’ to terminate a prefix argument that has more than one digit: ‘C-u 1 0 0 C-u’ sets the prefix argument to 100. See also InfiniteArgument.