Merging `statfmt` and `rulerfmt`

[CatsDeservePets]

What is the point in having two separate settings, statfmt and rulerfmt, to customise the bottom bar that act almost identical and only real difference being the placement (while also having promptfmt which does partly support alignment).
Ideally, there would be one single setting which allows for simple alignment and supports the options of statfmt and rulerfmt.

The discussion came up in #2021 (comment) while asking myself, where the new Mode expansion should go. rulerfmt seems like the obvious choice, but it is on the right while all the Vim like applications traditionally place their mode indicator on the bottom left. In the linked comment, @joelim-work mentioned he was not against merging them.

I also want to point out what @gokcehan wrote about statfmt and lf in general, which made me sad and should be kept in mind while discussing this topic: #1347 (comment)

Related links:

• Add statfmt option #1288
• Add rulerfmt option for improved ruler customization #1386
• Remove deprecated ruler option #1766

The problems:

I am unsure, how this merge could be done without breaking backwards compatibility.
Some letters have a different meaning in both formats, so which one to keep? Which one to reassign?
Should we use one of the existing variables (rulerfmt being the obvious choice)?
Re-introducing ruler and deprecating statfmt and rulerfmt seems also quite ironic as it was depreciated in favour of rulerfmt.

While there are more topics in want to discuss relating to the statusbar (like introducing a filename flag and an alternate version of %h which returns an empty string when the hidden count is 0) I would love to get some input about the merging part first.

Below is an overview of each options capabilities:

Rulerfmt

location:

bottom right corner

Special expansions:

• %a as the pressed keys
• %c as the number of files to be copied
• %d as the amount of free disk space remaining
• %f as the filter
• %h as the number of files hidden in the current directory
• %i as the position of the cursor
• %m as the number of files to be cut (moved)
• %p as the progress of file operations
• %P as the scroll percentage
• %s as the number of selected files
• %t as the number of files shown in the current directory
• %v as the number of visually selected files

Additional expansions:

are provided for environment variables exported by lf, in the form

• %{lf_<name>} (e.g. %{lf_selmode}) environment variables exported by lf
• %{lf_user_<name>} (e.g. %{lf_user_foo}) user-defined options

Additional information:

The | character splits the format string into sections. Any section containing a failed expansion (result is a blank string) is discarded and not shown.

Statfmt

location:

bottom left corner

Special expansions:

• %c as the link count
• %g as the group
• %l as the link target
• %m as the current mode
• %M as the current mode but also shown in Normal mode (displaying NORMAL instead of a blank string)
• %p as the file permissions
• %s as the file size
• %S as the file size but with a fixed width of four characters (left-padded with spaces)
• %t as the last modified time
• %u as the user

Additional expansions:

none

Additional information:

The | character splits the format string into sections. Any section containing a failed expansion (result is a blank string) is discarded and not shown.

Conflicts:

%c, %m, %p, %s, %t

Promptfmt (for good measure and comparison)

location:

top line.(allows alignment)

Special expansions:

• %d as the working directory with a trailing path separator
• %F as the current filter
• %f as the file name
• %h as the hostname
• %S may be used once and will provide a spacer so that the following parts are right aligned on the screen
• %u as the user name
• %w as the working directory

Additional information:

The home folder is shown as ~ in the working directory expansion.
Directory names are automatically shortened to a single character starting from the leftmost parent when the prompt does not fit the screen.

[joelim-work]

So regarding merging the two options, perhaps the simplest approach that doesn't break too much compatibility is to keep statfmt as is, and just add another placeholder in rulerfmt which then expands into the statfmt. Then there should be a way to configure the left and right sides of the ruler - I'm not sure if I like the %S syntax in promptfmt, because then it will look weird when combined with the | separators (e.g. %a | %b | %c %S %d | %e | %f), though maybe %| is fine. An alternative would be to split it into two options like rulerleftfmt and rulerrightfmt.

