bug: zellij: It is not clear how to configure keyboard bindings

[brianmay]

Are you following the right branch?

• My Nixpkgs and Home Manager versions are in sync

Is there an existing issue for this?

• I have searched the existing issues

Issue description

From the docs zellij keyboard bindings look like:

    // bind the Alt-n to open a new pane
    bind "Alt n" { NewPane; }
    // bind both the "h" key and the left-arrow key to move pane focus left
    bind "h" "Left" { MoveFocus "Left"; }
    // bind the "f" key to toggle the focused pane full-screen and switch to normal mode
    bind "f" { ToggleFocusFullscreen; SwitchToMode "Normal"; }

But it is far from clear what I have to set the settings to to generate this. And I can't see any documentation either.

I have seen bug #4054, but this hasn't really helped.

Maintainer CC

@mainr

System information

- system: `"x86_64-linux"`
 - host os: `Linux 6.1.61, NixOS, 23.05 (Stoat), 23.05.20231105.aeefe20`
 - multi-user?: `yes`
 - sandbox: `yes`
 - version: `nix-env (Nix) 2.13.6`
 - channels(brian): `""`
 - channels(root): `"nixos-23.05"`
 - nixpkgs: `/nix/var/nix/profiles/per-user/root/channels/nixos`

[brianmay]

After writing this I found #4160, looks like there isn't a solution yet. But when the solution is found, it should be clearly documented...

[pluiedev]

Yeah the problem here is that programs.zellij.settings was added before zellij switched from YAML to KDL, so it's actually kind of impossible to do things neatly for now

[brianmay]

Oh, that explains my confusion. I wasn't aware zellij changed formats.

[pluiedev]

Yeah they did, in version 0.32.0, although we should probably document this in the module somewhere, not just as a code comment — it can break things, and users should be aware of that

[gotcha]

I have added documentation: #4665

Feedback welcome !

[stale]

Thank you for your contribution! I marked this issue as stale due to inactivity. Please be considerate of people watching this issue and receiving notifications before commenting 'I have this issue too'. We welcome additional information that will help resolve this issue. Please read the relevant sections below before commenting.

If you are the original author of the issue

• If this is resolved, please consider closing it so that the maintainers know not to focus on this.
• If this might still be an issue, but you are not interested in promoting its resolution, please consider closing it while encouraging others to take over and reopen an issue if they care enough.
• If you know how to solve the issue, please consider submitting a Pull Request that addresses this issue.

If you are not the original author of the issue

• If you are also experiencing this issue, please add details of your situation to help with the debugging process.
• If you know how to solve the issue, please consider submitting a Pull Request that addresses this issue.

Memorandum on closing issues

Don't be afraid to manually close an issue, even if it holds valuable information. Closed issues stay in the system for people to search, read, cross-reference, or even reopen – nothing is lost! Closing obsolete issues is an important way to help maintainers focus their time and effort.

[brianmay]

I think this is still a concern. There is a proposal in #4465 to resolve, but looks like that has stalled too :-(.

[stale]

Thank you for your contribution! I marked this issue as stale due to inactivity. Please be considerate of people watching this issue and receiving notifications before commenting 'I have this issue too'. We welcome additional information that will help resolve this issue. Please read the relevant sections below before commenting.

If you are the original author of the issue

• If this is resolved, please consider closing it so that the maintainers know not to focus on this.
• If this might still be an issue, but you are not interested in promoting its resolution, please consider closing it while encouraging others to take over and reopen an issue if they care enough.
• If you know how to solve the issue, please consider submitting a Pull Request that addresses this issue.

If you are not the original author of the issue

• If you are also experiencing this issue, please add details of your situation to help with the debugging process.
• If you know how to solve the issue, please consider submitting a Pull Request that addresses this issue.

Memorandum on closing issues

Don't be afraid to manually close an issue, even if it holds valuable information. Closed issues stay in the system for people to search, read, cross-reference, or even reopen – nothing is lost! Closing obsolete issues is an important way to help maintainers focus their time and effort.

[b-m-f]

Still an issue

[stale]

Thank you for your contribution! I marked this issue as stale due to inactivity. Please be considerate of people watching this issue and receiving notifications before commenting 'I have this issue too'. We welcome additional information that will help resolve this issue. Please read the relevant sections below before commenting.

If you are the original author of the issue

• If this is resolved, please consider closing it so that the maintainers know not to focus on this.
• If this might still be an issue, but you are not interested in promoting its resolution, please consider closing it while encouraging others to take over and reopen an issue if they care enough.
• If you know how to solve the issue, please consider submitting a Pull Request that addresses this issue.

If you are not the original author of the issue

• If you are also experiencing this issue, please add details of your situation to help with the debugging process.
• If you know how to solve the issue, please consider submitting a Pull Request that addresses this issue.

