RE: Looking for a buffer-cycling library

[Drew Adams <drew.adams@oracle.com>]

TL;DRers: Skip it, unless you care.

> >> >> I'm looking for a buffer cycling mechanism that will ignore
> >> >> any buffer not loaded from or written to a file.  Example -
> >> >> any buffer whose name begins with '*' would be "jumped over"
> >>
> >> Just my 2 cents: why not use Icicles?
> >
> > Icicles does let you "ignore any buffer not loaded from or
> > written to a file".
> >
> > To do that, just use a positive prefix arg with `icicle-buffer':
> > `M-1 C-x b'.  That limits the candidates to names of buffers
> > visiting files & directories.
> 
> Wow.  Just wow.
> 
> In fact, I was thinking about feeding Icicles a regex like
> ^[^*].  Now I can see there's no need to.
> 
> I'll put "throwing Ido out and embracing Icicles" higher on my
> priority list.
> 
> > Here is the (long) doc for command `icicle-buffer' (`C-x b' in
> > Icicle mode, by default): [...]
> 
> Incredible.

Well, the doc is not the product. ;-)  The proof of the
pudding is in the eating.  So before we get carried away,
let me just say this -

Icicles is no panacea.  I wouldn't be without it, personally,
but there are those who like it and those who do not.  Some
things are still clunky in Icicles, and there are of course
bugs.

---

Maybe the most important thing to point out here is that you
need not swallow it whole.  Here are three ways to not have
it take over your Emacs ;-):

1. Icicles will not bind top-level commands (for instance,
it will not remap `C-x b' to `icicle-buffer' when in Icicle
mode) if you customize option `icicle-top-level-key-bindings'
to set it to `nil'.

By default, in Icicle mode Icicles does remap lots of
top-level vanilla commands to Icicles (multi-)commands.
But you need not let it - it is trivial to say "Hands off
my keys!".  (It need not be an all-or-nothing choice, of
course.)

2. It *is* possible to relegate Icicles completion to
particular commands, or to exclude it from particular
commands.  That's not the Icicles way. ;-)  But it is
possible.  More on this below.

3. There are a gazillion user options, to let you tune
Icicles to get the behavior you want.  In addition,
because one completion behavior does *not* fit all
contexts, you can easily change behavior on the fly.

The latter feature is quite important, as what makes
sense for discovery and exploring help is not necessarily
the best behavior for locating a file containing something
somewhere on your giant file system.

You are in charge.  You have a better idea than Emacs what
your context is, what you can expect in terms of matching
behavior, number of candidates, etc.  Not DWIM but Do What
You Want.

Sometimes you want Icicles to take time to tell you stuff
about a completion candidate, and sometimes you don't.
Sometimes you want it to take time to automatically refresh
the set of current candidates to match your updated input,
and sometimes you prefer to tell it when to refresh (on
demand).  And so on.

Tip: `M-?' during minibuffer input tells you what you can
change on the fly, how, and what your current settings are.
This is true for any minibuffer input, not just during
completion.

---

Before coming back to #2, which is about using Icicles
only here and there, for particular commands, let me say
that it is a   * f e a t u r e *   that Icicles completion
is available everywhere.  That's the idea behind the design.

In Icicle mode, which is a global minor mode, Icicles
*redefines* standard completion functions `completing-read',
`read-file-name', `read-from-minibuffer',...

You either appreciate this or you don't. ;-)  In this
respect, Icicles differs from other completion packages
(Ido, Helm, ..., Foobar).  By default, when you turn on
Icicle mode you do bite off a big chunk of something
different from vanilla Emacs.

You can choose to forego mapping Icicles top-level
commands to standard keys.  But the standard completion
functions used everywhere in Emacs commands are usurped
by Icicles when you are in Icicle mode.

What's the difference between co-opting keys for
Icicles top-level commands (which is optional) and
co-opting lower-level functions used by the top-level
commands bound to those keys (which is not optional)?

The difference is that even though the standard
completion functions are co-opted, if you stick to the
minibuffer keys that vanilla Emacs uses (`TAB', `RET',
etc.) then there is little difference from vanilla
Emacs behavior.  Even in Icicle mode.

IOW, if you choose to keep the standard binding of
`C-x b' to `switch-to-buffer' then its completion
behavior in Icicle mode is pretty much what you get
with vanilla Emacs.

It is when you use additional minibuffer keys (e.g.,
`S-TAB') that you get Icicles completion behavior.

OK, there are a few exceptions to the vanilla-behavior
claim: `SPC', `?', and `^J' (newline) self-insert
during Icicles completion (why not?), and `down' and
`up' arrows cycle completion candidates.  But the most
important vanilla keys are respected.  (And all of the
keys are customizable.) 

In sum, if you *want* Icicles completion everywhere then
you're in luck, out of the box, as soon as you turn on
`icicle-mode'.

You don't need to write (or find) and bind new commands
that call a special completion function such as
`foobar-mode-completing-read'.  Commands that use the
standard completion functions give you Icicles completion
for free.  No configuration needed to get something like
`foobar-mode-everywhere' or `foobar-mode-ubiquitous'.
No need to say which kinds of objects you want foobar-mode
completion for.

---

But what if you don't want that?  That's #2.

As mentioned, you can turn off Icicle mode: `M-x icy-mode'.
That's the answer?  Yup.  Toggle on/off.  No big deal.

And if you want to turn Icicle mode on or off for just
certain commands or certain parts of your code then you
can use these two macros: `icicle-with-icy-mode-OFF',
`icicle-with-icy-mode-ON'.

So if you want to leave Icicle mode OFF in general,
but you want Icicles completion for your own command
`my-choose-a-foo', then do something like this:

(defun my-choose-a-foo (afoo)
  (interactive
    (list
      (icicle-with-icy-mode-ON
        (completing-read "Choose a foo: " all-foos))))
  (message "Chosen foo: `%s'" afoo))

Similarly, if you want Icicle mode ON in general, but
you want it OFF for some particular code, wrap that
code with `icicle-with-icy-mode-OFF'.

HTH.