docs: update

- Added ? to show keybinds
- Fixed some bugs

README

@@ -9,19 +9,16 @@ 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 [, printf, dd and stty ***
 * tiny
 * single file
 * no compilation needed
 * correctly handles files with funky names (newlines, etc)
 * works with very small terminal sizes.
+* cd on exit
+* works when run in subshell $(shfm)
 
-*** 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
-
-*** 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] (?)
+*** see portability notes towards bottom of README.
 
 
 keybinds
@@ -40,17 +37,7 @@ q - quit
 ~ - go home
 ! - spawn shell
 . - toggle hidden files
-
-Additional keybinds:
-
-down  arrow  - down
-up    arrow  - up
-right arrow  - open file or directory
-left  arrow  - go up level
-
-enter/return - open file or directory
-backspace    - go up level
-
+? - show help
 
 todo
 ________________________________________________________________________________
@@ -59,11 +46,33 @@ ________________________________________________________________________________
 - [ ] print directories first (hard).
 - [x] fix buggy focus after exit from inline editor.
 - [ ] maybe file operations.
-- [ ] add / to directories.
-- [ ] use clearer variable names.
+- [x] add / to directories.
 - [x] going up directories should center entry.
-- [ ] abstract over sequences.
-- [ ] look into whether tput is feasible.
+- [x] abstract over sequences.
+- [x] look into whether tput is feasible.
+
+
+cd on exit
+________________________________________________________________________________
+
+On exit, the utility will print the path to working directory to <stdout>. To
+disable this behavior, run with 'shfm >/dev/null'. Usage of this output is
+rather flexible.
+
+    # cd to directory on exit
+    cd "$(shfm)"
+
+    # store pwd in var on exit
+    var=$(shfm)
+
+    # store pwd in a file one exit
+    shfm > file
+
+For ease of use, a wrapper function can be added to your .shellrc (.bashrc, etc).
+
+    shfm() {
+        cd "$(command shfm)"
+    }
 
 
 opener
@@ -95,7 +104,7 @@ Example scripts:
             mpv "$1"
         ;;
 
-        *.png|*.gif||*.jpg|*.jpe|*.jpeg)
+        *.png|*.gif|*.jpg|*.jpe|*.jpeg)
             gimp "$1"
         ;;
 
@@ -143,6 +152,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,17 +1,44 @@
 #!/bin/sh
 
+esc() {
+    case $1 in
+        # vt100 (IL is vt102) (DECTCEM is vt520)
+        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
+        DECTCEM) printf '%s[?25%s'  "$esc_c" "$2"      ;; # cursor visible
+        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
+
+        # xterm (since 1988, supported widely)
+        screen_alt) printf '%s[?1049%s' "$esc_c" "$2" ;; # alternate buffer
+    esac
+}
+
 term_setup() {
     stty=$(stty -g)
     stty -icanon -echo
-
-    printf '\033[?7l\033[?25l\033[2J\033[1;%sr' \
-        "$((LINES - 2))"
+    esc DECAWM l
+    esc DECTCEM l
+    esc ED2
+    esc DECSTBM 1 "$((LINES - 2))"
 }
 
 term_reset() {
-    printf '\033[?7h\033[?25h\033[2J\033[;r'
-
+    esc DECAWM h
+    esc DECTCEM h >&2
+    esc ED2       >&2
+    esc DECSTBM
     stty "$stty"
+
+    # needed for cd-on-exit
+    printf '%s\n' "$PWD" >&1
 }
 
 term_resize() {
@@ -28,23 +55,58 @@ term_resize() {
     bottom=$((LINES - 2))
 }
 
+term_scroll_down() {
+    case $((y - $#)) in
+        [0-9]*) return
+    esac
+
+    y=$((y + 1))
+    y2=$((y2 + 1 < bottom ? y2 + 1 : bottom))
+
+    line_print "$((y - 1))" "$@"
+    printf '\n'
+    line_print "$y" "$@"
+    status_line "$#"
+}
+
+term_scroll_up() {
+    case $y in
+        -*|0|1) return
+    esac
+
+    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 "$#"
+}
+
 cmd_run() {
-    printf '\033[?1049h\033[?25h'
-    "$@"
-    printf '\033[?25l\033[?1049l'
+    esc screen_alt h
+    esc DECTCEM h
+    esc DECSTBM
+    "$@" ||:
+    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
-        c=${tmp%"${tmp#?}"*}
-
+    while c=${tmp%"${tmp#?}"}; do
         case $c in
-            [[:print:]]) safe=$safe$c ;;
             '')          return ;;
