.zsh/plugins/history-substring-search.zsh

   1 #!/usr/bin/env zsh
   2 #
   3 # This is a clean-room implementation of the Fish[1] shell's history search
   4 # feature, where you can type in any part of any previously entered command
   5 # and press the UP and DOWN arrow keys to cycle through the matching commands.
   6 #
   7 #-----------------------------------------------------------------------------
   8 # Usage
   9 #-----------------------------------------------------------------------------
  10 #
  11 # 1. Load this script into your interactive ZSH session:
  12 #
  13 #       % source history-substring-search.zsh
  14 #
  15 #    If you want to use the zsh-syntax-highlighting[6] script along with this
  16 #    script, then make sure that you load it *before* you load this script:
  17 #
  18 #       % source zsh-syntax-highlighting.zsh
  19 #       % source history-substring-search.zsh
  20 #
  21 # 2. Type any part of any previous command and then:
  22 #
  23 #     * Press the UP arrow key to select the nearest command that (1) contains
  24 #       your query and (2) is older than the current command in the command
  25 #       history.
  26 #
  27 #     * Press the DOWN arrow key to select the nearest command that (1)
  28 #       contains your query and (2) is newer than the current command in the
  29 #       command history.
  30 #
  31 #     * Press ^U (the Control and U keys simultaneously) to abort the search.
  32 #
  33 # 3. If a matching command spans more than one line of text, press the LEFT
  34 #    arrow key to move the cursor away from the end of the command, and then:
  35 #
  36 #     * Press the UP arrow key to move the cursor to the line above.  When the
  37 #       cursor reaches the first line of the command, pressing the UP arrow
  38 #       key again will cause this script to perform another search.
  39 #
  40 #     * Press the DOWN arrow key to move the cursor to the line below.  When
  41 #       the cursor reaches the last line of the command, pressing the DOWN
  42 #       arrow key again will cause this script to perform another search.
  43 #
  44 #-----------------------------------------------------------------------------
  45 # Configuration
  46 #-----------------------------------------------------------------------------
  47 #
  48 # This script defines the following global variables. You may override their
  49 # default values only after having loaded this script into your ZSH session.
  50 #
  51 # * HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND is a global variable that defines
  52 #   how the query should be highlighted inside a matching command. Its default
  53 #   value causes this script to highlight using bold, white text on a magenta
  54 #   background. See the "Character Highlighting" section in the zshzle(1) man
  55 #   page to learn about the kinds of values you may assign to this variable.
  56 #
  57 # * HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND is a global variable that
  58 #   defines how the query should be highlighted when no commands in the
  59 #   history match it. Its default value causes this script to highlight using
  60 #   bold, white text on a red background. See the "Character Highlighting"
  61 #   section in the zshzle(1) man page to learn about the kinds of values you
  62 #   may assign to this variable.
  63 #
  64 # * HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS is a global variable that defines
  65 #   how the command history will be searched for your query. Its default value
  66 #   causes this script to perform a case-insensitive search. See the "Globbing
  67 #   Flags" section in the zshexpn(1) man page to learn about the kinds of
  68 #   values you may assign to this variable.
  69 #
  70 #-----------------------------------------------------------------------------
  71 # History
  72 #-----------------------------------------------------------------------------
  73 #
  74 # This script was originally written by Peter Stephenson[2], who published it
  75 # to the ZSH users mailing list (thereby making it public domain) in September
  76 # 2009. It was later revised by Guido van Steen and released under the BSD
  77 # license (see below) as part of the fizsh[3] project in January 2011.
  78 #
  79 # It was later extracted from fizsh[3] release 1.0.1, refactored heavily, and
  80 # repackaged as both an oh-my-zsh plugin[4] and as an independently loadable
  81 # ZSH script[5] by Suraj N. Kurapati in 2011.
  82 #
  83 # It was further developed[4] by Guido van Steen, Suraj N. Kurapati, Sorin
  84 # Ionescu, and Vincent Guerci in 2011.
  85 #
  86 # [1]: http://fishshell.com
  87 # [2]: http://www.zsh.org/mla/users/2009/msg00818.html
  88 # [3]: http://sourceforge.net/projects/fizsh/
  89 # [4]: https://github.com/robbyrussell/oh-my-zsh/pull/215
  90 # [5]: https://github.com/sunaku/zsh-history-substring-search
  91 # [6]: https://github.com/nicoulaj/zsh-syntax-highlighting
  92 #
  93 ##############################################################################
  94 #
  95 # Copyright (c) 2009 Peter Stephenson
  96 # Copyright (c) 2011 Guido van Steen
  97 # Copyright (c) 2011 Suraj N. Kurapati
  98 # Copyright (c) 2011 Sorin Ionescu
  99 # Copyright (c) 2011 Vincent Guerci
 100 # All rights reserved.
 101 #
 102 # Redistribution and use in source and binary forms, with or without
 103 # modification, are permitted provided that the following conditions are met:
 104 #
 105 #  * Redistributions of source code must retain the above copyright
 106 #    notice, this list of conditions and the following disclaimer.
 107 #
 108 #  * Redistributions in binary form must reproduce the above
 109 #    copyright notice, this list of conditions and the following
 110 #    disclaimer in the documentation and/or other materials provided
 111 #    with the distribution.
 112 #
 113 #  * Neither the name of the FIZSH nor the names of its contributors
 114 #    may be used to endorse or promote products derived from this
 115 #    software without specific prior written permission.
 116 #
 117 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 118 # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 119 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 120 # ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 121 # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 122 # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 123 # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 124 # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 125 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 126 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 127 # POSSIBILITY OF SUCH DAMAGE.
 128 #
 129 ##############################################################################
 130
 131 #-----------------------------------------------------------------------------
 132 # configuration variables
 133 #-----------------------------------------------------------------------------
 134
 135 HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND='bg=magenta,fg=white,bold'
 136 HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND='bg=red,fg=white,bold'
 137 HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS='i'
 138
 139 #-----------------------------------------------------------------------------
 140 # the main ZLE widgets
 141 #-----------------------------------------------------------------------------
 142
 143 function history-substring-search-up() {
 144   _history-substring-search-begin
 145
 146   _history-substring-search-up-history ||
 147   _history-substring-search-up-buffer ||
 148   _history-substring-search-up-search
 149
 150   _history-substring-search-end
 151 }
 152
 153 function history-substring-search-down() {
 154   _history-substring-search-begin
 155
 156   _history-substring-search-down-history ||
 157   _history-substring-search-down-buffer ||
 158   _history-substring-search-down-search
 159
 160   _history-substring-search-end
 161 }
 162
 163 zle -N history-substring-search-up
 164 zle -N history-substring-search-down
 165
 166 bindkey '\e[A' history-substring-search-up
 167 bindkey '\e[B' history-substring-search-down
 168
 169 #-----------------------------------------------------------------------------
 170 # implementation details
 171 #-----------------------------------------------------------------------------
 172
 173 setopt extendedglob
 174 if [[ $ZSH_VERSION == 4.3.<4->* || $ZSH_VERSION == 4.<4->* \
 175     || $ZSH_VERSION == <5->* ]]; then
 176     zmodload -F zsh/parameter
 177 else
 178     zmodload zsh/parameter 2>/dev/null
 179 fi
 180 #
 181 # We have to "override" some keys and widgets if the
 182 # zsh-syntax-highlighting plugin has not been loaded:
 183 #
 184 # https://github.com/nicoulaj/zsh-syntax-highlighting
 185 #
 186 if [[ $+functions[_zsh_highlight] -eq 0 ]]; then
 187   #
 188   # Dummy implementation of _zsh_highlight()
 189   # that simply removes existing highlights
 190   #
 191   function _zsh_highlight() {
 192     region_highlight=()
 193   }
 194
 195   #
 196   # Remove existing highlights when the user
 197   # inserts printable characters into $BUFFER
 198   #
 199   function ordinary-key-press() {
 200     if [[ $KEYS == [[:print:]] ]]; then
 201       region_highlight=()
 202     fi
 203     zle .self-insert
 204   }
 205   zle -N self-insert ordinary-key-press
 206
 207   #
 208   # Override ZLE widgets to invoke _zsh_highlight()
 209   #
 210   # https://github.com/nicoulaj/zsh-syntax-highlighting/blob/
 211   # bb7fcb79fad797a40077bebaf6f4e4a93c9d8163/zsh-syntax-highlighting.zsh#L121
 212   #
 213   #--------------8<-------------------8<-------------------8<-----------------
 214   #
 215   # Copyright (c) 2010-2011 zsh-syntax-highlighting contributors
 216   # All rights reserved.
 217   #
 218   # Redistribution and use in source and binary forms, with or without
 219   # modification, are permitted provided that the following conditions are
 220   # met:
 221   #
 222   #  * Redistributions of source code must retain the above copyright
 223   #    notice, this list of conditions and the following disclaimer.
 224   #
 225   #  * Redistributions in binary form must reproduce the above copyright
 226   #    notice, this list of conditions and the following disclaimer in the
 227   #    documentation and/or other materials provided with the distribution.
 228   #
 229   #  * Neither the name of the zsh-syntax-highlighting contributors nor the
 230   #    names of its contributors may be used to endorse or promote products
 231   #    derived from this software without specific prior written permission.
 232   #
 233   # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 234   # IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 235   # THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 236   # PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 237   # CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 238   # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 239   # PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 240   # PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 241   # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 242   # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 243   # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 244
 245   # Load ZSH module zsh/zleparameter, needed to override user defined widgets.
 246   zmodload zsh/zleparameter 2>/dev/null || {
 247     echo 'zsh-syntax-highlighting: failed loading zsh/zleparameter, exiting.' >&2
 248     return -1
 249   }
 250
 251   # Override ZLE widgets to make them invoke _zsh_highlight.
 252   for event in ${${(f)"$(zle -la)"}:#(_*|orig-*|.run-help|.which-command)}; do
 253     if [[ "$widgets[$event]" == completion:* ]]; then
 254       eval "zle -C orig-$event ${${${widgets[$event]}#*:}/:/ } ; $event() { builtin zle orig-$event && _zsh_highlight } ; zle -N $event"
 255     else
 256       case $event in
 257         accept-and-menu-complete)
 258           eval "$event() { builtin zle .$event && _zsh_highlight } ; zle -N $event"
 259           ;;
 260
 261         # The following widgets should NOT remove any previously
 262         # applied highlighting. Therefore we do not remap them.
 263         .forward-char|.backward-char|.up-line-or-history|.down-line-or-history)
 264           ;;
 265
 266         .*)
 267           clean_event=$event[2,${#event}] # Remove the leading dot in the event name
 268           case ${widgets[$clean_event]-} in
 269             (completion|user):*)
 270               ;;
 271             *)
 272               eval "$clean_event() { builtin zle $event && _zsh_highlight } ; zle -N $clean_event"
 273               ;;
 274           esac
 275           ;;
 276         *)
 277           ;;
 278       esac
 279     fi
 280   done
 281   unset event clean_event
 282   #-------------->8------------------->8------------------->8-----------------
 283 fi
 284
 285 function _history-substring-search-begin() {
 286   _history_substring_search_move_cursor_eol=false
 287   _history_substring_search_query_highlight=
 288
 289   #
 290   # Continue using the previous $_history_substring_search_result by default,
 291   # unless the current query was cleared or a new/different query was entered.
 292   #
 293   if [[ -z $BUFFER || $BUFFER != $_history_substring_search_result ]]; then
 294     #
 295     # For the purpose of highlighting we will also keep
 296     # a version without doubly-escaped meta characters.
 297     #
 298     _history_substring_search_query=$BUFFER
 299
 300     #
 301     # $BUFFER contains the text that is in the command-line currently.
 302     # we put an extra "\\" before meta characters such as "\(" and "\)",
 303     # so that they become "\\\(" and "\\\)".
 304     #
 305     _history_substring_search_query_escaped=${BUFFER//(#m)[\][()|\\*?#<>~^]/\\$MATCH}
 306
 307     #
 308     # Find all occurrences of the search query in the history file.
 309     #
 310     # (k) turns it an array of line numbers.
 311     #
 312     # (on) seems to remove duplicates, which are default
 313     #      options. They can be turned off by (ON).
 314     #
 315     _history_substring_search_matches=(${(kon)history[(R)(#$HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS)*${_history_substring_search_query_escaped}*]})
 316
 317     #
 318     # Define the range of values that $_history_substring_search_match_index
 319     # can take: [0, $_history_substring_search_matches_count_plus].
 320     #
 321     _history_substring_search_matches_count=$#_history_substring_search_matches
 322     _history_substring_search_matches_count_plus=$(( _history_substring_search_matches_count + 1 ))
 323     _history_substring_search_matches_count_sans=$(( _history_substring_search_matches_count - 1 ))
 324
 325     #
 326     # If $_history_substring_search_match_index is equal to
 327     # $_history_substring_search_matches_count_plus, this indicates that we
 328     # are beyond the beginning of $_history_substring_search_matches.
 329     #
 330     # If $_history_substring_search_match_index is equal to 0, this indicates
 331     # that we are beyond the end of $_history_substring_search_matches.
 332     #
 333     # If we have initially pressed "up" we have to initialize
 334     # $_history_substring_search_match_index to
 335     # $_history_substring_search_matches_count_plus so that it will be
 336     # decreased to $_history_substring_search_matches_count.
 337     #
 338     # If we have initially pressed "down" we have to initialize
 339     # $_history_substring_search_match_index to
 340     # $_history_substring_search_matches_count so that it will be increased to
 341     # $_history_substring_search_matches_count_plus.
 342     #
 343     if [[ $WIDGET == history-substring-search-down ]]; then
 344        _history_substring_search_match_index=$_history_substring_search_matches_count
 345     else
 346       _history_substring_search_match_index=$_history_substring_search_matches_count_plus
 347     fi
 348   fi
 349 }
 350
 351 function _history-substring-search-end() {
 352   _history_substring_search_result=$BUFFER
 353
 354   # move the cursor to the end of the command line
 355   if [[ $_history_substring_search_move_cursor_eol == true ]]; then
 356     CURSOR=${#BUFFER}
 357   fi
 358
 359   # highlight command line using zsh-syntax-highlighting
 360   _zsh_highlight
 361
 362   # highlight the search query inside the command line
 363   if [[ -n $_history_substring_search_query_highlight && -n $_history_substring_search_query ]]; then
 364     #
 365     # The following expression yields a variable $MBEGIN, which
 366     # indicates the begin position + 1 of the first occurrence
 367     # of _history_substring_search_query_escaped in $BUFFER.
 368     #
 369     : ${(S)BUFFER##(#m$HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS)($_history_substring_search_query##)}
 370     local begin=$(( MBEGIN - 1 ))
 371     local end=$(( begin + $#_history_substring_search_query ))
 372     region_highlight+=("$begin $end $_history_substring_search_query_highlight")
 373   fi
 374
 375   # For debugging purposes:
 376   # zle -R "mn: "$_history_substring_search_match_index" m#: "${#_history_substring_search_matches}
 377   # read -k -t 200 && zle -U $REPLY
 378
 379   # Exit successfully from the history-substring-search-* widgets.
 380   true
 381 }
 382
 383 function _history-substring-search-up-buffer() {
 384   #
 385   # Check if the UP arrow was pressed to move the cursor within a multi-line
 386   # buffer. This amounts to three tests:
 387   #
 388   # 1. $#buflines -gt 1.
 389   #
 390   # 2. $CURSOR -ne $#BUFFER.
 391   #
 392   # 3. Check if we are on the first line of the current multi-line buffer.
 393   #    If so, pressing UP would amount to leaving the multi-line buffer.
 394   #
 395   #    We check this by adding an extra "x" to $LBUFFER, which makes
 396   #    sure that xlbuflines is always equal to the number of lines
 397   #    until $CURSOR (including the line with the cursor on it).
 398   #
 399   local buflines XLBUFFER xlbuflines
 400   buflines=(${(f)BUFFER})
 401   XLBUFFER=$LBUFFER"x"
 402   xlbuflines=(${(f)XLBUFFER})
 403
 404   if [[ $#buflines -gt 1 && $CURSOR -ne $#BUFFER && $#xlbuflines -ne 1 ]]; then
 405     zle up-line-or-history
 406     return true
 407   fi
 408
 409   false
 410 }
 411
 412 function _history-substring-search-down-buffer() {
 413   #
 414   # Check if the DOWN arrow was pressed to move the cursor within a multi-line
 415   # buffer. This amounts to three tests:
 416   #
 417   # 1. $#buflines -gt 1.
 418   #
 419   # 2. $CURSOR -ne $#BUFFER.
 420   #
 421   # 3. Check if we are on the last line of the current multi-line buffer.
 422   #    If so, pressing DOWN would amount to leaving the multi-line buffer.
 423   #
 424   #    We check this by adding an extra "x" to $RBUFFER, which makes
 425   #    sure that xrbuflines is always equal to the number of lines
 426   #    from $CURSOR (including the line with the cursor on it).
 427   #
 428   local buflines XRBUFFER xrbuflines
 429   buflines=(${(f)BUFFER})
 430   XRBUFFER="x"$RBUFFER
 431   xrbuflines=(${(f)XRBUFFER})
 432
 433   if [[ $#buflines -gt 1 && $CURSOR -ne $#BUFFER && $#xrbuflines -ne 1 ]]; then
 434     zle down-line-or-history
 435     return true
 436   fi
 437
 438   false
 439 }
 440
 441 function _history-substring-search-up-history() {
 442   #
 443   # Behave like up in ZSH, except clear the $BUFFER
 444   # when beginning of history is reached like in Fish.
 445   #
 446   if [[ -z $_history_substring_search_query ]]; then
 447
 448     # we have reached the absolute top of history
 449     if [[ $HISTNO -eq 1 ]]; then
 450       BUFFER=
 451
 452     # going up from somewhere below the top of history
 453     else
 454       zle up-history
 455     fi
 456
 457     return true
 458   fi
 459
 460   false
 461 }
 462
 463 function _history-substring-search-down-history() {
 464   #
 465   # Behave like down-history in ZSH, except clear the
 466   # $BUFFER when end of history is reached like in Fish.
 467   #
 468   if [[ -z $_history_substring_search_query ]]; then
 469
 470     # going down from the absolute top of history
 471     if [[ $HISTNO -eq 1 && -z $BUFFER ]]; then
 472       BUFFER=${history[1]}
 473       _history_substring_search_move_cursor_eol=true
 474
 475     # going down from somewhere above the bottom of history
 476     else
 477       zle down-history
 478     fi
 479
 480     return true
 481   fi
 482
 483   false
 484 }
 485
 486 function _history-substring-search-up-search() {
 487   _history_substring_search_move_cursor_eol=true
 488
 489   #
 490   # Highlight matches during history-substring-up-search:
 491   #
 492   # The following constants have been initialized in
 493   # _history-substring-search-up/down-search():
 494   #
 495   # $_history_substring_search_matches is the current list of matches
 496   # $_history_substring_search_matches_count is the current number of matches
 497   # $_history_substring_search_matches_count_plus is the current number of matches + 1
 498   # $_history_substring_search_matches_count_sans is the current number of matches - 1
 499   # $_history_substring_search_match_index is the index of the current match
 500   #
 501   # The range of values that $_history_substring_search_match_index can take
 502   # is: [0, $_history_substring_search_matches_count_plus].  A value of 0
 503   # indicates that we are beyond the end of
 504   # $_history_substring_search_matches. A value of
 505   # $_history_substring_search_matches_count_plus indicates that we are beyond
 506   # the beginning of $_history_substring_search_matches.
 507   #
 508   # In _history-substring-search-up-search() the initial value of
 509   # $_history_substring_search_match_index is
 510   # $_history_substring_search_matches_count_plus.  This value is set in
 511   # _history-substring-search-begin().  _history-substring-search-up-search()
 512   # will initially decrease it to $_history_substring_search_matches_count.
 513   #
 514   if [[ $_history_substring_search_match_index -ge 2 ]]; then
 515     #
 516     # Highlight the next match:
 517     #
 518     # 1. Decrease the value of $_history_substring_search_match_index.
 519     #
 520     # 2. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
 521     #    to highlight the current buffer.
 522     #
 523     (( _history_substring_search_match_index-- ))
 524     BUFFER=$history[$_history_substring_search_matches[$_history_substring_search_match_index]]
 525     _history_substring_search_query_highlight=$HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
 526
 527   elif [[ $_history_substring_search_match_index -eq 1 ]]; then
 528     #
 529     # We will move beyond the end of $_history_substring_search_matches:
 530     #
 531     # 1. Decrease the value of $_history_substring_search_match_index.
 532     #
 533     # 2. Save the current buffer in $_history_substring_search_old_buffer,
 534     #    so that it can be retrieved by
 535     #    _history-substring-search-down-search() later.
 536     #
 537     # 3. Make $BUFFER equal to $_history_substring_search_query.
 538     #
 539     # 4. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
 540     #    to highlight the current buffer.
 541     #
 542     (( _history_substring_search_match_index-- ))
 543     _history_substring_search_old_buffer=$BUFFER
 544     BUFFER=$_history_substring_search_query
 545     _history_substring_search_query_highlight=$HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
 546
 547   elif [[ $_history_substring_search_match_index -eq $_history_substring_search_matches_count_plus ]]; then
 548     #
 549     # We were beyond the beginning of $_history_substring_search_matches but
 550     # UP makes us move back to $_history_substring_search_matches:
 551     #
 552     # 1. Decrease the value of $_history_substring_search_match_index.
 553     #
 554     # 2. Restore $BUFFER from $_history_substring_search_old_buffer.
 555     #
 556     # 3. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
 557     #    to highlight the current buffer.
 558     #
 559     (( _history_substring_search_match_index-- ))
 560     BUFFER=$_history_substring_search_old_buffer
 561     _history_substring_search_query_highlight=$HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
 562   fi
 563 }
 564
 565 function _history-substring-search-down-search() {
 566   _history_substring_search_move_cursor_eol=true
 567
 568   #
 569   # Highlight matches during history-substring-up-search:
 570   #
 571   # The following constants have been initialized in
 572   # _history-substring-search-up/down-search():
 573   #
 574   # $_history_substring_search_matches is the current list of matches
 575   # $_history_substring_search_matches_count is the current number of matches
 576   # $_history_substring_search_matches_count_plus is the current number of matches + 1
 577   # $_history_substring_search_matches_count_sans is the current number of matches - 1
 578   # $_history_substring_search_match_index is the index of the current match
 579   #
 580   # The range of values that $_history_substring_search_match_index can take
 581   # is: [0, $_history_substring_search_matches_count_plus].  A value of 0
 582   # indicates that we are beyond the end of
 583   # $_history_substring_search_matches. A value of
 584   # $_history_substring_search_matches_count_plus indicates that we are beyond
 585   # the beginning of $_history_substring_search_matches.
 586   #
 587   # In _history-substring-search-down-search() the initial value of
 588   # $_history_substring_search_match_index is
 589   # $_history_substring_search_matches_count.  This value is set in
 590   # _history-substring-search-begin().
 591   # _history-substring-search-down-search() will initially increase it to
 592   # $_history_substring_search_matches_count_plus.
 593   #
 594   if [[ $_history_substring_search_match_index -le $_history_substring_search_matches_count_sans ]]; then
 595     #
 596     # Highlight the next match:
 597     #
 598     # 1. Increase $_history_substring_search_match_index by 1.
 599     #
 600     # 2. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
 601     #    to highlight the current buffer.
 602     #
 603     (( _history_substring_search_match_index++ ))
 604     BUFFER=$history[$_history_substring_search_matches[$_history_substring_search_match_index]]
 605     _history_substring_search_query_highlight=$HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
 606
 607   elif [[ $_history_substring_search_match_index -eq $_history_substring_search_matches_count ]]; then
 608     #
 609     # We will move beyond the beginning of $_history_substring_search_matches:
 610     #
 611     # 1. Increase $_history_substring_search_match_index by 1.
 612     #
 613     # 2. Save the current buffer in $_history_substring_search_old_buffer, so
 614     #    that it can be retrieved by _history-substring-search-up-search()
 615     #    later.
 616     #
 617     # 3. Make $BUFFER equal to $_history_substring_search_query.
 618     #
 619     # 4. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
 620     #    to highlight the current buffer.
 621     #
 622     (( _history_substring_search_match_index++ ))
 623     _history_substring_search_old_buffer=$BUFFER
 624     BUFFER=$_history_substring_search_query
 625     _history_substring_search_query_highlight=$HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
 626
 627   elif [[ $_history_substring_search_match_index -eq 0 ]]; then
 628     #
 629     # We were beyond the end of $_history_substring_search_matches but DOWN
 630     # makes us move back to the $_history_substring_search_matches:
 631     #
 632     # 1. Increase $_history_substring_search_match_index by 1.
 633     #
 634     # 2. Restore $BUFFER from $_history_substring_search_old_buffer.
 635     #
 636     # 3. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
 637     #    to highlight the current buffer.
 638     #
 639     (( _history_substring_search_match_index++ ))
 640     BUFFER=$_history_substring_search_old_buffer
 641     _history_substring_search_query_highlight=$HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
 642   fi
 643 }
 644
 645 # -*- mode: zsh; sh-indentation: 2; indent-tabs-mode: nil; sh-basic-offset: 2; -*-
 646 # vim: ft=zsh sw=2 ts=2 et