# ExecEval (execute-keys / evaluation-commands)

**URL:** <https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539>\
**Category:** Manual++\
**Created:** [May 8, 2019, 2:15am UTC](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539 "2019-05-08T02:15:13Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![robertmeta](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/robertmeta/32/833_2.png) [@robertmeta](https://discuss.kakoune.com/u/robertmeta)\
**Post date:** [May 8, 2019, 2:15am UTC](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/1 "2019-05-08T02:15:13Z")

</div>

# Description

The **execute-keys** and **evaluate-commands** commands can be used to  
run Kakoune commands:

```
execute-keys [<switches>] <key> ...
evaluate-commands [<switches>] <command> ...

```

**execute-keys** runs keys as if they were pressed, whereas  
**evaluate-commands** evaluates its given parameters as if they were  
entered in the command prompt. By default, their execution happens  
within the context of the current client, and stops when the last  
key/command is reached, or an error is raised.

**execute-keys** also save the following registers, who are then  
restored when the commands have been executed: **/** , **"** , **|** ,  
**^** , **@**. **evaluate-commands** does not save any registers by  
default. (See [`:doc registers`](https://discuss.kakoune.com/t/registers/551/2))

# Optional switches

**-client** \<name\>  
execute in the context of the client named **name**

**-try-client** \<name\>  
execute in the context of the client named **name** if such client  
exists, or else in the current context

**-draft**  
execute in a copy of the context of the selected client. Modifications  
to the selections or input state will not affect the client. This  
permits to make some modification to the buffer without modifying the  
user’s selection

**-itersel**  
execute once per selection, in a context with only the considered  
selection. This permits avoiding cases where the selections may get  
merged

**-buffer** \<names\>  
execute in the context of each buffers in the comma separated list  
**names**. `*` as a name can be used to iterate on all non-debug buffers  
(See [`:doc buffers`](https://discuss.kakoune.com/t/buffers/536/2#debug-buffers))

**-save-regs** \<regs\>  
regs is a string of registers to be restored after execution (overwrites  
the list of registers saved by default, c.f. description)

# evaluate-commands specific switches

**-no-hooks**  
disable hook execution while executing the keys/commands (See  
[`:doc hooks`](https://discuss.kakoune.com/t/hooks/544/2#disabling-hooks))

# execute-keys specific switches

**-with-maps**  
use user key mapping in instead of built in keys (See  
[`:doc mapping`](https://discuss.kakoune.com/t/mappings/547/2))

**-with-hooks**  
the execution of keys will trigger existing hooks (See  
[`:doc hooks`](https://discuss.kakoune.com/t/hooks/544/2))

---

<div class="post-metadata">

**Author:** ![gustavo-hms](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/gustavo-hms/32/598_2.png) [@gustavo-hms](https://discuss.kakoune.com/u/gustavo-hms)\
**Post date:** [September 25, 2020, 3:06pm UTC](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/2 "2020-09-25T15:06:07Z")

</div>

Hi, @robertmeta! Could you please give me an example of using the `-draft` switch? Currently I don’t understand why it is useful. I mean, if it neither modify the buffer nor modify any register (since `execute-keys` restores the values of registers), it’s like it’s not been run at all. Certainly I’m missing something, so I’d be happy if you (or someone else in this community) could provide some examples showing me how it’s meant to be used.

---

<div class="post-metadata">

**Author:** ![tototest99](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/tototest99/32/629_2.png) [@tototest99](https://discuss.kakoune.com/u/tototest99)\
**Post date:** [September 25, 2020, 3:54pm UTC](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/3 "2020-09-25T15:54:03Z")

</div>

Given a word on a line selected, compare `exec X` and `exec -draft X`. The `draft` switch allow you for example to select something (here a line) and do whatever computation you want on this selection without touching your current selection(s) (and all val related).

---

<div class="post-metadata">

**Author:** ![alexherbo2](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/alexherbo2/32/1140_2.png) [@alexherbo2](https://discuss.kakoune.com/u/alexherbo2)\
**Post date:** [September 25, 2020, 4:44pm UTC](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/4 "2020-09-25T16:44:01Z")

</div>

You can see a Kakoune session as an Etherpad, where each client (window) is a user having a view on your pad (buffer).

Moving their cursors does not have consequence on your selection, but if they add or remove content, you will see the result, and it might have consequence on what you had selected.

A draft context is a headless client. You can open a new client with `:new` and pretend it is a draft context. Try all sort of things (move your selections, commit changes, set an option (at the global, buffer and window scope) with the result of what you selected) and see what happens and what you can access in your original client.

### Examples

[Search `-draft` in GitHub repositories](https://github.com/search?type=code&s=indexed&q=-draft+user:alexherbo2+user:Delapouite+user:occivink+user:Screwtapello)

### Control flow

```auto
try %{
  evaluate-commands -draft %{
    ...
  }
  ...
}

```

### Commit changes without changing the current mode

```auto
define-command surround-parenthesis %{
  execute-keys -draft i(
  execute-keys -draft a)
}

map global insert <a-)> '<a-;>: surround-parenthesis<ret>'

```

### Build options (highlighters and completers)

- [Intro to Kakoune highlighters](https://discuss.kakoune.com/t/intro-to-kakoune-highlighters/814)
- [Intro to Kakoune completers](https://discuss.kakoune.com/t/intro-to-kakoune-completers/1198)

---

<div class="post-metadata">

**Author:** ![gustavo-hms](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/gustavo-hms/32/598_2.png) [@gustavo-hms](https://discuss.kakoune.com/u/gustavo-hms)\
**Post date:** [September 25, 2020, 10:16pm UTC](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/5 "2020-09-25T22:16:28Z")

</div>

> [@alexherbo2](#):
>
> ```auto
> map global insert <a-)> '<a-;>: surround-parenthesis<ret>'
> 
> ```

I guess you mean

```auto
map global normal <a-)> '<a-;>: surround-parenthesis<ret>'

```

Right?

Thanks for the explanation. I mistakenly thought we couldn’t write to the buffer if we use the `-draft` switch and, as such, `evaluate-commands` and `execute-keys` wouldn’t produce any side effect.

---

<div class="post-metadata">

**Author:** ![alexherbo2](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/alexherbo2/32/1140_2.png) [@alexherbo2](https://discuss.kakoune.com/u/alexherbo2)\
**Post date:** [September 25, 2020, 10:56pm UTC](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/6 "2020-09-25T22:56:47Z")

</div>

Nope, `insert` not `normal`.

---

<div class="post-metadata">

**Author:** ![robertmeta](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/robertmeta/32/833_2.png) [@robertmeta](https://discuss.kakoune.com/u/robertmeta)\
**Post date:** [September 27, 2020, 5:42pm UTC](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/7 "2020-09-27T17:42:31Z")

</div>

Random aside: this is exactly the type of conversations I hoped Manual++ would generate, thanks for kicking it off @gustavo-hms

---

<div class="post-metadata">

**Author:** ![gustavo-hms](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/gustavo-hms/32/598_2.png) [@gustavo-hms](https://discuss.kakoune.com/u/gustavo-hms)\
**Post date:** [October 2, 2020, 7:13pm UTC](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/8 "2020-10-02T19:13:24Z")

</div>

> [@robertmeta](#):
>
> thanks for kicking it off @gustavo-hms

😉