Messages

You can think of xplr as a server. Like web servers listen to HTTP requests, xplr listens to messages.

xplr generally reads messages from multiple sources like keyboard input and pipes. Hence, you can control each xplr session in many ways.

As of writing, xplr supports the following messages

Explore

Explore the present working directory and register the filtered nodes. This operation is expensive. So, try avoiding using it too often. Once exploration is done, it will auto Refresh the state.

Refresh

Refresh the app state (uncluding 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.

ClearScreen

Clears the screen.

FocusNext

Focus next node.

FocusNextByRelativeIndex(usize)

Focus on the nth node relative to the current focus where n is a given value.

Example: FocusNextByRelativeIndex: 2

FocusNextByRelativeIndexFromInput

Focus on the nth node relative to the current focus where n is read from the input buffer.

FocusPrevious

Focus on the previous item.

FocusPreviousByRelativeIndex(usize)

Focus on the -nth node relative to the current focus where n is a given value.

Example: FocusPreviousByRelativeIndex: 2

FocusPreviousByRelativeIndexFromInput

Focus on the -nth node relative to the current focus where n is read from the input buffer.

FocusFirst

Focus on the first node.

FocusLast

Focus on the last node.

FocusPath(String)

Focus on the given path.

Example: FocusPath: /tmp

FocusPathFromInput

Focus on the path read from input buffer.

FocusByIndex(usize)

Focus on the absolute nth node where n is a given value.

Example: FocusByIndex: 2

FocusByIndexFromInput

Focus on the absolute nth node where n is read from the input buffer.

FocusByFileName(String)

Focus on the file by name from the present working directory.

Example: FocusByFileName: README.md

ChangeDirectory(String)

Change the present working directory ($PWD)

Example: ChangeDirectory: /tmp

Enter

Enter into the currently focused path if it’s a directory.

Back

Go back to the parent directory.

LastVisitedPath

Go to the last path visited.

NextVisitedPath

Go to the next path visited.

BufferInput(String)

Append/buffer the given string into the input buffer.

Example: BufferInput: foo

BufferInputFromKey

Append/buffer the characted read from a keyboard input into the input buffer.

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.

Example: SetInputBuffer: foo

ResetInputBuffer

Reset the input buffer back to null. It will not show in the UI.

SwitchMode(String)

Switch input mode. This will reset the input buffer and call Refresh automatically.

Example: SwitchMode: default

Call(Command)

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 Refresh or Explore depening on the expectation.

Example: Call: {command: bash, args: ["-c", "read -p test"]}

CallSilently(Command)

Like Call but without the flicker. The stdin, stdoutstderr will be piped to null. So it's non-interactive.

Example: CallSilently: {command: tput, args: ["bell"]}

BashExec(String)

An alias to Call: {command: bash, args: ["-c", "${command}"]} where ${command} is the given value.

Example: BashExec: "read -p test"

BashExecSilently(String)

Like BashExec but without the flicker. The stdin, stdout stderr will be piped to null. So it's non-interactive.

Example: BashExecSilently: "tput bell"

Select

Select the focused node.

SelectAll

Select all the visible nodes.

SelectPath(String)

Select the given path.

Example: SelectPath: "/tmp"

UnSelect

Unselect the focused node.

UnSelectAll

Unselect all the visible nodes.

UnSelectPath(String)

UnSelect the given path.

Example: UnSelectPath: "/tmp"

ToggleSelection

Toggle selection on the focused node.

ToggleSelectAll

Toggle between select all and unselect all.

ToggleSelectionByPath(String)

Toggle selection by file path.

Example: ToggleSelectionByPath: "/tmp"

ClearSelection

Clear the selection

AddNodeFilter(NodeFilterApplicable)

Add a filter to explude nodes while exploring directories.

Example: AddNodeFilter: {filter: RelativePathDoesStartWith, input: foo}

RemoveNodeFilter(NodeFilterApplicable)

Remove an existing filter.

Example: RemoveNodeFilter: {filter: RelativePathDoesStartWith, input: foo}

ToggleNodeFilter(NodeFilterApplicable)

Remove a filter if it exists, else, add a it.

Example: ToggleNodeFilter: {filter: RelativePathDoesStartWith, input: foo}

AddNodeFilterFromInput(NodeFilterFromInput)

Add a node filter reading the input from the buffer.

Example: AddNodeFilterFromInput: {filter: RelativePathDoesStartWith}

RemoveNodeFilterFromInput(NodeFilterFromInput)

Remove a node filter reading the input from the buffer.

Example: RemoveNodeFilterFromInput: {filter: RelativePathDoesStartWith}

ResetNodeFilters

Reset the node filters back to the default configuration.

LogInfo(String)

Log information message. Stored in $XPLR_LOGS.

Example: LogInfo: launching satellite

LogSuccess(String)

Log a success message. Stored in $XPLR_LOGS.

Example: LogSuccess: satellite reached destination. Stored in $XPLR_LOGS

LogError(String)

Log an error message, Stoted in $XPLR_LOGS

Example: LogError: satellite crashed

Quit

Quit with returncode zero (success).

PrintResultAndQuit

Print selected paths if it’s not empty, else, print the focused node’s path.

PrintAppStateAndQuit

Print the state of application in YAML format. Helpful for debugging or generating the default configuration file.

Debug(String)

Write the application state to a file, without quitting. Also helpful for debugging.

Terminate

Terminate the application with a non-zero return code.