# Custom Commands

A custom command lets you join several *Lx* actions into one useful action of your own.

You write what it does as a small Lua function. You can then run it from the command palette, give it a keyboard shortcut, or call it from another command.

## Make a Copy All command

This example selects the whole document and copies it.

Open the command palette and run `core:edit-user-settings`. Add this to the file:

```lua
local command = require("core.command")
local keymap = require("core.keymap")

command.register {
	["user:copy-all"] = function()
		if not command.perform("doc:select-all") then
			return false
		end

		return command.perform("doc:copy")
	end,
}

keymap.bind {
	text_editor = {
		["ctrl+shift+c"] = "user:copy-all",
	},
}
```

Save the settings file when you are done. *Lx* reloads it for you.

Now Ctrl+Shift+C selects everything and copies it. You can also run `user:copy-all` from the command palette.

## How it works

`command.register` gives your new action a name:

```lua
"user:copy-all"
```

The `user:` part makes it easy to recognize as one of your own commands. The part after it can be any short, clear name.

### Simple function

The simplest version runs both actions without checking or returning their results:

```lua
function()
	command.perform("doc:select-all")
	command.perform("doc:copy")
end
```

This version is easy to read. It still attempts Copy when Select All cannot handle the request. Because it has no `return`, *Lx* treats the custom command as handled.

### Check each result

The complete example at the top uses the checked version. It stops when Select All cannot handle the request. Copy runs only after Select All succeeds.

`command.perform` returns `true` when an action handles the request. It returns `false` when the action is unavailable or chooses not to handle it.

The checked function returns `false` when Select All fails. Otherwise, it returns Copy's result. Returning the result tells *Lx* whether the complete custom command handled the request.

A command function counts as handled unless it returns exactly `false`. Leaving out `return` therefore counts as handled, but returning a result explicitly makes a multi-step command much clearer.

`keymap.bind` gives the finished command a shortcut:

```lua
["ctrl+shift+c"] = "user:copy-all"
```

Use the `text_editor` group because selecting and copying text only makes sense in an editable document.

## Change an existing custom command

Edit its function and save your settings again. Registering the same name replaces the old version.

You do not need to remove the old command first.

## Running actions versus trying fallbacks

A custom function decides which actions run and whether to stop after a failure.

A list inside a shortcut has a different purpose:

```lua
["alt+up"] = {
	"autocomplete:previous",
	"doc:outline-previous",
}
```

That list tries the first action. It tries the second action only when the first one cannot handle the key.

Use a custom command when you want every listed action to run. Use a shortcut list when you want fallback choices.

## Finding command names

Open the command palette and search for the action you want. Command names use a group and an action joined by `:`, such as:

```text
doc:copy
doc:save
doc:duplicate-lines
core:edit-user-settings
```

See [Keyboard Shortcuts](keymap.md) for more key names and binding choices.
