Document a little

README.md

@@ -6,7 +6,7 @@ A hackable, minimal, fast TUI file explorer, stealing ideas from <a href="https:
 
 <p align="center">
 <a href="https://asciinema.org/a/3THQPXNVi801Yu8nWxO6qfUa4" target="_blank">
-<img src="https://s4.gifyu.com/images/xplr.gif"/>
+<img src="https://s4.gifyu.com/images/xplr.gif" />
 </a>
 </p>
 
@@ -20,11 +20,18 @@ A hackable, minimal, fast TUI file explorer, stealing ideas from <a href="https:
 
 <br>
 
-
 Though [xplr](https://github.com/sayanarijit/xplr) strives to be fast and minimalist, it's speciality is it's hackability.
 
 Once you read the [documentation](https://github.com/sayanarijit/xplr/wiki), you should be able to configure the key bindings,
 different run modes, and also the way it looks by modifying one single configuration file.
 
+<p align="center">
+
+<a href="https://asciinema.org/a/404815" target="_blank">
+<img src="https://s4.gifyu.com/images/xplr9d8b7b05c6bc39ae.gif" />
+</a>
+
+</p>
+
 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).

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,