Corkey grammar question

[theophilusx]

I just noticed the following in the corky-keys.el file and I'm not sure I really understand what is going on.

("," "Project specific leader key"
  ...
   ("l" "Link to REPL"
    ("p" "Link with project" :link-repl/project sesman-link-with-project)
    ("b" "Link with buffer" :link-repl/buffer sesman-link-with-buffer)
    ("d" "Link with directory" :link-repl/directory sesman-link-with-directory)
    ("l" "Link least specific" :link-repl/least-specific sesman-link-with-least-specific)
    ("u" "Unlink" :link-repl/unlink sesman-unlink))
  ...
)

and in the corgi-signals.el file we have

:link-repl/project sesman-link-with-project
:link-repl/buffer sesman-link-with-buffer
:link-repl/directory sesman-link-with-directory
:link-repl/least-specific sesman-link-with-least-specific
:link-repl/unlink sesman-unlink

under the cider-mode section. My questions are

• What does the construct ":link-repl/project sesman-link-with-project" do i.e. is sesman-link-with-project an argument for the :link-repl/project signal?
• This is a cider specific signal, but is defined in the corgi-keys.el file with the ',' prefix and no (obvious) linking to cider mode at that level. How does this work with other modes when it has such a mode specific definition in the keys file?

Finally, I also noticed the following definition at the end of the corgi-signals.el file

(dired-mode (:toggle/read-only wdired-change-to-wdired-mode))
 (wdired-mode (:toggle/read-only wdired-finish-edit))

Are these correct? They look like definitions to move in/out of wdired mode rather than doing read-only (not really sure what read-only means in a dired context). Is this simply to make :toggle/read-only 'mean' something in dired mode?

[plexus]

I think there's some confusion here about what signals are exactly, and what the point is of corkey.

Signals are a corkey-specific concept. They're a level of indirection, in this case instead of saying in the keys file: ", l p is bound to sesman-link-with-project", we say "what , l p does conceptually is link to a repl on the project level (:link-repl/project). This is just a symbol that we pick. Then in the bindings file we say: "when in cider-mode, to link to a repl on the project level is done with sesman-link-with-project".

This achieves two things, it means that we can have a mnemonic like SPC t w (toggle writable), or , e e (eval) which "just works", no matter which mode you're in. So in most buffers it'll toggle read-only-mode, but in dired buffers it toggles wdired-mode, because that's what making a dired buffer writable means. So you get consistency, you have to memorize fewer distinct bindings, your knowledge transfers.

The second thing this achieves is being able to rebind keys, e.g. maybe I want to use M-RET to eval, so I can add that to my user-keys file, and this binding will now be able to eval forms in any language we support. Depending on the mode it could be calling eval-last-sexp, cider-eval-last-sexp, geiser-eval-last-sexp, and so forth.

To really understand the motivation you can look at Spacemacs. Spacemacs tries to achieve a certain degree of consistency in key bindings, but they do this by adding and maintaining separate bindings for each mode. The result is that they're all slightly different and drifting apart, and if you want to use a different key for something you need to add bindings in your own config for every single mode where you want to use it.

The idea has also always been that this allows providing completely new keys files, e.g. you could create a keys file with Calva style mappings. Say that in that keys file it says ("C-f" :buffer/incremental-search), and in your user-signals file you have (:buffer/incremental-search <some-fancy-search-package>), now you can install that calva-style keys file, and still get your preferred commands.

[theophilusx]

Maybe I'm being a bit slow and am missing some of the subtitles or perhaps I'm just not being clear/concise, but what you wrote seems to mirror what I think my understanding of corkey is.

My main uncertainty was with definitions like

("p" "Link with project" :link-repl/project sesman-link-with-project)

in the corgi-keys.el file and

:link-repl/project sesman-link-with-project

in the corgi-signals.el file. I would have expected the corgi-keys.el file to just have

("p" "Link with project" :link-repl/project) The grammar explanation also seems to say that a target is either a signal or a command and that a signal is a keyword. The definition in the corgi-keys.el file seems to be a keyword and a command?

[plexus]

Oh sorry I missed that part. That's definitely a mistake, the keys file in this case should only contain the signal keyword.

[theophilusx]

OK, thanks that clarifies things for me. I'll focus on my clojure project for the next few days until the chrun from the move to emacs-corgi settles down (it was getting my clojure dev setup tweaked which brought me to corgi in the first place, so I need to make sure I'm not getting distracted from the main goal :smile: ).