From 1b1cd393bc804866f032414169522b59b825fb3f Mon Sep 17 00:00:00 2001 From: Arijit Basu Date: Sat, 3 Apr 2021 13:36:26 +0530 Subject: [PATCH] Document a little --- README.md | 11 ++++- src/app.rs | 142 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 16ac1d5..36629bd 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ A hackable, minimal, fast TUI file explorer, stealing ideas from - +

@@ -20,11 +20,18 @@ A hackable, minimal, fast TUI file explorer, stealing ideas from + + + + + +

+ If you come up with something cool, or if you feel it's lacking somewhere in portability, flexibility or performance, don't hesitate to [start a conversation](https://github.com/sayanarijit/xplr/discussions/2). diff --git a/src/app.rs b/src/app.rs index 670efd0..e9186f8 100644 --- a/src/app.rs +++ b/src/app.rs @@ -396,31 +396,173 @@ impl ExplorerConfig { #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)] pub enum ExternalMsg { + + /// 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. + /// + /// Example: `- Explore` + /// or `echo Explore >> ${XPLR_PIPE_MSG_IN:?}` Explore, + + /// 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. + /// + /// Example: `- Refresh` + /// or `echo Refresh >> ${XPLR_PIPE_MSG_IN:?}` Refresh, + + /// Clears the screen. + /// + /// Example: `- ClearScreen` + /// or `echo ClearScreen >> ${XPLR_PIPE_MSG_IN:?}` ClearScreen, + + /// Focus next node. + /// + /// Example: `- FocusNext` + /// or `echo FocusNext >> ${XPLR_PIPE_MSG_IN:?}` FocusNext, + + /// Focus on the `n`th node relative to the current focus where `n` is a given value. + /// + /// Example: `- FocusNextByRelativeIndex: 2` + /// or `echo "FocusNextByRelativeIndex: 2" >> ${XPLR_PIPE_MSG_IN:?}` FocusNextByRelativeIndex(usize), + + /// Focus on the `n`th node relative to the current focus where `n` is read from + /// the input buffer. + /// + /// Example: `- FocusNextByRelativeIndexFromInput` + /// or `echo FocusNextByRelativeIndexFromInput >> ${XPLR_PIPE_MSG_IN:?}` FocusNextByRelativeIndexFromInput, + + /// Focus on the previous item. + /// + /// Example: `- FocusPrevious` + /// or `echo FocusPrevious >> ${XPLR_PIPE_MSG_IN:?}` FocusPrevious, + + /// Focus on the `-n`th node relative to the current focus where `n` is a given value. + /// + /// Example: `- FocusPreviousByRelativeIndex: 2` + /// or `echo "FocusPreviousByRelativeIndex: 2" >> ${XPLR_PIPE_MSG_IN:?}` FocusPreviousByRelativeIndex(usize), + + /// Focus on the `-n`th node relative to the current focus where `n` is read from + /// the input buffer. + /// + /// Example: `- FocusPreviousByRelativeIndexFromInput` + /// or `echo FocusPreviousByRelativeIndexFromInput >> ${XPLR_PIPE_MSG_IN:?}` FocusPreviousByRelativeIndexFromInput, + + /// Focus on the first node. + /// + /// Example: `- FocusFirst` + /// or `echo FocusFirst >> ${XPLR_PIPE_MSG_IN:?}` FocusFirst, + + /// Focus on the last node. + /// + /// Example: `- FocusLast` + /// or `echo FocusLast >> ${XPLR_PIPE_MSG_IN:?}` FocusLast, + + /// Focus on the given path. + /// + /// Example: `- FocusPath: /tmp` + /// or `echo "FocusPath: /tmp" >> ${XPLR_PIPE_MSG_IN:?}` FocusPath(String), + + /// Focus on the path read from input buffer. + /// + /// Example: `- FocusPathFromInput` + /// or `echo "FocusPathFromInput" >> ${XPLR_PIPE_MSG_IN:?}` FocusPathFromInput, + + /// Focus on the absolute `n`th node where `n` is a given value. + /// + /// Example: `- FocusByIndex: 2` + /// or `echo "FocusByIndex: 2" >> ${XPLR_PIPE_MSG_IN:?}` FocusByIndex(usize), + + /// Focus on the absolute `n`th node where `n` is read from the input buffer. + /// + /// Example: `- FocusByIndexFromInput` + /// or `echo "FocusByIndexFromInput" >> ${XPLR_PIPE_MSG_IN:?}` FocusByIndexFromInput, + + /// Focus on the file by name from the present working directory. + /// + /// Example: `- FocusByFileName: README.md` + /// or `echo "FocusByFileName: README.md" >> ${XPLR_PIPE_MSG_IN:?}` FocusByFileName(String), + + /// Change the present working directory ($PWD) + /// + /// Example: `- ChangeDirectory: /tmp` + /// or `echo "ChangeDirectory: README.md" >> ${XPLR_PIPE_MSG_IN:?}` ChangeDirectory(String), + + /// Enter into the currently focused path if it's a directory. + /// + /// Example: `- Enter` + /// or `echo Enter >> ${XPLR_PIPE_MSG_IN:?}` Enter, + + /// Go back to the parent directory. + /// + /// Example: `- Back` + /// or `echo Back >> ${XPLR_PIPE_MSG_IN:?}` Back, + + /// Append/buffer the given string into the input buffer. + /// + /// Example: `- Back` + /// or `echo Back >> ${XPLR_PIPE_MSG_IN:?}` BufferInput(String), + + /// Append/buffer the characted read from a keyboard input into the + /// input buffer. + /// + /// Example: `- BufferInputFromKey` + /// Note: this doesn't work with pipes. BufferInputFromKey, + + /// 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"` + /// or `echo SetInputBuffer: "foo" >> ${XPLR_PIPE_MSG_IN:?}` SetInputBuffer(String), + + /// Reset the input buffer back to null. It will not show in the UI. + /// + /// Example: `- ReSetInputBuffer: "foo"` + /// or `echo ReSetInputBuffer >> ${XPLR_PIPE_MSG_IN:?}` ResetInputBuffer, + + /// Switch input mode. + /// This will call `Refresh` automatically. + /// + /// Example: `- SwitchMode: "default"` + /// or `echo SwitchMode: "default" >> ${XPLR_PIPE_MSG_IN:?}` SwitchMode(String), + + /// Call a shell command with the given arguments. + /// Note that the arguments will be shell-escaped. + /// So read the variables, the `-c` option of teh shell + /// can be used. + /// You may need to pass `Refresh` or `Explore` depening on the expectation. + /// + /// Example: `- Call: {command: "bash", args: ["-c", "echo $PWD"]}` + /// or `echo 'Call: {command: "ls", atgs: ["-l"]}' >> ${XPLR_PIPE_MSG_IN:?}` Call(Command), + + // TODO document Select, UnSelect, ToggleSelection,