docs: update

This also adds a dependency on the test utility.

README

@@ -9,19 +9,14 @@ screenshot: https://user-images.githubusercontent.com/6799467/89270554-2b40ab00-
 features
 ________________________________________________________________________________
 
-* no dependencies other than a POSIX shell + POSIX printf, dd and stty ***
+* no dependencies other than a POSIX shell + POSIX test, printf, dd and stty ***
 * tiny
 * single file
 * no compilation needed
 * correctly handles files with funky names (newlines, etc)
 * works with very small terminal sizes.
 
-*** SIGWINCH and the size parameter to stty are not /yet/ POSIX but will be.
+*** see portability notes towards bottom of README.
-    - https://austingroupbugs.net/view.php?id=1053
-    - https://austingroupbugs.net/view.php?id=1151
-
-*** Raw escape sequences are used in place of tput. These are strictly VT100
-    sequences minus \033[?1049[lh], \033[?25[lh] and \033[?7[lh] (?)
 
 
 keybinds
@@ -59,11 +54,10 @@ ________________________________________________________________________________
 - [ ] print directories first (hard).
 - [x] fix buggy focus after exit from inline editor.
 - [ ] maybe file operations.
-- [ ] add / to directories.
+- [x] add / to directories.
-- [ ] use clearer variable names.
 - [x] going up directories should center entry.
-- [ ] abstract over sequences.
+- [x] abstract over sequences.
-- [ ] look into whether tput is feasible.
+- [x] look into whether tput is feasible.
 
 
 opener
@@ -95,7 +89,7 @@ Example scripts:
             mpv "$1"
         ;;
 
-        *.png|*.gif||*.jpg|*.jpe|*.jpeg)
+        *.png|*.gif|*.jpg|*.jpe|*.jpeg)
             gimp "$1"
         ;;
 
@@ -143,6 +137,44 @@ Example scripts:
     esac
 
 
+portability notes
+________________________________________________________________________________
+
+* SIGWINCH and the size parameter to stty are not /yet/ POSIX (but will be).
+
+  - https://austingroupbugs.net/view.php?id=1053
+  - https://austingroupbugs.net/view.php?id=1151
+
+
+* VT100/ANSI escape sequences (widely available) are used in place of tput. A
+  few non-VT100 sequences /are/ needed however.
+
+  - IL      vt102  \033[L:         controls upwards scroll.    (required)
+  - ?       xterm  \033[?1049[lh]: controls alternate screen.  (optional)
+  - DECTCEM vt520  \033[?25[lh]:   controls cursor visibility. (optional)
+
+  Why avoid tput?
+
+  POSIX only specifies three operands for tput; clear, init and reset [0]. We
+  cannot rely on anything additional working across operating systems and tput
+  implementations.
+
+  Further, a tput implementation may use terminfo names (example: setaf) or
+  termcap names (example: AF). We cannot blindly use tput and expect it to
+  work everywhere. [1]
+
+  We could simply follow terminfo and yell at anyone who doesn't though I'm
+  also not too keen on requiring tput as a dependency as not all systems have
+  it. I've found that raw VT100/VT102 sequences work widely.
+
+  Neofetch uses them and supports a wide array of operating systems (Linux,
+  IRIX, AIX, HP-UX, various BSDs, Haiku, MINIX, OpenIndiana, FreeMiNT, etc.
+  YMMV
+
+  [0] https://pubs.opengroup.org/onlinepubs/009695399/utilities/tput.html
+  [1] https://invisible-island.net/ncurses/man/tput.1.html#h2-PORTABILITY
+
+
 implementation details
 ________________________________________________________________________________
 

shfm

@@ -1,16 +1,40 @@
 #!/bin/sh
 
+esc() {
+    case $1 in
+        # vt100 (IL is vt102)
+        CUD)        printf '%s[%sB'     "$esc_c" "$2"      ;; # cursor down
+        CUP)        printf '%s[%s;%sH'  "$esc_c" "$2" "$3" ;; # cursor home
+        CUU)        printf '%s[%sA'     "$esc_c" "$2"      ;; # cursor up
+        DECAWM)     printf '%s[?7%s'    "$esc_c" "$2"      ;; # line wrap
+        DECRC)      printf '%s8'        "$esc_c"           ;; # cursor restore
+        DECSC)      printf '%s7'        "$esc_c"           ;; # cursor save
+        DECSTBM)    printf '%s[%s;%sr'  "$esc_c" "$2" "$3" ;; # scroll region
+        ED[0-2])    printf '%s[%sJ'     "$esc_c" "${1#ED}" ;; # clear screen
+        EL[0-2])    printf '%s[%sK'     "$esc_c" "${1#EL}" ;; # clear line
+        IL)         printf '%s[%sL'     "$esc_c" "$2"      ;; # insert line
+        SGR)        printf '%s[%s;%sm'  "$esc_c" "$2" "$3" ;; # colors
+
+        # private (and optional)
+        DECTCEM)    printf '%s[?25%s'   "$esc_c" "$2" ;; # cursor visible (vt520)
+        screen_alt) printf '%s[?1049%s' "$esc_c" "$2" ;; # alternate buf  (xterm)
+    esac
+}
+
 term_setup() {
     stty=$(stty -g)
     stty -icanon -echo
-
+    esc DECAWM l
-    printf '\033[?7l\033[?25l\033[2J\033[1;%sr' \
+    esc DECTCEM l
-        "$((LINES - 2))"
+    esc ED2
+    esc DECSTBM 1 "$((LINES - 2))"
 }
 
 term_reset() {
-    printf '\033[?7h\033[?25h\033[2J\033[;r'
+    esc DECAWM h
-
+    esc DECTCEM h
+    esc ED2
+    esc DECSTBM
     stty "$stty"
 }
 
