Re: Prefix-Arg (non-interactive!) in Info

[Eli Zaretskii]

> From: Memnon Anon <gegendosenfleisch@googlemail.com>
> Cc: help-gnu-emacs@gnu.org
> Date: Fri, 13 Aug 2010 19:04:30 +0200
> 
> The function asked for was org-clock-in.
> 
> ,----[ org-clock-in ]
> | org-clock-in is an interactive compiled Lisp function.
> | 
> | (org-clock-in &optional SELECT START-TIME)
> | 
> | Start the clock on the current item.
> | If necessary, clock-out of the currently active clock.
> | With a prefix argument SELECT (C-u), offer a list of recently clocked tasks 
> to
> | clock into.  When SELECT is C-u C-u, clock into the current task and mark
> | is as the default task, a special task that will always be offered in
> | the clocking selection, associated with the letter `d'.
> `----
> 
> I knew `C-u' = 4 (and not "t" as someone suggested), so I tried 
> (global-set-key (kbd "<F12>") (lambda () (interactive) (org-clock-in 4)))
>                                                         ^^^^^^^^^^^^^^^
> This did not work, but I was hardly surprised.

You are wrong assuming that the prefix arg is always 4.  Its ``value''
depends on how the function accesses it; the node in the ELisp manual
that Drew pointed to spells out the possible ``values''.  In addition,
it matters how the function tests the possible values of the argument;
if the function just checks that its argument (in this case, SELECT)
is non-nil, then '(4) will do, but so will '(foobar).

> (defun multiply-by-seven (number)       ; Interactive version.
>        "Multiply NUMBER by seven."
>        (interactive "p")
>        (message "The result is %d" (* 7 number)))
> 
> (multiply-by-seven 2) --> 14
> M-8 M-x multiply-by-seven --> 56
> C-u M-x multiply-by-seven --> 28
> Works for this function...
> 
> So I tried to figure out in what form org-clock-in wanted its argument
> of 4 passed in.
> 
> And I found nothing, until I turned to google.

It would be better (and more educational) to simply read the code of
the function (and submit a bug report regarding the unclear doc
string).  In there, you'd see that org-clock-in uses (interactive "P"),
which assigns the raw prefix argument to SELECT, and it tests its
value like this:

      (when (equal select '(4))

which tells you that it really wants the list '(4) -- not very clean,
I'd say.

> Now I am really confused:
> I expected this to work, but it does not:
> (multiply-by-seven '(4)).

That's because multiply-by-seven uses (interactive "p") -- lowercase
`p' -- which assigns to NUMBER the numerical value of the prefix arg.

The meaning of the interactive codes, such as "P" and "p", is
explained in the node "Interactive Codes" in the ELisp manual.