xplr v0.10 ditched yaml and goes the Neovim way with its own "init.lua"

[sayanarijit]

Taking inspiration from Neovim, xplr v0.10 has embraced embedded luajit to enable better hackability.

But why Lua?

Portability & distribution

With only bash and YAML, we are limited to what interpreters, vms or shells are installed in the users system.

For e.g. we can't write a hack that executes a Python script and claim that it will work the same on any machine. Some system doesn't even come with bash installed. Or even if installed, we still need to worry about the version.

Lua on the other hand, can be shipped with xplr natively, because it's really tiny. That means, we can write a lua script and claim that it should work fine on any system. Even if there's no lua installed.

This lets us distribute our customizations for other users to use via a plugin system.

Safety

Writing a safe bash script is really difficult. We need to escape or quote file paths properly, deal with unset and empty variables, handle errors and returncodes properly. A simple whitespace or special character in a filename can do devastating damage to our important files. With embedded lua, we can expose many utility functions that helps overcome these safety pitfalls.

Scriptability

With only bash and YAML, we are also limited to what's being exposed via the output pipes. Exposing the whole app state via pipes will be really inefficient. Although, it's possible to dump the app state as yaml, we still need yq to parse it which is again a portability issue. With lua, we get the whole app state passed as input. We also get inputs passed by the user when executing the plugin (think lua require'foo'.do_something(input=bar) in neovim). Also, we can avoid exporting global variables e.g. $OPENER and define it in the plugin config (think lua require'foo'.setup(config=bar)).

Speed

Speed will be a bonus since we won't need to read files or write to pipe files. The input and returned outputs will be converted directly by the binding logic. Also, we can surely expect lua scripts to execute faster than bash scripts.

Community

Ever since neovim started embedding Lua, there's been an explosion of plugins from the community. With embedded Lua support, xplr can become part of this awesome ecosystem too.

Neovim reasoning

For further reasoning, read the Neovim explaination: https://github.com/neovim/neovim/wiki/FAQ#why-embed-lua-instead-of-x

How to migrate

See https://github.com/sayanarijit/xplr/wiki/Upgrade-Guide#v091---v0101

API documentation

https://github.com/sayanarijit/xplr/wiki/Lua-API

NOTE: Some documentations are yet to be ported to Lua. Contributions are welcome. See https://github.com/sayanarijit/xplr/issues.

[maximbaz]

This is awesome!

I've upgraded xplr on Arch and thus am migrating my config to Lua now, right off the bat the following observations:

1. Broken symlinks break xplr again 😁

2. We fixed this additional space at some point via handlebars, I guess it's either the bug resurfaced, or we need a similar fix in lua? I haven't had a look yet to be honest, thought to report in case you maybe can immediately nail it down.

This is when I'm disabling all icons like so:

xplr.config.node_types.directory.meta.icon = ''
xplr.config.node_types.file.meta.icon = ''
xplr.config.node_types.symlink.meta.icon = ''

3. Love the idea that keys remapping is easy as this:

key = xplr.config.modes.builtin.default.key_bindings.on_key
key.a = key['ctrl-a']
key['ctrl-a'] = nil

However there are two annoying things which I think we could easily fix with one change: there is still a notion of "remaps" in xplr, I suggest we get rid of it entirely.

Example one: search is bound to / and ctrl-f, I want to remove ctrl-f and only keep /. Simply setting key['ctrl-f'] = nil will remove both shortcuts, so I have to do this instead:

key['/'] = key['ctrl-f']
key['ctrl-f'] = nil

Similarly, next visited path is bound both to ctrl-i and tab by default, if I want to free up tab with key['tab'] = nil (with the definition of key above) it won't work, I have to remove it from .remaps, instead of from .on_key, like so:

key = xplr.config.modes.builtin.default.key_bindings.remaps
key['tab'] = nil

I'll go back now to continue migrating my config, and will let you know if I spot more things 😉

[sayanarijit]

1. Broken symlinks break xplr again grin

Fixed in https://github.com/sayanarijit/xplr/releases/tag/v0.10.2

