Document all the messages for human

docs/en/src/message.md

@@ -2,13 +2,9 @@ Message
 =======
 
 You can think of xplr as a server. Just like web servers listen to HTTP
-requests, xplr listens to messages.
+requests, xplr listens to [messages](full-list-of-messages).
 
-See the
-[**full list of messages**](https://docs.rs/xplr/latest/xplr/app/enum.ExternalMsg.html#variants)
-that xplr can handle.
-
-You can send messages to an xplr session in the following ways:
+You can send these messages to an xplr session in the following ways:
 
 - Via [key bindings](modes.md#key-bindings)
 - Via [Lua function calls](#lua-function-calls)
@@ -35,6 +31,684 @@ represented using
 - Call: { command: bash, args: ["-c", "read -p test"] }
 
 
+Full List of Messages
+---------------------
+
+### "ExplorePwd"
+
+YAML: `ExplorePwd`
+
+Explore the present working directory and register the filtered nodes.
+This operation is expensive. So, try to avoid using it too often.
+
+### "ExplorePwdAsync"
+
+YAML: `ExplorePwdAsync`
+
+Explore the present working directory and register the filtered nodes asynchronously.
+This operation happens asynchronously. That means, the xplr directory buffers won't be updated
+immediately. Hence, it needs to be used with care and probably with special checks in place.
+To explore `$PWD` synchronously, use `ExplorePwd` instead.
+
+### "ExploreParentsAsync"
+
+YAML: `ExploreParentsAsync`
+
+Explore the present working directory along with its parents and register the filtered nodes.
+This operation happens asynchronously. That means, the xplr directory buffers won't be updated
+immediately. Hence, it needs to be used with care and probably with special checks in place.
+To explore just the `$PWD` synchronously, use `ExplorePwd` instead.
+
+### "Refresh"
+
+YAML: `Refresh`
+
+Refresh the UI.
+But it will not re-explore the directory if the working directory is the same.
+If there is some change in the working directory and you want to re-explore it,
+use the `Explore` message instead.
+Also, it will not clear the screen. Use `ClearScreen` for that.
+
+### "ClearScreen"
+
+YAML: `ClearScreen`
+
+Clears the screen.
+
+### "FocusNext"
+
+YAML: `FocusNext`
+
+Focus next node.
+
+### : { FocusNextByRelativeIndex = int }
+
+YAML: `FocusNextByRelativeIndex: int`
+
+Focus on the `n`th node relative to the current focus where `n` is a given value.
+
+**YAML Example:** `FocusNextByRelativeIndex: 2`
+**Lua Example:** `{ FocusNextByRelativeIndex = 2 }`
+
+### "FocusNextByRelativeIndexFromInput"
+
+YAML: `FocusNextByRelativeIndexFromInput`
+
+Focus on the `n`th node relative to the current focus where `n` is read from
+the input buffer.
+
+### "FocusPrevious"
+
+YAML: `FocusPrevious`
+
+Focus on the previous item.
+
+### { FocusPreviousByRelativeIndex = int }
+
+YAML: `FocusPreviousByRelativeIndex: int`
+
+Focus on the `-n`th node relative to the current focus where `n` is a given value.
+
+**YAML Example:** `FocusPreviousByRelativeIndex: 2`
+**Lua Example:** `{ FocusPreviousByRelativeIndex = 2 }`
+
+### "FocusPreviousByRelativeIndexFromInput"
+
+YAML: `FocusPreviousByRelativeIndexFromInput`
+
+Focus on the `-n`th node relative to the current focus where `n` is read from
+the input buffer.
+
+### "FocusFirst"
+
+YAML: `FocusFirst`
+
+Focus on the first node.
+
+### "FocusLast"
+
+YAML: `FocusLast`
+
+Focus on the last node.
+
+### { FocusPath = "string" }
+
+YAML: `FocusPath: string`
+
+Focus on the given path.
+
+**YAML Example:** `FocusPath: /path/to/file`
+**Lua Example:** `{ FocusPath = "/path/to/file" }`
+
+### "FocusPathFromInput"
+
+YAML: `FocusPathFromInput`
+
+Focus on the path read from input buffer.
+
+### { FocusByIndex = int }
+
+YAML: `FocusByIndex: int`
+
+Focus on the absolute `n`th node where `n` is a given value.
+
+**YAML Example:** `FocusByIndex: 2`
+**Lua Example:** `{ FocusByIndex = 2 }`
+
+### "FocusByIndexFromInput"
+
+YAML: `FocusByIndexFromInput`
+
+Focus on the absolute `n`th node where `n` is read from the input buffer.
+
+### { FocusByFileName = "string" }
+
+YAML: `FocusByFileName: string`
+
+Focus on the file by name from the present working directory.
+
+**YAML Example:** `FocusByFileName: filename.ext`
+**Lua Example:** `{ FocusByFileName = "filename.ext" }`
+
+### { ChangeDirectory = "string" }
+
+YAML: `ChangeDirectory: string`
+
+Change the present working directory ($PWD)
+
+**YAML Example:** `ChangeDirectory: /path/to/directory`
+**Lua Example:** `{ ChangeDirectory = "/path/to/directory" }`
+
+### "Enter"
+
+YAML: `Enter`
+
+Enter into the currently focused path if it's a directory.
+
+### "Back"
+
+YAML: `Back`
+
+Go back to the parent directory.
+
+### "LastVisitedPath"
+
+YAML: `LastVisitedPath`
+
+Go to the last path visited.
+
+### "NextVisitedPath"
+
+YAML: `NextVisitedPath`
+
+Go to the next path visited.
+
+### "FollowSymlink"
+
+YAML: `FollowSymlink`
+
+Follow the symlink under focus to its actual location.
+
+### { BufferInput = "string" }
+
+YAML: `BufferInput(String)`
+
+Append/buffer the given string into the input buffer.
+
+**YAML Example:** `BufferInput: foo`
+**Lua Example:** `{ BufferInput = "foo" }`
+
+### "BufferInputFromKey"
+
+YAML: `BufferInputFromKey`
+
+Append/buffer the characted read from a keyboard input into the
+input buffer.
+
+### { SetInputBuffer = "string" }
+
+YAML: `SetInputBuffer: string`
+
+Set/rewrite the input buffer with the given string.
+When the input buffer is not-null (even if empty string)
+it will show in the UI.
+
+**YAML Example:** `SetInputBuffer: foo`
+**Lua Example:** `{ SetInputBuffer = "foo" }`
+
+### "RemoveInputBufferLastCharacter"
+
+YAML: `RemoveInputBufferLastCharacter`
+
+Remove input buffer's last character.
+
+### "RemoveInputBufferLastWord"
+
+YAML: `RemoveInputBufferLastWord`
+
+Remove input buffer's last word.
+
+### "ResetInputBuffer"
+
+YAML: `ResetInputBuffer`
+
+Reset the input buffer back to null. It will not show in the UI.
+
+### { SwitchMode = "string" }
+
+YAML: `SwitchMode: string`
+
+Switch input [mode](modes.md).
+
+> **NOTE:** To be specific about which mode to switch to, use `SwitchModeBuiltin` or
+`SwitchModeCustom` instead.
+
+**YAML Example:** `SwitchMode: default`
+**Lua Example:** `{ SwitchMode = "default" }`
+
+### { SwitchModeBuiltin = "string" }
+
+YAML: `SwitchModeBuiltin: string`
+
+Switch to a [builtin mode](modes.md#builtin).
+
+**YAML Example:** `SwitchModeBuiltin: default`
+**Lua Example:** `{ SwitchModeBuiltin = "default" }`
+
+### { SwitchModeCustom = "string" }
+
+YAML: `SwitchModeCustom: string`
+
+Switch to a [custom mode](modes.md#custom).
+
+**YAML Example:** `SwitchModeCustom: my_custom_mode`
+**Lua Example:** `{ SwitchModeCustom = "my_custom_mode" }`
+
+### "PopMode"
+
+YAML: `PopMode`
+
+Pop the last mode from the history and switch to it.
+
+### { SwitchLayout = "string" }
+
+YAML: `SwitchLayout: string`
+
+Switch [layout](layouts.md).
+
+> **NOTE:** To be specific about which layout to switch to, use `SwitchLayoutBuiltin` or
+`SwitchLayoutCustom` instead.
+
+**YAML Example:** `SwitchLayout: default`
+**Lua Example:** `{ SwitchLayout = "default" }`
+
+### { SwitchLayoutBuiltin = "string" }
+
+YAML: `SwitchLayoutBuiltin: string`
+
+Switch to a [builtin layout](layouts.md#builtin).
+
+**YAML Example:** `SwitchLayoutBuiltin: default`
+**Lua Example:** `{ SwitchLayoutBuiltin = "default" }`
+
+### { SwitchLayoutCustom = "string" }
+
+YAML: `SwitchLayoutCustom: string`
+
+Switch to a [custom layout](layouts.md#custom).
+
+**YAML Example:** `SwitchLayoutCustom: my_custom_layout`
+**Lua Example:** `{ SwitchLayoutCustom = "my_custom_layout" }`
+
+### { Call = "string" }
+
+YAML: `Call: string`
+
+Call a shell command with the given arguments.
+Note that the arguments will be shell-escaped.
+So to read the variables, the `-c` option of the shell
+can be used.
+You may need to pass `ExplorePwd` depening on the expectation.
+
+**YAML Example:** `Call: { command: bash, args: ["-c", "read -p test"] }`
+**Lua Example:** `{ Call = { command = "bash", args = { "-c", "read -p test" } } }`
+
+### { CallSilently = "string" }
+
+YAML: `CallSilently: string`
+
+Like `Call` but without the flicker. The stdin, stdout
+stderr will be piped to null. So it's non-interactive.
+
+**YAML Example:** `CallSilently: { command: tput, args: ["bell"] }`
+**Lua Example:** `{ CallSilently = { command = "tput", args = { "bell" } } }`
+
+### { CallLua = "string" }
+
+YAML: `CallLua: string`
+
+Call a Lua function.
+A [`CallLuaArg`](#calllua-argument) object will be passed to the
+[function](#lua-function-calls) as argument.
+The function can optionally return a list of messages for xplr to handle
+after the executing the function.
+
+**YAML Example:** `CallLua: custom.some_custom_funtion`
+**Lua Example:** `{ CallLua = "custom.some_custom_funtion" }`
+
+### { CallLuaSilently = "string" }
+
+YAML: `CallLuaSilently: string`
+
+Like `CallLua` but without the flicker. The stdin, stdout
+stderr will be piped to null. So it's non-interactive.
+
+**YAML Example:** `CallLuaSilently: custom.some_custom_function`
+**Lua Example:** `{ CallLuaSilently = "custom.some_custom_function" }`
+
+### { BashExec = "string" }
+
+YAML: `BashExec: string`
+
+An alias to `Call: {command: bash, args: ["-c", "{string}"], silent: false}`
+where `{string}` is the given value.
+
+**YAML Example:** `BashExec: "read -p test"`
+**Lua Example:** `{ BashExec = "read -p test" }`
+
+### { BashExecSilently = "string" }
+
+YAML: `BashExecSilently(String)`
+
+Like `BashExec` but without the flicker. The stdin, stdout
+stderr will be piped to null. So it's non-interactive.
+
+**YAML Example:** `BashExecSilently: "tput bell"`
+**Lua Example:** `{ BashExecSilently = "tput bell" }`
+
+### "Select"
+
+YAML: `Select`
+
+Select the focused node.
+
+### "SelectAll"
+
+YAML: `SelectAll`
+
+Select all the visible nodes.
+
+### { SelectPath = "string" }
+
+YAML: `SelectPath: string`
+
+Select the given path.
+
+**YAML Example:** `SelectPath: /path/to/file`
+**Lua Example:** `{ SelectPath = "/path/to/file" }`
+
+### "UnSelect"
+
+YAML: `UnSelect`
+
+Unselect the focused node.
+
+### "UnSelectAll"
+
+YAML: `UnSelectAll`
+
+Unselect all the visible nodes.
+
+### { UnSelectPath = "string)" }
+
+YAML: `UnSelectPath: string`
+
+UnSelect the given path.
+
+**YAML Example:** `UnSelectPath: /path/to/file`
+**Lua Example:** `{ UnSelectPath = "/path/to/file" }`
+
+### "ToggleSelection"
+
+YAML: `ToggleSelection`
+
+Toggle selection on the focused node.
+
+### "ToggleSelectAll"
+
+YAML: `ToggleSelectAll`
+
+Toggle between select all and unselect all.
+
+### { ToggleSelectionByPath = "string" }
+
+YAML: `ToggleSelectionByPath: string`
+
+Toggle selection by file path.
+
+**YAML Example:** `ToggleSelectionByPath: /path/to/file`
+**Lua Example:** `{ ToggleSelectionByPath = "/path/to/file" }`
+
+### "ClearSelection"
+
+YAML: `ClearSelection`
+
+Clear the selection.
+
+### { AddNodeFilter = { filter = "[NodeFilter](filtering.md#filter)", input = "string" }
+
+YAML: `AddNodeFilter: { filter = [NodeFilter](filtering.md#filter), input = string`
+
+Add a [filter](filtering.md) to exclude nodes while exploring directories.
+
+**YAML Example:** `AddNodeFilter: { filter: RelativePathDoesStartWith, input: foo }`
+**Lua Example:** `{ AddNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" }`
+
+### { RemoveNodeFilter = { filter = "[NodeFilter](filtering.md#filter)", input = "string" }
+
+YAML: `RemoveNodeFilter: { filter = [NodeFilter](filtering.md#filter), input = string`
+
+Remove an existing [filter](filtering.md).
+
+**YAML Example:** `RemoveNodeFilter: { filter: RelativePathDoesStartWith, input: foo }`
+**Lua Example:** `{ RemoveNodeFilter: { filter: "RelativePathDoesStartWith", input: "foo" } }`
+
+### { ToggleNodeFilter = { filter = "[NodeFilter](filtering.md#filter)", input = "string" }
+
+YAML: `ToggleNodeFilter: { filter = [NodeFilter](filtering.md#filter), input = string`
+
+Remove a [filter](filter.md) if it exists, else, add a it.
+
+**YAML Example:** `ToggleNodeFilter: { filter: RelativePathDoesStartWith, input: foo }`
+**Lua Example:** `{ ToggleNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }`
+
+### { AddNodeFilterFromInput = "[NodeFilter](filtering.md#filter)" }
+
+YAML: `AddNodeFilterFromInput: [NodeFilter](filtering.md#filter)`
+
+Add a node [filter](filtering.md) reading the input from the buffer.
+
+**YAML Example:** `AddNodeFilterFromInput: RelativePathDoesStartWith`
+**Lua Example:** `{ AddNodeFilterFromInput = "RelativePathDoesStartWith" }`
+
+### { RemoveNodeFilterFromInput = "[NodeFilter](filtering.md#filter)" }
+
+YAML: `RemoveNodeFilterFromInput: [NodeFilter](filtering.md#filter)`
+
+Remove a node [filter](filtering.md) reading the input from the buffer.
+
+**YAML Example:** `RemoveNodeFilterFromInput: RelativePathDoesStartWith`
+**Lua Example:** `{ RemoveNodeFilterFromInput = "RelativePathDoesStartWith" }`
+
+### "RemoveLastNodeFilter"
+
+YAML: `RemoveLastNodeFilter`
+
+Remove the last node [filter](filtering.md).
+
+### "ResetNodeFilters"
+
+YAML: `ResetNodeFilters`
+
+Reset the node [filters](filtering.md) back to the default configuration.
+
+### "ClearNodeFilters"
+
+YAML: `ClearNodeFilters`
+
+Clear all the node [filters](filtering.md).
+
+### { AddNodeSorter = { sorter = "[NodeSorter](sorting.md#sorter)", reverse = bool } }
+
+YAML: `AddNodeSorter: { sorter: [NodeSorter](sorting.md#sorter), reverse = bool }`
+
+Add a [sorter](sorting.md#sorter) to sort nodes while exploring directories.
+
+**YAML Example:** `AddNodeSorter: { sorter: ByRelativePath, reverse: false }`
+**YAML Example:** `{ AddNodeSorter = { sorter = "ByRelativePath", reverse = false } }`
+
+### { RemoveNodeSorter = "[NodeSorter](sorting.md#sorter)" }
+
+YAML: `RemoveNodeSorter: [NodeSorter](sorting.md#sorter)`
+
+Remove an existing [sorter](sorting.md#sorter).
+
+**YAML Example:** `RemoveNodeSorter: ByRelativePath`
+**Lua Example:** `{ RemoveNodeSorter = "ByRelativePath" }`
+
+### { ReverseNodeSorter = "[NodeSorter](sorting.md#sorter)" }
+
+YAML: `ReverseNodeSorter: [NodeSorter](sorting.md#sorter)`
+
+Reverse a node [sorter](sorting.md#sorter).
+
+**YAML Example:** `ReverseNodeSorter: ByRelativePath`
+**Lua Example:** `{ ReverseNodeSorter = "ByRelativePath" }`
+
+### { ToggleNodeSorter = { sorter = "[NodeSorter](sorting.md#sorter)", reverse = bool } }
+
+YAML: `ToggleNodeSorter: { sorter: [NodeSorter](sorting.md#sorter), reverse = bool }`
+
+Remove a [sorter](#sorting.md#sorter) if it exists, else, add a it.
+
+**YAML Example:** `ToggleSorterSorter: {sorter: ByRelativePath, reverse: false }`
+**Lua Example:** `{ ToggleSorterSorter: { sorter = "ByRelativePath", reverse = false } }`
+
+### "ReverseNodeSorters"
+
+YAML: `ReverseNodeSorters`
+
+Reverse the node [sorters](sorting.md#sorter).
+
+### "RemoveLastNodeSorter"
+
+YAML: `RemoveLastNodeSorter`
+
+Remove the last node [sorter](sorting.md#sorter).
+
+### "ResetNodeSorters"
+
+YAML: `ResetNodeSorters`
+
+Reset the node [sorters](sorting.md#sorter) back to the default configuration.
+
+### "ClearNodeSorters"
+
+YAML: `ClearNodeSorters`
+
+Clear all the node [sorters](sorting.md#sorter).
+
+### "EnableMouse"
+
+YAML: `EnableMouse`
+
+Enable mouse
+
+### "DisableMouse"
+
+YAML: `DisableMouse`
+
+Disable mouse
+
+### "ToggleMouse"
+
+YAML: `ToggleMouse`
+
+Toggle mouse
+
+### { StartFifo = "string" }
+
+YAML: `StartFifo: string`
+
+Start piping the focused path to the given fifo path
+
+**YAML Example:** `StartFifo: /tmp/xplr.fifo`
+**Lua Example:** `{ StartFifo = "/tmp/xplr.fifo }`
+
+### "StopFifo"
+
+YAML: `StopFifo`
+
+Close the active fifo and stop piping.
+
+### { ToggleFifo = "string" }
+
+YAML: `ToggleFifo: string`
+
+Toggle betwen {Start|Stop}Fifo
+
+**YAML Example:** `ToggleFifo: /path/to/fifo`
+**Lua Example:** `{ ToggleFifo = "/path/to/fifo" }`
+
+### { LogInfo = "string" }
+
+YAML: `LogInfo: string`
+
+Log information message.
+
+**YAML Example:** `LogInfo: launching satellite`
+**Lua Example:** `{ LogInfo = "launching satellite" }`
+
+### { LogSuccess = "String" }
+
+YAML: `LogSuccess: string`
+
+Log a success message.
+
+**YAML Example:** `LogSuccess: satellite reached destination`.
+**Lua Example:** `{ LogSuccess = "satellite reached destination" }`.
+
+### { LogWarning = "string" }
+
+YAML: `LogWarning: string`
+
+Log an warning message.
+
+**YAML Example:** `LogWarning: satellite is heating`
+**Lua Example:** `{ LogWarning = "satellite is heating" }`
+
+### { LogError = "string" }
+
+YAML: `LogError: string`
+
+Log an error message.
+
+**YAML Example:** `LogError: satellite crashed`
+**Lua Example:** `{ LogError = "satellite crashed" }`
+
+### "Quit"
+
+YAML: `Quit`
+
+Quit with returncode zero (success).
+
+### "PrintPwdAndQuit"
+
+YAML: `PrintPwdAndQuit`
+
+Print $PWD and quit.
+
+### "PrintFocusPathAndQuit"
+
+YAML: `PrintFocusPathAndQuit`
+
+Print the path under focus and quit. It can be empty string if there's nothing to focus.
+
+### "PrintSelectionAndQuit"
+
+YAML: `PrintSelectionAndQuit`
+
+Print the selected paths and quit. It can be empty is no path is selected.
+
+### "PrintResultAndQuit"
+
+YAML: `PrintResultAndQuit`
+
+Print the selected paths if it's not empty, else, print the focused node's path.
+
+### "PrintAppStateAndQuit"
+
+YAML: `PrintAppStateAndQuit`
+
+Print the state of application in YAML format. Helpful for debugging or generating
+the default configuration file.
+
+### { Debug = "string" }
+
+YAML: `Debug: string`
+
+Write the application state to a file, without quitting. Also helpful for debugging.
+
+**YAML Example:**  `Debug: /path/to/file`
+**Lua Example:**  `{ Debug = "/path/to/file" }`
+
+### "Terminate"
+
+YAML: `Terminate`
+
+Terminate the application with a non-zero return code.
+
+
 Lua Function Calls
 ------------------