Using Go templates to customize the ruler

[joelim-work]

From discussion in #2057

Currently the ruler at the bottom can be customized using the statfmt and rulerfmt options. While these options contain some level of flexibility, there are still some limitations when it comes to customization:

• Placeholders were substituted as-is, and there was no way to manipulate the result of the substitution. For example there was no way to display an alternate text if a placeholder expanded to an empty string.
• Colors/styles could only be applied on the result of an entire expansion, and it wasn't possible to color/style part of an expansion.
• There was no support for specifying field widths, (e.g. pad with spaces).
• The statfmt could not be drawn on the right side of the screen, and similarly rulerfmt components could not be drawn on the left side of the screen.

The PR #2083 changes this to use Go templates instead to provide greater flexibility for customization, with the syntax being closer to a programming language instead of a format string. The tradeoff for the extra customizability is that the configuration is now more complex, which increases the barrier of entry for users.

---

To illustrate the history of the ruler configation:

1. Originally the ruler was fixed and there was no opportunity for users to customize its appearance
2. Then the ruler option was added in Customizable statusline, df #1168, which allowed users to choose which fields to display and in which order:

   set ruler 'acc:progress:selection:ind'

3. Then it was replaced with rulerfmt in Add rulerfmt option for improved ruler customization #1386 to allow for custom formatting:

   set rulerfmt "%a|  %p|  \033[7;31m %m \033[0m|  \033[7;33m %c \033[0m|  \033[7;35m %s \033[0m|  \033[7;34m %f \033[0m|  %i/%t"

4. And with the new changes, the ruler file will look like this:

   {{with .Message -}}
       {{. -}}
   {{else with .Stat -}}
       {{.Permissions | printf "\033[36m%s\033[0m" -}}
       {{with .LinkCount}} {{.}}{{end -}}
       {{with .User}} {{.}}{{end -}}
       {{with .Group}} {{.}}{{end -}}
       {{.Size | humanize | printf " %5s" -}}
       {{.ModTime | printf " %s" -}}
       {{with .Target}} -> {{.}}{{end -}}
   {{end -}}
   {{.SPACER -}}
   {{with .Keys}}  {{.}}{{end -}}
   {{with .Progress}}  {{join . " "}}{{end -}}
   {{with .Copy}}  {{len . | printf "\033[7;33m %d \033[0m"}}{{end -}}
   {{with .Cut}}  {{len . | printf "\033[7;31m %d \033[0m"}}{{end -}}
   {{with .Select}}  {{len . | printf "\033[7;35m %d \033[0m"}}{{end -}}
   {{with .Visual}}  {{len . | printf "\033[7;36m %d \033[0m"}}{{end -}}
   {{with .Filter}}  {{join . " " | printf "\033[7;34m %s \033[0m"}}{{end -}}
   {{printf "  %d/%d" .Index .Total}}

Each step allows for greater flexibility in customization, but at the same time results in more complex syntax.

---

Another suggestion would be to use a scripting language like Lua for handling the configuration, but then that requires using some 3rd party library (as opposed to the standard library), and the implementation would be even more complex as the API has to bridge between Lua and Go. I am probably not interested in taking things that far.

Anyway this is an idea that I want to suggest, hopefully it is not too confusing for users.

[CatsDeservePets]

Each step allows for greater flexibility in customization, but at the same time results in more complex syntax.

That is always the trade-off. I'd say we could add some example configurations to the wiki and mention that inside the built-in documentation.

Another suggestion would be to use a scripting language like Lua for handling the configuration, but then that requires using some 3rd party library (as opposed to the standard library), and the implementation would be even more complex as the API has to bridge between Lua and Go. I am probably not interested in taking things that far.

This seems overblown just to have more status-bar customisation.

[joelim-work]

I agree with adding a section in the wiki for this.

There are some disadvantages I forgot to mention though:

• As the configuration complexity increases with each step, the number of users who will actually use it will decrease as it requires the user to:
  • Be willing to invest time and effort to learn how the configuration syntax works
  • Actually have such specific requirements in the first place
• The size of the lf binary does increase (about 5.6MiB to 6.9MiB on my system). This doesn't matter for most users (and yazi is even bigger still), but I guess there are users out there that have to deal with slow connections, like File size of `lf` executable increased #1836

