bug#2723: Emacs 23: `interactive': prefix argument "P" and region "r" are mutually exclusive.

[Alan Mackenzie <acm@muc.de>]

Hi, Stefan et al.,

On Fri, Mar 20, 2009 at 09:19:51AM -0400, Stefan Monnier wrote:
> >> > It seems that `(interactive "rP")' is only supplying the defun with two
> >> > parameters.
> >> Read C-h f interactive RET, and if you read carefully enough you'll see
> >> you need (interactive "r\nP")
> > No.

> I see two bugs:
> 1 - the doc is unclear about the need for a newline.
> 2 - arguments without prompts should signal a warning when provided with
>     a prompt (this would have helped you find your problem).

OK, here's a pair of patches for bug 1.  Any comments before I commit
them?


2009-03-21  Alan Mackenzie  <acm@muc.de>

        * callint.c (Finteractive): Clarify the doc string - even
        promptless elements need \n separators.


*** callint.c.orig	2009-03-08 14:56:05.000000000 +0000
--- callint.c	2009-03-21 14:49:33.360805672 +0000
***************
*** 68,85 ****
  DEFUN ("interactive", Finteractive, Sinteractive, 0, UNEVALLED, 0,
         doc: /* Specify a way of parsing arguments for interactive use of a function.
  For example, write
!   (defun foo (arg) "Doc string" (interactive "p") ...use arg...)
! to make ARG be the prefix argument when `foo' is called as a command.
  The "call" to `interactive' is actually a declaration rather than a function;
   it tells `call-interactively' how to read arguments
   to pass to the function.
  When actually called, `interactive' just returns nil.
  
! The argument of `interactive' is usually a string containing a code letter
!  followed by a prompt.  (Some code letters do not use I/O to get
!  the argument and do not need prompts.)  To prompt for multiple arguments,
!  give a code letter, its prompt, a newline, and another code letter, etc.
!  Prompts are passed to format, and may use % escapes to print the
   arguments that have already been read.
  If the argument is not a string, it is evaluated to get a list of
   arguments to pass to the function.
--- 68,86 ----
  DEFUN ("interactive", Finteractive, Sinteractive, 0, UNEVALLED, 0,
         doc: /* Specify a way of parsing arguments for interactive use of a function.
  For example, write
!  (defun foo (arg buf) "Doc string" (interactive "P\\nbbuffer: ") .... )
!  to make ARG be the raw prefix argument, and set BUF to an existing buffer,
!  when `foo' is called as a command.
  The "call" to `interactive' is actually a declaration rather than a function;
   it tells `call-interactively' how to read arguments
   to pass to the function.
  When actually called, `interactive' just returns nil.
  
! Usually the argument of `interactive' is a string containing a code letter
!  followed optionally by a prompt.  (Some code letters do not use I/O to get
!  the argument and do not use prompts.)  To get several arguments, concatenate
!  the individual strings, separating them by newline characters.
! Prompts are passed to format, and may use % escapes to print the
   arguments that have already been read.
  If the argument is not a string, it is evaluated to get a list of
   arguments to pass to the function.



2009-03-21  Alan Mackenzie  <acm@muc.de>

        * commands.texi (Using Interactive): Clarify string argument to
        `interactive' - even promptless elements need \n separators.


*** commands.texi.orig	2009-02-12 12:10:45.000000000 +0000
--- commands.texi	2009-03-21 14:55:01.964850264 +0000
***************
*** 158,181 ****
  or more arguments.
  
  @item
! It may be a string; then its contents should consist of a code character
! followed by a prompt (which some code characters use and some ignore).
! The prompt ends either with the end of the string or with a newline.
! Here is a simple example:
  
  @smallexample
! (interactive "bFrobnicate buffer: ")
  @end smallexample
  
  @noindent
! The code letter @samp{b} says to read the name of an existing buffer,
! with completion.  The buffer name is the sole argument passed to the
! command.  The rest of the string is a prompt.
! 
! If there is a newline character in the string, it terminates the prompt.
! If the string does not end there, then the rest of the string should
! contain another code character and prompt, specifying another argument.
! You can specify any number of arguments in this way.
  
  @c Emacs 19 feature
  The prompt string can use @samp{%} to include previous argument values
--- 158,179 ----
  or more arguments.
  
  @item
! It may be a string; its contents are a sequence of elements separated
! by newlines, one for each parameter@footnote{Some elements actually
! supply two parameters.}.  Each element consists of a code character
! (@pxref{ Interactive Codes}) optionally followed by a prompt (which
! some code characters use and some ignore).  Here is an example:
  
  @smallexample
! (interactive "P\nbFrobnicate buffer: ")
  @end smallexample
  
  @noindent
! The code letter @samp{P} sets the command's first argument to the raw
! command prefix (@pxref{Prefix Command Arguments}).  @samp{bFrobnicate
! buffer: } prompts the user with @samp{Frobnicate buffer: } to enter
! the name of an existing buffer, which becomes the second and final
! argument.
  
  @c Emacs 19 feature
  The prompt string can use @samp{%} to include previous argument values

> 
>         Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).