Memorandum on closing issues

Don't be afraid to manually close an issue, even if it holds valuable information. Closed issues stay in the system for people to search, read, cross-reference, or even reopen – nothing is lost! Closing obsolete issues is an important way to help maintainers focus their time and effort.

[pluiedev]

Still a thing.

[Dietr1ch]

Can we get a textual extraSettings out to allow configuring things?

I guess that figuring out the best way to transform nix values into KDL configs in a more generic way is going to take a while.

---

EDIT: We have a generic conversion into KDL already,

home-manager/modules/programs/zellij.nix

Line 69 in 60bb110

text = lib.hm.generators.toKDL { } cfg.settings;

The problem seems to be how to configure things. It'd be neat to have an example that sets up a bunch of common things like theme, keybinds and plugins. I'll take a stab at it tomorrow.

---

EDIT2: From a quick look I'm missing the trailing semicolons to set up bindings and I don't see them on the test to the KDL conversion. Figuring this out and/or fixing this seems to need a dive into that commit.

  programs = {
    zellij = {
      enable = true;
      
      
      # Generates ~/.config/zellij/config.kdl
      settings = {
        # https://zellij.dev/documentation/configuration
        theme = "nord";  # https://zellij.dev/documentation/options#theme

        # https://github.com/zellij-org/zellij/blob/main/zellij-utils/assets/config/default.kdl
        keybinds = {

          locked = {
            "bind 'Ctrl h'" = {
              SwitchToMode = "Normal";
            };
          };

        };
      };  # ..programs.zellij.settings

    };  # ..programs.zellij
  };  # ..programs

keybinds {
	locked {
		bind 'Ctrl h' {
			SwitchToMode "Normal"  # <-- Missing trailing ;
		}
	}
}

[brianmay]

Have a look at the KDL spec: https://kdl.dev/

I think though the terminating semicolon may not be important. when there is only one node. Or nodes a separated by new lines.

But what is wrong, is we have to represent a list of nodes with a attrset.

{
   SwitchToMode = "Normal";
};

But it isn't a attrset...

• We don't have unique keys. SwitchToMode is not a unique key, we can repeat that numerous times.
• Order of nodes is important, but we can't preserve the order in a attrset.
• Nodes may have a name but no arguments, something we cannot represent.

An example of a valid KDL document is:

contents {
  section "First section" {
    paragraph "This is the first paragraph"
    paragraph "This is the second paragraph"
  }
}

A array for list of nodes would be better.

I suspect what is happened is that toKDL was built without referencing the KDL spec. And as a result it isn't really a good generic solution to writing KDL files.

On the positive side though, I think zellij is the only program that uses toKDL, so is the only program that we risk breaking if we try to fix this.

My feeling is we should support something like:

keybinds = {
       locked = [
            {
              name = "bind";
              args=["Ctrl h"];
              children=[{ name="SwitchToMode"; args=["Normal"]; }];
            }
          ] 
       ];
};

(apologies if there are syntax errors here...)

Not sure if children have to appear last or if they can appear anywhere in the list. I believe they have to be at the end, meaning having children separate from args makes sense.

I think this would be sufficient for zellij. It hasn't yet addressed properties, which are supported in KDL but maybe not used by zellij:

author "Alex Monad" email="alex@example.com" active=true

This can be solved with:

[
    {
       name = "author";
       args = [ "Alex Monad"];
       properties = { email="alex@example.com"; active=true; };
    }
]

Assuming order of properties is not important.

Or type annotations (I can't actually wrap my head around why you might want these):

numbers (u8)10 (i32)20 myfloat=(f32)1.5 {
  strings (uuid)"123e4567-e89b-12d3-a456-426614174000" (date)"2021-02-03" filter=(regex)r"$\d+"
  (author)person name="Alex"
}

[Dietr1ch]

I suspect what is happened is that toKDL was built without referencing the KDL spec. And as a result it isn't really a good generic solution to writing KDL files.

To be fair their websites call their https://github.com/kdl-org/kdl/blob/main/SPEC.md a living one, and while it's now at version 1.0.0 I'm guessing toKDL might precede it.

On the positive side though, I think zellij is the only program that uses toKDL, so is the only program that we risk breaking if we try to fix this.

I believe so too. KDL's FAQ asks "Why yet another document language?" and "Have you seen that one XKCD comic about standards?", but I guess that comic #927¹ wasn't strong enough to avoid having another language around that just introduces new syntax without expressiveness worth its weight (tooling, debugger, libraries, it's expensive to have your own language).

Beyond what I believe, you seem to be right too, here's a search for KDL on the repo, it only mentions the new files to handle KDL and home-manager/modules/programs/zellij.nix is the only user of all the KDL machinery.

Footnotes

1. Yes, I've seen this referenced enough that I don't need to open the link to 927 anymore. ↩