merge

plugins/z/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018-2022 Alexandros Kozak
+Copyright (c) 2018-2023 Alexandros Kozak
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

plugins/z/MANUAL.md

@@ -1,5 +1,11 @@
 # Zsh-z
 
+[![MIT License](img/mit_license.svg)](https://opensource.org/licenses/MIT)
+![Zsh version 4.3.11 and higher](img/zsh_4.3.11_plus.svg)
+[![GitHub stars](https://img.shields.io/github/stars/agkozak/zsh-z.svg)](https://github.com/agkozak/zsh-z/stargazers)
+
+![Zsh-z demo](img/demo.gif)
+
 Zsh-z is a command line tool that allows you to jump quickly to directories that you have visited frequently in the past, or recently -- but most often a combination of the two (a concept known as ["frecency"](https://en.wikipedia.org/wiki/Frecency)). It works by keeping track of when you go to directories and how much time you spend in them. It is then in the position to guess where you want to go when you type a partial string, e.g., `z src` might take you to `~/src/zsh`. `z zsh` might also get you there, and `z c/z` might prove to be even more specific -- it all depends on your habits and how much time you have been using Zsh-z to build up a database. After using Zsh-z for a little while, you will get to where you want to be by typing considerably less than you would need if you were using `cd`.
 
 Zsh-z is a native Zsh port of [rupa/z](https://github.com/rupa/z), a tool written for `bash` and Zsh that uses embedded `awk` scripts to do the heavy lifting. It was quite possibly my most used command line tool for a couple of years. I decided to translate it, `awk` parts and all, into pure Zsh script, to see if by eliminating calls to external tools (`awk`, `sort`, `date`, `sed`, `mv`, `rm`, and `chown`) and reducing forking through subshells I could make it faster. The performance increase is impressive, particularly on systems where forking is slow, such as Cygwin, MSYS2, and WSL. I have found that, in those environments, switching directories using Zsh-z can be over 100% faster than it is using `rupa/z`.
@@ -28,6 +34,16 @@ Zsh-z is a drop-in replacement for `rupa/z` and will, by default, use the same d
 <details>
     <summary>Here are the latest features and updates.</summary>
 
+- August 24, 2023
+    + Zsh-z will now run when `setopt NO_UNSET` has been enabled (props @ntninja).
+- August 23, 2023
+    + Better logic for loading `zsh/files` (props @z0rc)
+- August 2, 2023
+    + Zsh-z still uses the `zsh/files` module when possible, but will fall back on the standard `chown`, `mv`, and `rm` commands in its absence.
+- April 27, 2023
+    + Zsh-z now allows the user to specify the directory-changing command using the `ZSHZ_CD` environment variable (default: `builtin cd`; props @basnijholt).
+- January 27, 2023
+    + If the datafile directory specified by `ZSHZ_DATA` or `_Z_DATA` does not already exist, create it (props @mattmc3).
 - June 29, 2022
     + Zsh-z is less likely to leave temporary files sitting around (props @mafredri).
 - June 27, 2022
@@ -56,7 +72,7 @@ Zsh-z is a drop-in replacement for `rupa/z` and will, by default, use the same d
     + Temporarily disabling use of `print -v`, which seems to be mangling CJK multibyte strings.
 - July 27, 2021
     + Internal escaping of path names now works with older versions of ZSH.
-    + Zsh-z now detects and discards any incomplete or incorrectly formattted database entries.
+    + Zsh-z now detects and discards any incomplete or incorrectly formatted database entries.
 - July 10, 2021
     + Setting `ZSHZ_TRAILING_SLASH=1` makes it so that a search pattern ending in `/` can match the end of a path; e.g. `z foo/` can match `/path/to/foo`.
 - June 25, 2021
@@ -77,7 +93,7 @@ Zsh-z is a drop-in replacement for `rupa/z` and will, by default, use the same d
 - January 11, 2021
     + Major refactoring of the code.
     + `z -lr` and `z -lt` work as expected.
-    + `EXTENDED_GLOB` has been disabled within the plugin to accomodate old-fashioned Windows directories with names such as `Progra~1`.
+    + `EXTENDED_GLOB` has been disabled within the plugin to accommodate old-fashioned Windows directories with names such as `Progra~1`.
     + Removed `zshelldoc` documentation.
 - January 6, 2021
     + I have corrected the frecency routine so that it matches `rupa/z`'s math, but for the present, Zsh-z will continue to display ranks as 1/10000th of what they are in `rupa/z` -- [they had to multiply theirs by 10000](https://github.com/rupa/z/commit/f1f113d9bae9effaef6b1e15853b5eeb445e0712) to work around `bash`'s inadequacies at dealing with decimal fractions.
@@ -94,13 +110,13 @@ Zsh-z is a drop-in replacement for `rupa/z` and will, by default, use the same d
 
 ### General observations
 
-This script can be installed simply by downloading it and sourcing it from your `.zshrc`:
+This plugin can be installed simply by putting the various files in a directory together and by sourcing `zsh-z.plugin.zsh` in your `.zshrc`:
 
     source /path/to/zsh-z.plugin.zsh
 
-For tab completion to work, you will want to have loaded `compinit`. The frameworks handle this themselves. If you are not using a framework, put
+For tab completion to work, `_zshz` *must* be in the same directory as `zsh-z.plugin.zsh`, and you will want to have loaded `compinit`. The frameworks handle this themselves. If you are not using a framework, put
 
-    autoload -U compinit && compinit
+    autoload -U compinit; compinit
 
 in your .zshrc somewhere below where you source `zsh-z.plugin.zsh`.
 
@@ -118,13 +134,19 @@ Add the line
 
 to your `.zshrc`, somewhere above the line that says `antigen apply`.
 
-### For [oh-my-zsh](http://ohmyz.sh/) users
+### For [Oh My Zsh](http://ohmyz.sh/) users
 
-Execute the following command:
+Zsh-z is now included as part of Oh My Zsh! As long as you are using an up-to-date installation of Oh My Zsh, you can activate Zsh-z simply by adding `z` to your `plugins` array in your `.zshrc`, e.g.,
+
+    plugins=( git z )
+
+It is as simple as that.
+
+If, however, you prefer always to use the latest version of Zsh-z from the `agkozak/zsh-z` repo, you may install it thus:
 
     git clone https://github.com/agkozak/zsh-z ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-z
 
-and add `zsh-z` to the line of your `.zshrc` that specifies `plugins=()`, e.g., `plugins=( git zsh-z )`.
+and activate it by adding `zsh-z` to the line of your `.zshrc` that specifies `plugins=()`, e.g., `plugins=( git zsh-z )`.
 
 ### For [prezto](https://github.com/sorin-ionescu/prezto) users
 
@@ -166,7 +188,7 @@ Add a backslash to the end of the last line add `'zsh-z'` to the list, e.g.,
 Then relaunch `zsh`.
 
 ### For [zcomet](https://github.com/agkozak/zcomet) users
-        
+
 Simply add
 
     zcomet load agkozak/zsh-z
@@ -246,6 +268,7 @@ to install `zsh-z`.
 Zsh-z has environment variables (they all begin with `ZSHZ_`) that change its behavior if you set them; you can also keep your old ones if you have been using `rupa/z` (they begin with `_Z_`).
 
 * `ZSHZ_CMD` changes the command name (default: `z`)
+* `ZSHZ_CD` specifies the default directory-changing command (default: `builtin cd`)
 * `ZSHZ_COMPLETION` can be `'frecent'` (default) or `'legacy'`, depending on whether you want your completion results sorted according to frecency or simply sorted alphabetically
 * `ZSHZ_DATA` changes the database file (default: `~/.z`)
 * `ZSHZ_ECHO` displays the new path name when changing directories (default: `0`)

plugins/z/_z

@@ -5,7 +5,7 @@
 #
 # https://github.com/agkozak/zsh-z
 #
-# Copyright (c) 2018-2022 Alexandros Kozak
+# Copyright (c) 2018-2023 Alexandros Kozak
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal

plugins/z/img/mit_license.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="78" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="78" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h47v20H0z"/><path fill="#97CA00" d="M47 0h31v20H47z"/><path fill="url(#b)" d="M0 0h78v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"><text x="245" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="370">license</text><text x="245" y="140" transform="scale(.1)" textLength="370">license</text><text x="615" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="210">MIT</text><text x="615" y="140" transform="scale(.1)" textLength="210">MIT</text></g> </svg>

plugins/z/img/zsh_4.3.11_plus.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="84" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="84" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h29v20H0z"/><path fill="#e05d44" d="M29 0h55v20H29z"/><path fill="url(#b)" d="M0 0h84v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"><text x="155" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="190">zsh</text><text x="155" y="140" transform="scale(.1)" textLength="190">zsh</text><text x="555" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="450">4.3.11+</text><text x="555" y="140" transform="scale(.1)" textLength="450">4.3.11+</text></g> </svg>

plugins/z/z.plugin.zsh

@@ -4,7 +4,7 @@
 #
 # https://github.com/agkozak/zsh-z
 #
-# Copyright (c) 2018-2022 Alexandros Kozak
+# Copyright (c) 2018-2023 Alexandros Kozak
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -52,6 +52,7 @@
 #   ZSHZ_CASE -> if `ignore', pattern matching is case-insensitive; if `smart',
 #     pattern matching is case-insensitive only when the pattern is all
 #     lowercase
+#   ZSHZ_CD -> the directory-changing command that is used (default: builtin cd)
 #   ZSHZ_CMD -> name of command (default: z)
 #   ZSHZ_COMPLETION -> completion method (default: 'frecent'; 'legacy' for
 #     alphabetic sorting)
@@ -99,20 +100,30 @@ With no ARGUMENT, list the directory history in ascending rank.
 }
 
 # Load zsh/datetime module, if necessary
-(( $+EPOCHSECONDS )) || zmodload zsh/datetime
-
-# Load zsh/files, if necessary
-[[ ${builtins[zf_chown]} == 'defined' &&
-   ${builtins[zf_mv]}    == 'defined' &&
-   ${builtins[zf_rm]}    == 'defined' ]] ||
-  zmodload -F zsh/files b:zf_chown b:zf_mv b:zf_rm
-
-# Load zsh/system, if necessary
-[[ ${modules[zsh/system]} == 'loaded' ]] || zmodload zsh/system &> /dev/null
+(( ${+EPOCHSECONDS} )) || zmodload zsh/datetime
 
 # Global associative array for internal use
 typeset -gA ZSHZ
 
+# Fallback utilities in case Zsh lacks zsh/files (as is the case with MobaXterm)
+ZSHZ[CHOWN]='chown'
+ZSHZ[MV]='mv'
+ZSHZ[RM]='rm'
+# Try to load zsh/files utilities
+if [[ ${builtins[zf_chown]-} != 'defined' ||
+      ${builtins[zf_mv]-}    != 'defined' ||
+      ${builtins[zf_rm]-}    != 'defined' ]]; then
+  zmodload -F zsh/files b:zf_chown b:zf_mv b:zf_rm &> /dev/null
+fi
+# Use zsh/files, if it is available
+[[ ${builtins[zf_chown]-} == 'defined' ]] && ZSHZ[CHOWN]='zf_chown'
+[[ ${builtins[zf_mv]-} == 'defined' ]] && ZSHZ[MV]='zf_mv'
+[[ ${builtins[zf_rm]-} == 'defined' ]] && ZSHZ[RM]='zf_rm'
+
+
+# Load zsh/system, if necessary
+[[ ${modules[zsh/system]-} == 'loaded' ]] || zmodload zsh/system &> /dev/null
+
 # Make sure ZSHZ_EXCLUDE_DIRS has been declared so that other scripts can
 # simply append to it
 (( ${+ZSHZ_EXCLUDE_DIRS} )) || typeset -gUa ZSHZ_EXCLUDE_DIRS
@@ -129,6 +140,7 @@ is-at-least 5.3.0 && ZSHZ[PRINTV]=1
 # Globals:
 #   ZSHZ
 #   ZSHZ_CASE
+#   ZSHZ_CD
 #   ZSHZ_COMPLETION
 #   ZSHZ_DATA
 #   ZSHZ_DEBUG
@@ -143,15 +155,25 @@ is-at-least 5.3.0 && ZSHZ[PRINTV]=1
 zshz() {
 
   # Don't use `emulate -L zsh' - it breaks PUSHD_IGNORE_DUPS
-  setopt LOCAL_OPTIONS NO_KSH_ARRAYS NO_SH_WORD_SPLIT EXTENDED_GLOB
+  setopt LOCAL_OPTIONS NO_KSH_ARRAYS NO_SH_WORD_SPLIT EXTENDED_GLOB UNSET
   (( ZSHZ_DEBUG )) && setopt LOCAL_OPTIONS WARN_CREATE_GLOBAL
 
   local REPLY
   local -a lines
 
-  # Allow the user to specify the datafile name in $ZSHZ_DATA (default: ~/.z)
+  # Allow the user to specify a custom datafile in $ZSHZ_DATA (or legacy $_Z_DATA)
+  local custom_datafile="${ZSHZ_DATA:-$_Z_DATA}"
+
+  # If a datafile was provided as a standalone file without a directory path
+  # print a warning and exit
+  if [[ -n ${custom_datafile} && ${custom_datafile} != */* ]]; then
+    print "ERROR: You configured a custom Zsh-z datafile (${custom_datafile}), but have not specified its directory." >&2
+    exit
+  fi
+
+  # If the user specified a datafile, use that or default to ~/.z
   # If the datafile is a symlink, it gets dereferenced
-  local datafile=${${ZSHZ_DATA:-${_Z_DATA:-${HOME}/.z}}:A}
+  local datafile=${${custom_datafile:-$HOME/.z}:A}
 
   # If the datafile is a directory, print a warning and exit
   if [[ -d $datafile ]]; then
@@ -161,7 +183,7 @@ zshz() {
 
   # Make sure that the datafile exists before attempting to read it or lock it
   # for writing
-  [[ -f $datafile ]] || touch "$datafile"
+  [[ -f $datafile ]] || { mkdir -p "${datafile:h}" && touch "$datafile" }
 
   # Bail if we don't own the datafile and $ZSHZ_OWNER is not set
   [[ -z ${ZSHZ_OWNER:-${_Z_OWNER}} && -f $datafile && ! -O $datafile ]] &&
@@ -265,7 +287,7 @@ zshz() {
 
     if (( ret != 0 )); then
       # Avoid clobbering the datafile if the write to tempfile failed
-      zf_rm -f "$tempfile"
+      ${ZSHZ[RM]} -f "$tempfile"
       return $ret
     fi
 
@@ -273,16 +295,17 @@ zshz() {
     owner=${ZSHZ_OWNER:-${_Z_OWNER}}
 
     if (( ZSHZ[USE_FLOCK] )); then
-      zf_mv "$tempfile" "$datafile" 2> /dev/null || zf_rm -f "$tempfile"
+      ${ZSHZ[MV]} "$tempfile" "$datafile" 2> /dev/null || ${ZSHZ[RM]} -f "$tempfile"
 
       if [[ -n $owner ]]; then
-        zf_chown ${owner}:"$(id -ng ${owner})" "$datafile"
+        ${ZSHZ[CHOWN]} ${owner}:"$(id -ng ${owner})" "$datafile"
       fi
     else
       if [[ -n $owner ]]; then
-        zf_chown "${owner}":"$(id -ng "${owner}")" "$tempfile"
+        ${ZSHZ[CHOWN]} "${owner}":"$(id -ng "${owner}")" "$tempfile"
       fi
-      zf_mv -f "$tempfile" "$datafile" 2> /dev/null || zf_rm -f "$tempfile"
+      ${ZSHZ[MV]} -f "$tempfile" "$datafile" 2> /dev/null ||
+          ${ZSHZ[RM]} -f "$tempfile"
     fi
 
     # In order to make z -x work, we have to disable zsh-z's adding
@@ -294,7 +317,7 @@ zshz() {
   }
 
   ############################################################
-  # Read the curent datafile contents, update them, "age" them
+  # Read the current datafile contents, update them, "age" them
   # when the total rank gets high enough, and print the new
   # contents to STDOUT.
   #
@@ -620,7 +643,7 @@ zshz() {
         *)
           # Frecency routine
           (( dx = EPOCHSECONDS - time_field ))
-          rank=$(( 10000 * rank_field * (3.75/((0.0001 * dx + 1) + 0.25)) ))
+          rank=$(( 10000 * rank_field * (3.75/( (0.0001 * dx + 1) + 0.25)) ))
           ;;
       esac
 
@@ -756,6 +779,26 @@ zshz() {
     [[ $output_format != 'completion' ]] && output_format='list'
   }
 
+  #########################################################
+  # Allow the user to specify directory-changing command
+  # using $ZSHZ_CD (default: builtin cd).
+  #
+  # Globals:
+  #   ZSHZ_CD
+  #
+  # Arguments:
+  #   $* Path
+  #########################################################
+  zshz_cd() {
+    setopt LOCAL_OPTIONS NO_WARN_CREATE_GLOBAL
+
+    if [[ -z $ZSHZ_CD ]]; then
+      builtin cd "$*"
+    else
+      ${=ZSHZ_CD} "$*"
+    fi
+  }
+
   #########################################################
   # If $ZSHZ_ECHO == 1, display paths as you jump to them.
   # If it is also the case that $ZSHZ_TILDE == 1, display
@@ -773,7 +816,7 @@ zshz() {
 
   if [[ ${@: -1} == /* ]] && (( ! $+opts[-e] && ! $+opts[-l] )); then
     # cd if possible; echo the new path if $ZSHZ_ECHO == 1
-    [[ -d ${@: -1} ]] && builtin cd ${@: -1} && _zshz_echo && return
+    [[ -d ${@: -1} ]] && zshz_cd ${@: -1} && _zshz_echo && return
   fi
 
   # With option -c, make sure query string matches beginning of matches;
@@ -830,12 +873,12 @@ zshz() {
       print -- "$cd"
     else
       # cd if possible; echo the new path if $ZSHZ_ECHO == 1
-      [[ -d $cd ]] && builtin cd "$cd" && _zshz_echo
+      [[ -d $cd ]] && zshz_cd "$cd" && _zshz_echo
     fi
   else
     # if $req is a valid path, cd to it; echo the new path if $ZSHZ_ECHO == 1
     if ! (( $+opts[-e] || $+opts[-l] )) && [[ -d $req ]]; then
-      builtin cd "$req" && _zshz_echo
+      zshz_cd "$req" && _zshz_echo
     else
       return $ret2
     fi
@@ -852,6 +895,9 @@ alias ${ZSHZ_CMD:-${_Z_CMD:-z}}='zshz 2>&1'
 #   ZSHZ
 ############################################################
 _zshz_precmd() {
+  # Protect against `setopt NO_UNSET'
+  setopt LOCAL_OPTIONS UNSET
+
   # Do not add PWD to datafile when in HOME directory, or
   # if `z -x' has just been run
   [[ $PWD == "$HOME" ]] || (( ZSHZ[DIRECTORY_REMOVED] )) && return
@@ -899,10 +945,10 @@ add-zsh-hook chpwd _zshz_chpwd
 # Completion
 ############################################################
 
-# Standarized $0 handling
-# (See https://github.com/agkozak/Zsh-100-Commits-Club/blob/master/Zsh-Plugin-Standard.adoc)
-0=${${ZERO:-${0:#$ZSH_ARGZERO}}:-${(%):-%N}}
-0=${${(M)0:#/*}:-$PWD/$0}
+# Standardized $0 handling
+# https://zdharma-continuum.github.io/Zsh-100-Commits-Club/Zsh-Plugin-Standard.html
+0="${${ZERO:-${0:#$ZSH_ARGZERO}}:-${(%):-%N}}"
+0="${${(M)0:#/*}:-$PWD/$0}"
 
 (( ${fpath[(ie)${0:A:h}]} <= ${#fpath} )) || fpath=( "${0:A:h}" "${fpath[@]}" )
 
@@ -926,7 +972,7 @@ ZSHZ[FUNCTIONS]='_zshz_usage
 # Enable WARN_NESTED_VAR for functions listed in
 #   ZSHZ[FUNCTIONS]
 ############################################################
-(( ZSHZ_DEBUG )) && () {
+(( ${+ZSHZ_DEBUG} )) && () {
   if is-at-least 5.4.0; then
     local x
     for x in ${=ZSHZ[FUNCTIONS]}; do