Overall I think I am personally in favor of this change, but my opinion is biased since I see it as an opportunity to throw away the hacky | syntax I invented. Though I would like to get some more interest from other users first before committing to this kind of large change.

[CatsDeservePets]

Though I would like to get some more interest from other users first before committing to this kind of large change.

I was thinking the same. I am asking myself: Do people care that little about this feature? Or is it just because lfs discussions are not that active in general.

[joelim-work]

I think it's because most people interested in new features (or just 'new' in general) have moved onto yazi 😂

TBH I feel that most of the key features of a terminal file manager are already implemented in lf (though recent contributions like custom info and Visual mode from you are nice additions), and in a lot of cases adding a new feature won't garner enough interest for it to be worth the complexity. The last time I accepted a sizeable feature was the locale setting in #1818, and ever since I have regretted it because it could have probably just been implemented using a combination of on-load, addcustominfo and LC_COLLATE=... sort, but I also felt that reverting it just to satisfy my minimalistic vision of lf would be selfish on my part.

Anyway apologies for the off-topic rant, but this is why most changes I make are bug fixes, cleanups, and filling in missing gaps in functionality that users would otherwise expect to be there already.

[CatsDeservePets]

The lack of Visual mode and git indicators were the only 2 things I really missed.
Looking back I am actually kinda surprised that Visual mode got merged considering how complex it was.
I was also not prepared how useful the combination of on-load and addcustominfo could be in terms of sorting, which is nice.

While I still would have liked to see my PR about file indicators to get merged (I still have it in a custom branch) I also think that having people like you might be the best thing in the long-term. If every little (and big) feature would get merged, the source code would be hardly maintainable after some time. You are basically holding this project together at this point, what I do appreciate.

[mikeri]

I think this sounds like a really cool idea, but if we go this route, why not go all the way and drop the ruler/stats/prompt wording and instead use templates for the top and bottom bars? That would feel more consistent and allow fuller customization.

[joelim-work]

The top bar is handled by promptfmt, but I think users don't have so many requirements (usually just display the filename) for that, so there isn't as much motivation to change anything there.

[mikeri]

There is also the point about consistency. I feel it will not make much sense to have two different ways of customizing the bars. Especially for new users; to use go template for the bottom bar, but the easy but somewhat esoteric pipe based syntax for the top bar. Admittedly I have not checked the code so can't really speak on it, but I would imagine that in the long run it would also lessen the maintenance burden to have one common "bar customization" framework.

[andis-sprinkis]

Will the per-client shell output be possible in the new ruler templates?

I currently have a set-rulerfmt script (called in on-select, on-init) that prints the /dev/mapper path of the mount point device using mountpoint.

#!/usr/bin/env sh
set -eu

rulerfmt="%a| %p| \033[7;31m %m \033[0m| \033[7;33m %c \033[0m| \033[7;35m %s \033[0m| \033[7;34m %f \033[0m| %i/%t %P"

mnt_str=""

if [ -d "$f" ] && mountpoint -q -- "$f" 1>/dev/null 2>/dev/null; then
  dev="$(set +e; grep " ${f} " "/proc/mounts" | cut -d" " -f1; set -e)"

  if [ "$dev" ]; then
    mnt_str="\033[0;90m${dev}\033[0m| "
  fi
fi

rulerfmt_updated="${mnt_str}${rulerfmt}"

if [ "$lf_rulerfmt" != "$rulerfmt_updated" ]; then
  lf -remote "send ${id} set rulerfmt \"${rulerfmt_updated}\""
fi

[CatsDeservePets]

You can use user_{option} inside the ruler.

I use this to display the current git branch inside my ruler:

cmd on-cd &{{
	lf -remote "send $id tty-write \"\033]0;${PWD/#$HOME/~}\007\""

	ref=""
	if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
		ref=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
		if [ "$ref" = "HEAD" ]; then
			ref=$(git rev-parse --short HEAD 2>/dev/null)
		fi
	fi
	lf -remote "send $id :set user_ref '$ref'"

}}

Inside my ruler, I have this:

{{with $.UserOptions.ref}} {{printf "(%s)" .}}{{end -}}

[andis-sprinkis]

Thank you, that answers my question. The per client user_ options should make it viable.