Automatically set header (or footer) for a binding in --bind?

[pbnj]

A common use-case for --header is to document the available keybindings and their actions.

For example:

fzf \
  --reverse \
  --header-lines=1 \
  --header='CTRL-X: kill / CTRL-R: reload' \
  --bind='start:reload:ps -ef' \
  --bind='ctrl-r:reload:ps -ef' \
  --bind='ctrl-x:execute:kill -9 {2}'

For large and complex fzf scripts, keeping headers in parity with bindings & actions can become more challenging.

It would be extremely useful if FZF could automatically generate the header (or footer, more on this in "Suggestion 2" below) for these use-cases

Suggestion 1

One suggestion is to set or declare the header text of a binding in the --bind itself.

Example:

fzf \
  --reverse \
  --header-lines=1 \
  --bind='start:reload:ps -ef' \
  --bind='ctrl-r:set-header(reload)+reload(ps -ef)' \
  --bind='ctrl-x:set-header(kill)+execute(kill -9 {2})'

Equivalent to

fzf \
  --reverse \
  --header-lines=1 \
  --header='CTRL-R: reload / CTRL-X: kill' \
  --bind='start:reload:ps -ef' \
  --bind='ctrl-r:reload:ps -ef' \
  --bind='ctrl-x:execute:kill -9 {2}'

Suggestion 2

Since --header is currently used for column header use-cases (i.e. ps -ef | fzf --header-lines 1) and for binding/action documentation (i.e. --header='CTRL-R: reload') and since there are existing header actions like change-header() and transform-header() which can introduce complexity and/or conflicts, then perhaps a "footer" concept can be introduced for this feature.

Example:

fzf \
  --reverse \
  --header-lines=1 \
  --bind='start:reload:ps -ef' \
  --bind='ctrl-r:set-footer(reload)+reload(ps -ef)' \
  --bind='ctrl-x:set-footer(kill)+execute(kill -9 {2})' \
  --bind='?:toggle-footer'

Equivalent to:

fzf \
  --reverse \
  --header-lines=1 \
  --bind='start:reload:ps -ef' \
  --bind='ctrl-r:reload(ps -ef)' \
  --bind='ctrl-x:execute(kill -9 {2})' \
  --bind='?:toggle-footer' \
  --footer='CTRL-R: reload / CTRL-X: kill'

The footer approach would keep the header uncluttered by splitting the column header use-case from the binding/action documentation use-case without increasing complexity.

Thoughts?

[junegunn]

FYI,

  --bind='start:reload:ps -ef' \
  --bind='ctrl-r:reload:ps -ef' \

can be written as this since 0.59.0

  --bind='start,ctrl-r:reload:ps -ef' \

---

While automatic header generation is a tempting idea, I don't think we can easily reach consensus on how the header should look like without introducing a bunch of options.

• Should it be in multiple-lines? If so, how many lines can we use for the header?
• Should each line be aligned?
• How about the colors and text styles?
• ...

---

ctrl-r:set-header(reload)+reload(ps -ef)

Each bind expression binds actions to a key or an event. So this naturally reads "when you press CTRL-R, fzf will perform set-header and reload". So this is going to be very confusing.

---

For large and complex fzf scripts, keeping headers in parity with bindings & actions can become more challenging.

I believe such a script can define and use its own API to incrementally generate options (think of the builder pattern).

# Pseudo-code

ob = OptionBuilder()
ob.bind(key: 'ctrl-x', label: 'do something', actions: [...])
ob.bind(key: 'ctrl-y', label: 'do something else', actions: [...])
...

ob.build() {
  return "--bind ${ob.bindings} --header #{ob.header} #{ob.rest}"
}

---

keep the header uncluttered

--header-lines-border should help in this case.
See https://junegunn.github.io/fzf/releases/0.59.0/#secondary-border-for-the-header-lines