Add spacemacs/set-keys

[justbur]

These functions are better versions of evil-leader/set-key and
evil-leader/set-key-for-mode. The difference is the ability to specify
a prefix with a name that will automatically be declared.

Here's an illustration of how it is meant to be used, which will simultaneously declare "p" and "pp" as prefixes with names "prefix-name" and "sub-prefix-name" as well as the corresponding bindings. More string-command or string-list pairs can be used, and they can also be nested. I think this makes for a nicely structured and cleaner way to define bindings, avoiding the need to declare prefixes.

(spacemacs/set-keys
    "r" 'root-binding
    "p" '("prefix-name"
          "pb" awesome-command
          "pp" ("sub-prefix-name"
                "ppr" awesome-command-2))
    "f" 'second-root-binding)

EDIT: This post only applies to the implementation in the first commit

[justbur]

@syl20bnr I know you're busy, but I was curious what you thought of this idea

[syl20bnr]

This is a sensitive subject that requires a lot of thought, I'm sure of one thing though, the proposal here is hard to read and understand without looking at the documentation of the function. This function may be the most called function in the distribution, it has to be understandable without requiring to read the doc.
So the first direction I would give is to use keywords like :prefix, :bindings, ":use-leader", :use-major-mode-leader, or :use leader / :use major-mode-leader or :prefix leader... as I said it requires lot of thought :-)

[justbur]

I understand. I just wanted to get started on a better solution.
On Sun, Aug 30, 2015 at 8:56 PM Sylvain Benner notifications@github.com
wrote:

This is a sensitive subject that requires a lot of thought, I'm sure of
one thing though, the proposal here is hard to read and understand without
looking at the documentation of the function. This function may be the most
called function in the distribution, it has to be understandable without
requiring to read the doc.
So the first direction I would give is to use keywords like :prefix,
:bindings, ":use-leader", :use-major-mode-leader, or :use leader / :use
major-mode-leader or :prefix leader... as I said it requires lot of
thought :-)

—
Reply to this email directly or view it on GitHub
#2731 (comment).

[justbur]

Ok, this is implementation number two. I think it's pretty self-explanatory. spacemacs/set-keys now works exactly like evil-leader/set-key, but it adds optional keyword arguments that can be used to specify a major-mode, prefix, and prefix-name. The prefix is applied to the front of all of the keys. The examples below I think show what you need to know.

(defun test1 () (interactive) (message "test 1"))
(defun test2 () (interactive) (message "test 2"))
;; equivalent to evil-leader/set-key
(spacemacs/set-keys
  "[" 'test1)
;; binds "][" and "]]", and declares name of "]" prefix
(spacemacs/set-keys
  "[" 'test1
  "]" 'test2
  :prefix-keys "]"
  :prefix-name "backwards-bracket")
;; similar to the previous one, but only binds in emacs-lisp-mode
(spacemacs/set-keys
  "[" 'test1
  "]" 'test2
  :major-mode 'emacs-lisp-mode
  :prefix-keys "m["
  :prefix-name "forward-bracket")

Adding an example from the spacemacs layer

(spacemacs/set-keys
  "b" 'spacemacs/helm-buffers-smart-do-search
  "B" 'spacemacs/helm-buffers-smart-do-search-region-or-symbol
  :prefix-keys "s"
  :prefix-name "search/symbol")
(spacemacs/set-keys
  "b" 'helm-do-ag-buffers
  "B" 'spacemacs/helm-buffers-do-ag-region-or-symbol
  "a" 'helm-ag-this-file
  "A" 'spacemacs/helm-file-do-ag-region-or-symbol
  "f" 'helm-do-ag
  "F" 'spacemacs/helm-files-do-ag-region-or-symbol
  "p" 'spacemacs/helm-project-do-ag
  "P" 'spacemacs/helm-project-do-ag-region-or-symbol
  :prefix-keys "sa"
  :prefix-name "search-ag")

EDIT: the keyword arguments are allowed to come before or after the bindings.

[justbur]

@syl20bnr I'm going to unify all the stuff related to declaring prefixes in which-key and update this function to use it. Then we will have one interface to defining keys that incorporates the ability to simultaneously declare prefixes.

[syl20bnr]

I'm not sure that unifying prefix and bindings is a good thing, I'm not sure I want to hide such core emacs lisp functions. I want users to use them.

[syl20bnr]

Let use the raw emacs way to define key bindings and let just migrate the prefix stuff to which-key. I prefer them to be separated calls. This way key bindings definition are still raw compatible stock emacs and more portable.

[syl20bnr]

What I like with your which-key solution is that we don't even bother to define prefix names, that's really cool. This is all only which-key config. Since which-key is a bootstrap package it can be used anywhere.

[justbur]

Ok fair enough. Most of the key bindings are made using evil-leader and I
had the thought that eventually it might be necessary and or useful to be
able to remove that dependency and providing a Spacemacs function would
make any changes easier. But I understand the argument for keeping the
level of abstraction low.

I'll forget this function and work on migrating the prefix declarations to
which-key functions.

For the bootstrap thing does it still make sense to have the config in the
Spacemacs layer of which-key is already loaded at that point? I know the
mode has to be activated somewhere...
On Thu, Sep 3, 2015 at 11:09 AM Sylvain Benner notifications@github.com
wrote:

What I like with your which-key solution is that we don't even bother to
define prefix names, that's really cool. This is all only which-key config.
Since which-key is a bootstrap package it can be used anywhere.

—
Reply to this email directly or view it on GitHub
#2731 (comment).

[syl20bnr]

Good question, it should stay in spacemacs layer but the loading :step should be pre.

[justbur]

Closing in favor of #2876