diff options
| -rw-r--r-- | ChangeLog | 5 | ||||
| -rw-r--r-- | Doc/Zsh/contrib.yo | 162 |
2 files changed, 166 insertions, 1 deletions
diff --git a/ChangeLog b/ChangeLog index 41a56f966..ef35827d2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2015-09-24 Barton E. Schaefer <schaefer@zsh.org> + + * 36623: Doc/Zsh/contrib.yo: document bracketed-paste-magic and + url-quote-magic; add cross-reference to vim text object widgets + 2015-09-24 Mikael Magnusson <mikachu@gmail.com> * 36603: Src/glob.c: fix dirfd leak during Y shortcut qualifier diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index 741d4ad07..b966e781c 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -1705,7 +1705,10 @@ item(tt(select-word-style), tt(match-word-context), tt(match-words-by-style))( The eight `tt(-match)' functions are drop-in replacements for the builtin widgets without the suffix. By default they behave in a similar way. However, by the use of styles and the function tt(select-word-style), -the way words are matched can be altered. +the way words are matched can be altered. For comparison, the widgets +described in ifzman(zmanref(zshzle) under Text Objects)\ +ifnzman(noderef(Text Objects)) use fixed definitions of words, compatible +with the tt(vim) editor. The simplest way of configuring the functions is to use tt(select-word-style), which can either be called as a normal function with @@ -1895,6 +1898,100 @@ The tt(word-context) style is implemented by the function tt(match-word-context). This should not usually need to be called directly. ) +tindex(bracketed-paste-magic) +item(bracketed-paste-magic)( +The tt(bracketed-paste) widget (see ifzman(subsection Miscellaneous in +zmanref(zshzle))ifnzman(noderef(Miscellaneous) in noderef(Zle Widgets))) +inserts pasted text literally into the editor buffer rather than interpret +it as keystrokes. This disables some common usages where the self-insert +widget is replaced in order to accomplish some extra processing. An +example is the contributed tt(url-quote-magic) widget described below. + +The tt(bracketed-paste-magic) widget is meant to replace tt(bracketed-paste) +with a wrapper that re-enables these self-insert actions, and other +actions as selected by zstyles. Therefore this widget is installed with +ifzman() +example(autoload -Uz bracketed-paste-magic +zle -N bracketed-paste bracketed-paste-magic) + +Other than enabling some widget processing, tt(bracketed-paste-magic) +attempts to replicate tt(bracketed-paste) as faithfully as possible. + +The following zstyles may be set to control processing of pasted text. +All are looked up in the context `tt(:bracketed-paste-magic)'. + +startitem() +item(tt(active-widgets))( +A list of patterns matching widget names that should be activated during +the paste. All other key sequences are processed as self-insert-unmeta. +The default is `tt(self-*)' so any user-defined widgets named with that +prefix are active along with the builtin self-insert. + +If this style is not set (explicitly deleted) or set to an empty value, +no widgets are active and the pasted text is inserted literally. If the +value includes `tt(undefined-key)', any unknown sequences are discarded +from the pasted text. +) +item(tt(inactive-keys))( +The inverse of tt(active-widgets), a list of key sequences that always use +tt(self-insert-unmeta) even when bound to an active widget. Note that +this is a list of literal key sequences, not patterns. +) +item(tt(paste-init))( +A list of function names, called in widget context (but not as widgets). +The functions are called in order until one of them returns a non-zero +status. The parameter `tt(PASTED)' contains the initial state of the +pasted text. All other ZLE parameters such as `tt(BUFFER)' have their +normal values and side-effects, and full history is available, so for +example tt(paste-init) functions may move words from tt(BUFFER) into +tt(PASTED) to make those words visible to the tt(active-widgets). + +A non-zero return from a tt(paste-init) function does em(not) prevent the +paste itself from proceeding. + +Loading tt(bracketed-paste-magic) defines tt(backward-extend-paste), a +helper function for use in tt(paste-init). + +example(zstyle :bracketed-paste-magic paste-init \ + backward-extend-paste) + +When a paste would insert into the middle of a word or append text to a +word already on the line, tt(backward-extend-paste) moves the prefix +from tt(LBUFFER) into tt(PASTED) so that the tt(active-widgets) see the +full word so far. This may be useful with tt(url-quote-magic). +) +item(tt(paste-finish))( +Another list of function names called in order until one returns non-zero. +These functions are called em(after) the pasted text has been processed +by the tt(active-widgets), but em(before) it is inserted into `tt(BUFFER)'. +ZLE parameters have their normal values and side-effects. + +A non-zero return from a tt(paste-finish) function does em(not) prevent +the paste itself from proceeding. + +Loading tt(bracketed-paste-magic) also defines tt(quote-paste), a helper +function for use in tt(paste-finish). + +example(zstyle :bracketed-paste-magic paste-finish \ + quote-paste +zstyle :bracketed-paste-magic:finish quote-style \ + qqq) + +When the pasted text is inserted into tt(BUFFER), it is quoted per the +tt(quote-style) value. To forcibly turn off the built-in numeric prefix +quoting of tt(bracketed-paste), use: + +example(zstyle :bracketed-paste-magic:finish quote-style \ + none) +) +enditem() + +em(Important:) During tt(active-widgets) processing of the paste (after +tt(paste-init) and before tt(paste-finish)), tt(BUFFER) starts empty and +history is restricted, so cursor motions, etc., may not pass outside of +the pasted content. Text assigned to tt(BUFFER) by the active widgets +is copied back into tt(PASTED) before tt(paste-finish). +) tindex(copy-earlier-word) item(tt(copy-earlier-word))( This widget works like a combination of tt(insert-last-word) and @@ -2557,6 +2654,69 @@ start of the previous line. Using a numeric argument less than -1 has the effect of moving the line above the cursor up by minus that number of lines. ) +tindex(url-quote-magic) +item(tt(url-quote-magic))( +This widget replaces the built-in tt(self-insert) to make it easier to +type URLs as command line arguments. As you type, the input character is +analyzed and, if it may need quoting, the current word is checked for a +URI scheme. If one is found and the current word is not already in +quotes, a backslash is inserted before the input character. + +Styles to control quoting behavior: + +startitem() +item(tt(url-metas))( +This style is looked up in the context `tt(:url-quote-magic:)var(scheme)' +(where var(scheme) is that of the current URL, e.g. "tt(ftp)"). The value +is a string listing the characters to be treated as globbing +metacharacters when appearing in a URL using that scheme. The default is +to quote all zsh extended globbing characters, excluding 'tt(<)' and +'tt(>)' but including braces (as in brace expansion). See also +tt(url-seps). +) +item(tt(url-seps))( +Like tt(url-metas), but lists characters that should be considered command +separators, redirections, history references, etc. The default is to +quote the standard set of shell separators, excluding those that overlap +with the extended globbing characters, but including 'tt(<)' and +'tt(>)' and the first character of tt($histchars). +) +item(tt(url-globbers))( +This style is looked up in the context `tt(:url-quote-magic)'. The values +form a list of command names that are expected to do their own globbing +on the URL string. This implies that they are aliased to use the +`tt(noglob)' modifier. When the first word on the line matches one of the +values em(and) the URL refers to a local file (see tt(url-local-schema)), +only the tt(url-seps) characters are quoted; the tt(url-metas) are left +alone, allowing them to affect command-line parsing, completion, etc. The +default values are a literal `tt(noglob)' plus (when the tt(zsh/parameter) +module is available) any commands aliased to the helper function +`tt(urlglobber)' or its alias `tt(globurl)'. +) +item(tt(url-local-schema))( +This style is always looked up in the context `tt(:urlglobber)', even +though it is used by both url-quote-magic and urlglobber. The values form +a list of URI schema that should be treated as referring to local files by +their real local path names, as opposed to files which are specified +relative to a web-server-defined document root. The defaults are +"tt(ftp)" and "tt(file)". +) +item(tt(url-other-schema))( +Like tt(url-local-schema), but lists all other URI schema upon which +tt(urlglobber) and tt(url-quote-magic) should act. If the URI on the +command line does not have a scheme appearing either in this list or in +tt(url-local-schema), it is not magically quoted. The default values are +"tt(http)", "tt(https)", and "tt(ftp)". When a scheme appears both here +and in tt(url-local-schema), it is quoted differently depending on whether +the command name appears in tt(url-globbers). +) +enditem() + +Loading tt(url-quote-magic) also defines a helper function `tt(urlglobber)' +and aliases `tt(globurl)' to `tt(noglob urlglobber)'. This function takes +a local URL apart, attempts to pattern-match the local file portion of the +URL path, and then puts the results back into URL format again. +) tindex(which-command) item(tt(which-command))( This function is a drop-in replacement for the builtin widget |