diff options
Diffstat (limited to 'Doc/Zsh')
| -rw-r--r-- | Doc/Zsh/compsys.yo | 10 | ||||
| -rw-r--r-- | Doc/Zsh/compwid.yo | 587 | ||||
| -rw-r--r-- | Doc/Zsh/guide.yo | 1 | ||||
| -rw-r--r-- | Doc/Zsh/mod_zftp.yo | 7 | ||||
| -rw-r--r-- | Doc/Zsh/zftpsys.yo | 435 |
5 files changed, 735 insertions, 305 deletions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 632cb3195..159f944c3 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -1,4 +1,4 @@ -texinode(Completion System)()(Zsh Modules)(Top) +texinode(Completion System)(Zftp Function System)(Zsh Modules)(Top) chapter(Completion System) cindex(completion, system) cindex(completion, programmable) @@ -165,8 +165,8 @@ var(function) autoloadable (exactly equivalent to tt(autoload )var(function)). ) xitem(tt(compconf) var(definitions...)) -xitem(tt(compconf)) -item(tt(compconf) [ tt(-l) ] var(keys...))( +xitem(tt(compconf) [ tt(-L) ] ) +item(tt(compconf) [ tt(-l) ] [ tt(-L) ] var(keys...))( Several aspects of the completion system can be configured by the user. The configuration values are stored under the keys described below in the associative array `tt(compconfig)'. After sourcing @@ -183,7 +183,9 @@ you should not set all values at once by doing `tt(compconfig=(...))'. In the second form (without arguments), this function lists all keys and their values. If given the tt(-l) option as its first argument, as in the last form, the other arguments are taken as names of keys and -the values of these keys are printed one per line. +the values of these keys are printed one per line. In either case, if the +tt(-L) option is given, the keys and values are printed as calls to this +function, usable to be put in a setup script. ) enditem() diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo index 0a626f4e1..34f1140b9 100644 --- a/Doc/Zsh/compwid.yo +++ b/Doc/Zsh/compwid.yo @@ -4,27 +4,27 @@ cindex(completion, widgets) cindex(completion, programmable) cindex(completion, controlling) sect(Description) -Completion widgets are defined using the tt(-C) option to the tt(zle) +Completion widgets are defined by the tt(-C) option to the tt(zle) builtin command provided by the tt(zle) module (see ifzman(zmanref(zshzle))\ ifnzman(noderef(The zle Module))\ -). For example, the invocation: +). For example, -indent(nofill( -tt(zle -C complete expand-or-complete completer))) +indent( +nofill(tt(zle -C complete expand-or-complete completer)) +) -defines a widget named tt(complete). If this widget is bound to a key +defines a widget named tt(complete). When this widget is bound to a key using the tt(bindkey) builtin command defined in the tt(zle) module (see ifzman(zmanref(zshzle))\ ifnzman(noderef(Zsh Line Editor))\ -) typing that key will make the completion code call the shell -function tt(completer). This function is responsible for generating -the possible matches using the builtins described below. Once the -function returns, the completion code takes over control again and -treats the matches the way the builtin widget tt(expand-or-complete) -would do it. For this second argument, the name of any of the builtin -widgets that handle completions can be given, i.e. it may be any of +), typing that key will call the shell function tt(completer). This +function is responsible for generating the possible matches using the +builtins described below. Once the function returns, the completion code +takes over control again and treats the matches as the builtin widget +tt(expand-or-complete) would do. For this second argument, the name of any +of the builtin widgets that handle completions can be given: tt(complete-word), tt(expand-or-complete), tt(expand-or-complete-prefix), tt(menu-complete), tt(menu-expand-or-complete), tt(reverse-menu-complete), @@ -40,94 +40,103 @@ endmenu() texinode(Special Parameters)(Builtin Commands)()(Completion Widgets) sect(Special Parameters) -Inside completion widgets some parameters have special meaning. They -will be used inside the widget function and other shell functions -called from it. Outside of these function they are not special to the -shell in any way. - -The parameters are used to give information about the internal state -from the completion code to the completion widget and can be set to -give information to the completion code from the completion -widget. Some of the builtin commands and the condition codes use or -change the current values of these parameters. While the completion -widget is active, these parameters are reset on each function exit to -the values they had when the function was entered. +Inside completion widgets, and any functions called from those, some +parameters have special meaning; outside these function they are not +special to the shell in any way. These parameters are used to pass +information between the completion code and the completion widget. Some of +the builtin commands and the condition codes use or change the current +values of these parameters. Any existing values will be hidden during +execution of completion widgets; except for tt(compstate), the parameters +are reset on each function exit (including nested function calls from +within the completion widget) to the values they had when the function was +entered. startitem() item(tt(words))( -This array contains the words from the line. +This array contains the words present on the command line currently being +edited. ) item(tt(CURRENT))( This is the number of the current word, i.e. the word the cursor is -currently on in the tt(words) array. Note that this value is only -correct, if the tt(ksharrays) options is not set. +currently on in the tt(words) array. Note that this value is only +correct if the tt(ksharrays) options is not set. ) item(tt(PREFIX))( -This should be set to that part of the current word that should be -taken as the string every possible match has to begin with. Initially -this will be set to the part of the current word from the beginning of -the word up to the position of the cursor. When +Initially this will be set to the part of the current word from the +beginning of the word up to the position of the cursor; it may be altered +to give a common prefix for all matches. ) item(tt(IPREFIX))( -When a part of the current word should not be considered part of the -matches, this part should be taken from the tt(PREFIX) parameter and -appended to this parameter. This will initially be set to the empty -string when called from the completion code. +Initially this will be set to the empty string. It functions like +tt(PREFIX), and gives a string which precedes the one in tt(PREFIX) and is +not considered part of the list of matches. Typically, a string is +transferred from the beginning of tt(PREFIX) to the end of tt(IPREFIX), for +example: + +tt(indent( +nofill(IPREFIX=${PREFIX%%\=*}=) +nofill(PREFIX=${PREFIX#*=}) +)) + +causes the part of the prefix up to and including the first equal sign not +to be treated as part of a matched string. ) item(tt(SUFFIX))( -This should be set to that part of the current word that should be -taken as the string every possible match has to end with. The -completion code sets this to the part of the current word from the -cursor position to the end. +Initially this will be set to the part of the current word from the +cursor position to the end; it may be altered to give a common suffix for +all matches. It is most useful when the option tt(COMPLETE_IN_WORD) is +set, as otherwise the whole word on the command line is treated as a +prefix. ) item(tt(ISUFFIX))( -Like tt(IPREFIX), but for a suffix that should not be considered part -of the matches. +As tt(IPREFIX), but for a suffix that should not be considered part +of the matches; note that the tt(ISUFFIX) string follows the tt(SUFFIX) +string. ) item(tt(compstate))( -This is an associative array with various keys and values the -completion uses to give informtaion to the completion widget and to -get information regarding the further processing from it. The keys -are: +This is an associative array with various keys and values that the +completion code uses to exchange information with the completion widget. +The keys are: startitem() item(tt(context))( This will be set by the completion code to the overall context -completion is attempted in. Possible values are: +in which completion is attempted. Possible values are: startitem() item(tt(command))( -when completing for a normal command (in a command position or for an -argument) +when completing for a normal command (either in a command position or for +an argument of the command). ) item(tt(redirect))( -when completing after a redirection operator +when completing after a redirection operator. ) item(tt(condition))( -when completing inside a `tt([[)...tt(]])' conditional expressing; in +when completing inside a `tt([[)...tt(]])' conditional expression; in this case the tt(words) array contains the words inside the -conditional expression +conditional expression. ) item(tt(math))( when completing in a mathematical environment such as a -`tt(LPAR()LPAR())...tt(RPAR()RPAR())' construct +`tt(LPAR()LPAR())...tt(RPAR()RPAR())' construct. ) item(tt(value))( -when completing the value of a parameter assignment +when completing the value of a parameter assignment. ) item(tt(array_value))( when completing inside the value of an array parameter assignment; in -this case the tt(words) array contains the words inside the parentheses +this case the tt(words) array contains the words inside the parentheses. ) item(tt(subscript))( -when completing inside a parameter subscript +when completing inside a parameter subscript. ) item(tt(parameter))( -when the name of a parameter in a parameter expansion +when completing the name of a parameter in a parameter expansion beginning +with tt($) but not tt(${). ) item(tt(brace_parameter))( -when the name of a parameter in a parameter expansion that started -with tt(${) +when completing the name of a parameter in a parameter expansion beginning +with tt(${). ) enditem() ) @@ -136,154 +145,147 @@ The name of the parameter when completing in a subscript or in the value of a parameter assignment. ) item(tt(redirect))( -The redirection operator when completing in a redirection position. +The redirection operator when completing in a redirection position, +i.e. one of tt(<), tt(>), etc. ) item(tt(quoting))( -If completion is done inside single quotes, this is set to the string -tt(single). When completing inside double quotes this is set to -tt(double). When completing inside backticks it is set to tt(backtick). +When completing inside single quotes, this is set to the string +tt(single); inside double quotes, the string +tt(double); inside backticks, the string tt(backtick). Otherwise it is unset. ) item(tt(quote))( When completing inside quotes, this contains the quotation character -(i.e. either a single quote, a double quote, or a backtick). +(i.e. either a single quote, a double quote, or a backtick). Otherwise it +is unset. ) item(tt(nmatches))( -This is always set to the number of matches generated and accepted by -the completion code so far. +The number of matches generated and accepted by the completion code so far. ) item(tt(matcher))( -When completion is used with a global match specification (i.e. a -tt(compctl) with only a tt(-M) option), this contains the -number of the specification string which is currently used. +When completion is performed with a global match specification as defined +by + +indent( +nofill(tt(compctl -M) var(spec1 ... specN ...)) +) + +this gives the number of the specification string currently in use. +In this case, matching is performed with each specification in turn. ) item(tt(matcher_string))( -This is set to the global match specification string currently used. +The global match specification string var(specN) currently used. ) item(tt(total_matchers))( The total number of global match specifications. ) item(tt(restore))( -This is set to tt(auto) before a function is entered. If a function -unsets it or sets it to any other string, the special parameters -mentioned above (tt(words), tt(CURRENT), tt(PREFIX), tt(IPREFIX), and -tt(SUFFIX)) will not be restored to their previous values when the -function exits as is normally done. +This is set to tt(auto) before a function is entered, which forces the +special parameters mentioned above (tt(words), tt(CURRENT), tt(PREFIX), +tt(IPREFIX), tt(SUFFIX), and tt(ISUFFIX)) to be restored to their +previous values when the function exits. If a function unsets it or +sets it to any other string, they will not be restored. ) item(tt(list))( -On entry to the completion widget this will be unset, if the set of -matches generated will not be listed. It is set to tt(list), -tt(autolist), or tt(ambiguous) if the matches will always be listed, -if they will be listed due to tt(AUTO_LIST) being set, or if they will -be listed if there is no unambiguous string to insert and -tt(LIST_AMBIGUOUS) is set, respectively. Inside the completion widget -it may be set to any of these values to make the completion code as if -the appropriate options had been set. +This controls whether or how the list of matches will be displayed. If it +is unset or empty they will never be listed; if is set to tt(list), they +will always be listed; if tt(autolist) or tt(ambiguous), they will be +listed when the tt(AUTO_LIST) or tt(LIST_AMBIGUOUS) options respectively +would normally cause them to be. It will be set appropriately on entry to +a completion widget and may be changed there. ) item(tt(force_list))( If the value for the tt(list) key is tt(ambiguous), the list will normally be shown only if there are at least two matches in the -list. Setting tt(force_list) to an non-empty string makes the list be +list. Setting tt(force_list) to an non-empty string forces the list to be shown even if there is only one match. ) item(tt(list_max))( Initially this is set to the value of the tt(LISTMAX) parameter. -Completion widgets may set it to any other numeric value and the value -stored at when the widget finishes will be used in the same way the -value of tt(LISTMAX) is used. +It may be set to any other numeric value; when the widget exits this value +will be used in the same way as the value of tt(LISTMAX). ) item(tt(last_prompt))( If this is set to an non-empty string, the completion code will move the cursor back to the previous prompt after the list of completions -has been displayed. Initially this is set depending on the setting of +has been displayed. Initially this is set or unset according to the tt(ALWAYS_LAST_PROMPT) option. ) item(tt(insert))( -This will be unset by the completon code if the contents of the -command line will not be changed. It is set to tt(unambiguous), -tt(menu), or tt(automenu) if a common unambiguous string will be -inserted or if the first match will be inserted and menu completion -will be started (due to tt(MENU_COMPLETE) or tt(AUTO_MENU) being set), -respectively. - -On exit it may be set to any of the values above with the obvious -result or to a number or a string of the form -`var(group):var(match)'. If it is set to a number the match whose -number is given will be inserted in the command line. A string like -`tt(2:4)' specifies which match from which group should be -inserted. In this example the fourth match of the second group is -inserted. All groups and matches are number from one upwards. In the -value of this key, negative numbers count backward from the last match -or group (with `tt(-1)' selecting the last match or group) and values -out of the range from one to the number of matches or groups are -wrapped around (so that a value of zero selects the last match and a -value equal to the number of matches or groups plus one selects the -first one). +This controls the manner in which a match is inserted into the command +line. On entry to the widget fuction, if it is unset the command line is +not to be changed; if set to tt(unambiguous), any prefix common to all +matches is to be inserted; if set to tt(menu) or tt(automenu) the usual +behaviour of the tt(MENU_COMPLETE) or tt(AUTO_MENU) options, respectively, +is to be used. + +On exit it may be set to any of the values above, or to a number, in which +case the match whose number is given will be inserted into the command line. +It may also be set to a string of the form `var(group):var(match)' which +specifies a match from a group of matches to be inserted, counting from 1 +upwards (e.g. `tt(2:4)' specifies the fourth match of the second group). +Negative numbers count backward from the last match or group (with `tt(-1)' +selecting the last match or group) and out-of-range values are wrapped +around, so that a value of zero selects the last match or group and a value +one more than the maximum selects the first. ) item(tt(to_end))( -On entry to the completion widget this is set to tt(single) if the -cursor would be moved to the end of the word only if completion -generated only one match and that is inserted into the line. Depending -on the original position of the cursor and the setting of the option -tt(ALWAYS_TO_END) this may also be set to the string tt(match) if the -cursor would be moved to the end if a whole match would be inserted -(either if there is only one match or if menucompletion is used). - -The value of this key after the completion widget exits will be used -to determin when the cursor will be moved to the end of the string -inserted into the line. If it is unset or set to the empty string, the -cursor will never be moved to the end. If it is set to tt(single), it -will be moved to the end only if completion generated only one -match. A value of tt(always) says to move the cursor always to the end -(even with normal completion when an unambiguous string is inserted), -and any other value says to move the cursor to the end when a full -match is inserted (a single match or the first match when using -menucompletion). +Specifies the occasions on which the cursor is moved to the end of a string +when a match is inserted. On entry to a widget function, it may be +tt(single) if this will happen when a single unambiguous match was inserted +or tt(match) if it will happen any time a match is inserted (for example, +by menucompletion; this is likely to be the effect of the tt(ALWAYS_TO_END) +option). + +On exit, it may be set to tt(single) as above. It may also be set to +tt(always), or to the empty string or unset; in those cases the cursor will +be moved to the end of the string always or never respectively. Any +other string is treated as tt(match). ) item(tt(old_list))( This is set to tt(yes) if there is still a valid list of completions -from a previous completion at the time the widget is invoked. Such a -list exists if it was generated by the previous key press. If the list -is also shown on the screen, the value of this key is tt(shown). +from a previous completion at the time the widget is invoked. This will +usually be the case if and only if the previous editing operation was a +completion widget or one of the builtin completion fuctions. If there is a +valid list and it is also currently shown on the screen, the value of this +key is tt(shown). After the widget has exited the value of this key is only used if it -was set to tt(keep). In this case, the completion code will continue -to use this old list. If the widget generated new matches, they will +was set to tt(keep). In this case the completion code will continue +to use this old list. If the widget generated new matches, they will not be used. ) item(tt(old_insert))( On entry to the widget this will be set to the number of the match of -an old list of completions that is currently inserted in the command +an old list of completions that is currently inserted into the command line. If no match has been inserted, this is unset. -As with tt(old_list), the value of this key will only be used if it is -the string tt(keep). If it was set to this value by the widget and -there was an old match inserted in the line, this match will be kept -and if the value of the tt(insert) key says that another match should -be inserted, this will be inserted after the old one. +As with tt(old_list), the value of this key will only be used if it is the +string tt(keep). If it was set to this value by the widget and there was an +old match inserted into the command line, this match will be kept and if +the value of the tt(insert) key specifies that another match should be +inserted, this will be inserted after the old one. ) item(tt(exact))( -This is set to tt(accept) if an exact match would be accepted by the -completion code due to tt(REC_EXACT) being set or it is unset if an -exact match would not be accepted. +Controls the behaviour when the tt(REC_EXACT) option is set. It will be +set to tt(accept) if an exact match would be accepted, and will be unset +otherwise. ) item(tt(exact_string))( -This is set to the string of an exact match if one was found and unset -otherwise. +The string of an exact match if one was found, otherwise unset. ) item(tt(pattern_match))( -If the option tt(GLOB_COMPLETE) is set, this is initially set to -`tt(*)' and unset otherwise. If the completion widget sets it to a -`tt(*)', the completion code will from then on behave as if -tt(GLOB_COMPLETE) is set, i.e. if the strings in tt(PREFIX) and -tt(SUFFIX) contain unquoted metacharacters, they will be treated as -patterns. If the string is set to any other non-empty string, the -strings will be treated as patterns but the code will not automatically -insert a star at the cursor position. +Locally controls the behaviour given by the tt(GLOB_COMPLETE) option. +Initially it is set to `tt(*)' if and only if the option is set. +The completion widget may set it to either of these two values, or to any +other non-empty string. If it is non-empty, unquoted metacharacters on the +command line will be treated as patterns; if it is `tt(*)', then +additionally a wildcard `tt(*)' is assumed at the cursor position; if +it is empty or unset, metacharacters will be treated literally. ) item(tt(pattern_insert))( -Normally this is set to tt(menu) which means that menu-completion will be -used whenever the matches were generated using pattern matching. If this +Normally this is set to tt(menu), which specifies that menu-completion will +be used whenever the matches were generated using pattern matching. If it is set to any other non-empty string by the user and menu-completion is not selected by other option settings, the code will insert an unambiguous string for the generated matches as with normal completion. @@ -293,10 +295,10 @@ This key is read-only and will always be set to the unambiguous string the completion code has generated for all matches added so far. ) item(tt(unambiguous_cursor))( -This gives the position the cursor would be placed at when the -unambiguous string would be inserted, relative to the value of the -tt(unambiguous) key. The cursor would be placed before the character -whise index is given by this key. +This gives the position the cursor would be placed at if the +unambiguous string in the tt(unambiguous) key were inserted, relative to +the value of that key. The cursor would be placed before the character +whose index is given by this key. ) enditem() ) @@ -308,12 +310,13 @@ startitem() findex(compgen) item(tt(compgen) var(flags ...))( -Generate matches according to the given var(flags) which can be any of -the option flags supported by the tt(compctl) builtin command (see +Generate matches according to the given var(flags). These can be any of +the normal option flags (not those for extended completion) supported by +the tt(compctl) builtin command (see ifzman(zmanref(zshcompctl))\ ifnzman(noderef(Programmable Completion))\ -) except for the tt(-t) and tt(-l) flags. Also, when using the tt(-K) -flag, the function given as argument to it can not access the command +) except for the tt(-t) and tt(-l) flags. However, when using the tt(-K) +flag, the function given as argument to it cannot access the command line with the tt(read) builtin command. The matches will be generated in the same way as if the completion code @@ -323,11 +326,11 @@ possible completions that match the prefix and suffix from the special parameters desribed above. These strings will be compared with the generated matches using the normal matching rules and any matching specifications given with the tt(-M) flag to tt(compgen) and the -global matching specifications given to the tt(compctl) builtin -command. +global matching specifications given via the tt(compctl -M )var(spec1 ...) +builtin command. -The return value can be used to test if matches were added. It is zero -if at least one match was added and non-zero otherwise. +The return value is zero if at least one match was added and non-zero +otherwise. ) xitem(tt(compadd) [ tt(-qQfnUam) ] [ tt(-F) var(array) ]) xitem([ tt(-P) var(prefix) ] [ tt(-S) var(suffix) ]) @@ -339,12 +342,12 @@ xitem([ tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ]) xitem([ tt(-M) var(match-spec) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ]) item([ tt(--) ] [ var(words) ... ])( -This builtin command can be used to add matches and directly control +This builtin command can be used to add matches directly and control all the information the completion code stores with each possible match. The return value is zero if at least one match was added and non-zero if no matches were added. -The completion code breaks the string to complete into six fields in +The completion code breaks the string to complete into seven fields in the order: indent( @@ -352,46 +355,43 @@ var(<ipre><apre><hpre><word><hsuf><asuf><isuf>) ) The first field -is an ignored prefix taken from the line, the contents of the +is an ignored prefix taken from the command line, the contents of the tt(IPREFIX) parameter plus the string given with the tt(-i) -option. With the tt(-U) option given, only the string from the tt(-i) -option is used. The field var(<apre>) is a optional prefix string that -should automatically be added by the completion code, this is what can -be gievn with the tt(-P) option. The var(<hpre>) field is a string +option. With the tt(-U) option, only the string from the tt(-i) +option is used. The field var(<apre>) is an optional prefix string +given with the tt(-P) option. The var(<hpre>) field is a string that is considered part of the match but that should not be shown when -listing completions, it is given with the tt(-p) option. E.g. for -functions that do filename generation, one might want to use this for -a common path prefix. var(<word>) is the part of the match that should -appear in the list of completions, one of the tt(words) given at the -end. The field var(<hsuf>) is like var(<hpre>) but gives a suffix that -should be matched but will not be listed. Finally, var(<asuf>) is the -suffix given with tt(-S) that should automatically be added by the -completion code and var(<isuf>) is like var(<ipre>), but taken from -the tt(ISUFFIX) parameter and the tt(-I) option. +listing completions, given with the tt(-p) option; for example, +functions that do filename generation might specify +a common path prefix this way. var(<word>) is the part of the match that +should appear in the list of completions, one of the tt(words) given at the +end. The suffixes var(<hsuf>), var(<asuf>) and var(<isuf>) correspond to +the prefixes var(<hpre>), var(<apre>) and var(<ipre>) and are given by the +options tt(-s), tt(-S) and tt(-I), respectively. The supported flags are: startitem() item(tt(-P) var(prefix))( -The same as for tt(compctl) and tt(compgen), it gives a string that -should be inserted before the given words when they are completed. The -string given is not considered to be part of the match. +As for tt(compctl) and tt(compgen), it gives a string to +be inserted before the given var(words). The +string given is not considered as part of the match. ) item(tt(-S) var(suffix))( -Like tt(-P) but gives a string that has to be inserted after the match. +Like tt(-P) but gives a string to be inserted after the match. ) item(tt(-p) var(hidden-prefix))( -This gives a string that should be inserted in the line before the +This gives a string that should be inserted into the command line before the match but that should not appear in the list of matches. Unless the -tt(-U) option is given, the string on the line has to match this -string. +tt(-U) option is given, this string must be matched as part of the string +on the command line. ) item(tt(-s) var(hidden-suffix))( Like `tt(-p)', but gives a string to insert after the match. ) item(tt(-i) var(ignored-prefix))( This gives a string to insert into the command line just before any -string given with the `tt(-P)' option. Without `tt(-P)' the string is +string given with the `tt(-P)' option. Without `tt(-P)' the string is inserted before the string given with `tt(-p)' or directly before the match. ) @@ -399,128 +399,123 @@ item(tt(-I) var(ignored-suffix))( Like tt(-i), but gives an ignored suffix. ) item(tt(-J) var(name))( -As for tt(compctl) and tt(compgen) this gives the name of the group +As for tt(compctl) and tt(compgen), this gives the name of the group of matches the words should be stored in. ) item(tt(-V) var(name))( Like tt(-J) but naming a unsorted group. ) item(tt(-X) var(explanation))( -The var(explanation) string will be printed with the list of matches, -as for tt(compctl -X). +As for tt(compctl) and tt(compgen), the var(explanation) string will be +printed with the list of matches. ) item(tt(-q))( -This flag has the same meaning as for tt(compctl) and tt(compgen), -too. It makes the suffix given with tt(-S) be automatically removed if -the next character typed is a blank or does not insert anything or if +As for tt(compctl) and tt(compgen), +the suffix given with tt(-S) will be automatically removed if +the next character typed is a blank or does not insert anything, or if the suffix consists of only one character and the next character typed is the same character. ) item(tt(-r) var(remove-chars))( -This makes the suffix given with tt(-S) be automatically removed if +This is a more versatile form of the tt(-q) option. +The suffix given with tt(-S) will be automatically removed if the next character typed inserts one of the characters given in the -var(remove-chars). This string is parsed as a characters class with -the usual backslash-sequences understood, e.g. using `tt(-r "a-z\t")' -removes the suffix if the next character typed inserts one of the -lower case letters or a TAB, and `tt(-r "^0-9")' removes the suffix if -the next character typed inserts anything but a digit. One extra +var(remove-chars). This string is parsed as a characters class and +understands the backslash sequences used by the tt(print) command. For +example, `tt(-r "a-z\t")' removes the suffix if the next character typed +inserts a lowercase character or a TAB, and `tt(-r "^0-9")' removes the +suffix if the next character typed inserts anything but a digit. One extra backslash sequence is understood in this string: `tt(\-)' stands for all characters that insert nothing. Thus `tt(-S "=" -q)' is the same as `tt(-S "=" -r "= \t\n\-")'. ) item(tt(-R) var(remove-func))( -For the cases where one wants to remove suffix and the tt(-r) option -does not give enough control, this option can be used. It stores the -name of the shell function var(remove-func) in the matches. If one of -the matches is finally accepted and the tt(-S)-suffix inserted, this -function will be called after the next character typed. It gets the -length of the suffix as its argument and can use the special -parameters available in zle widgets (see +This is another form of the tt(-r) option. When a suffix given with the +tt(-S) option has been inserted and the completion accepted, the function +var(remove-func) will be called after the next character typed. It is +passed the length of the suffix as an argument and can use the special +parameters available in ordinary (non-completion) zle widgets (see ifzman(zmanref(zshzle))\ ifnzman(noderef(Zsh Line Editor))\ ) to analyse and modify the command line. ) item(tt(-f))( -If this flag is given, the matches build are marked as being the names -of files. They need not be actual filenames, though. But if they are -and the option tt(LIST_TYPES) is set, the characters describing the -types of the files in the completion lists will be shown. This also -makes a slash automatically be added when the name of a directory is -completed. +If this flag is given, all of the matches built from var(words) are +marked as being the names of files. They are not required to be actual +filenames, but if they are, and the option tt(LIST_TYPES) is set, the +characters describing the types of the files in the completion lists will +be shown. This also forces a slash to be added when the name of a +directory is completed. ) item(tt(-W) var(file-prefix))( This option has the same meaning as for the tt(compctl) and tt(compgen) builtin commands. Here, however, only one string may be -given, not an array. This string is used as a pathname that will be -prepended to the given words and the prefix given with the tt(-p) -option to perform the file-tests when showing completion -listings. Hence it is only useful if combined with the tt(-f) flag, -since the tests will only be performed if that flag is given. +given, not an array. This string is a pathname that will be +prepended to each of the matches formed by the given var(words) together +with any prefix specified by the tt(-p) option to form a complete filename +for testing. Hence it is only useful if combined with the tt(-f) flag, as +the tests will not otherwise be performed. ) item(tt(-a))( -When used by tt(compctl) or tt(compgen) the completion code normally +In the tt(compctl) or tt(compgen) commands, the completion code normally builds two sets of matches: the normal one where words with one of the suffixes in the array parameter tt(fignore) are not considered possible matches, and the alternate set where the words excluded from the first set are stored. Normally only the matches in the first -set are used. But if this set is empty, the words from the alternate +set are used, but if this set is empty, the words from the alternate set are used. The tt(compadd) builtin does not use tt(fignore) parameter and -normally stores all words in the first set. With the tt(-a)-flag -given, however, they are all stored in the alternate set unless this -flag is overridden by the tt(-F) option. +normally stores all words in the first set. With the tt(-a)-flag +given, however, the given var(words) are stored in the alternate set unless +this flag is overridden by the tt(-F) option. ) item(tt(-F) var(array))( -This can be used to give an array containing suffixes like the +Specifies an array containing suffixes in the same form as the tt(fignore) parameter. Words with one of these suffixes are stored in the alternate set of matches and words without one of these suffixes are stored in the normal set. The var(array) may be the name of an array parameter or a list of -literal suffixes enclosed in parentheses as in `tt(-F "(.o .h)")'. If -the name of an array is given, the elements of the array are taken as -the suffixes. +literal suffixes enclosed in parentheses and quoted, as in `tt(-F "(.o +.h)")'. If the name of an array is given, the elements of the array are +taken as the suffixes. ) item(tt(-Q))( -As for tt(compctl) and tt(compgen) this flag instructs the completion +As for tt(compctl) and tt(compgen), this flag instructs the completion code not to quote any metacharacters in the words when inserting them -in the command line. +into the command line. ) item(tt(-M) var(match-spec))( -This option allows one to give local match specifications with the -same meaning and format as for the tt(compctl) and tt(compgen) -builtin commands. Note that they will only be used if the tt(-m) is -given, too. +As for tt(compctl) and tt(compgen), this gives local match specifications. +Note that they will only be used if the tt(-U) option is not given. ) item(tt(-n))( -Words added with tt(compadd) with this flag will be used as possible -matches as usual but they not appear in the completion listing. +Specifies that the words added are to be used as possible +matches, but are not to appear in the completion listing. ) item(tt(-U))( -If this flag is given, all words given will be accepted, no matching +If this flag is given, all words given will be accepted and no matching will be done by the completion code. Normally this is used in functions that do the matching themselves. Note that with tt(compadd) this option does not automatically turn on -menu completion if tt(AUTO_LIST) is set as the same options for the -tt(compctl) and tt(compgen) builtin command do. +menu completion if tt(AUTO_LIST), unlike the corresponding option of +tt(compctl) and tt(compgen) commands. ) item(tt(-O) var(array))( If this option is given, the var(words) are em(not) added to the set of -possible completions. Instead, matching is done as usual and all -var(words) given as arguments that are matched will be stored in the -array parameter whose name is given as var(array). +possible completions. Instead, matching is done as usual and all of the +var(words) given as arguments that match the string on the command line +will be stored in the array parameter whose name is given as var(array). ) item(tt(-A) var(array))( -Like the tt(-O) option this keeps the var(words) from being stored as -possible completions. The matching words are instead stored in the array -parameter given as var(array). In difference to the tt(-O) option this -does not store the unchanged var(words) given as arguments, but instead -the strings the completion code generated while matching. For example, +As the tt(-O) option, except that instead of those of the var(words) which +match being stored in var(array), the strings generated internally by the +completion code are stored. For example, with a matching specification of `tt(-M "L:|no=")', the string `tt(nof)' -on the line and the string `tt(foo)' as one of the var(words), this option -will make the string `tt(nofoo)' be stored in the array, whereas the tt(-O) +on the command line and the string `tt(foo)' as one of the var(words), this +option stores the string `tt(nofoo)' in the array, whereas the tt(-O) option stores the `tt(foo)' originally given. ) item(tt(-), tt(--))( @@ -535,9 +530,9 @@ xitem(tt(compset -P) [ var(number) ] var(pattern)) xitem(tt(compset -s) var(number)) xitem(tt(compset -S) [ var(number) ] var(pattern)) xitem(tt(compset -n) var(begin) [ var(end) ]) -item(tt(compset -p) var(beg-pat) [ var(end-pat) ])( -This builtin allows to easily modify the special parameters and at -the same time, to do tests on their values. +item(tt(compset -N) var(beg-pat) [ var(end-pat) ])( +This command simplifies modification of the special parameters, +while its return value allows tests on them to be carried out. The options are: @@ -554,19 +549,19 @@ tt(PREFIX) and appended to tt(IPREFIX). Without the optional var(number), the longest match is taken, but if var(number) is given, anything up to the var(number)'th match is -moved. If the var(number) is negative, the var(number)'th longest +moved. If the var(number) is negative, the var(number)'th longest match is moved. For example, if tt(PREFIX) contains the string -`tt(a=b=c)' doing tt(compset -P '*\=') will move the string `tt(a=b=)' -into the tt(IPREFIX) parameter, but tt(compset -P 1 '*\=') moves only +`tt(a=b=c)', then tt(compset -P '*\=') will move the string `tt(a=b=)' +into the tt(IPREFIX) parameter, but tt(compset -P 1 '*\=') will move only the string `tt(a=)'. ) item(tt(-s) var(number))( -Like tt(-p), but prepend the last var(number) characters from the -parameter tt(SUFFIX) to the contents of the parameter tt(ISUFFIX). +As tt(-p), but transfer the last var(number) characters from the +value of tt(SUFFIX) to the front of the value of tt(ISUFFIX). ) item(tt(-S) [ var(number) ] var(pattern))( -Like tt(-P), but matching from the end of tt(SUFFIX) and moving the -matched portion into the parameter tt(ISUFFIX). +As tt(-P), but match the last portion of tt(SUFFIX) and transfer the +matched portion to the front of the value of tt(ISUFFIX). ) item(tt(-n) var(begin) [ var(end) ])( If the current word position as specified by the parameter tt(CURRENT) @@ -576,52 +571,51 @@ of the parameter tt(CURRENT) is decremented by var(begin). If the optional var(end) is given, the modification is done only if the current word position is also less than or equal to var(end). In -this case, the words from position var(end) onwards are removed from -the tt(words) array, too. +this case, the words from position var(end) onwards are also removed from +the tt(words) array. -Both of these numbers may be negative to make them count backwards +Both var(begin) and var(end) may be negative to count backwards from the last element of the tt(words) array. ) item(tt(-N) var(beg-pat) [ var(end-pat) ])( -If one of the elements of the tt(words) array up to the one at the +If one of the elements of the tt(words) array before the one at the index given by the value of the parameter tt(CURRENT) matches the -pattern var(beg-pat), all elements up to the matching one are removed -from the tt(words) array and the value of tt(CURRENT) is changed to +pattern var(beg-pat), all elements up to and including the matching one are +removed from the tt(words) array and the value of tt(CURRENT) is changed to point to the same word in the changed array. -If the optional pattern var(end-pat) is also given and there is an +If the optional pattern var(end-pat) is also given, and there is an element in the tt(words) array matching this pattern, the parameters are modified only if the index of this word is higher than the one -given by the tt(CURRENT) parameter (meaning that the matching word has -to be after the cursor). In this case, the words from the word -matching tt(end-pat) onwards are also removed from the tt(words) +given by the tt(CURRENT) parameter (so that the matching word has +to be after the cursor). In this case, the words starting with the one +matching tt(end-pat) are also removed from the tt(words) array. If tt(words) contains no word matching var(end-pat), the -testing and modification is done as if it were not given. +testing and modification is performed as if it were not given. ) enditem() -In all of these cases the return value is zero if the test succeded -and the parameters were modified, and non-zero otherwise. This allows -one to use this builtin in tests as in: +In all the above cases the return value is zero if the test succeded +and the parameters were modified and non-zero otherwise. This allows +one to use this builtin in tests such as: indent( tt(if compset -P '*\='; then ...) ) -Which makes anything up to and including the last equal sign be +This forces anything up to and including the last equal sign to be ignored by the completion code. ) item(tt(compcall) [ tt(-TD) ])( -This allows one to use completion definitions given with the -tt(compctl) builtin from within completion widgets. It makes the -completion code complete the current word according to the -tt(compctl)s defined. Normally only tt(compctl)s given for specific -commands are used. To make the code use the completion flags given to -the tt(-T) option of tt(compctl), one can give the tt(-T) flag to -tt(compctl). Likewise, the tt(-D) flag to tt(compcall) makes the -default completion flags given to tt(compctl) with the tt(-D) option -be used. +This allows the use of completions defined with the tt(compctl) builtin +from within completion widgets. The list of matches will be generated as +if one of the non-widget completion function (tt(complete-word), etc.) +had been called, except that only tt(compctl)s given for specific commands +are used. To force the code to try completions defined with the tt(-T) +option of tt(compctl) and/or the default completion (whether defined by +tt(compctl -D) or the builtin default) in the appropriate places, the +tt(-T) and/or tt(-D) flags can be passed to tt(compcall). The return value can be used to test if a matching tt(compctl) definition was found. It is non-zero if a tt(compctl) was found and @@ -632,30 +626,25 @@ enditem() texinode(Condition Codes)(Examples)(Builtin Commands)(Completion Widgets) sect(Condition Codes) -Inside completion widgets not only the builtin commands described -above can be used, but also some additional condition codes. These -work on the special parameters and can be used to easily build -completion functions that generate different matches depending on the -strings on the line. All of these condition codes perform tests also -done by the tt(compset) builtin, but they don't modify the contents of -the special parameters. - -The following condition codes are made available inside completion -widgets: +The following additional condition codes for use within the tt([[ ... ]]) +construct are available in completion widgets. These work on the special +parameters. All of these tests can also be performed by the tt(compset) +builtin, but in the case of the condition codes the contents of the special +parameters are not modified. startitem() item(tt(-prefix) [ var(number) ] var(pattern))( -true if the test for the tt(-P) option of tt(compset) would succeed +true if the test for the tt(-P) option of tt(compset) would succeed. ) item(tt(-suffix) [ var(number) ] var(pattern))( -true if the test for the tt(-S) option of tt(compset) would succeed +true if the test for the tt(-S) option of tt(compset) would succeed. ) item(tt(-after) var(beg-pat))( true if the test of the tt(-N) option with only the var(beg-pat) given -would succeed +would succeed. ) item(tt(-between) var(beg-pat end-pat))( -true if the test for the tt(-N) option with both patterns would succeed +true if the test for the tt(-N) option with both patterns would succeed. ) enditem() @@ -674,17 +663,17 @@ indent(nofill( tt(bindkey '^X\t' complete))) After that the shell function tt(complete-history) will be invoked -after typing control-X and TAB. The function should then generte the +after typing control-X and TAB. The function should then generate the matches, e.g.: indent(nofill( tt(complete-history LPAR()RPAR() { compgen -H 0 '' }))) -In this the function will complete words from the history matching the +This function will complete words from the history matching the current word. -For a description of the example completion system from the -distributions, see +For a description of the widget-based completion system provided with the +source code distribution, see ifzman(zmanref(zshcompsys))\ ifnzman(noderef(Completion System))\ . diff --git a/Doc/Zsh/guide.yo b/Doc/Zsh/guide.yo index 81347da1f..f9c485875 100644 --- a/Doc/Zsh/guide.yo +++ b/Doc/Zsh/guide.yo @@ -32,6 +32,7 @@ menu(Programmable Completion) menu(Completion Widgets) menu(Zsh Modules) menu(Completion System) +menu(Zftp Function System) --- Indices --- diff --git a/Doc/Zsh/mod_zftp.yo b/Doc/Zsh/mod_zftp.yo index 395bf26de..ec16aa531 100644 --- a/Doc/Zsh/mod_zftp.yo +++ b/Doc/Zsh/mod_zftp.yo @@ -10,8 +10,11 @@ item(tt(zftp) var(subcommand) [ var(args) ])( The tt(zftp) module is a client for FTP (file transfer protocol). It is implemented as a builtin to allow full use of shell command line editing, file I/O, and job control mechanisms. Often, users will -access it via shell functions providing higher level abilities such as -username and password lookup. However, it is entirely usable in its +access it via shell functions providing a more powerful interface; a set is +provided with the tt(zsh) distribution and is described in +ifzman(zmanref(zshzftpsys))\ +ifnzman(noderef(Zftp Function System))\ +. However, the tt(zftp) command is entirely usable in its own right. All commands consist of the command name tt(zftp) followed by the name diff --git a/Doc/Zsh/zftpsys.yo b/Doc/Zsh/zftpsys.yo new file mode 100644 index 000000000..f20a0a6c3 --- /dev/null +++ b/Doc/Zsh/zftpsys.yo @@ -0,0 +1,435 @@ +texinode(Zftp Function System)()(Completion System)(Top) +chapter(Zftp Function System) +cindex(zftp, function system) +sect(Description) + +This describes the set of shell functions supplied with the source +distribution as an interface to the tt(zftp) builtin command, allowing you +to perform FTP operations from the shell command line or within functions +or scripts. The interface is similar to a traditional FTP client (e.g. the +manref(ftp)(1) command itself), but as it is entirely done within the shell +all the familar completion, editing and globbing features, and so on, are +present, and macros are particularly simple to write as they are just +ordinary shell functions. + +The prerequisite is that the tt(zftp) command, as described in +ifzman(\ +zmanref(zshmodules) +)\ +ifnzman(\ +noderef(The zftp Module) +), must be available in the +version of tt(zsh) installed at your site. If the shell is configured to +load new commands at run time, it probably is: typing tt(zmodload zftp) +will make sure (if that runs silently, it has worked). If this is not the +case, it is possible tt(zftp) was linked into the shell anyway: to test +this, type tt(which zftp) and if tt(zftp) is available you will get the +message tt(zftp: shell built-in command). + +Commands given directly with tt(zftp) builtin may be interspersed between +the functions in this suite; in a few cases, using tt(zftp) directly may +cause some of the status information stored in shell parameters to become +invalid. Note in particular the description of the variables +tt($ZFTP_TMOUT), tt($ZFTP_PREFS) and tt($ZFTP_VERBOSE) for tt(zftp). + +startmenu() +menu(Installation) +menu(Zftp Functions) +menu(Miscellaneous Features) +endmenu() + +texinode(Installation)(Zftp Functions)()(Zftp Function System) +sect(Installation) + +You should make sure all the functions from the tt(Functions/Zftp) +directory of the source distribution are available; they all begin with the +two letters tt(zf). They may already have been installed on your system; +otherwise, you will need to find them and copy them. The directory should +appear as one of the elements of the tt($fpath) array, and the functions +should be autoloaded. Finally, to initialise the use of the system you +need to call the tt(zfinit) function. The following code in your +tt(.zshrc) will arrange for this; assume the functions are stored in the +directory tt(~/myfns): + +tt(indent( +nofill(fpath=(~/myfns $fpath)) +nofill(autoload ~/myfns/zf*(:t)) +nofill(zfinit) +)) + +Note that tt(zfinit) assumes you are using the tt(zmodload) method to +load the tt(zftp) command. If it is already built into the shell, change +tt(zfinit) to tt(zfinit -n). + +texinode(Zftp Functions)(Miscellaneous Features)(Installation)(Zftp Function System) +sect(Functions) + +The sequence of operations in performing a file transfer is essentially the +same as that in a standard FTP client. + +subsect(Opening a connection) +startitem() +item(tt(zfparams [ var(host) [ var(user) [ var(password) ... ] ] ]))( +Set or show the parameters for a future tt(zfopen) with no arguments. If +no arguments are given, the current parameters are displayed (the password +will be shown as a line of asterisks). If a host is given, and either the +var(user) or var(password) is not, they will be prompted for; also, any +parameter given as `tt(?)' will be prompted for. + +As tt(zfopen) calls tt(zfparams) to store the parameters, this usually need +not be called directly. +) +item(tt(zfopen [ -1 ] [ var(host) [ var(user) [ var(password) [ var(account) ] ] ] ]))( +If var(host) is present, open a connection to that host under username +var(user) with password var(password) (and, on the rare occasions when it +is necessary account var(account)). If a necessary parameter is missing or +given as `tt(?)' it will be prompted for. If var(host) is not present, use +a previously stored set of parameters. + +If the command was successful, and the terminal is an tt(xterm), a summary +will appear in the title bar, giving the local tt(host:directory) and the +remote tt(host:directory); this is handled by the function tt(zftp_chpwd), +described below. + +Normally, the var(host), var(user) and var(password) are internally +recorded for later re-opening, either by a tt(zfopen) with no arguments, or +automatically (see below). With the option tt(-1), no information is +stored. +) +item(tt(zfanon [ -1 ] var(host)))( +Open a connection var(host) for anonymous FTP. The username used is +tt(anonymous). The password (which will be reported the first time) is +generated from var(user)tt(@)tt(host); this is then stored in the shell +parameter tt($EMAIL_ADDR) which can alternatively be set manually to a +suitable string. +) +enditem() + +subsect(Directory management) +startitem() +xitem(tt(zfcd [ var(dir) ])) +xitem(tt(zfcd -)) +item(tt(zfcd var(old) var(new)))( +Change the current directory on the remote server: this is implemented to +have many of the features of the shell builtin tt(cd). + +In the first form with var(dir) present, change to the directory var(dir). +The command tt(zfcd ..) is treated specially, so is guaranteed to work on +non-UNIX servers (note this is handled internall by tt(zftp)). If var(dir) +is omitted, has the effect of tt(zfcd ~). + +The second form changes to the directory previously current. + +The third form attempts to change the current directory by replacing the +first occurrence of the string var(old) with the string var(new) in the +current directory. + +Note that in this command, and indeed anywhere a remote filename is +expected, the string which on the local host corresponds to tt(~) is +converted back to a tt(~) before being passed to the remote machine. +This is convenient because of the way expansion is performed on the command +line before tt(zfcd) receives a string. For example, suppose the command +is tt(zfcd ~/foo). The shell will expand this to a full path as in tt(zfcd +/home/user2/pws/foo). At this stage, tt(zfcd) recognises the initial path +as tt(~), and the directory sent to the remote host is tt(~/foo), so that +the tt(~) will be expanded by the server to the correct remote host +directory. Other named directories of the form tt(~name) are not treated +in this fashion. +) +item(tt(zfhere))( +Change directory on the remote server to the one corresponding to the +current local directory, with special handling of tt(~) as in tt(zfcd). +For example, if the current local directory is tt(~/foo/bar), then +tt(zfhere) performs the effect of tt(zfcd ~/foo/bar). +) +item(tt(zfdir [ -rfd ] [ - ] [ var(dir-options) ] [ var(dir) ]))( +Produce a long directory listing. The arguments var(dir-options) and +var(dir) are passed directly to the server and their effect is +implementation dependent, but specifying a particular remote directory +var(dir) is usually possible. The output is passed through pager. + +The directory is usually cached for re-use. In fact, two caches are +maintained. One is for use when there is no var(dir-options) or var(dir), +i.e. a full listing of the current remote directory; it is flushed +when the current remote directory changes. The other is +kept for repeated use of tt(zfdir) with the same arguments; for example, +repeated use of tt(zfdir /pub/gnu) will only require the directory to be +retrieved on the first call. Alternatively, this cache can be re-viewed with +the tt(-r) option. As relative directories will confuse +tt(zfdir), the tt(-f) option can be used to force the cache to be flushed. +Also, the option tt(-d) will delete both caches without showing a directory +listing. +) +item(tt(zfls) [ var(ls-options) ] [ var(dir) ])( +List files on the remote server. With no arguments, this will produce a +simple list of file names for the current remote directory. Any arguments +are passed directory to the server. No pager and no caching is used. +) +enditem() + +subsect(Status commands) +startitem() +item(tt(zftype) [ var(type) ])( +With no arguments, show the type of data to be transferred, usually ASCII +or binary. With an argument, change the type: the types tt(A) or +tt(ASCII) for ASCII data and tt(B) or tt(BINARY), tt(I) or tt(IMAGE) for +binary data are understood case-insensitively. +) +item(tt(zfstat) [ -v ])( +Show the status of the current or last connection, as well as the status of +some of tt(zftp)'s status variables. With the tt(-v) option, a more +verbose listing is produced by querying the server for its version of +events, too. +) +enditem() + +subsect(Retrieving files) +The commands for retrieving files all take at least two options. tt(-G) +suppresses remote filename expansion which would otherwise be performed +(see below for a more detailed description of that). tt(-t) attempts +to set the modification time of the local file to that of the remote file: +this requires version 5 of tt(perl), see the description of the function +tt(zfrtime) below for more information. + +startitem() +item(tt(zfget [ -Gt ] var(file1) ...))( +Retrieve all the listed files var(file1) ... one at a time from the remote +server. If a file contains a `tt(/)', the full name is passed to the +remote server, but the file is stored locally under the name given by the +part after the final `tt(/)'. +) +item(tt(zfuget [ -Gvst ] var(file1) ...))( +As tt(zfget), but only retrieve files where the version on the remote +server is newer (has a later modification time), or where the local file +does not exist. If the remote file is older but the files have different +sizes, or if the sizes are the same but the remote file is newer, the user +will usually be queried. With the option tt(-s), the command runs silently +and will always retrieve the file in either of those two cases. With the +option tt(-v), the command prints more information about the files while it +is working out whether or not to transfer them. +) +item(tt(zfcget [ -Gt ] var(file1) ...))( +As tt(zfget), but if any of the local files exists, and is shorter than +the corresponding remote file, the command assumes that it is the result of +a partially completed transfer and attempts to transfer the rest of the +file. This is useful on a poor connection which keeps failing. + +Note that this requires a commonly implemented, but non-standard, version +of the FTP protocol, so is not guaranteed to work on all servers. +) +xitem(tt(zfgcp [ -Gt ] var(remote-file) var(local-file))) +item(tt(zfgcp [ -Gt ] var(rfile1) ... var(ldir)))( +This retrieves files from the remote server with arguments behaving +similarly to the tt(cp) command. + +In the first form, copy var(remote-file) from the server to the local file +var(local-file). + +In the second form, copy all the remote files var(rfile1) ... into the +local directory var(ldir) retaining the same basenames. This assumes UNIX +directory semantics. +) +enditem() + +subsect(Sending files) +startitem() +item(tt(zfput var(file1) ...))( +Send all the var(file1) ... given separately to the remote server. If a +filename contains a `tt(/)', the full filename is used locally to find the +file, but only the basename is used for the remote file name. +) +item(tt(zfuput [ -vs ] var(file1) ...))( +As tt(zfput), but only send files which are newer than their local +equivalents, or if the remote file does not exist. The logic is the same +as for tt(zfuget), but reversed between local and remote files. +) +item(tt(zfcput var(file1) ...))( +As tt(zfput), but if any remote file already exists and is shorter than the +local equivalent, assume it is the result of an incomplete transfer and +send the rest of the file to append to the existing part. As the FTP +append command is part of the standard set, this is in principle more +likely to work than tt(zfcget). +) +xitem(tt(zfpcp var(local-file) var(remote-file))) +item(tt(zfpcp var(lfile1) ... var(rdir)))( +This sends files to the remote server with arguments behaving similarly to +the tt(cp) command. + +With two arguments, copy var(local-file) to the server as +var(remote-file). + +With more than two arguments, copy all the local files var(lfile1) ... into +the existing remote directory var(rdir) retaining the same basenames. This +assumes UNIX directory semantics. + +A problem arises if you attempt to use tt(zfpcp) var(lfile1) var(rdir), +i.e. the second form of copying but with two arguments, as the command has +no simple way of knowing if var(rdir) corresponds to a directory or a +filename. It attempts to resolve this in various ways. First, if the +var(rdir) argument is tt(.) or tt(..) or ends in a slash, it is assumed to +be a directory. Secondly, if the operation of copying to a remote file in +the first form failed, and the remote server sends back the expected +failure code 553 and a reply including the string `tt(Is a directory)', +then tt(zfpcp) will retry using the second form. +) +enditem() + +subsect(Closing the connectino) +startitem() +item(tt(zfclose))( +Close the connection. +) +enditem() + +subsect(Other functions) +Mostly, these functions will not be called directly (apart from +tt(zfinit)), but are described here for completeness. You may wish to +alter tt(zftp_chpwd) and tt(zftp_progress), in particular. + +startitem() +item(tt(zfinit [ -n ]))( +As decribed above, this is used to initialise the zftp function system. +The tt(-n) option should be used if the zftp command is already built into +the shell. +) +item(tt(zfautocheck [ -dn ]))( +This function is called to implement automatic reopening behaviour, as +described in more detail below. The options must appear in the first +argument; tt(-n) prevents the command from changing to the old directory, +while tt(-d) prevents it from setting the variable tt(do_close), which it +otherwise does as a flag for automatically closing the connection after a +transfer. The host and directory for the last session are stored in the +variable tt($zflastsession), but the internal host/user/password parameters +must also be correctly set. +) +item(tt(zfcd_match var(prefix) var(suffix)))( +This performs matching for completion of remote directory names. If the +remote server is UNIX, it will attempt to persuade the server to list the +remote directory with subdirectories marked, which usually works but is not +guaranteed. On other hosts it simply calls tt(zfget_match) and hence +completes all files, not just directories. On some systems, directories +may not even look like filenames. +) +item(tt(zfget_match var(prefix) var(suffix)))( +This performs matching for completion of remote filenames. It caches files +for the current directory (only) in the shell parameter tt($zftp_fcache). +It is in the form to be called by the tt(-K) option of tt(compctl), but +also works when called from a widget-style completion function with +var(prefix) and var(suffix) set appropriately. +) +item(tt(zfrglob var(varname)))( +Perform remote globbing, as describes in more detail below. var(varname) +is the name of a variable containing the pattern to be expanded; if there +were any matches, the same variable will be set to the exanded set of +filenames on return. +) +item(tt(zfrtime var(lfile) var(rfile) [ var(time) ]))( +Set the local file var(lfile) to have the same modification time as the +remote file var(rfile), or the explicit time var(time) in FTP format +tt(CCYYMMDDhhmmSS) for the GMT timezone. + +Currently this requires tt(perl) version 5 to perform the conversion from +GMT to local time. This is unfortunately difficult to do using shell code +alone. +) +item(tt(zftp_chpwd))( +This function is called every time a connection is opened, or closed, or +the remote directory changes. This version alters the title bar of an +tt(xterm) or tt(sun-cmd) terminal emulator to reflect the local and remote +hostnames and current directories. It works best when combined with the +function tt(chpwd). In particular, a function of the form + +tt(indent( +nofill(chpwd() {) +nofill( if [[ -n $ZFTP_USER ]]; then) +nofill( zftp_chpwd) +nofill( else) +nofill( # usual chpwd e.g put host:directory in title bar) +nofill( fi) +nofill(}) +)) + +fits in well. +) +item(tt(zftp_progress))( +This function shows the status of the transfer as the percentage of the +total so far transferred. It will not write anything unless the output is +going to a terminal; however, if you transfer files in the background, you +should tt(unfunction) this first. (Background file transfers don't work on +all OSes.) Note also that if you alter it, any output em(must) be to +standard error, as standard output may be a file being received. +) +enditem() + +texinode(Miscellaneous Features)()(Zftp Functions)(Zftp Function System) +sect(Miscellaneous Features) + +subsect(Remote globbing) + +The commands for retrieving files usually perform filename expansion +(globbing) on their arguments; this can be turned off by passing the option +tt(-G) to each of the commands. Normally this operates by retrieving a +complete list of files for the directory in question, then matching these +locally against the pattern supplied. This has the advantage that the full +range of zsh patterns (respecting the setting of the option +tt(EXTENDED_GLOB)) can be used. However, it means that the directory part +of a filename will not be expanded and must be given exactly. If the +remote server does not support the UNIX directory semantics, directory +handling is problematic and it is recommended that globbing only be used +within the current directory. The list of files in the current directory, +if retrieved, will be cached, so that subsequent globs in the same +directory without an interventing tt(zfcd) are fast. + +If the variable tt($zfrglob) is set to a non-zero length, globbing is +instead performed on the remote host: the server is asked for a list of +matching files. This is highly dependent on how the server is implemented, +though typically UNIX servers will provide support for basic glob +patterns. This may in some cases be faster, as it avoids retrieving the +entire list of directory contents. + +subsect(Automatic and temporary reopening) + +As described for the tt(zfopen) command, a subsequent tt(zfopen) with no +parameters will reopen the connection to the last host (this includes +connections made with the tt(zfanon) command). Opened in this fashion, the +connection starts in the default remote directory and will remain open +until explicitly closed. + +Automatic re-opening is also available. If a connection is not currently +open and a command requiring a connection is given, the last connection is +implicitly reopened. In this case the directory which was current when the +connection was closed again becomes the current directory (unless, of +course, the command given changes it). Automatic reopening will also take +place if the connection was close by the remote server for whatever reason +(e.g. a timeout). It is not available if the tt(-1) option to tt(zfopen) +or tt(zfanon) was used. + +Furthermore, if the command issued is a file transfer, the connection will +be closed after the transfer is finished, hence providing a one-shot mode +for transfers. This does not apply to directory changing or listing +commands; for example a tt(zfdir) may reopen a connection but will leave it +open. Also, automatic closure will only ever happen in the same command as +automatic opening, i.e a tt(zfdir) directly followed by a tt(zfget) will +never close the connection automatically. + +Information about the previous connection is given by the tt(zfstat) +function. So, for example, if that reports: + +tt(indent( +nofill(Not connected.) +nofill(Last session: ftp.bar.com:/pub/textfiles) +)) + +then the command tt(zfget file.txt) will attempt to reopen a connection to +tt(ftp.bar.com), retrieve the file tt(/pub/textfiles/file.txt), and +immediately close the connection again. On the other hand, tt(zfcd ..) +will open the connection in the directory tt(/pub) and leave it open. + +subsect(Completion) + +Completion of remote files and directories is supported. The older, +tt(compctl)-style completion is defined when tt(zfinit) is called; support +for the new widget-based completion system is provided in the function +tt(Completion/Builtins/_zftp), which should be installed with the other +functions of the completion system and hence should automatically be +available. |