`this-command-keys-vector', prefix keys, and Customize

`this-command-keys-vector', prefix keys, and Customize

[Drew Adams]

Consider this:

 (global-set-key [menu-bar edit foo] '("Foo" . foo-cmd))

Then, choosing `Edit > Foo' from the menu bar results in this
value for `(this-command-keys-vector)':

  [(menu-bar) edit foo]

I don't find the parenthesized form `(menu-bar)' documented
anywhere.  Is it really correct?  In a sense it obviously is,
since Emacs apparently works that way.

And someone will no doubt reply that it is internal, so it can
be anything Emacs Dev wants it to be.  Maybe.

But we document the form of keys and keymaps, and users should
be able to know what the form is (or all possible forms are) in
such a case, and count on that.  Either that or provide
functions (an API) that abstract from the actual form and let
you construct and manipulate its components etc.

Now consider this, as a way of letting users define a key
sequence to be used as a prefix key and tested against existing
prefix keys:

 (defcustom pref-key [] "doc..."
    :type '(key-sequence :tag "Prefix Key" :value []))

Now how can a user customize that, to match the actual prefix
key returned as the first part of [(menu-bar) edit foo]?
S?he can enter <menu-bar> <edit> in the Customize edit field.
But that gives [menu-bar edit], not [(menu-bar) edit].

How can code test a value such as [menu-bar edit] against the
prefix part of what `this-command-keys-vector' returns, which
is [(menu-bar) edit]?

Is there a bug in `this-command-keys-vector', so that it
should in fact return [menu-bar edit foo] here, not
[(menu-bar) edit foo]?

Or is there a problem with Customize, so that it should
return [(menu-bar) edit] for the input <menu-bar> <edit>?

Or is there some function `same-key' that handles all such
forms of keys, testing for equivalence, so that instead of

 (equal ACTUAL-PREFIX  OPTION-PREFIX), i.e., in this case
 (equal [(menu-bar) edit]  [menu-bar edit])
        ^^^^^actual^^^^^^  ^^^^option^^^^^

I could test (same-key ACTUAL-PREFIX  OPTION-PREFIX)?

If not, and I need to roll my own such test function, what
are the possible forms of a prefix key as a vector?

Is it enough to wrap any non-list elements of ACTUAL-PREFIX
and OPTION-PREFIX with #'list, so, in effect, the comparison
here becomes:

  (equal [(menu-bar) (edit)] [(menu-bar) (edit)])?

Or to unwrap any list elements, so it becomes:

  (equal [menu-bar edit] [menu-bar edit])?

What's the right way, or a good way, to go about this?

I want to test an actual prefix key, obtained as part of
`this-command-keys-vector', against a prefix key chosen
by the user as an option value.

Thanks for any help.  Perhaps this is all clearly documented
somewhere, the coding is trivial, and I just haven't come
across it yet.  That's my hope anyway.

RE: `this-command-keys-vector', prefix keys, and Customize

[Drew Adams]

> Or is there some function `same-key' that handles all such
> forms of keys, testing for equivalence, so I could test
> (same-key ACTUAL-PREFIX OPTION-PREFIX)?
>
> If not, and I need to roll my own such test function,
> what are the possible forms of a prefix key as a vector?
> 
> Is it enough to unwrap any list elements in the vector?

Doing only that seems to work so far (but with only a little
testing).

(defun uncons (obj) "..." (if (consp obj) (car obj) obj))

(defun same-vector-key-p (key1 key2) "..."
       (equal (apply #'vector (mapcar #'uncons key1))
              (apply #'vector (mapcar #'uncons key2)))))

But I do wonder whether there is a predefined function for
this kind of thing.  And whether this is the right way to
approach the problem.