---

On the topic of providing a method of configuring the prompt/ruler in a way that is both clean in design and flexible for users, I don't think this is an easy problem to solve. Other tools like vim and yazi embed scripting languages like Vimscript and Lua so users can literally program how they want their prompt/ruler to look like.

For instance the statusbar in yazi is implemented in Lua, and although I have not tried it I'm quite sure users can write their own version if they wish. The documentation also mentions examples of using the children_add function to add custom fields like below:

Status:children_add(function(self)
	local h = self._current.hovered
	if h and h.link_to then
		return " -> " .. tostring(h.link_to)
	else
		return ""
	end
end, 3300, Status.LEFT)

On the other hand lf doesn't embed any scripting language, so all of the logic has to be encoded in a single string, which is both limiting and can lead to configuration that is verbose and ugly. I acknowledge that the | separator syntax that I came up with is rather unconventional, but otherwise it's difficult to specify 'optional' fields that shouldn't be displayed if they are irrelevant.

I should also mention that the current syntax also doesn't allow for certain features that would otherwise be possible in scripting languages:

• Specifying field widths (e.g. truncating fields that are too long, or padding fields that are too short)
• Using different styles depending on the value of a field (e.g. display blue for NORMAL mode and yellow for VISUAL mode)
• Using multiple styles on different parts of a field (e.g. coloring the r/w/x flags differently for file permissions)
• Display different content depending on the value of a field (e.g. [empty] if the value of a string is empty)
• Specifying multiple sections, (e.g. a user might want to have a left, middle and right section).

I don't really know what can be done about this, at least not without introducing substantial changes. TBH I suspect users who consider the ability to heavily customize the statusbar as a deal-breaker won't care about this anyway since they can just use yazi instead, which is a decision I can understand.

---

EDIT: I have never touched promptfmt before. I imagine most users are satisfied with displaying just a few fields like the hostname/user/filename so there hasn't been much reason to change anything there.

[CatsDeservePets]

So regarding merging the two options, perhaps the simplest approach that doesn't break too much compatibility is to keep statfmt as is, and just add another placeholder in rulerfmt which then expands into the statfmt. Then there should be a way to configure the left and right sides of the ruler - I'm not sure if I like the %S syntax in promptfmt, because then it will look weird when combined with the | separators (e.g. %a | %b | %c %S %d | %e | %f), though maybe %| is fine. An alternative would be to split it into two options like rulerleftfmt and rulerrightfmt.

I am in favour of using a divider instead of rulerleftfmt and rulerrightfmt. This would make users probably also demand statleftfmt and statrightfmt. This seems really messy. While I am fine with using %| as a divider, it could easily create confusion with |. Why not just use %= like Vim does? This is what Vim has to say about it:

Separation point between alignment sections. Each section will
be separated by an equal number of spaces. With one %= what
comes after it will be right-aligned. With two %= there is a
middle part, with white space left and right of it.

---

I should also mention that the current syntax also doesn't allow for certain features that would otherwise be possible in scripting languages:

• Specifying field widths (e.g. truncating fields that are too long, or padding fields that are too short)
• Using different styles depending on the value of a field (e.g. display blue for NORMAL mode and yellow for VISUAL mode)
• Using multiple styles on different parts of a field (e.g. coloring the r/w/x flags differently for file permissions)
• Display different content depending on the value of a field (e.g. [empty] if the value of a string is empty)
• Specifying multiple sections, (e.g. a user might want to have a left, middle and right section).

I don't really know what can be done about this, at least not without introducing substantial changes.

Some ideas I have:

