From 42ac9185c99bdbb82b971cce8ed90f7d546029b6 Mon Sep 17 00:00:00 2001 From: "Suraj N. Kurapati" Date: Fri, 24 Jun 2011 15:19:56 -0700 Subject: [PATCH] format comments to fit screen and be readable --- history-substring-search.zsh | 334 ++++++++++++++++++++++------------- 1 file changed, 210 insertions(+), 124 deletions(-) diff --git a/history-substring-search.zsh b/history-substring-search.zsh index 2ebd540..2123984 100644 --- a/history-substring-search.zsh +++ b/history-substring-search.zsh @@ -60,28 +60,34 @@ # ############################################################################## -# IMPORTANT / NOTE THAT: -# "up" (in e.g. "up-history()" corresponds with "backward" (in e.g. "history-substring-search-backward()" -# "down" (in e.g. "down-history()" corresponds with "forward" (in e.g. "history-substring-search-forward()" +# NOTE: The "up" in "up-history()" corresponds to "backward" +# in "history-substring-search-backward()", and so on. +# +# NOTE: The "down" in "down-history()" corresponds to "forward" +# in "history-substring-search-forward()", and so on. setopt extendedglob zmodload -F zsh/parameter -# We have to "override" some keys and widgets, unless -# the zsh-syntax-highlighting plugin has been loaded: +# +# We have to "override" some keys and widgets if the +# zsh-syntax-highlighting plugin has not been loaded: # # https://github.com/nicoulaj/zsh-syntax-highlighting # if [[ $+functions[_zsh_highlight] -eq 0 ]]; then - + # # Dummy implementation of _zsh_highlight() # that simply removes existing highlights + # function _zsh_highlight() { region_highlight=() } + # # Remove existing highlights when the user # inserts printable characters into $BUFFER + # function ordinary-key-press() { if [[ $KEYS = [[:print:]] ]]; then region_highlight=() @@ -90,6 +96,7 @@ if [[ $+functions[_zsh_highlight] -eq 0 ]]; then } zle -N self-insert ordinary-key-press + # # Override ZLE widgets to invoke _zsh_highlight() # # https://github.com/nicoulaj/zsh-syntax-highlighting/blob/ @@ -172,46 +179,59 @@ HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND='bg=red,fg=white,bold' HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS='i' # "i" means case insensitive, see "Globbing Flags" in zshexpn(1) _history-substring-search-begin() { - + # # Continue using the previous $_history_substring_search_result by default, # unless the current query was cleared or a new/different query was entered. + # if [[ -z $BUFFER || $BUFFER != $_history_substring_search_result ]]; then + # + # For the purpose of highlighting we will also keep + # a version without doubly-escaped meta characters. + # + _history_substring_search_query=$BUFFER - # BUFFER contains the text that is in the command-line currently. + # + # $BUFFER contains the text that is in the command-line currently. # we put an extra "\\" before meta characters such as "\(" and "\)", # so that they become "\\\(" and "\\\)". + # _history_substring_search_query_escaped=${BUFFER//(#m)[\][()|\\*?#<>~^]/\\$MATCH} - # For the purpose of highlighting we will also keep a version without - # doubly-escaped meta characters. - _history_substring_search_query=${BUFFER} - - # Find all occurrences of the pattern *${_history_substring_search_query}* within the history file. + # + # Find all occurrences of the search query in the history file. + # # (k) turns it an array of line numbers. - # (on) seems to remove duplicates, which are default options. They can be turned off by (ON). + # + # (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}*]}) + # # Define the range of values that $_history_substring_search_match_number # can take: [0, $_history_substring_search_number_of_matches_plus_one]. + # _history_substring_search_number_of_matches=${#_history_substring_search_matches} let "_history_substring_search_number_of_matches_plus_one = $_history_substring_search_number_of_matches + 1" let "_history_substring_search_number_of_matches_minus_one = $_history_substring_search_number_of_matches - 1" - # initial value of $_history_substring_search_match_number, which can - # only be decreased by ${WIDGET/forward/backward}. + # + # initial value of $_history_substring_search_match_number, + # which can only be decreased by ${WIDGET/forward/backward}. + # let "_history_substring_search_match_number = $_history_substring_search_number_of_matches_plus_one" fi } _history-substring-search-highlight() { _zsh_highlight - if [[ -n $_history_substring_search_query ]]; then - # $_history_substring_search_query_escaped string was not empty. - # So, highlight it: - # 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. + if [[ -n $_history_substring_search_query ]]; then + # + # 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. + # : ${(S)BUFFER##(#m$HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS)($_history_substring_search_query##)} let "_history_substring_search_query_mbegin = $MBEGIN - 1" let "_history_substring_search_query_mend = $_history_substring_search_query_mbegin + $#_history_substring_search_query" @@ -220,7 +240,7 @@ _history-substring-search-highlight() { } _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer() { - + # # Check if the UP arrow was pressed to move the cursor within a multi-line # buffer. This amounts to three tests: # @@ -231,20 +251,23 @@ _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer() # 3. Check if we are on the first line of the current multi-line buffer. # If so, pressing UP would amount to leaving the multi-line buffer. # - # We check this by adding an extra "x" to $LBUFFER, which makes sure that - # xlbuflines is always equal to the number of lines until $CURSOR - # (including the line with the cursor on it). + # We check this by adding an extra "x" to $LBUFFER, which makes + # sure that xlbuflines is always equal to the number of lines + # until $CURSOR (including the line with the cursor on it). # buflines=(${(f)BUFFER}) local XLBUFFER=$LBUFFER"x" xlbuflines=(${(f)XLBUFFER}) + if [[ $#buflines -gt 1 && $CURSOR -ne $#BUFFER && $#xlbuflines -ne 1 ]]; then zle up-line-or-history _history_substring_search_move_cursor_eol=false - - # $_history_substring_search_move_up_within_mutiline_buffer should reflect whether the call to + # + # $_history_substring_search_move_up_within_mutiline_buffer should reflect + # whether the call to # _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer() # has succeeded or failed: + # _history_substring_search_move_up_within_mutiline_buffer=true else _history_substring_search_move_up_within_mutiline_buffer=false @@ -252,7 +275,7 @@ _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer() } _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer() { - + # # Check if the DOWN arrow was pressed to move the cursor within a multi-line # buffer. This amounts to three tests: # @@ -263,20 +286,23 @@ _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer # 3. Check if we are on the last line of the current multi-line buffer. # If so, pressing DOWN would amount to leaving the multi-line buffer. # - # We check this by adding an extra "x" to $RBUFFER, which makes sure that - # xrbuflines is always equal to the number of lines from $CURSOR - # (including the line with the cursor on it). + # We check this by adding an extra "x" to $RBUFFER, which makes + # sure that xrbuflines is always equal to the number of lines + # from $CURSOR (including the line with the cursor on it). # buflines=(${(f)BUFFER}) local XRBUFFER="x"$RBUFFER xrbuflines=(${(f)XRBUFFER}) + if [[ $#buflines -gt 1 && $CURSOR -ne $#BUFFER && $#xrbuflines -ne 1 ]]; then zle down-line-or-history _history_substring_search_move_cursor_eol=false - - # $_history_substring_search_move_down_within_mutiline_buffer should reflect whether the call to + # + # $_history_substring_search_move_down_within_mutiline_buffer should + # reflect whether the call to # _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer() # has succeeded or failed: + # _history_substring_search_move_down_within_mutiline_buffer=true else _history_substring_search_move_down_within_mutiline_buffer=false @@ -284,22 +310,26 @@ _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer } _history-substring-search-check-up-history() { - - # When searching without a search query history-substring-search-backward should behave like - # up-history. Apart from this such a search should end with an empty BUFFER like in Fish. - if [[ $_history_substring_search_query == "" ]]; then - + # + # When searching without a search query history-substring-search-backward + # should behave like up-history. Apart from this, such a search should end + # with an empty $BUFFER like in Fish. + # + if [[ -z $_history_substring_search_query ]]; then # As long as we are not at the last history entry, call up-history(): if [[ $HISTNO -gt 1 ]]; then zle up-history else - - # [[ $HISTNO -eq 1 ]] means that _history-substring-search-check-UP-history() has arrived - # at the last entry of the history file. - # In that case we make $_history_substring_search_last_entry_in_history equal to $BUFFER. - # This value can later be retrieved by _history-substring-search-check-DOWN-history(). - # Moreover the current buffer should be made empty. - # In all other cases $_history_substring_search_last_entry_in_history should remain empty: + # + # [[ $HISTNO -eq 1 ]] means that + # _history-substring-search-check-UP-history() has arrived at the last + # entry of the history file. In that case we make + # $_history_substring_search_last_entry_in_history equal to $BUFFER. + # This value can later be retrieved by + # _history-substring-search-check-DOWN-history(). Moreover the current + # buffer should be made empty. In all other cases + # $_history_substring_search_last_entry_in_history should remain empty: + # [[ $#_history_substring_search_last_entry_in_history -eq 0 ]] && _history_substring_search_last_entry_in_history=$BUFFER BUFFER="" fi @@ -313,30 +343,35 @@ _history-substring-search-check-up-history() { } _history-substring-search-check-down-history() { - - # When searching without a search query the widget history-substring-search-forward should behave like - # down-history. Apart from this such a search should end with an empty buffer: - if [[ $_history_substring_search_query == "" ]]; then - - # If _history-substring-search-check-UP-history() has previously arrived at the last history entry - # it will have made $_history_substring_search_last_entry_in_history equal to $BUFFER - # (see the description of _history-substring-search-check-UP-history()). - # Therefore, here we test if $_history_substring_search_last_entry_in_history is equal - # to an empty string: + # + # When searching without a search query the widget + # history-substring-search-forward should behave like down-history. Apart + # from this, such a search should end with an empty buffer: + # + if [[ -z $_history_substring_search_query ]]; then + # + # If _history-substring-search-check-UP-history() has previously arrived + # at the last history entry it will have made + # $_history_substring_search_last_entry_in_history equal to $BUFFER (see + # the description of _history-substring-search-check-UP-history()). + # Therefore, here we test if + # $_history_substring_search_last_entry_in_history is equal to an empty + # string: + # if [[ $#_history_substring_search_last_entry_in_history -eq 0 ]]; then - # If so we can safely call down-history(): zle down-history else - - # If not we make $BUFFER equal to $_history_substring_search_last_entry_in_history - # and we move the the cursor to the end of the buffer: + # If not we make $BUFFER equal to + # $_history_substring_search_last_entry_in_history and we move the the + # cursor to the end of the buffer: BUFFER=$_history_substring_search_last_entry_in_history CURSOR=$#BUFFER - # And we make $_history_substring_search_last_entry_in_history equal to an empty string, - # so that later we will be able to call up-history() and down-history() again: - _history_substring_search_last_entry_in_history="" + # And we make $_history_substring_search_last_entry_in_history equal to + # an empty string, so that later we will be able to call up-history() + # and down-history() again: + _history_substring_search_last_entry_in_history='' fi # $_history_substring_search_down_history should reflect whether @@ -348,110 +383,159 @@ _history-substring-search-check-down-history() { } _history-substring-search-highlight-matches-up() { - # Highlight matches during a history-backward-search: # - # $_history_substring_search_matches: the current list of matches - # $_history_substring_search_number_of_matches: the current number of matches - # $_history_substring_search_number_of_matches_plus_one: the current number of matches + 1 - # $_history_substring_search_number_of_matches_minus_one: the current number of matches - 1 - # $_history_substring_search_match_number: the number of the current match - - # The range of values that $_history_substring_search_match_number can take is: - # [0, $_history_substring_search_number_of_matches_plus_one]. - # A value of 0 indicates that we are beyond the end of $_history_substring_search_matches. - # A value of $_history_substring_search_number_of_matches_plus_one indicates that we are beyond - # the beginning of $_history_substring_search_matches. - - # The initial value of $_history_substring_search_match_number is $_history_substring_search_number_of_matches_plus_one. - + # Highlight matches during a history-substring-search: + # + # * $_history_substring_search_matches: the current list of matches + # * $_history_substring_search_number_of_matches: the current number of matches + # * $_history_substring_search_number_of_matches_plus_one: the current number of matches + 1 + # * $_history_substring_search_number_of_matches_minus_one: the current number of matches - 1 + # * $_history_substring_search_match_number: the number of the current match + # + # The range of values that $_history_substring_search_match_number can take + # is: [0, $_history_substring_search_number_of_matches_plus_one]. A value + # of 0 indicates that we are beyond the end of + # $_history_substring_search_matches. A value of + # $_history_substring_search_number_of_matches_plus_one indicates that we + # are beyond the beginning of $_history_substring_search_matches. + # + # The initial value of $_history_substring_search_match_number is + # $_history_substring_search_number_of_matches_plus_one. + # if [[ $_history_substring_search_match_number -ge 2 ]]; then - + # # Highlight the next match: - # 1) Decrease the value of $_history_substring_search_match_number. - # 2) Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND to highlight the current buffer. + # + # 1. Decrease the value of $_history_substring_search_match_number. + # + # 2. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND + # to highlight the current buffer. + # let "_history_substring_search_match_number = $_history_substring_search_match_number - 1" BUFFER=$history[$_history_substring_search_matches[$_history_substring_search_match_number]] _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND - elif [[ $_history_substring_search_match_number -eq 1 ]]; then + elif [[ $_history_substring_search_match_number -eq 1 ]]; then + # # We will move beyond the end of $_history_substring_search_matches: - # 1) Decrease the value of $_history_substring_search_match_number. - # 2) Save the current buffer in $_history_substring_search_old_buffer, so that it can be retrieved by + # + # 1. Decrease the value of $_history_substring_search_match_number. + # + # 2. Save the current buffer in $_history_substring_search_old_buffer, + # so that it can be retrieved by # _history-substring-search-highlight-matches-down() later. - # 3) Make $BUFFER equal to $_history_substring_search_query. - # 4) Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND to highlight the current buffer. + # + # 3. Make $BUFFER equal to $_history_substring_search_query. + # + # 4. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND + # to highlight the current buffer. + # let "_history_substring_search_match_number = $_history_substring_search_match_number - 1" _history_substring_search_old_buffer=$BUFFER BUFFER=$_history_substring_search_query _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND - elif [[ $_history_substring_search_match_number -eq $_history_substring_search_number_of_matches_plus_one ]]; then - # We were beyond the beginning of $_history_substring_search_matches but UP makes us - # move back to $_history_substring_search_matches: - # 1) Decrease the value $of _history_substring_search_match_number. - # 2) Restore $BUFFER from $_history_substring_search_old_buffer. - # 3) Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND to highlight the current buffer. + elif [[ $_history_substring_search_match_number -eq $_history_substring_search_number_of_matches_plus_one ]]; then + # + # We were beyond the beginning of $_history_substring_search_matches but + # UP makes us move back to $_history_substring_search_matches: + # + # 1. Decrease the value $of _history_substring_search_match_number. + # + # 2. Restore $BUFFER from $_history_substring_search_old_buffer. + # + # 3. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND + # to highlight the current buffer. + # let "_history_substring_search_match_number = $_history_substring_search_match_number - 1" BUFFER=$_history_substring_search_old_buffer _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND fi + _history_substring_search_move_cursor_eol=true } _history-substring-search-highlight-matches-down() { - - # Highlight matches during a history-backward-search: + # + # Highlight matches during a history-substring-search: # # $_history_substring_search_matches: the current list of matches # $_history_substring_search_number_of_matches: the current number of matches # $_history_substring_search_number_of_matches_plus_one: the current number of matches + 1 # $_history_substring_search_number_of_matches_minus_one: the current number of matches - 1 # $_history_substring_search_match_number: the number of the current match - - # The range of values that $_history_substring_search_match_number can take is: - # [0, $_history_substring_search_number_of_matches_plus_one]. - # A value of 0 indicates that we are beyond the end of $_history_substring_search_matches. - # A value of $_history_substring_search_number_of_matches_plus_one indicates that we are beyond - # the beginning of $_history_substring_search_matches. - - # The initial value of $_history_substring_search_match_number is $_history_substring_search_number_of_matches_plus_one. + # + # The range of values that $_history_substring_search_match_number can take + # is: [0, $_history_substring_search_number_of_matches_plus_one]. A value + # of 0 indicates that we are beyond the end of + # $_history_substring_search_matches. A value of + # $_history_substring_search_number_of_matches_plus_one indicates that we + # are beyond the beginning of $_history_substring_search_matches. + # + # The initial value of $_history_substring_search_match_number is + # $_history_substring_search_number_of_matches_plus_one. + # if [[ $_history_substring_search_match_number -eq $_history_substring_search_number_of_matches_plus_one ]]; then - - # DOWN was pressed immediately. $_history_substring_search_match_number is still equal to - # $_history_substring_search_match_number_plus_one. However, there is no highlighting yet: - # 1) We have to use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND to highlight the current buffer. + # + # DOWN was pressed immediately. $_history_substring_search_match_number is + # still equal to $_history_substring_search_match_number_plus_one. + # However, there is no highlighting yet: + # + # 1. We have to use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND + # to highlight the current buffer. + # _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND - elif [[ $_history_substring_search_match_number -le $_history_substring_search_number_of_matches_minus_one ]]; then + elif [[ $_history_substring_search_match_number -le $_history_substring_search_number_of_matches_minus_one ]]; then + # # Highlight the next match: - # 1) Increase $_history_substring_search_match_number by 1. - # 2) Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND to highlight the current buffer. + # + # 1. Increase $_history_substring_search_match_number by 1. + # + # 2. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND + # to highlight the current buffer. + # let "_history_substring_search_match_number = $_history_substring_search_match_number + 1" BUFFER=$history[$_history_substring_search_matches[$_history_substring_search_match_number]] _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND - elif [[ $_history_substring_search_match_number -eq $_history_substring_search_number_of_matches ]]; then + elif [[ $_history_substring_search_match_number -eq $_history_substring_search_number_of_matches ]]; then + # # We will move beyond the beginning of $_history_substring_search_matches: - # 1) Increase $_history_substring_search_match_number by 1. - # 2) Save the current buffer in $_history_substring_search_old_buffer, so that it can be retrieved by - # _history-substring-search-highlight-matches-UP() later. - # 3) Make $BUFFER equal to $_history_substring_search_query. - # 4) Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND to highlight the current buffer. + # + # 1. Increase $_history_substring_search_match_number by 1. + # + # 2. Save the current buffer in $_history_substring_search_old_buffer, + # so that it can be retrieved by + # _history-substring-search-highlight-matches-up() later. + # + # 3. Make $BUFFER equal to $_history_substring_search_query. + # + # 4. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND + # to highlight the current buffer. + # let "_history_substring_search_match_number = $_history_substring_search_match_number + 1" _history_substring_search_old_buffer=$BUFFER BUFFER=$_history_substring_search_query _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND - elif [[ $_history_substring_search_match_number -eq 0 ]]; then - # We were beyond the end of $_history_substring_search_matches but DOWN makes us - # move back to the $_history_substring_search_matches: - # 1) Increase $_history_substring_search_match_number by 1. - # 2) Restore $BUFFER from $_history_substring_search_old_buffer. - # 3) Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND to highlight the current buffer. + elif [[ $_history_substring_search_match_number -eq 0 ]]; then + # + # We were beyond the end of $_history_substring_search_matches but DOWN + # makes us move back to the $_history_substring_search_matches: + # + # 1. Increase $_history_substring_search_match_number by 1. + # + # 2. Restore $BUFFER from $_history_substring_search_old_buffer. + # + # 3. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND + # to highlight the current buffer. + # let "_history_substring_search_match_number = $_history_substring_search_match_number + 1" BUFFER=$_history_substring_search_old_buffer _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND fi + _history_substring_search_move_cursor_eol=true } @@ -469,7 +553,7 @@ _history-substring-search-end() { # zle -R "mn: "$_history_substring_search_match_number" m#: "${#_history_substring_search_matches} # read -k -t 200 && zle -U $REPLY - # Suppress any errors: + # Exit successfully from the history-substring-search-* widgets. true } @@ -485,7 +569,8 @@ history-substring-search-backward() { # we only continue if we have NOT entered into up-history: if [[ $_history_substring_search_up_history == false ]]; then - # _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer sets a boolean named + # _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer + # sets a boolean named # $_history_substring_search_check_move_up_within_mutiline_buffer: _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer @@ -513,7 +598,8 @@ history-substring-search-forward() { # We only continue if we have NOT entered into down-history: if [[ $_history_substring_search_down_history == false ]]; then - # _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer sets a boolean named + # _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer + # sets a boolean named # $_history_substring_search_check_move_down_within_mutiline_buffer: _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer