Merge pull request #62 from alyssais/declare

declare global variables to support `setopt warn_create_global`

.gitignore

@@ -0,0 +1,2 @@
+# zsh word code files (zcompile)
+*.zwc

README.md

@@ -1,10 +1,8 @@
-zsh-history-substring-search
-==============================================================================
+# zsh-history-substring-search
 
 This is a clean-room implementation of the [Fish shell][1]'s history search
-feature, where you can type in any part of any previously entered command
-and press the UP and DOWN arrow keys to cycle through the matching commands.
-You can also use K and J in VI mode or ^P and ^N in EMACS mode for the same.
+feature, where you can type in any part of any command from history and then
+press chosen keys, such as the UP and DOWN arrows, to cycle through matches.
 
 [1]: http://fishshell.com
 [2]: http://www.zsh.org/mla/users/2009/msg00818.html
@@ -13,13 +11,13 @@ You can also use K and J in VI mode or ^P and ^N in EMACS mode for the same.
 [5]: https://github.com/zsh-users/zsh-history-substring-search
 [6]: https://github.com/zsh-users/zsh-syntax-highlighting
 
-------------------------------------------------------------------------------
+
 Requirements
 ------------------------------------------------------------------------------
 
 * [ZSH](http://zsh.sourceforge.net) 4.3 or newer
 
-------------------------------------------------------------------------------
+
 Usage
 ------------------------------------------------------------------------------
 
@@ -33,88 +31,112 @@ Usage
         % source zsh-syntax-highlighting.zsh
         % source zsh-history-substring-search.zsh
 
-2.  Bind keyboard shortcuts to this script's functions:
+2.  Bind keyboard shortcuts to this script's functions.
 
-        # bind UP and DOWN arrow keys
-        zmodload zsh/terminfo
-        bindkey "$terminfo[kcuu1]" history-substring-search-up
-        bindkey "$terminfo[kcud1]" history-substring-search-down
+    Users typically bind their UP and DOWN arrow keys to this script, thus:
+    * Run `cat -v` in your favorite terminal emulator to observe key codes.
+    * Press the UP arrow key and observe what is printed in your terminal.
+    * Press the DOWN arrow key and observe what is printed in your terminal.
+    * Press the Control and C keys simultaneously to terminate the `cat -v`.
+    * Use your observations from the previous steps to create key bindings.
+      For example, if you observed `^[[A` for UP and `^[[B` for DOWN, then:
+
+            bindkey '^[[A' history-substring-search-up
+            bindkey '^[[B' history-substring-search-down
+
+    You might also want to bind the Control-P/N keys for use in EMACS mode:
 
-        # bind P and N for EMACS mode
         bindkey -M emacs '^P' history-substring-search-up
         bindkey -M emacs '^N' history-substring-search-down
 
-        # bind k and j for VI mode
+    You might also want to bind the `k` and `j` keys for use in VI mode:
+
         bindkey -M vicmd 'k' history-substring-search-up
         bindkey -M vicmd 'j' history-substring-search-down
 
-    Ubuntu 12.04 users might need to use this snippet instead:
-
-        # bind UP and DOWN arrow keys
-        bindkey '^[[A' history-substring-search-up
-        bindkey '^[[B' history-substring-search-down
-
 3.  Type any part of any previous command and then:
 
-    * Press the UP arrow key to select the nearest command that (1) contains
-      your query and (2) is older than the current command in the command
-      history.
+    * Press the `history-substring-search-up` key, which was configured in
+      step 2 above, to select the nearest command that (1) contains your query
+      and (2) is also older than the current command in your command history.
 
-    * Press the DOWN arrow key to select the nearest command that (1)
-      contains your query and (2) is newer than the current command in the
-      command history.
+    * Press the `history-substring-search-down` key, which was configured in
+      step 2 above, to select the nearest command that (1) contains your query
+      and (2) is also newer than the current command in your command history.
 
-    * Press ^U (the Control and U keys simultaneously) to abort the search.
+    * Press `^U` the Control and U keys simultaneously to abort the search.
 
 4.  If a matching command spans more than one line of text, press the LEFT
     arrow key to move the cursor away from the end of the command, and then:
 
-    * Press the UP arrow key to move the cursor to the line above.  When the
-      cursor reaches the first line of the command, pressing the UP arrow
-      key again will cause this script to perform another search.
+    * Press the `history-substring-search-up` key, which was configured in
+      step 2 above, to move the cursor to the line above the cursored line.
+      When the cursor reaches the first line of the command, pressing the
+      `history-substring-search-up` key again will cause this script to
+      perform another search.
+
+    * Press the `history-substring-search-down` key, which was configured in
+      step 2 above, to move the cursor to the line below the cursored line.
+      When the cursor reaches the last line of the command, pressing the
+      `history-substring-search-down` key, which was configured in step 2
+      above, again will cause this script to perform another search.
 
-    * Press the DOWN arrow key to move the cursor to the line below.  When
-      the cursor reaches the last line of the command, pressing the DOWN
-      arrow key again will cause this script to perform another search.
 
-------------------------------------------------------------------------------
 Configuration
 ------------------------------------------------------------------------------
 
 This script defines the following global variables. You may override their
 default values only after having loaded this script into your ZSH session.
 
-* HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND is a global variable that defines
+* `HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND` is a global variable that defines
   how the query should be highlighted inside a matching command. Its default
   value causes this script to highlight using bold, white text on a magenta
   background. See the "Character Highlighting" section in the zshzle(1) man
   page to learn about the kinds of values you may assign to this variable.
 
-* HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND is a global variable that
+* `HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND` is a global variable that
   defines how the query should be highlighted when no commands in the
   history match it. Its default value causes this script to highlight using
   bold, white text on a red background. See the "Character Highlighting"
   section in the zshzle(1) man page to learn about the kinds of values you
   may assign to this variable.
 
-* HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS is a global variable that defines
+* `HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS` is a global variable that defines
   how the command history will be searched for your query. Its default value
   causes this script to perform a case-insensitive search. See the "Globbing
   Flags" section in the zshexpn(1) man page to learn about the kinds of
   values you may assign to this variable.
 
-------------------------------------------------------------------------------
+* `HISTORY_SUBSTRING_SEARCH_ENSURE_UNIQUE` is a global variable that defines
+  whether all search results returned are _unique_. If set to a non-empty
+  value, then only unique search results are presented. This behaviour is off
+  by default. An alternative way to ensure that search results are unique is
+  to use `setopt HIST_IGNORE_ALL_DUPS`. If this configuration variable is off
+  and `setopt HIST_IGNORE_ALL_DUPS` is unset, then `setopt HIST_FIND_NO_DUPS`
+  is still respected and it makes this script skip duplicate _adjacent_ search
+  results as you cycle through them, but this does not guarantee that search
+  results are unique: if your search results were "Dog", "Dog", "HotDog",
+  "Dog", then cycling them gives "Dog", "HotDog", "Dog". Notice that the "Dog"
+  search result appeared twice as you cycled through them. If you wish to
+  receive globally unique search results only once, then use this
+  configuration variable, or use `setopt HIST_IGNORE_ALL_DUPS`.
+
+
 History
 ------------------------------------------------------------------------------
 
-This script was originally written by [Peter Stephenson][2], who published it
-to the ZSH users mailing list (thereby making it public domain) in September
-2009. It was later revised by Guido van Steen and released under the BSD
-license (see below) as part of [the fizsh project][3] in January 2011.
+* September 2009: [Peter Stephenson][2] originally wrote this script and it
+  published to the zsh-users mailing list.
 
-It was later extracted from fizsh release 1.0.1, refactored heavily, and
-repackaged as both an [oh-my-zsh plugin][4] and as an independently loadable
-[ZSH script][5] by Suraj N. Kurapati in 2011.
+* January 2011: Guido van Steen (@guidovansteen) revised this script and
+  released it under the 3-clause BSD license as part of [fizsh][3], the
+  Friendly Interactive ZSHell.
 
-It was [further developed][4] by Guido van Steen, Suraj N. Kurapati, Sorin
-Ionescu, and Vincent Guerci in 2011.
+* January 2011: Suraj N. Kurapati (@sunaku) extracted this script from
+  [fizsh][3] 1.0.1, refactored it heavily, and finally repackaged it as an
+  [oh-my-zsh plugin][4] and as an independently loadable [ZSH script][5].
+
+* July 2011: Guido van Steen, Suraj N. Kurapati, and Sorin Ionescu
+  (@sorin-ionescu) [further developed it][4] with Vincent Guerci (@vguerci).
+
+* March 2016: Geza Lore (@gezalore) greatly refactored it in pull request #55.

zsh-history-substring-search.plugin.zsh

@@ -1,12 +0,0 @@
-# This file integrates the zsh-history-substring-search script into oh-my-zsh.
-
-source "${0:r:r}.zsh"
-
-if test "$CASE_SENSITIVE" = true; then
-  unset HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS
-fi
-
-if test "$DISABLE_COLOR" = true; then
-  unset HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
-  unset HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
-fi

zsh-history-substring-search.zsh

@@ -6,6 +6,7 @@
 # Copyright (c) 2011 Suraj N. Kurapati
 # Copyright (c) 2011 Sorin Ionescu
 # Copyright (c) 2011 Vincent Guerci
+# Copyright (c) 2016 Geza Lore
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -37,19 +38,41 @@
 #
 ##############################################################################
 
+#-----------------------------------------------------------------------------
+# declare global variables
+#-----------------------------------------------------------------------------
+
+typeset -g BUFFER MATCH MBEGIN MEND CURSOR
+typeset -g HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
+typeset -g HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
+typeset -g HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS
+typeset -g HISTORY_SUBSTRING_SEARCH_ENSURE_UNIQUE
+typeset -g _history_substring_search_refresh_display
+typeset -g _history_substring_search_query_highlight
+typeset -g _history_substring_search_result
+typeset -g _history_substring_search_query
+typeset -g -A _history_substring_search_raw_matches
+typeset -g _history_substring_search_raw_match_index
+typeset -g -A _history_substring_search_matches
+typeset -g -A _history_substring_search_unique_filter
+typeset -g _history_substring_search_match_index
+
 #-----------------------------------------------------------------------------
 # configuration variables
 #-----------------------------------------------------------------------------
 
-HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND='bg=magenta,fg=white,bold'
-HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND='bg=red,fg=white,bold'
-HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS='i'
+typeset -g HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND='bg=magenta,fg=white,bold'
+typeset -g HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND='bg=red,fg=white,bold'
+typeset -g HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS='i'
+typeset -g HISTORY_SUBSTRING_SEARCH_ENSURE_UNIQUE=''
+typeset -g _history_substring_search_{refresh_display,query_highlight,result,query,match_index,raw_match_index}
+typeset -ga _history_substring_search{,_raw}_matches
 
 #-----------------------------------------------------------------------------
 # the main ZLE widgets
 #-----------------------------------------------------------------------------
 
-function history-substring-search-up() {
+history-substring-search-up() {
   _history-substring-search-begin
 
   _history-substring-search-up-history ||
@@ -59,7 +82,7 @@ function history-substring-search-up() {
   _history-substring-search-end
 }
 
-function history-substring-search-down() {
+history-substring-search-down() {
   _history-substring-search-begin
 
   _history-substring-search-down-history ||
@@ -90,7 +113,7 @@ if [[ $+functions[_zsh_highlight] -eq 0 ]]; then
   # simply removes any existing highlights when the
   # user inserts printable characters into $BUFFER.
   #
-  function _zsh_highlight() {
+  _zsh_highlight() {
     if [[ $KEYS == [[:print:]] ]]; then
       region_highlight=()
     fi
@@ -143,7 +166,7 @@ if [[ $+functions[_zsh_highlight] -eq 0 ]]; then
 
     # Override ZLE widgets to make them invoke _zsh_highlight.
     local cur_widget
-    for cur_widget in ${${(f)"$(builtin zle -la)"}:#(.*|_*|orig-*|run-help|which-command|beep)}; do
+    for cur_widget in ${${(f)"$(builtin zle -la)"}:#(.*|_*|orig-*|run-help|which-command|beep|yank*)}; do
       case $widgets[$cur_widget] in
 
         # Already rebound event: do nothing.
@@ -173,20 +196,39 @@ if [[ $+functions[_zsh_highlight] -eq 0 ]]; then
   _zsh_highlight_bind_widgets
 fi
 
-function _history-substring-search-begin() {
+_history-substring-search-begin() {
   setopt localoptions extendedglob
 
   _history_substring_search_refresh_display=
   _history_substring_search_query_highlight=
 
   #
-  # Continue using the previous $_history_substring_search_result by default,
-  # unless the current query was cleared or a new/different query was entered.
+  # If the buffer is the same as the previously displayed history substring
+  # search result, then just keep stepping through the match list. Otherwise
+  # start a new search.
   #
-  if [[ -z $BUFFER || $BUFFER != $_history_substring_search_result ]]; then
+  if [[ -n $BUFFER && $BUFFER == ${_history_substring_search_result:-} ]]; then
+    return;
+  fi
+
+  #
+  # Clear the previous result.
+  #
+  _history_substring_search_result=''
+
+  if [[ -z $BUFFER ]]; then
     #
-    # For the purpose of highlighting we will also keep
-    # a version without doubly-escaped meta characters.
+    # If the buffer is empty, we will just act like up-history/down-history
+    # in ZSH, so we do not need to actually search the history. This should
+    # speed things up a little.
+    #
+    _history_substring_search_query=
+    _history_substring_search_raw_matches=()
+
+  else
+    #
+    # For the purpose of highlighting we keep a copy of the original
+    # query string.
     #
     _history_substring_search_query=$BUFFER
 
@@ -195,58 +237,68 @@ function _history-substring-search-begin() {
     # we put an extra "\\" before meta characters such as "\(" and "\)",
     # so that they become "\\\(" and "\\\)".
     #
-    _history_substring_search_query_escaped=${BUFFER//(#m)[\][()|\\*?#<>~^]/\\$MATCH}
+    local escaped_query=${BUFFER//(#m)[\][()|\\*?#<>~^]/\\$MATCH}
 
     #
     # Find all occurrences of the search query in the history file.
     #
-    # (k) turns it an array of line numbers.
+    # (k) returns the "keys" (history index numbers) instead of the values
+    # (R) returns values in reverse older, so the index of the youngest
+    # matching history entry is at the head of the list.
     #
-    # (on) seems to remove duplicates, which are default
-    #      options. They can be turned off by (ON).
-    #
-    _history_substring_search_matches=(${(kon)history[(R)(#$HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS)*${_history_substring_search_query_escaped}*]})
+    _history_substring_search_raw_matches=(${(k)history[(R)(#$HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS)*${escaped_query}*]})
+  fi
 
-    #
-    # Define the range of values that $_history_substring_search_match_index
-    # can take: [0, $_history_substring_search_matches_count_plus].
-    #
-    _history_substring_search_matches_count=$#_history_substring_search_matches
-    _history_substring_search_matches_count_plus=$(( _history_substring_search_matches_count + 1 ))
-    _history_substring_search_matches_count_sans=$(( _history_substring_search_matches_count - 1 ))
+  #
+  # In order to stay as responsive as possible, we will process the raw
+  # matches lazily (when the user requests the next match) to choose items
+  # that need to be displayed to the user.
+  # _history_substring_search_raw_match_index holds the index of the last
+  # unprocessed entry in _history_substring_search_raw_matches. Any items
+  # that need to be displayed will be added to
+  # _history_substring_search_matches.
+  #
+  # We use an associative array (_history_substring_search_unique_filter) as
+  # a 'set' data structure to ensure uniqueness of the results if desired.
+  # If an entry (key) is in the set (non-empty value), then we have already
+  # added that entry to _history_substring_search_matches.
+  #
+  _history_substring_search_raw_match_index=0
+  _history_substring_search_matches=()
+  unset _history_substring_search_unique_filter
+  typeset -A -g _history_substring_search_unique_filter
 
-    #
-    # If $_history_substring_search_match_index is equal to
-    # $_history_substring_search_matches_count_plus, this indicates that we
-    # are beyond the beginning of $_history_substring_search_matches.
-    #
-    # If $_history_substring_search_match_index is equal to 0, this indicates
-    # that we are beyond the end of $_history_substring_search_matches.
-    #
-    # If we have initially pressed "up" we have to initialize
-    # $_history_substring_search_match_index to
-    # $_history_substring_search_matches_count_plus so that it will be
-    # decreased to $_history_substring_search_matches_count.
-    #
-    # If we have initially pressed "down" we have to initialize
-    # $_history_substring_search_match_index to
-    # $_history_substring_search_matches_count so that it will be increased to
-    # $_history_substring_search_matches_count_plus.
-    #
-    if [[ $WIDGET == history-substring-search-down ]]; then
-       _history_substring_search_match_index=$_history_substring_search_matches_count
-    else
-      _history_substring_search_match_index=$_history_substring_search_matches_count_plus
-    fi
+  #
+  # If $_history_substring_search_match_index is equal to
+  # $#_history_substring_search_matches + 1, this indicates that we
+  # are beyond the end of $_history_substring_search_matches and that we
+  # have also processed all entries in
+  # _history_substring_search_raw_matches.
+  #
+  # If $#_history_substring_search_match_index is equal to 0, this indicates
+  # that we are beyond the beginning of $_history_substring_search_matches.
+  #
+  # If we have initially pressed "up" we have to initialize
+  # $_history_substring_search_match_index to 0 so that it will be
+  # incremented to 1.
+  #
+  # If we have initially pressed "down" we have to initialize
+  # $_history_substring_search_match_index to 1 so that it will be
+  # decremented to 0.
+  #
+  if [[ $WIDGET == history-substring-search-down ]]; then
+     _history_substring_search_match_index=1
+  else
+    _history_substring_search_match_index=0
   fi
 }
 
-function _history-substring-search-end() {
+_history-substring-search-end() {
   setopt localoptions extendedglob
 
   _history_substring_search_result=$BUFFER
 
-  # the search was succesful so display the result properly by clearing away
+  # the search was successful so display the result properly by clearing away
   # existing highlights and moving the cursor to the end of the result buffer
   if [[ $_history_substring_search_refresh_display -eq 1 ]]; then
     region_highlight=()
@@ -261,7 +313,7 @@ function _history-substring-search-end() {
     #
     # The following expression yields a variable $MBEGIN, which
     # indicates the begin position + 1 of the first occurrence
-    # of _history_substring_search_query_escaped in $BUFFER.
+    # of _history_substring_search_query in $BUFFER.
     #
     : ${(S)BUFFER##(#m$HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS)($_history_substring_search_query##)}
     local begin=$(( MBEGIN - 1 ))
@@ -277,7 +329,7 @@ function _history-substring-search-end() {
   return 0
 }
 
-function _history-substring-search-up-buffer() {
+_history-substring-search-up-buffer() {
   #
   # Check if the UP arrow was pressed to move the cursor within a multi-line
   # buffer. This amounts to three tests:
@@ -306,7 +358,7 @@ function _history-substring-search-up-buffer() {
   return 1
 }
 
-function _history-substring-search-down-buffer() {
+_history-substring-search-down-buffer() {
   #
   # Check if the DOWN arrow was pressed to move the cursor within a multi-line
   # buffer. This amounts to three tests:
@@ -335,7 +387,7 @@ function _history-substring-search-down-buffer() {
   return 1
 }
 
-function _history-substring-search-up-history() {
+_history-substring-search-up-history() {
   #
   # Behave like up in ZSH, except clear the $BUFFER
   # when beginning of history is reached like in Fish.
@@ -357,7 +409,7 @@ function _history-substring-search-up-history() {
   return 1
 }
 
-function _history-substring-search-down-history() {
+_history-substring-search-down-history() {
   #
   # Behave like down-history in ZSH, except clear the
   # $BUFFER when end of history is reached like in Fish.
@@ -380,181 +432,314 @@ function _history-substring-search-down-history() {
   return 1
 }
 
-function _history-substring-search-not-found() {
+_history_substring_search_process_raw_matches() {
   #
-  # Nothing matched the search query, so put it back into the $BUFFER while
-  # highlighting it accordingly so the user can revise it and search again.
+  # Process more outstanding raw matches and append any matches that need to
+  # be displayed to the user to _history_substring_search_matches.
+  # Return whether there were any more results appended.
+  #
+
+  #
+  # While we have more raw matches. Process them to see if there are any more
+  # matches that need to be displayed to the user.
+  #
+  while [[ $_history_substring_search_raw_match_index -lt $#_history_substring_search_raw_matches ]]; do
+    #
+    # Move on to the next raw entry and get its history index.
+    #
+    (( _history_substring_search_raw_match_index++ ))
+    local index=${_history_substring_search_raw_matches[$_history_substring_search_raw_match_index]}
+
+    #
+    # If HISTORY_SUBSTRING_SEARCH_ENSURE_UNIQUE is set to a non-empty value,
+    # then ensure that only unique matches are presented to the user.
+    # When HIST_IGNORE_ALL_DUPS is set, ZSH already ensures a unique history,
+    # so in this case we do not need to do anything.
+    #
+    if [[ ! -o HIST_IGNORE_ALL_DUPS && -n $HISTORY_SUBSTRING_SEARCH_ENSURE_UNIQUE ]]; then
+      #
+      # Get the actual history entry at the new index, and check if we have
+      # already added it to _history_substring_search_matches.
+      #
+      local entry=${history[$index]}
+
+      if [[ -z ${_history_substring_search_unique_filter[$entry]} ]]; then
+        #
+        # This is a new unique entry. Add it to the filter and append the
+        # index to _history_substring_search_matches.
+        #
+        _history_substring_search_unique_filter[$entry]=1
+        _history_substring_search_matches+=($index)
+
+        #
+        # Indicate that we did find a match.
+        #
+        return 0
+      fi
+
+    else
+      #
+      # Just append the new history index to the processed matches.
+      #
+      _history_substring_search_matches+=($index)
+
+      #
+      # Indicate that we did find a match.
+      #
+      return 0
+    fi
+
+  done
+
+  #
+  # We are beyond the end of the list of raw matches. Indicate that no
+  # more matches are available.
+  #
+  return 1
+}
+
+_history-substring-search-has-next() {
+  #
+  # Predicate function that returns whether any more older matches are
+  # available.
+  #
+
+  if  [[ $_history_substring_search_match_index -lt $#_history_substring_search_matches ]]; then
+    #
+    # We did not reach the end of the processed list, so we do have further
+    # matches.
+    #
+    return 0
+
+  else
+    #
+    # We are at the end of the processed list. Try to process further
+    # unprocessed matches. _history_substring_search_process_raw_matches
+    # returns whether any more matches were available, so just return
+    # that result.
+    #
+    _history_substring_search_process_raw_matches
+    return $?
+  fi
+}
+
+_history-substring-search-has-prev() {
+  #
+  # Predicate function that returns whether any more younger matches are
+  # available.
+  #
+
+  if [[ $_history_substring_search_match_index -gt 1 ]]; then
+    #
+    # We did not reach the beginning of the processed list, so we do have
+    # further matches.
+    #
+    return 0
+
+  else
+    #
+    # We are at the beginning of the processed list. We do not have any more
+    # matches.
+    #
+    return 1
+  fi
+}
+
+_history-substring-search-found() {
+  #
+  # A match is available. The index of the match is held in
+  # $_history_substring_search_match_index
+  #
+  # 1. Make $BUFFER equal to the matching history entry.
+  #
+  # 2. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
+  #    to highlight the current buffer.
+  #
+  BUFFER=$history[$_history_substring_search_matches[$_history_substring_search_match_index]]
+  _history_substring_search_query_highlight=$HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
+}
+
+_history-substring-search-not-found() {
+  #
+  # No more matches are available.
+  #
+  # 1. Make $BUFFER equal to $_history_substring_search_query so the user can
+  #    revise it and search again.
+  #
+  # 2. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
+  #    to highlight the current buffer.
   #
-  _history_substring_search_old_buffer=$BUFFER
   BUFFER=$_history_substring_search_query
   _history_substring_search_query_highlight=$HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
 }
 
-function _history-substring-search-up-search() {
+_history-substring-search-up-search() {
   _history_substring_search_refresh_display=1
 
   #
-  # Highlight matches during history-substring-up-search:
+  # Select history entry during history-substring-down-search:
   #
-  # The following constants have been initialized in
+  # The following variables have been initialized in
   # _history-substring-search-up/down-search():
   #
-  # $_history_substring_search_matches is the current list of matches
-  # $_history_substring_search_matches_count is the current number of matches
-  # $_history_substring_search_matches_count_plus is the current number of matches + 1
-  # $_history_substring_search_matches_count_sans is the current number of matches - 1
+  # $_history_substring_search_matches is the current list of matches that
+  # need to be displayed to the user.
   # $_history_substring_search_match_index is the index of the current match
+  # that is being displayed to the user.
   #
   # The range of values that $_history_substring_search_match_index can take
-  # is: [0, $_history_substring_search_matches_count_plus].  A value of 0
-  # indicates that we are beyond the end of
+  # is: [0, $#_history_substring_search_matches + 1].  A value of 0
+  # indicates that we are beyond the beginning of
   # $_history_substring_search_matches. A value of
-  # $_history_substring_search_matches_count_plus indicates that we are beyond
-  # the beginning of $_history_substring_search_matches.
+  # $#_history_substring_search_matches + 1 indicates that we are beyond
+  # the end of $_history_substring_search_matches and that we have also
+  # processed all entries in _history_substring_search_raw_matches.
+  #
+  # If $_history_substring_search_match_index equals
+  # $#_history_substring_search_matches and
+  # $_history_substring_search_raw_match_index is not greater than
+  # $#_history_substring_search_raw_matches, then we need to further process
+  # $_history_substring_search_raw_matches to see if there are any more
+  # entries that need to be displayed to the user.
   #
   # In _history-substring-search-up-search() the initial value of
-  # $_history_substring_search_match_index is
-  # $_history_substring_search_matches_count_plus.  This value is set in
-  # _history-substring-search-begin().  _history-substring-search-up-search()
-  # will initially decrease it to $_history_substring_search_matches_count.
+  # $_history_substring_search_match_index is 0. This value is set in
+  # _history-substring-search-begin(). _history-substring-search-up-search()
+  # will initially increment it to 1.
   #
-  if [[ $_history_substring_search_match_index -ge 2 ]]; then
-    #
-    # Highlight the next match:
-    #
-    # 1. Decrease the value of $_history_substring_search_match_index.
-    #
-    # 2. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
-    #    to highlight the current buffer.
-    #
-    (( _history_substring_search_match_index-- ))
-    BUFFER=$history[$_history_substring_search_matches[$_history_substring_search_match_index]]
-    _history_substring_search_query_highlight=$HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
 
-  elif [[ $_history_substring_search_match_index -eq 1 ]]; then
+  if [[ $_history_substring_search_match_index -gt $#_history_substring_search_matches ]]; then
     #
-    # We will move beyond the end of $_history_substring_search_matches:
+    # We are beyond the end of $_history_substring_search_matches. This
+    # can only happen if we have also exhausted the unprocessed matches in
+    # _history_substring_search_raw_matches.
     #
-    # 1. Decrease the value of $_history_substring_search_match_index.
+    # 1. Update display to indicate search not found.
     #
-    # 2. Save the current buffer in $_history_substring_search_old_buffer,
-    #    so that it can be retrieved by
-    #    _history-substring-search-down-search() later.
-    #
-    # 3. Make $BUFFER equal to $_history_substring_search_query.
-    #
-    # 4. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
-    #    to highlight the current buffer.
-    #
-    (( _history_substring_search_match_index-- ))
     _history-substring-search-not-found
+    return
+  fi
 
-  elif [[ $_history_substring_search_match_index -eq $_history_substring_search_matches_count_plus ]]; then
+  if _history-substring-search-has-next; then
     #
-    # We were beyond the beginning of $_history_substring_search_matches but
-    # UP makes us move back to $_history_substring_search_matches:
+    # We do have older matches.
     #
-    # 1. Decrease the value of $_history_substring_search_match_index.
+    # 1. Move index to point to the next match.
+    # 2. Update display to indicate search found.
     #
-    # 2. Restore $BUFFER from $_history_substring_search_old_buffer.
-    #
-    # 3. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
-    #    to highlight the current buffer.
-    #
-    (( _history_substring_search_match_index-- ))
-    BUFFER=$_history_substring_search_old_buffer
-    _history_substring_search_query_highlight=$HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
+    (( _history_substring_search_match_index++ ))
+    _history-substring-search-found
 
   else
     #
-    # We are at the beginning of history and there are no further matches.
+    # We do not have older matches.
     #
+    # 1. Move the index beyond the end of
+    #    _history_substring_search_matches.
+    # 2. Update display to indicate search not found.
+    #
+    (( _history_substring_search_match_index++ ))
     _history-substring-search-not-found
   fi
+
+  #
+  # When HIST_FIND_NO_DUPS is set, meaning that only unique command lines from
+  # history should be matched, make sure the new and old results are different.
+  #
+  # However, if the HIST_IGNORE_ALL_DUPS shell option, or
+  # HISTORY_SUBSTRING_SEARCH_ENSURE_UNIQUE is set, then we already have a
+  # unique history, so in this case we do not need to do anything.
+  #
+  if [[ -o HIST_IGNORE_ALL_DUPS || -n $HISTORY_SUBSTRING_SEARCH_ENSURE_UNIQUE ]]; then
+    return
+  fi
+
+  if [[ -o HIST_FIND_NO_DUPS && $BUFFER == $_history_substring_search_result ]]; then
+    #
+    # Repeat the current search so that a different (unique) match is found.
+    #
+    _history-substring-search-up-search
+  fi
 }
 
-function _history-substring-search-down-search() {
+_history-substring-search-down-search() {
   _history_substring_search_refresh_display=1
 
   #
-  # Highlight matches during history-substring-up-search:
+  # Select history entry during history-substring-down-search:
   #
-  # The following constants have been initialized in
+  # The following variables have been initialized in
   # _history-substring-search-up/down-search():
   #
-  # $_history_substring_search_matches is the current list of matches
-  # $_history_substring_search_matches_count is the current number of matches
-  # $_history_substring_search_matches_count_plus is the current number of matches + 1
-  # $_history_substring_search_matches_count_sans is the current number of matches - 1
+  # $_history_substring_search_matches is the current list of matches that
+  # need to be displayed to the user.
   # $_history_substring_search_match_index is the index of the current match
+  # that is being displayed to the user.
   #
   # The range of values that $_history_substring_search_match_index can take
-  # is: [0, $_history_substring_search_matches_count_plus].  A value of 0
-  # indicates that we are beyond the end of
+  # is: [0, $#_history_substring_search_matches + 1].  A value of 0
+  # indicates that we are beyond the beginning of
   # $_history_substring_search_matches. A value of
-  # $_history_substring_search_matches_count_plus indicates that we are beyond
-  # the beginning of $_history_substring_search_matches.
+  # $#_history_substring_search_matches + 1 indicates that we are beyond
+  # the end of $_history_substring_search_matches and that we have also
+  # processed all entries in _history_substring_search_raw_matches.
   #
   # In _history-substring-search-down-search() the initial value of
-  # $_history_substring_search_match_index is
-  # $_history_substring_search_matches_count.  This value is set in
-  # _history-substring-search-begin().
-  # _history-substring-search-down-search() will initially increase it to
-  # $_history_substring_search_matches_count_plus.
+  # $_history_substring_search_match_index is 1. This value is set in
+  # _history-substring-search-begin(). _history-substring-search-down-search()
+  # will initially decrement it to 0.
   #
-  if [[ $_history_substring_search_match_index -le $_history_substring_search_matches_count_sans ]]; then
-    #
-    # Highlight the next match:
-    #
-    # 1. Increase $_history_substring_search_match_index by 1.
-    #
-    # 2. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
-    #    to highlight the current buffer.
-    #
-    (( _history_substring_search_match_index++ ))
-    BUFFER=$history[$_history_substring_search_matches[$_history_substring_search_match_index]]
-    _history_substring_search_query_highlight=$HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
 
-  elif [[ $_history_substring_search_match_index -eq $_history_substring_search_matches_count ]]; then
+  if [[ $_history_substring_search_match_index -lt 1 ]]; then
     #
-    # We will move beyond the beginning of $_history_substring_search_matches:
+    # We are beyond the beginning of $_history_substring_search_matches.
     #
-    # 1. Increase $_history_substring_search_match_index by 1.
+    # 1. Update display to indicate search not found.
     #
-    # 2. Save the current buffer in $_history_substring_search_old_buffer, so
-    #    that it can be retrieved by _history-substring-search-up-search()
-    #    later.
-    #
-    # 3. Make $BUFFER equal to $_history_substring_search_query.
-    #
-    # 4. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
-    #    to highlight the current buffer.
-    #
-    (( _history_substring_search_match_index++ ))
     _history-substring-search-not-found
+    return
+  fi
 
-  elif [[ $_history_substring_search_match_index -eq 0 ]]; then
+  if _history-substring-search-has-prev; then
     #
-    # We were beyond the end of $_history_substring_search_matches but DOWN
-    # makes us move back to the $_history_substring_search_matches:
+    # We do have younger matches.
     #
-    # 1. Increase $_history_substring_search_match_index by 1.
+    # 1. Move index to point to the previous match.
+    # 2. Update display to indicate search found.
     #
-    # 2. Restore $BUFFER from $_history_substring_search_old_buffer.
-    #
-    # 3. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
-    #    to highlight the current buffer.
-    #
-    (( _history_substring_search_match_index++ ))
-    BUFFER=$_history_substring_search_old_buffer
-    _history_substring_search_query_highlight=$HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
+    (( _history_substring_search_match_index-- ))
+    _history-substring-search-found
 
   else
     #
-    # We are at the end of history and there are no further matches.
+    # We do not have younger matches.
     #
+    # 1. Move the index beyond the beginning of
+    #    _history_substring_search_matches.
+    # 2. Update display to indicate search not found.
+    #
+    (( _history_substring_search_match_index-- ))
     _history-substring-search-not-found
   fi
+
+  #
+  # When HIST_FIND_NO_DUPS is set, meaning that only unique command lines from
+  # history should be matched, make sure the new and old results are different.
+  #
+  # However, if the HIST_IGNORE_ALL_DUPS shell option, or
+  # HISTORY_SUBSTRING_SEARCH_ENSURE_UNIQUE is set, then we already have a
+  # unique history, so in this case we do not need to do anything.
+  #
+  if [[ -o HIST_IGNORE_ALL_DUPS || -n $HISTORY_SUBSTRING_SEARCH_ENSURE_UNIQUE ]]; then
+    return
+  fi
+
+  if [[ -o HIST_FIND_NO_DUPS && $BUFFER == $_history_substring_search_result ]]; then
+    #
+    # Repeat the current search so that a different (unique) match is found.
+    #
+    _history-substring-search-down-search
+  fi
 }
 
 # -*- mode: zsh; sh-indentation: 2; indent-tabs-mode: nil; sh-basic-offset: 2; -*-