• Allow rulerfmt like env var expansion in statfmt. Now one could write set statfmt "%{lf_user_mode_color} %M" and use map/vmap to set the colour var when switching modes for example. Perhaps it could also make sense to also re-evaluate %{lf_user_<name>} vars after expansion so they can include format strings. This would allow replacing some formats with others on the fly.
• I initially thought about exposing something like nvim_eval_statusline() which takes 2 parameters: expansion (string) and format (enum, either ruler or stat (maybe also prompt, not sure if needed). In theory, this is simple. But thinking about it, how should a user get the result of the call (This is the same problem as How do I execute scripts that take a choice via stdin without needing to press <enter>? #1616 (comment)).
  There would be 2 use cases for this:
  • Injecting rulerfmt expansions into statfmt and vice versa. This could be solved with your approach:

    add another placeholder in rulerfmt which then expands into the statfmt.

  • Retrieving expanded values to modify or act upon them. Not sure how to solve this without evaluating all possible statfmt and rulerfmt values twice and storing them as an env var or introducing a new hook which is something @gokcehan was really against so we won't do this. Would it possible to call lf from inside a script and have it wait inside a loop, until a certain result env var is set by lf (only for this command)? But this also seems like a hacky solution (if even possible).

---

TBH I suspect users who consider the ability to heavily customize the statusbar as a deal-breaker won't care about this anyway since they can just use yazi instead, which is a decision I can understand.

I actually tried exactly this in the past, but it was too verbose, not really documented and complicated. One of the reason I personally prefer lf over yazi is its ease of customisation. I have to do so much work to make previews etc. behave like I want and I still feel limited. Might have to do with language constraints by Rust that require this verbosity (or skill issues on my part :D).

---

EDIT: I have never touched promptfmt before. I imagine most users are satisfied with displaying just a few fields like the hostname/user/filename so there hasn't been much reason to change anything there.

I didn't mean to imply that we need to change it. I just thought it made sense to also list it here.

[joelim-work]

I am in favour of using a divider instead of rulerleftfmt and rulerrightfmt. This would make users probably also demand statleftfmt and statrightfmt. This seems really messy. While I am fine with using %| as a divider, it could easily create confusion with |. Why not just use %= like Vim does? This is what Vim has to say about it:

Separation point between alignment sections. Each section will
be separated by an equal number of spaces. With one %= what
comes after it will be right-aligned. With two %= there is a
middle part, with white space left and right of it.

Using %= sounds better actually, I just didn't think it should be a letter like S.

• Allow rulerfmt like env var expansion in statfmt. Now one could write set statfmt "%{lf_user_mode_color} %M" and use map/vmap to set the colour var when switching modes for example. Perhaps it could also make sense to also re-evaluate %{lf_user_<name>} vars after expansion so they can include format strings. This would allow replacing some formats with others on the fly.

Preventing the escape character from being treated literally was done so that displaying settings (e.g. %{lf_promptfmt}) wouldn't mess up the UI, but I think it's fine to allow it for user-defined variables, something like below:

func formatRulerOpt(name string, val string) string {
	if strings.HasPrefix(name, "lf_user_") {
		return val
	}

	// handle escape character so it doesn't mess up the ruler
	val = strings.ReplaceAll(val, "\033", "\033[7m\\033\033[0m")

	// display name of builtin options for clarity
	return fmt.Sprintf("%s=%s", strings.TrimPrefix(name, "lf_"), val)
}

set rulerfmt "%{lf_promptfmt} | %{lf_user_color}hello world"
set user_color "\033[31m"

That being said, I'm not sure I really want to enhance the expansion syntax to allow for other features like field widths. At some point it becomes so complex that it becomes a mini programming language of its own, and even then just to provide functionality that is merely cosmetic in nature.

I actually tried exactly this in the past, but it was too verbose, not really documented and complicated. One of the reason I personally prefer lf over yazi is its ease of customisation. I have to do so much work to make previews etc. behave like I want and I still feel limited. Might have to do with language constraints by Rust that require this verbosity (or skill issues on my part :D).

Managing user configuration is actually a very difficult challenge. Make it too high-level, and users will complain that it is too limiting in terms of features. Make it too low-level and users will complain that it is too complex just to configure a basic use case. IMO it is impossible to satisfy every user, and I prefer to instead focus on at least making the internal code simple and hopefully also extendable.

This is off-topic but TBH I probably should try out yazi at some point myself, it has 3x as many stars on GitHub compared to lf, so they must be doing something right. I also recall reading somewhere (forgot which place) that the author wrote yazi because they were not satisfied with any of the currently existing alternatives, which includes lf. And I think this is a fair result - lf is stuck with historical design decisions (e.g. the lfrc configuration language is very limited and requires the shell/lf -remote even for just basic flow control), so in my eyes yazi will always be the better and more modern file manager and I don't intend to challenge that.

[CatsDeservePets]

This is off-topic but TBH I probably should try out yazi at some point myself, it has 3x as many stars on GitHub compared to lf, so they must be doing something right. I also recall reading somewhere (forgot which place) that the author wrote yazi because they were not satisfied with any of the currently existing alternatives, which includes lf. And I think this is a fair result - lf is stuck with historical design decisions (e.g. the lfrc configuration language is very limited and requires the shell/lf -remote even for just basic flow control), so in my eyes yazi will always be the better and more modern file manager and I don't intend to challenge that.

I think one big reason is Rust. People who like Rust reaally like it. This attracts lots of contributers. Its first version is almost exactly 2 years old and it has almost the same amount of commits as lf already.
It also mentions inside the readme that breaking changes are to be expected.
lf on the other hand tries to break as litte as possible. Both approaches have their advantages and disadvantages.

I also got the feeling that yazis out of the box experience is much better than lfs with image and archive preview working out of the box. But on the other hand, the last time I checked it out you needed a plugin to disable the borders and showing line numbers wasn't possible at all (which is a deal breaker for me).

To me it seems the target audience is a different one. yazi has this "it just works" approach but makes it hard to really tinker with it, while lf wants to provide you with the necessary tools and expects you to do the rest. I mean yazi offers some tools as well, but I found them not really intuitive (might be a me problem).

I personally think yazis ui is "too much" for me, I want it cleaner and simpler. After trying ranger, yazi, joshuto and vifm I always come back to lf.

[CatsDeservePets]

But let's talk about lf again :D
I was thinking about how to implement this. When having an expansion for statfmt inside rulerfmt, statfmt should already include the alignment markers otherwise I don't know how this should work at all. Then drawRuler() should set a flag to not print statfmt.
Or should there be a special syntax like lf_user_ that can expand not the full statfmt but its expansions instead?
Now thinking about this, the latter seems to be the much better option, as it allows for flexibility of placement and also doesn't require some weird checks whether to draw statfmt or not. This would also eliminate the need to implement the alignment parsing for both options.

[joelim-work]

I agree on having alignment markers (%=). My suggestion was to just use rulerfmt for defining the statusbar, and then add some placeholder (e.g. %S) which is treated just like any other regular expansion like pressed keys or cut/copied/selected files, except it is expanded into the result of evaluating statfmt (in this case statfmt shouldn't need to support alignment markers, only rulerfmt). Then for the most part you can maintain backwards compatibility, with just the default rulerfmt being changed to include %S %= at the start.

This is of course just in theory though, I haven't tried it out or anything so I'm not sure how well it will actually work.

[CatsDeservePets]

I have to think about this more. I don't want to add changes just for the sake of changing. It needs to provide a real benefit which I don't really see if you still have to set stafmt and rulerfmt but now one expands into the other.
Maybe we could introduce a new function for formatting which takes a flag whether to expand stat or ruler (and maybe prompt?) and acts accordingly (perhaps using maps internally or something like that). This would remove the need for the near identical methods for expanding. The function could also check whether statfmt is set or not, and if not use perhaps some new expansions with statfmt expansions merged (and slightly changed for duplicate, otherwise fall back to legacy behaviour.
Like I said, I need to think more about this, these are just some ideas I got.