1. [We fixed](https://github.com/sayanarijit/xplr/pull/79) this additional space at some point via handlebars, I guess it's either the bug resurfaced, or we need a similar fix in lua? I haven't had a look yet to be honest, thought to report in case you maybe can immediately nail it down.

Sorry, I got too excited to test it 😅

This is when I'm disabling all icons like so:

xplr.config.node_types.directory.meta.icon = ''
xplr.config.node_types.file.meta.icon = ''
xplr.config.node_types.symlink.meta.icon = ''

Icons can now be disabled by xplr.config.node_types.directory.meta.icon = nil, due to one of the Lua weirdness where setting values to nil deletes the whole map entry.

1. Love the idea that keys remapping is easy as this:

key = xplr.config.modes.builtin.default.key_bindings.on_key
key.a = key['ctrl-a']
key['ctrl-a'] = nil

However there are two annoying things which I think we could easily fix with one change: there is still a notion of "remaps" in xplr, I suggest we get rid of it entirely.

Example one: search is bound to / and ctrl-f, I want to remove ctrl-f and only keep /. Simply setting key['ctrl-f'] = nil will remove both shortcuts, so I have to do this instead:

key['/'] = key['ctrl-f']
key['ctrl-f'] = nil

Agree. I added remap primarily to avoid redundant help menu lines, i.e. when you want two keys to do the same job, but only want to see one entry in the help menu (one primary others as aliases). But it seems to be causing more confusion than solving problems.

Similarly, next visited path is bound both to ctrl-i and tab by default, if I want to free up tab with key['tab'] = nil (with the definition of key above) it won't work, I have to remove it from .remaps, instead of from .on_key, like so:

key = xplr.config.modes.builtin.default.key_bindings.remaps
key['tab'] = nil

I'll go back now to continue migrating my config, and will let you know if I spot more things wink

I explicitly added the remap to make it visible and obvious in the help menu so that when trying to map ctrl-i and tab to different actions, people don't get surprising behavior when they map to the same action. But if we remove remap altogether, we won't need it anymore (although, users will have to figure out the tab - ctrl-i story themselves).

[maximbaz]

I'm done! It was overall good experience.

Loved the trick that I can make shortvar = some.very.long.variable.path and then use shortvar everywhere, I think it makes config really clean. If you know more such lua tricks, please tell me! 😁

To add to the feedback above:

1. Another bug due to having notion of remaps:

key = xplr.config.modes.builtin.search.key_bindings.on_key
key['ctrl-p'] = key['tab']
key['tab'] = key.right

This alone does not remap ctrl-p consistently, I had to scratch my head to realize that I must also add this:

xplr.config.modes.builtin.search.key_bindings.remaps['ctrl-p'] = nil

2. If we can get rid of remaps, it would be nice, but after that maybe we could simply group entries somehow, if we can detect that multiple keys are assigned to the same object? I.e. in the example above:

I guess this matches your thoughts, you do want to avoid redundant help lines, I agree with this, just thinking we could maybe solve this internally, without exposing this "remap" to users.

3. This is maybe not an issue, but I realized that PopMode is not done on mappings in default mode, so if I want to remap gk -> gg and gj -> G, I can't do this:

key = xplr.config.modes.builtin.go_to.key_bindings.on_key
key.k = key.g
key.j = xplr.config.modes.builtin.default.key_bindings.on_key.G

I have to do this:

key = xplr.config.modes.builtin.go_to.key_bindings.on_key
key.k = key.g
key.j = {
  help = "go to bottom",
  messages = {
    "FocusLast",
    "PopMode"
  }
}

Not sure if you want to add PopMode to default mode bindings for easier remap?

Icons can now be disabled by xplr.config.node_types.directory.meta.icon = nil, due to one of the Lua weirdness where setting values to nil deletes the whole map entry.

Ah it's probably just an extra space here!

xplr/src/init.lua

Lines 2021 to 2022 in 91838f8

	if m.meta.icon == nil then
	r = r .. " "

[sayanarijit]

If you know more such lua tricks, please tell me!

I'm learning Lua myself. I think this is a good resource, although, I haven't fully gone through it yet. Furthermore, I'm yet to convert my init.vim to init.lua.

As for the PopMode, I agree it should be in the default mode too.

[sayanarijit]

Wrote a basic documentation of the Lua API here: https://github.com/sayanarijit/xplr/wiki/Lua-API

[maximbaz]

By the way, after you introduced me to Lua I started seeing it everywhere, in all different projects 😂 So I can only say this, nice pick!

[nfrid]

is there a way to get lsp integration like including libs? it would be great to have some sort of code completion or/and api documentation built in an editor

[sayanarijit]

As of now there's no lsp integration. But I'm open to ideas on how to implement it.