-            *)           safe=$safe\? ;;
+            [[:cntrl:]]) safe=$safe\? ;;
+            *)           safe=$safe$c ;;
         esac
 
         tmp=${tmp#?}
@@ -56,11 +118,7 @@ hist_search() {
 
     for file do
         case ${PWD%%/}/$file in
-            "$old_pwd")
-                y=$j
-                y2=$((j > bottom ? mid : j))
-                cur=$file
-            ;;
+            "$old_pwd") y=$j y2=$((j > bottom ? mid : j)) cur=$file
         esac
 
         j=$((j + 1))
@@ -68,7 +126,8 @@ hist_search() {
 }
 
 list_print() {
-    printf '\033[2J\033[H'
+    esc ED2
+    esc CUP
 
     i=1
     end=$((bottom + 1))
@@ -86,34 +145,54 @@ list_print() {
     esac
 
     for file do
-        file_escape "$file"
-
         case $i in
-            "$y2") printf '\033[34;7m'
+            "$y2") esc SGR 0 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() {
     list_print "$@"
-    status_line "($y/$#) $PWD"
+    status_line "$#"
 }
 
 status_line() {
-    printf '\0337\033[%sH\033[31;7m%-*s\033[m\0338' \
-        "$LINES" "$COLUMNS" "$1"
+    esc DECSC
+    esc CUP "$LINES"
+
+    case $USER in
+        root) esc SGR 31 7 ;;
+           *) esc SGR 34 7 ;;
+    esac
+
+    printf '%*s\r%s ' "$COLUMNS" "" "($y/$1)"
+
+    case $ltype in
+        '') printf %s "$PWD" ;;
+         *) printf %s "$ltype"
+    esac
+
+    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,40 +202,58 @@ 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 0 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"
+    [ -d "$1" ] && printf /
+    esc SGR
+    printf '\r'
 }
 
 main() {
     set -e
 
     case $1 in
-        -v)
-            printf '%s 0.1\n' "${0##*/}"
+        -h|--help)
+            printf 'shfm -[hv] <starting dir>\n'
             exit 0
         ;;
+
+        -v|--version)
+            printf 'shfm 0.4\n'
+            exit 0
+        ;;
+
+        *)
+            cd -- "${1:-"$PWD"}"
+        ;;
     esac
 
-    esc_char=$(printf '\033')
+    esc_c=$(printf '\033')
     bs_char=$(printf '\177')
 
-    cd "${1:-"$PWD"}"
     set -- *
     cur=$1
 
@@ -171,54 +268,21 @@ main() {
 
     while key=$(dd ibs=1 count=1 2>/dev/null); do
         case $key${esc:=0} in
-            k?|A2) # ARROW UP
-                case $y in
-                    -*|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
+            k?|A2)
+                term_scroll_up "$@"
             ;;
 
-            j?|B2) # ARROW DOWN
-                case $((y - $#)) in
-                    -*)
-                        y=$((y + 1))
-                        y2=$((y2 + 1 < bottom ? y2 + 1 : bottom))
-
-                        print_line "$((y - 1))" "$@"
-                        printf '\n'
-                        print_line "$y" "$@"
-
-                        status_line "($y/$#) $PWD"
-                    ;;
-                esac
+            j?|B2)
+                term_scroll_down "$@"
             ;;
 
             l?|C2|"$esc") # ARROW RIGHT
-                if cd "$cur" >/dev/null 2>&1; then
+                if [ -d "$cur" ] && cd "$cur" >/dev/null 2>&1; then
                     set -- *
-                    y=1 y2=1 cur=$1
+                    y=1 y2=1 cur=$1 ltype=
                     redraw "$@"
-                else
+
+                elif [ -e "$cur" ]; then
                     cmd_run "${SHFM_OPENER:="${EDITOR:=vi}"}" "$cur"
                 fi
             ;;
@@ -226,9 +290,9 @@ main() {
             h?|D2|"$bs_char"?) # ARROW LEFT
                 old_pwd=$PWD
 
-                case $search in
-                    1) search=0 ;;
-                    *) cd .. || continue ;;
+                case $ltype in
+                    '') cd .. || continue ;;
+                     *) ltype= ;;
                 esac
 
                 set -- *
@@ -237,6 +301,10 @@ main() {
             ;;
 
             g?)
+                case $y in
+                    1) continue
+                esac
+
                 y=1 y2=1 cur=$1
                 redraw "$@"
             ;;
@@ -249,15 +317,8 @@ main() {
 
             .?)
                 case ${hidden:=1} in
-                    1)
-                        hidden=0
-                        set -- .[!.]*
-                    ;;
-
-                    *)
-                        hidden=1
-                        set -- *
-                    ;;
+                    1) hidden=0; set -- .[!.]* ;;
+                    *) hidden=1; set -- *      ;;
                 esac
 
                 y=1 y2=1 cur=$1
@@ -267,8 +328,14 @@ main() {
             :?)
                 prompt "cd: " r
 
-                cd "${ans:="$0"}" >/dev/null 2>&1|| continue
+                # false positive, behavior intentional
+                # shellcheck disable=2088
+                case $ans in
+                    '~')   ans=$HOME ;;
+                    '~/'*) ans=$HOME/${ans#"~/"}
+                esac
 
+                cd "${ans:="$0"}" >/dev/null 2>&1|| continue
                 set -- *
                 y=1 y2=1 cur=$1
                 redraw "$@"
@@ -276,16 +343,14 @@ main() {
 
             /?)
                 prompt / r
-
-                set -- *"$ans"*
-                y=1 y2=1 cur=$1 search=1
+                set -- "$ans"*
+                y=1 y2=1 cur=$1 ltype="search $PWD/$ans*"
                 redraw "$@"
-                status_line "($y/$#) search $ans"
+                status_line "$#"
             ;;
 
             -?)
                 cd "$OLDPWD" >/dev/null 2>&1|| continue
-
                 set -- *
                 y=1 y2=1 cur=$1
                 redraw "$@"
@@ -293,7 +358,6 @@ main() {
 
             \~?)
                 cd || continue
-
                 set -- *
                 y=1 y2=1 cur=$1
                 redraw "$@"
@@ -302,20 +366,40 @@ main() {
             \!?)
                 export SHFM_LEVEL
                 SHFM_LEVEL=$((SHFM_LEVEL + 1))
-
                 cmd_run "${SHELL:=/bin/sh}"
             ;;
 
+            \??)
+                set -- 'j - down' \
+                       'k - up' \
+                       'l - open file or directory' \
+                       'h - go up level' \
+                       'g - go to top' \
+                       'G - go to bottom' \
+                       'q - quit' \
+                       ': - cd to <input>' \
+                       '/ - search current directory <input>*' \
+                       '- - go to last directory' \
+                       '~ - go home' \
+                       '! - spawn shell' \
+                       '. - toggle hidden files' \
+                       '? - show keybinds'
+
+                y=1 y2=1 cur=$1 ltype=keybinds
+                redraw "$@"
+                status_line "$#"
+            ;;
+
             q?)
                 exit 0
             ;;
 
             # handle keys which emit escape sequences
-            "$esc_char"*) esc=1 ;;
-                    '[1') esc=2 ;;
-                       *) esc=0 ;;
+            "$esc_c"*) esc=1 ;;
+                 '[1') esc=2 ;;
+                    *) esc=0 ;;
         esac
     done
 }
 
-main "$@"
+main "$@" >/dev/tty