@@ -28,19 +52,56 @@ term_resize() {
     bottom=$((LINES - 2))
 }
 
+term_scroll_down() {
+    case $((y - $#)) in
+        -*)
+            y=$((y + 1))
+            y2=$((y2 + 1 < bottom ? y2 + 1 : bottom))
+
+            line_print "$((y - 1))" "$@"
+            printf '\n'
+            line_print "$y" "$@"
+            status_line "($y/$#) $PWD"
+        ;;
+    esac
+}
+
+term_scroll_up() {
+    case $y in
+        -*|0|1) ;;
+
+        *)
+            y=$((y - 1))
+
+            line_print "$((y + 1))" "$@"
+
+            case $y2 in
+                1) esc IL ;;
+                *) esc CUU; y2=$((y2 > 1 ? y2 - 1 : 1))
+            esac
+
+            line_print "$y" "$@"
+            status_line "($y/$#) $PWD"
+        ;;
+    esac
+}
+
 cmd_run() {
-    printf '\033[?1049h\033[?25h'
+    esc screen_alt h
+    esc DECTCEM h
+    esc DECSTBM
     "$@"
-    printf '\033[?25l\033[?1049l'
+    esc DECSTBM 1 "$((LINES - 2))"
+    esc screen_alt l
+    esc DECTCEM l
+    esc CUP "$y2"
 }
 
 file_escape() {
     tmp=$1 safe=
 
     # loop over string char by char
-    while :; do
+    while c=${tmp%"${tmp#?}"}; do
-        c=${tmp%"${tmp#?}"*}
-
         case $c in
             [[:print:]]) safe=$safe$c ;;
             '')          return ;;
@@ -56,11 +117,7 @@ hist_search() {
 
     for file do
         case ${PWD%%/}/$file in
-            "$old_pwd")
+            "$old_pwd") y=$j y2=$((j > bottom ? mid : j)) cur=$file
-                y=$j
-                y2=$((j > bottom ? mid : j))
-                cur=$file
-            ;;
         esac
 
         j=$((j + 1))
@@ -68,7 +125,8 @@ hist_search() {
 }
 
 list_print() {
-    printf '\033[2J\033[H'
+    esc ED2
+    esc CUP
 
     i=1
     end=$((bottom + 1))
@@ -86,20 +144,21 @@ list_print() {
     esac
 
     for file do
-        file_escape "$file"
-
         case $i in
-            "$y2") printf '\033[34;7m'
+            "$y2") esc SGR 34 7
         esac
 
         case $((i - end)) in
-            -*) printf '%s\033[m\033[B\r' "$safe"
+            -*)
+                line_format "$file"
+                esc CUD
+            ;;
         esac
 
         i=$((i + 1))
     done
 
-    printf '\033[%sH' "$((y > bottom ? y2 : y))"
+    esc CUP "$((y > bottom ? y2 : y))"
 }
 
 redraw() {
@@ -108,12 +167,20 @@ redraw() {
 }
 
 status_line() {
-    printf '\0337\033[%sH\033[31;7m%-*s\033[m\0338' \
+    esc DECSC
-        "$LINES" "$COLUMNS" "$1"
+    esc CUP "$LINES"
+    esc SGR 31 7
+    printf '%-*s' "$COLUMNS" "$1"
+    esc SGR
+    esc DECRC
 }
 
 prompt() {
-    printf '\0337\033[%sH%s\033[?25h\033[K' "$LINES" "$1"
+    esc DECSC
+    esc CUP "$LINES"
+    printf %s "$1"
+    esc DECTCEM h
+    esc EL0
 
     case $2 in
         r)
@@ -123,24 +190,34 @@ prompt() {
         ;;
     esac
 
-    printf '\0338\033[?25l'
+    esc DECRC
+    esc DECTCEM l
     status_line "($y/$#) $PWD"
 }
 
-print_line() {
+line_print() {
     offset=$1
 
     case $offset in
-        "$y") printf '\033[34;7m'
+        "$y") esc SGR 34 7
     esac
 
     shift "$offset"
-    file_escape "$1"
-    printf '\033[K%s\033[m\r' "$safe"
 
     case $offset in
         "$y") cur=$1
     esac
