Created Live Previews (markdown)

Live-Previews.md

@@ -0,0 +1,119 @@
+
+# Live Previews
+
+A live preview is a window that shows information about whatever file or directory `nnn` has highlighted. As the cursor moves, the live preview window will automatically update.
+
+## A Simple Example
+
+There are two aspects to creating a live preview:
+1. A preview command
+1. A setup command
+
+### A Preview Command Example
+
+```sh
+#!/usr/bin/env sh
+# #############################################################################
+# Description: Minimal example to preview files and directories
+#              No external dependencies
+#              Can be easily extended
+#              Automatically exits when the NNN_FIFO closes
+#              Prints a `tree` if directory or `head` if it's a file
+#
+# Shell: POSIX compliant
+# Author: Todd Yamakawa
+#
+# ToDo:
+#   1. Add support for more types of files
+#         e.g. binary files, we shouldn't try to `head` those
+# #############################################################################
+
+# Check FIFO
+NNN_FIFO=${NNN_FIFO:-$1}
+if [ ! -r "$NNN_FIFO" ]; then
+    echo "Unable to open \$NNN_FIFO='$NNN_FIFO'" | less
+    exit 2
+fi
+
+# Read selection from $NNN_FIFO
+while read -r selection; do
+    clear
+    lines=$(($(tput lines)-1))
+    cols=$(tput cols)
+
+    # Print directory tree
+    if [ -d "$selection" ]; then
+        cd "$selection" || continue
+        tree | head -n $lines | cut -c 1-"$cols"
+        continue
+    fi
+
+    # Print file head
+    if [ -f "$selection" ]; then
+        head -n $lines "$selection" | cut -c 1-"$cols"
+        continue
+    fi
+
+    # Something went wrong
+    echo "Unknown type: '$selection'"
+done < "$NNN_FIFO"
+```
+
+
+### A Setup Command Example
+
+To create your own setup command, you need the following steps:
+1. Create a `NNN_FIFO`
+1. Run your preview command in the background
+1. Run `nnn`
+1. Delete your `NNN_FIFO`
+
+Here is am example `bash`/`zsh` function. To use this example, you will need to set the preview command.
+For the preview window:
+- It uses `tmux` split if you're currently running in a `tmux` environment
+  - `tmux 3.0` is required for setting environment variables in a new pane
+- Otherwise it uses an `xterm` window
+
+
+```shell
+nnn-preview ()
+{
+    # Block nesting of nnn in subshells
+    if [ -n "$NNNLVL" ] && [ "${NNNLVL:-0}" -ge 1 ]; then
+        echo "nnn is already running"
+        return
+    fi
+
+    # The default behaviour is to cd on quit (nnn checks if NNN_TMPFILE is set)
+    # To cd on quit only on ^G, remove the "export" as in:
+    #     NNN_TMPFILE="${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.lastd"
+    # NOTE: NNN_TMPFILE is fixed, should not be modified
+    export NNN_TMPFILE="${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.lastd"
+
+    # This will create a fifo where all nnn selections will be written to
+    NNN_FIFO="$(mktemp --suffix=-nnn -u)"
+    export NNN_FIFO
+    (umask 077; mkfifo "$NNN_FIFO")
+
+    # Preview command
+    preview_cmd="/path/to/preview_cmd.sh"
+
+    # Use `tmux` split as preview
+    if [ -e "${TMUX%%,*}" ]; then
+        tmux split-window -e "NNN_FIFO=$NNN_FIFO" -dh "$preview_cmd"
+
+    # Use `xterm` as a preview window
+    elif (which xterm &> /dev/null); then
+        xterm -e "$preview_cmd" &
+
+    # Unable to find a program to use as a preview window
+    else
+        echo "unable to open preview, please install tmux or xterm"
+    fi
+
+    nnn "$@"
+
+    rm -f "$NNN_FIFO"
+}
+```
+