== Q. When is a menu not a menu? A. When it's a la carte. ==


This page describes library '''<tt>[[lacarte.el]]</tt>''', which lets you execute [[menu-bar]] menu commands from the keyboard, using [[completion]].  Use it as an alternative to vanilla
Emacs menu-bar access, including the default `F10' behavior of
`menu-bar-open' and that of standard library ##tmm.el##. 

Use the keyboard to access any menu item, without knowing where it
is or what its full name is.  Type part of its name and use
completion to get the rest: the complete path and item name.
When you choose a menu-item candidate, the corresponding command is executed.

Completion candidates have this form:

    menu > submenu > subsubmenu > ... > menu item

For example:

    File > Open Recent > Cleanup list
    File > Open Recent > Edit list...

Put this in your [[init file]] (##~/.emacs##):

  (require 'lacarte)

For convenience, bind a [[key sequence]] to `lacarte-execute-command':

  (global-set-key [?\e ?\M-x] 'lacarte-execute-command)

Type `##<ESC> M-x##' (or `ESC ESC X', which is the same thing). You're prompted for a command or menu command to execute.  Each menu
item's full name, for completion, has its parent menu names as
prefixes.






[:Commands]
== Commands and Menu Commands ==

Use `lacarte-execute-command' if you don't care whether a command
is on a menu.  Then, if you want a command that affects a [[buffer]],
just type `buf'.

Consider also replacing the standard bindings of `tmm-menu' and
`menu-bar-open':

  (global-set-key [?\M-`] 'lacarte-execute-command)
  (global-set-key [f10]   'lacarte-execute-command)


`lacarte-execute-menu-command' uses only menu commands.
`lacarte-execute-command' lets you choose among ordinary Emacs
[[command]]s, in addition to menu commands.  You can use a [[prefix argument]]
with `lacarte-execute-command' to get the same effect as
`lacarte-execute-menu-command'.


You can use a [[prefix argument]] with `lacarte-execute-menu-command' to
have it offer only items from specific current menu-bar menus:

* No prefix arg       - all menu-bar menus
* Positive prefix arg - [[major mode|major-mode]] menu
* Zero prefix arg     - global menus
* Negative prefix arg - [[minor mode|minor-mode]] menus









[:SortingAndCycling]
== Completion Candidate Sorting and Cycling ==

If you also use library [[Sortie]] (<tt>[[sortie.el]]</tt>), or if you use [[Icicles]], then:

* You can change the ''sorting'' of completion candidates on the fly,
with '''`##C-,##'''' (by default).  Available sort orders include ##by menu
depth##, ##by menu length##, ##by last use as minibuffer input##,
##alphabetical##, and (for `lacarte-execute-command' only) ##menu
items first##.  If you use Icicles then additional sort orders are
available.

* You can ''cycle'' among matching candidates.  If you don't use
Icicles then set option `completion-cycle-threshold' to non-`nil'
to be able to cycle.  With vanilla Emacs (but not with Icicles),
cycling and showing all matching completion candidates are
mutually exclusive - `completion-cycle-threshold' controls
whether and how many candidates to cycle among.







[:FindingCommands]
== Menu Organization Can Help You Find a Command ==

Unlike commands listed in a flat `*Apropos*' page, menu items are organized, grouped logically by common area of application (`File', `Edit',...).  This grouping is also available when cycling among completion candidates (depending on the sort order).

Suppose you want to execute a command that puts the [[cursor]] at the end of a buffer, but you don't remember its name, what menu it might be a part of, or where it might appear in that (possibly complex) menu. You type `##ESC M-x##' and then type `buffer' at the prompt. Then cycle through all menu items that contain the word `buffer'. 

There are ''lots'' of such menu items. But (again, depending on the sort order)  all items from the same menu (e.g. `File') are grouped together. You cycle quickly (not reading) to the `Edit' menu, because you guess that moving the cursor has more to do with editing than with file operations, tool use, buffer choice, help, etc. Then you cycle more slowly among the `buffer' menu items in the `Edit' menu. You quickly find `<code>Edit > Go To > Goto End of Buffer</code>'.






[:CompletionMatching]
== Completion Matching ==

During completion you can match the separator of menu components,
which is the value of [[option]] '''`lacarte-menu-separator'''', and which
defaults to '''` > ''''.

As usual (with Emacs 23 or later), you can use completion styles
to control how completion candidates are matched by your
minibuffer input.

If you don't use [[Icicles]] then completion matching uses option
'''`lacarte-completion-styles'''', not standard option
`completion-styles'.  (Emacs 23 and later only.)  By default this
includes style `flex' (Emacs 27+) or `basic' (Emacs 20-26).  You
can use any list of styles you like, but some might not be so
useful.  The `initials' style, for example, is useless, because it
hardcodes a hyphen (`-') as the separator - see [[https://debbugs.gnu.org/cgi/bugreport.cgi?bug=17559|Emacs bug #17559]].

If you use Icicles then more powerful matching is available.  You
can of course just use vanilla Emacs matching, with its
`completion-styles'.  But you can also use other matching methods,
including ''[[regular-expression]]'' matching and various kinds of [[https://www.emacswiki.org/emacs/Icicles_-_Completion_Methods_and_Styles#FuzzyCompletion|fuzzy matching]].

With [[regexp]] matching (which Icicles calls [[https://www.emacswiki.org/emacs/Icicles_-_Apropos_Completions|"apropos" matching]]) you
can type pattern ##^e.+buff##, and then quickly cycle to `##Edit > Go
To > Goto End of Buffer##'.  Or type ##.*print.*buf##, to choose from
the menu commands that match `print' followed somewhere by `buf'.
And in particular, with regexp matching, you can use ##^## and ##$##
to directly match the first and last menu components,
respectively.   If you know how to use regexps, you can easily and
quickly get to a menu command you want, or at least narrow the
list of candidates for completion and cycling.

If you use Icicles you can also use [[https://www.emacswiki.org/emacs/Icicles_-_Progressive_Completion|progressive completion]], which
means matching ''multiple patterns''.  You specify the patterns
progressively, but they are matched ''in all possible orders''.  For
example, if you want a menu command that has to do with buffers
and highlighting, type `buf M-SPC hig S-TAB'.  (`M-SPC', not
`SPC', is the default key for separating match patterns, because
space characters are often part of completion candidates.)

And if you use Icicles you can prune matches not only by adding
patterns to match, but also by adding ''patterns to NOT match''.
(Icicles calls this [[https://www.emacswiki.org/emacs/Icicles_-_Nutshell_View#ChippingAway|"chipping away the non-elephant"]].)







[:MoreIciclesBenefits]
== Additional Benefits of Using Icicles with La Carte ==

* When you cycle to a candidate menu item, or you complete to one
(entirely), the Emacs ''command associated with the menu item'' is
shown in the [[mode line]] of buffer `*Completions*'.

* You can use '''`M-h'''' to complete your minibuffer input against
commands, including menu-item commands, ''that you've entered
previously''.  (You can of course also use the standard history
keys, such as `M-p' and `M-r', to access these commands.)

* You can display the ''complete documentation'' (doc string) for the
command corresponding to each menu item, as the item appears in
the minibuffer.  To do this, just cycle menu-item candidates
using '''`##C-M-<down>##'''' (instead of `##<down>##').
The documentation appears in buffer `*Help*'.







----
'''See Also:'''

* [[EmacsNewbieWithIcicles|Emacs Newbie with Icicles]] -- A good place to start.

* [[Icicles - Key Completion]] -- Navigate the [[menu bar]] menus by using '''[[Icicles]]''' to complete the `menu-bar' prefix key!


----

DrewsElispLibraries referenced here: Lisp:lacarte.el, Lisp:sortie.el, Lisp:icicles.el

CategoryCompletion CategoryMenus CategoryKeys