+
+    line_format "$1"
+}
+
+line_format() {
+    file_escape "$1"
+    esc EL0
+    printf %s "$safe"
+    test -d "$1" && printf /
+    esc SGR
+    printf '\r'
 }
 
 main() {
@@ -148,12 +225,12 @@ main() {
 
     case $1 in
         -v)
-            printf '%s 0.1\n' "${0##*/}"
+            printf '%s 0.2\n' "${0##*/}"
             exit 0
         ;;
     esac
 
-    esc_char=$(printf '\033')
+    esc_c=$(printf '\033')
     bs_char=$(printf '\177')
 
     cd "${1:-"$PWD"}"
@@ -171,52 +248,18 @@ main() {
 
     while key=$(dd ibs=1 count=1 2>/dev/null); do
         case $key${esc:=0} in
-            k?|A2) # ARROW UP
+            k?|A2)
-                case $y in
+                term_scroll_up "$@"
-                    -*|0|1) ;;
-
-                    *)
-                        y=$((y - 1))
-
-                        print_line "$((y + 1))" "$@"
-
-                        case $y2 in
-                            1)
-                                printf '\033[L'
-                            ;;
-
-                            *)
-                                printf '\033[A'
-                                y2=$((y2 > 1 ? y2 - 1 : 1))
-                            ;;
-                        esac
-
-                        print_line "$y" "$@"
-
-                        status_line "($y/$#) $PWD"
-                    ;;
-                esac
             ;;
 
-            j?|B2) # ARROW DOWN
+            j?|B2)
-                case $((y - $#)) in
+                term_scroll_down "$@"
-                    -*)
-                        y=$((y + 1))
-                        y2=$((y2 + 1 < bottom ? y2 + 1 : bottom))
-
-                        print_line "$((y - 1))" "$@"
-                        printf '\n'
-                        print_line "$y" "$@"
-
-                        status_line "($y/$#) $PWD"
-                    ;;
-                esac
             ;;
 
             l?|C2|"$esc") # ARROW RIGHT
                 if cd "$cur" >/dev/null 2>&1; then
                     set -- *
-                    y=1 y2=1 cur=$1
+                    y=1 y2=1 cur=$1 search=0
                     redraw "$@"
                 else
                     cmd_run "${SHFM_OPENER:="${EDITOR:=vi}"}" "$cur"
@@ -237,6 +280,10 @@ main() {
             ;;
 
             g?)
+                case $y in
+                    1) continue
+                esac
+
                 y=1 y2=1 cur=$1
                 redraw "$@"
             ;;
@@ -266,9 +313,7 @@ main() {
 
             :?)
                 prompt "cd: " r
-
                 cd "${ans:="$0"}" >/dev/null 2>&1|| continue
-
                 set -- *
                 y=1 y2=1 cur=$1
                 redraw "$@"
@@ -276,7 +321,6 @@ main() {
 
             /?)
                 prompt / r
-
                 set -- *"$ans"*
                 y=1 y2=1 cur=$1 search=1
                 redraw "$@"
@@ -285,7 +329,6 @@ main() {
 
             -?)
                 cd "$OLDPWD" >/dev/null 2>&1|| continue
-
                 set -- *
                 y=1 y2=1 cur=$1
                 redraw "$@"
@@ -293,7 +336,6 @@ main() {
 
             \~?)
                 cd || continue
-
                 set -- *
                 y=1 y2=1 cur=$1
                 redraw "$@"
@@ -302,7 +344,6 @@ main() {
             \!?)
                 export SHFM_LEVEL
                 SHFM_LEVEL=$((SHFM_LEVEL + 1))
-
                 cmd_run "${SHELL:=/bin/sh}"
             ;;
 
@@ -311,9 +352,9 @@ main() {
             ;;
 
             # handle keys which emit escape sequences
-            "$esc_char"*) esc=1 ;;
+            "$esc_c"*) esc=1 ;;
-                    '[1') esc=2 ;;
+                 '[1') esc=2 ;;
-                       *) esc=0 ;;
+                    *) esc=0 ;;
         esac
     done
 }