diff options
Diffstat (limited to 'assets/info/zsh.info-4')
| -rw-r--r-- | assets/info/zsh.info-4 | 7058 |
1 files changed, 7058 insertions, 0 deletions
diff --git a/assets/info/zsh.info-4 b/assets/info/zsh.info-4 new file mode 100644 index 00000000..8ab37ffc --- /dev/null +++ b/assets/info/zsh.info-4 @@ -0,0 +1,7058 @@ +This is zsh.info, produced by makeinfo version 4.8 from ./zsh.texi. + +INFO-DIR-SECTION Utilities +START-INFO-DIR-ENTRY +* ZSH: (zsh). The Z Shell Manual. +END-INFO-DIR-ENTRY + + +File: zsh.info, Node: Completion Functions, Next: Completion System Variables, Prev: Bindable Commands, Up: Completion System + +20.6 Utility Functions +====================== + + + +Descriptions follow for utility functions that may be useful when +writing completion functions. If functions are installed in +subdirectories, most of these reside in the Base subdirectory. Like +the example functions for commands in the distribution, the utility +functions generating matches all follow the convention of returning +status zero if they generated completions and non-zero if no matching +completions could be added. + + +_absolute_command_paths + This function completes external commands as absolute paths (unlike + _command_names -e which completes their basenames). It takes no + arguments. + +_all_labels [ -x ] [ -12VJ ] TAG NAME DESCR [ COMMAND ARG ... ] + This is a convenient interface to the _next_label function below, + implementing the loop shown in the _next_label example. The + COMMAND and its arguments are called to generate the matches. The + options stored in the parameter NAME will automatically be inserted + into the ARGs passed to the COMMAND. Normally, they are put + directly after the COMMAND, but if one of the ARGs is a single + hyphen, they are inserted directly before that. If the hyphen is + the last argument, it will be removed from the argument list + before the COMMAND is called. This allows _all_labels to be used + in almost all cases where the matches can be generated by a single + call to the compadd builtin command or by a call to one of the + utility functions. + + For example: + + + local expl + ... + if _requested foo; then + ... + _all_labels foo expl '...' compadd ... - $matches + fi + + Will complete the strings from the matches parameter, using + compadd with additional options which will take precedence over + those generated by _all_labels. + +_alternative [ -O NAME ] [ -C NAME ] SPEC ... + This function is useful in simple cases where multiple tags are + available. Essentially it implements a loop like the one + described for the _tags function below. + + The tags to use and the action to perform if a tag is requested are + described using the SPECs which are of the form: + `TAG:DESCR:ACTION'. The TAGs are offered using _tags and if the + tag is requested, the ACTION is executed with the given + description DESCR. The ACTIONs are those accepted by the + _arguments function (described below), excluding the `->STATE' and + `=...' forms. + + For example, the ACTION may be a simple function call: + + + _alternative \ + 'users:user:_users' \ + 'hosts:host:_hosts' + + offers usernames and hostnames as possible matches, generated by + the _users and _hosts functions respectively. + + Like _arguments, this function uses _all_labels to execute the + actions, which will loop over all sets of tags. Special handling + is only required if there is an additional valid tag, for example + inside a function called from _alternative. + + The option `-O NAME' is used in the same way as by the _arguments + function. In other words, the elements of the NAME array will be + passed to compadd when executing an action. + + Like _tags this function supports the -C option to give a + different name for the argument context field. + +_arguments [ -nswWCRS ] [ -A PAT ] [ -O NAME ] [ -M MATCHSPEC ] + [ : ] SPEC ... +_arguments [ OPT ... ] -- [ -l ] [ -i PATS ] [ -s PAIR ] + [ HELPSPEC ...] + This function can be used to give a complete specification for + completion for a command whose arguments follow standard UNIX + option and argument conventions. + + _Options Overview_ + + Options to _arguments itself must be in separate words, i.e. -s -w, + not -sw. The options are followed by SPECs that describe options + and arguments of the analyzed command. To avoid ambiguity, all + options to _arguments itself may be separated from the SPEC forms + by a single colon. + + The `--' form is used to intuit SPEC forms from the help output of + the command being analyzed, and is described in detail below. The + OPTS for the `--' form are otherwise the same options as the first + form. Note that `-s' following `--' has a distinct meaning from + `-s' preceding `--', and both may appear. + + The option switches -s, -S, -A, -w, and -W affect how _arguments + parses the analyzed command line's options. These switches are + useful for commands with standard argument parsing. + + The options of _arguments have the following meanings: + + + -n + With this option, _arguments sets the parameter NORMARG to + the position of the first normal argument in the $words array, + i.e. the position after the end of the options. If that + argument has not been reached, NORMARG is set to -1. The + caller should declare `integer NORMARG' if the -n option is + passed; otherwise the parameter is not used. + + -s + Enable _option stacking_ for single-letter options, whereby + multiple single-letter options may be combined into a single + word. For example, the two options `-x' and `-y' may be + combined into a single word `-xy'. By default, every word + corresponds to a single option name (`-xy' is a single option + named `xy'). + + Options beginning with a single hyphen or plus sign are + eligible for stacking; words beginning with two hyphens are + not. + + Note that -s after -- has a different meaning, which is + documented in the segment entitled `Deriving SPEC forms from + the help output'. + + -w + In combination with -s, allow option stacking even if one or + more of the options take arguments. For example, if -x takes + an argument, with no -s, `-xy' is considered as a single + (unhandled) option; with -s, -xy is an option with the + argument `y'; with both -s and -w, -xy is the option -x and + the option -y with arguments to -x (and to -y, if it takes + arguments) still to come in subsequent words. + + -W + This option takes -w a stage further: it is possible to + complete single-letter options even after an argument that + occurs in the same word. However, it depends on the action + performed whether options will really be completed at this + point. For more control, use a utility function like _guard + as part of the action. + + -C + Modify the curcontext parameter for an action of the form + `->STATE'. This is discussed in detail below. + + -R + Return status 300 instead of zero when a $state is to be + handled, in the `->STRING' syntax. + + -S + Do not complete options after a `--' appearing on the line, + and ignore the `--'. For example, with -S, in the line + + + foobar -x -- -y + + the `-x' is considered an option, the `-y' is considered an + argument, and the `--' is considered to be neither. + + -A PAT + Do not complete options after the first non-option argument + on the line. PAT is a pattern matching all strings which are + not to be taken as arguments. For example, to make + _arguments stop completing options after the first normal + argument, but ignoring all strings starting with a hyphen + even if they are not described by one of the OPTSPECs, the + form is `-A "-*"'. + + -O NAME + Pass the elements of the array NAME as arguments to functions + called to execute ACTIONs. This is discussed in detail below. + + -M MATCHSPEC + Use the match specification MATCHSPEC for completing option + names and values. The default MATCHSPEC allows partial word + completion after `_' and `-', such as completing `-f-b' to + `-foo-bar'. The default MATCHSPEC is: + r:|[_-]=* r:|=* + + + _SPECs: overview_ + + Each of the following forms is a SPEC describing individual sets of + options or arguments on the command line being analyzed. + + + N:MESSAGE:ACTION + N::MESSAGE:ACTION + This describes the N'th normal argument. The MESSAGE will be + printed above the matches generated and the ACTION indicates + what can be completed in this position (see below). If there + are two colons before the MESSAGE the argument is optional. + If the MESSAGE contains only white space, nothing will be + printed above the matches unless the action adds an + explanation string itself. + + :MESSAGE:ACTION + ::MESSAGE:ACTION + Similar, but describes the _next_ argument, whatever number + that happens to be. If all arguments are specified in this + form in the correct order the numbers are unnecessary. + + *:MESSAGE:ACTION + *::MESSAGE:ACTION + *:::MESSAGE:ACTION + This describes how arguments (usually non-option arguments, + those not beginning with - or +) are to be completed when + neither of the first two forms was provided. Any number of + arguments can be completed in this fashion. + + With two colons before the MESSAGE, the words special array + and the CURRENT special parameter are modified to refer only + to the normal arguments when the ACTION is executed or + evaluated. With three colons before the MESSAGE they are + modified to refer only to the normal arguments covered by + this description. + + OPTSPEC + OPTSPEC:... + This describes an option. The colon indicates handling for + one or more arguments to the option; if it is not present, + the option is assumed to take no arguments. + + The following forms are available for the initial OPTSPEC, + whether or not the option has arguments. + + + *OPTSPEC + Here OPTSPEC is one of the remaining forms below. This + indicates the following OPTSPEC may be repeated. + Otherwise if the corresponding option is already present + on the command line to the left of the cursor it will + not be offered again. + + -OPTNAME + +OPTNAME + In the simplest form the OPTSPEC is just the option name + beginning with a minus or a plus sign, such as `-foo'. + The first argument for the option (if any) must follow + as a _separate_ word directly after the option. + + Either of `-+OPTNAME' and `+-OPTNAME' can be used to + specify that -OPTNAME and +OPTNAME are both valid. + + In all the remaining forms, the leading `-' may be + replaced by or paired with `+' in this way. + + -OPTNAME- + The first argument of the option must come directly + after the option name _in the same word_. For example, + `-foo-:...' specifies that the completed option and + argument will look like `-fooARG'. + + -OPTNAME+ + The first argument may appear immediately after OPTNAME + in the same word, or may appear as a separate word after + the option. For example, `-foo+:...' specifies that the + completed option and argument will look like either + `-fooARG' or `-foo ARG'. + + -OPTNAME= + The argument may appear as the next word, or in same + word as the option name provided that it is separated + from it by an equals sign, for example `-foo=ARG' or + `-foo ARG'. + + -OPTNAME=- + The argument to the option must appear after an equals + sign in the same word, and may not be given in the next + argument. + + OPTSPEC[EXPLANATION] + An explanation string may be appended to any of the + preceding forms of OPTSPEC by enclosing it in brackets, + as in `-q[query operation]'. + + The verbose style is used to decide whether the + explanation strings are displayed with the option in a + completion listing. + + If no bracketed explanation string is given but the + auto-description style is set and only one argument is + described for this OPTSPEC, the value of the style is + displayed, with any appearance of the sequence `%d' in + it replaced by the MESSAGE of the first OPTARG that + follows the OPTSPEC; see below. + + + It is possible for options with a literal `+' or `=' to + appear, but that character must be quoted, for example `-\+'. + + Each OPTARG following an OPTSPEC must take one of the + following forms: + + + :MESSAGE:ACTION + ::MESSAGE:ACTION + An argument to the option; MESSAGE and ACTION are + treated as for ordinary arguments. In the first form, + the argument is mandatory, and in the second form it is + optional. + + This group may be repeated for options which take + multiple arguments. In other words, + :MESSAGE1:ACTION1:MESSAGE2:ACTION2 specifies that the + option takes two arguments. + + :*PATTERN:MESSAGE:ACTION + :*PATTERN::MESSAGE:ACTION + :*PATTERN:::MESSAGE:ACTION + This describes multiple arguments. Only the last OPTARG + for an option taking multiple arguments may be given in + this form. If the PATTERN is empty (i.e. :*:), all the + remaining words on the line are to be completed as + described by the ACTION; otherwise, all the words up to + and including a word matching the PATTERN are to be + completed using the ACTION. + + Multiple colons are treated as for the `*:...' forms for + ordinary arguments: when the MESSAGE is preceded by two + colons, the words special array and the CURRENT special + parameter are modified during the execution or + evaluation of the ACTION to refer only to the words + after the option. When preceded by three colons, they + are modified to refer only to the words covered by this + description. + + + + Any literal colon in an OPTNAME, MESSAGE, or ACTION must be + preceded by a backslash, `\:'. + + Each of the forms above may be preceded by a list in parentheses + of option names and argument numbers. If the given option is on + the command line, the options and arguments indicated in + parentheses will not be offered. For example, `(-two -three + 1)-one:...' completes the option `-one'; if this appears on the + command line, the options -two and -three and the first ordinary + argument will not be completed after it. `(-foo):...' specifies + an ordinary argument completion; -foo will not be completed if + that argument is already present. + + Other items may appear in the list of excluded options to indicate + various other items that should not be applied when the current + specification is matched: a single star (*) for the rest arguments + (i.e. a specification of the form `*:...'); a colon (:) for all + normal (non-option-) arguments; and a hyphen (-) for all options. + For example, if `(*)' appears before an option and the option + appears on the command line, the list of remaining arguments + (those shown in the above table beginning with `*:') will not be + completed. + + To aid in reuse of specifications, it is possible to precede any + of the forms above with `!'; then the form will no longer be + completed, although if the option or argument appears on the + command line they will be skipped as normal. The main use for + this is when the arguments are given by an array, and _arguments + is called repeatedly for more specific contexts: on the first call + `_arguments $global_options' is used, and on subsequent calls + `_arguments !$^global_options'. + + _SPECs: actions_ + + In each of the forms above the ACTION determines how completions + should be generated. Except for the `->STRING' form below, the + ACTION will be executed by calling the _all_labels function to + process all tag labels. No special handling of tags is needed + unless a function call introduces a new one. + + The functions called to execute ACTIONs will be called with the + elements of the array named by the `-O NAME' option as arguments. + This can be used, for example, to pass the same set of options for + the compadd builtin to all ACTIONs. + + The forms for ACTION are as follows. + + + (single unquoted space) + This is useful where an argument is required but it is not + possible or desirable to generate matches for it. The + MESSAGE will be displayed but no completions listed. Note + that even in this case the colon at the end of the MESSAGE is + needed; it may only be omitted when neither a MESSAGE nor an + ACTION is given. + + (ITEM1 ITEM2 ...) + One of a list of possible matches, for example: + + + :foo:(foo bar baz) + + ((ITEM1\:DESC1 ...)) + Similar to the above, but with descriptions for each possible + match. Note the backslash before the colon. For example, + + + :foo:((a\:bar b\:baz)) + + The matches will be listed together with their descriptions + if the description style is set with the values tag in the + context. + + ->STRING + In this form, _arguments processes the arguments and options + and then returns control to the calling function with + parameters set to indicate the state of processing; the + calling function then makes its own arrangements for + generating completions. For example, functions that + implement a state machine can use this type of action. + + Where _arguments encounters ACTION in the `->STRING' format, + it will strip all leading and trailing whitespace from STRING + and set the array state to the set of all STRINGs for which an + action is to be performed. The elements of the array + state_descr are assigned the corresponding MESSAGE field from + each OPTARG containing such an ACTION. + + By default and in common with all other well behaved + completion functions, _arguments returns status zero if it + was able to add matches and non-zero otherwise. However, if + the -R option is given, _arguments will instead return a + status of 300 to indicate that $state is to be handled. + + In addition to $state and $state_descr, _arguments also sets + the global parameters `context', `line' and `opt_args' as + described below, and does not reset any changes made to the + special parameters such as PREFIX and words. This gives the + calling function the choice of resetting these parameters or + propagating changes in them. + + A function calling _arguments with at least one action + containing a `->STRING' must therefore declare appropriate + local parameters: + + + local context state state_descr line + typeset -A opt_args + + to prevent _arguments from altering the global environment. + + {EVAL-STRING} + A string in braces is evaluated as shell code to generate + matches. If the EVAL-STRING itself does not begin with an + opening parenthesis or brace it is split into separate words + before execution. + + = ACTION + If the ACTION starts with `= ' (an equals sign followed by a + space), _arguments will insert the contents of the ARGUMENT + field of the current context as the new first element in the + words special array and increment the value of the CURRENT + special parameter. This has the effect of inserting a dummy + word onto the completion command line while not changing the + point at which completion is taking place. + + This is most useful with one of the specifiers that restrict + the words on the command line on which the ACTION is to + operate (the two- and three-colon forms above). One + particular use is when an ACTION itself causes _arguments on + a restricted range; it is necessary to use this trick to + insert an appropriate command name into the range for the + second call to _arguments to be able to parse the line. + + WORD... + WORD... + This covers all forms other than those above. If the ACTION + starts with a space, the remaining list of words will be + invoked unchanged. + + Otherwise it will be invoked with some extra strings placed + after the first word; these are to be passed down as options + to the compadd builtin. They ensure that the state specified + by _arguments, in particular the descriptions of options and + arguments, is correctly passed to the completion command. + These additional arguments are taken from the array parameter + `expl'; this will be set up before executing the ACTION and + hence may be referred to inside it, typically in an expansion + of the form `$expl[@]' which preserves empty elements of the + array. + + + During the performance of the action the array `line' will be set + to the normal arguments from the command line, i.e. the words from + the command line after the command name excluding all options and + their arguments. Options are stored in the associative array + `opt_args' with option names as keys and their arguments as the + values. For options that have more than one argument these are + given as one string, separated by colons. All colons and + backslashes in the original arguments are preceded with + backslashes. + + The parameter `context' is set when returning to the calling + function to perform an action of the form `->STRING'. It is set + to an array of elements corresponding to the elements of $state. + Each element is a suitable name for the argument field of the + context: either a string of the form `option-OPT-N' for the N'th + argument of the option -OPT, or a string of the form `argument-N' + for the N'th argument. For `rest' arguments, that is those in the + list at the end not handled by position, N is the string `rest'. + For example, when completing the argument of the -o option, the + name is `option-o-1', while for the second normal (non-option-) + argument it is `argument-2'. + + Furthermore, during the evaluation of the ACTION the context name + in the curcontext parameter is altered to append the same string + that is stored in the context parameter. + + The option -C tells _arguments to modify the curcontext parameter + for an action of the form `->STATE'. This is the standard + parameter used to keep track of the current context. Here it (and + not the context array) should be made local to the calling + function to avoid passing back the modified value and should be + initialised to the current value at the start of the function: + + + local curcontext="$curcontext" + + This is useful where it is not possible for multiple states to be + valid together. + + _Grouping Options_ + + Options can be grouped to simplify exclusion lists. A group is + introduced with `+' followed by a name for the group in the + subsequent word. Whole groups can then be referenced in an + exclusion list or a group name can be used to disambiguate between + two forms of the same option. For example: + + + _arguments \ + '(group2--x)-a' \ + + group1 \ + -m \ + '(group2)-n' \ + + group2 \ + -x -y + + If the name of a group is specified in the form `(NAME)' then only + one value from that group will ever be completed; more formally, + all specifications are mutually exclusive to all other + specifications in that group. This is useful for defining options + that are aliases for each other. For example: + + + _arguments \ + -a -b \ + + '(operation)' \ + {-c,--compress}'[compress]' \ + {-d,--decompress}'[decompress]' \ + {-l,--list}'[list]' + + If an option in a group appears on the command line, it is stored + in the associative array `opt_args' with 'GROUP-OPTION' as a key. + In the example above, a key `operation-c' is used if the option + `-c' is present on the command line. + + _Specifying Multiple Sets of Arguments_ + + It is possible to specify multiple sets of options and arguments + with the sets separated by single hyphens. This differs from + groups in that sets are considered to be mutually exclusive of + each other. + + Specifications before the first set and from any group are common + to all sets. For example: + + + _arguments \ + -a \ + - set1 \ + -c \ + - set2 \ + -d \ + ':arg:(x2 y2)' + + This defines two sets. When the command line contains the option + `-c', the `-d' option and the argument will not be considered + possible completions. When it contains `-d' or an argument, the + option `-c' will not be considered. However, after `-a' both sets + will still be considered valid. + + As for groups, the name of a set may appear in exclusion lists, + either alone or preceding a normal option or argument + specification. + + The completion code has to parse the command line separately for + each set. This can be slow so sets should only be used when + necessary. A useful alternative is often an option specification + with rest-arguments (as in `-foo:*:...'); here the option -foo + swallows up all remaining arguments as described by the OPTARG + definitions. + + _Deriving SPEC forms from the help output_ + + The option `--' allows _arguments to work out the names of long + options that support the `--help' option which is standard in many + GNU commands. The command word is called with the argument + `--help' and the output examined for option names. Clearly, it can + be dangerous to pass this to commands which may not support this + option as the behaviour of the command is unspecified. + + In addition to options, `_arguments --' will try to deduce the + types of arguments available for options when the form `--OPT=VAL' + is valid. It is also possible to provide hints by examining the + help text of the command and adding HELPSPEC of the form + `PATTERN:MESSAGE:ACTION'; note that other _arguments SPEC forms + are not used. The PATTERN is matched against the help text for an + option, and if it matches the MESSAGE and ACTION are used as for + other argument specifiers. The special case of `*:' means both + MESSAGE and ACTION are empty, which has the effect of causing + options having no description in the help output to be ordered in + listings ahead of options that have a description. + + For example: + + + _arguments -- '*\*:toggle:(yes no)' \ + '*=FILE*:file:_files' \ + '*=DIR*:directory:_files -/' \ + '*=PATH*:directory:_files -/' + + Here, `yes' and `no' will be completed as the argument of options + whose description ends in a star; file names will be completed for + options that contain the substring `=FILE' in the description; and + directories will be completed for options whose description + contains `=DIR' or `=PATH'. The last three are in fact the + default and so need not be given explicitly, although it is + possible to override the use of these patterns. A typical help + text which uses this feature is: + + + -C, --directory=DIR change to directory DIR + + so that the above specifications will cause directories to be + completed after `--directory', though not after `-C'. + + Note also that _arguments tries to find out automatically if the + argument for an option is optional. This can be specified + explicitly by doubling the colon before the MESSAGE. + + If the PATTERN ends in `(-)', this will be removed from the + pattern and the ACTION will be used only directly after the `=', + not in the next word. This is the behaviour of a normal + specification defined with the form `=-'. + + By default, the command (with the option `-help') is run after + resetting all the locale categories (except for LC_CTYPE) to `C'. + If the localized help output is known to work, the option `-l' can + be specified after the `_arguments --' so that the command is run + in the current locale. + + The `_arguments --' can be followed by the option `-i PATTERNS' to + give patterns for options which are not to be completed. The + patterns can be given as the name of an array parameter or as a + literal list in parentheses. For example, + + + _arguments -- -i \ + "(--(en|dis)able-FEATURE*)" + + will cause completion to ignore the options `--enable-FEATURE' and + `--disable-FEATURE' (this example is useful with GNU configure). + + The `_arguments --' form can also be followed by the option `-s + PAIR' to describe option aliases. The PAIR consists of a list of + alternating patterns and corresponding replacements, enclosed in + parens and quoted so that it forms a single argument word in the + _arguments call. + + For example, some configure-script help output describes options + only as `--enable-foo', but the script also accepts the negated + form `--disable-foo'. To allow completion of the second form: + + + _arguments -- -s "((#s)--enable- --disable-)" + + _Miscellaneous notes_ + + Finally, note that _arguments generally expects to be the primary + function handling any completion for which it is used. It may + have side effects which change the treatment of any matches added + by other functions called after it. To combine _arguments with + other functions, those functions should be called either before + _arguments, as an ACTION within a SPEC, or in handlers for + `->STATE' actions. + + Here is a more general example of the use of _arguments: + + + _arguments '-l+:left border:' \ + '-format:paper size:(letter A4)' \ + '*-copy:output file:_files::resolution:(300 600)' \ + ':postscript file:_files -g \*.\(ps\|eps\)' \ + '*:page number:' + + This describes three options: `-l', `-format', and `-copy'. The + first takes one argument described as `LEFT BORDER' for which no + completion will be offered because of the empty action. Its + argument may come directly after the `-l' or it may be given as + the next word on the line. + + The `-format' option takes one argument in the next word, + described as `PAPER SIZE' for which only the strings `letter' and + `A4' will be completed. + + The `-copy' option may appear more than once on the command line + and takes two arguments. The first is mandatory and will be + completed as a filename. The second is optional (because of the + second colon before the description `RESOLUTION') and will be + completed from the strings `300' and `600'. + + The last two descriptions say what should be completed as + arguments. The first describes the first argument as a + `POSTSCRIPT FILE' and makes files ending in `ps' or `eps' be + completed. The last description gives all other arguments the + description `PAGE NUMBERS' but does not offer completions. + +_cache_invalid CACHE_IDENTIFIER + This function returns status zero if the completions cache + corresponding to the given cache identifier needs rebuilding. It + determines this by looking up the cache-policy style for the + current context. This should provide a function name which is run + with the full path to the relevant cache file as the only argument. + + Example: + + + _example_caching_policy () { + # rebuild if cache is more than a week old + local -a oldp + oldp=( "$1"(Nm+7) ) + (( $#oldp )) + } + +_call_function RETURN NAME [ ARG ... ] + If a function NAME exists, it is called with the arguments ARGs. + The RETURN argument gives the name of a parameter in which the + return status from the function NAME should be stored; if RETURN + is empty or a single hyphen it is ignored. + + The return status of _call_function itself is zero if the function + NAME exists and was called and non-zero otherwise. + +_call_program [ -l ] [ -p ] TAG STRING ... + This function provides a mechanism for the user to override the + use of an external command. It looks up the command style with + the supplied TAG. If the style is set, its value is used as the + command to execute. The STRINGs from the call to _call_program, + or from the style if set, are concatenated with spaces between + them and the resulting string is evaluated. The return status is + the return status of the command called. + + By default, the command is run in an environment where all the + locale categories (except for LC_CTYPE) are reset to `C' by + calling the utility function _comp_locale (see below). If the + option `-l' is given, the command is run with the current locale. + + If the option `-p' is supplied it indicates that the command + output is influenced by the permissions it is run with. If the + gain-privileges style is set to true, _call_program will make use + of commands such as sudo, if present on the command-line, to match + the permissions to whatever the final command is likely to run + under. When looking up the gain-privileges and command styles, the + command component of the zstyle context will end with a slash + (`/') followed by the command that would be used to gain + privileges. + +_combination [ -s PATTERN ] TAG STYLE SPEC ... FIELD OPTS ... + This function is used to complete combinations of values, for + example pairs of hostnames and usernames. The STYLE argument + gives the style which defines the pairs; it is looked up in a + context with the TAG specified. + + The style name consists of field names separated by hyphens, for + example `users-hosts-ports'. For each field for a value is + already known, a SPEC of the form `FIELD=PATTERN' is given. For + example, if the command line so far specifies a user `pws', the + argument `users=pws' should appear. + + The next argument with no equals sign is taken as the name of the + field for which completions should be generated (presumably not + one of the FIELDs for which the value is known). + + The matches generated will be taken from the value of the style. + These should contain the possible values for the combinations in + the appropriate order (users, hosts, ports in the example above). + The values for the different fields are separated by colons. This + can be altered with the option -s to _combination which specifies a + pattern. Typically this is a character class, as for example `-s + "[:@]"' in the case of the users-hosts style. Each + `FIELD=PATTERN' specification restricts the completions which + apply to elements of the style with appropriately matching fields. + + If no style with the given name is defined for the given tag, or + if none of the strings in style's value match, but a function name + of the required field preceded by an underscore is defined, that + function will be called to generate the matches. For example, if + there is no `users-hosts-ports' or no matching hostname when a + host is required, the function `_hosts' will automatically be + called. + + If the same name is used for more than one field, in both the + `FIELD=PATTERN' and the argument that gives the name of the field + to be completed, the number of the field (starting with one) may + be given after the fieldname, separated from it by a colon. + + All arguments after the required field name are passed to compadd + when generating matches from the style value, or to the functions + for the fields if they are called. + +_command_names [ -e | - ] + This function completes words that are valid at command position: + names of aliases, builtins, hashed commands, functions, and so on. + With the -e flag, only hashed commands are completed. The - flag + is ignored. + +_comp_locale + This function resets all the locale categories other than LC_CTYPE + to `C' so that the output from external commands can be easily + analyzed by the completion system. LC_CTYPE retains the current + value (taking LC_ALL and LANG into account), ensuring that + non-ASCII characters in file names are still handled properly. + + This function should normally be run only in a subshell, because + the new locale is exported to the environment. Typical usage would + be `$(_comp_locale; COMMAND ...)'. + +_completers [ -p ] + This function completes names of completers. + + + -p + Include the leading underscore (`_') in the matches. + + +_describe [-12JVx] [ -oO | -t TAG ] DESCR NAME1 [ NAME2 ] [ OPT ... ] + [ -- NAME1 [ NAME2 ] [ OPT ... ] ... ] + This function associates completions with descriptions. Multiple + groups separated by -- can be supplied, potentially with different + completion options OPTs. + + The DESCR is taken as a string to display above the matches if the + format style for the descriptions tag is set. This is followed by + one or two names of arrays followed by options to pass to compadd. + The array NAME1 contains the possible completions with their + descriptions in the form `COMPLETION:DESCRIPTION'. Any literal + colons in COMPLETION must be quoted with a backslash. If a NAME2 + is given, it should have the same number of elements as NAME1; in + this case the corresponding elements are added as possible + completions instead of the COMPLETION strings from NAME1. The + completion list will retain the descriptions from NAME1. Finally, + a set of completion options can appear. + + If the option `-o' appears before the first argument, the matches + added will be treated as names of command options (N.B. not shell + options), typically following a `-', `--' or `+' on the command + line. In this case _describe uses the prefix-hidden, + prefix-needed and verbose styles to find out if the strings should + be added as completions and if the descriptions should be shown. + Without the `-o' option, only the verbose style is used to decide + how descriptions are shown. If `-O' is used instead of `-o', + command options are completed as above but _describe will not + handle the prefix-needed style. + + With the -t option a TAG can be specified. The default is + `values' or, if the -o option is given, `options'. + + The options -1, -2, -J, -V, -x are passed to _next_label. + + If selected by the list-grouped style, strings with the same + description will appear together in the list. + + _describe uses the _all_labels function to generate the matches, so + it does not need to appear inside a loop over tag labels. + +_description [ -x ] [ -12VJ ] TAG NAME DESCR [ SPEC ... ] + This function is not to be confused with the previous one; it is + used as a helper function for creating options to compadd. It is + buried inside many of the higher level completion functions and so + often does not need to be called directly. + + The styles listed below are tested in the current context using the + given TAG. The resulting options for compadd are put into the + array named NAME (this is traditionally `expl', but this + convention is not enforced). The description for the + corresponding set of matches is passed to the function in DESCR. + + The styles tested are: format, hidden, matcher, ignore-line, + ignored-patterns, group-name and sort. The format style is first + tested for the given TAG and then for the descriptions tag if no + value was found, while the remainder are only tested for the tag + given as the first argument. The function also calls _setup which + tests some more styles. + + The string returned by the format style (if any) will be modified + so that the sequence `%d' is replaced by the DESCR given as the + third argument without any leading or trailing white space. If, + after removing the white space, the DESCR is the empty string, the + format style will not be used and the options put into the NAME + array will not contain an explanation string to be displayed above + the matches. + + If _description is called with more than three arguments, the + additional SPECs should be of the form `CHAR:STR'. These supply + escape sequence replacements for the format style: every + appearance of `%CHAR' will be replaced by STRING. + + If the -x option is given, the description will be passed to + compadd using the -x option instead of the default -X. This means + that the description will be displayed even if there are no + corresponding matches. + + The options placed in the array NAME take account of the + group-name style, so matches are placed in a separate group where + necessary. The group normally has its elements sorted (by passing + the option -J to compadd), but if an option starting with `-V', + `-J', `-1', or `-2' is passed to _description, that option will be + included in the array. Hence it is possible for the completion + group to be unsorted by giving the option `-V', `-1V', or `-2V'. + + In most cases, the function will be used like this: + + + local expl + _description files expl file + compadd "$expl[@]" - "$files[@]" + + Note the use of the parameter expl, the hyphen, and the list of + matches. Almost all calls to compadd within the completion system + use a similar format; this ensures that user-specified styles are + correctly passed down to the builtins which implement the + internals of completion. + +_dir_list [ -s SEP ] [ -S ] + Complete a list of directory names separated by colons (the same + format as $PATH). + + + -s SEP + Use SEP as separator between items. SEP defaults to a colon + (`:'). + + -S + Add SEP instead of slash (`/') as an autoremoveable suffix. + + +_dispatch CONTEXT STRING ... + This sets the current context to CONTEXT and looks for completion + functions to handle this context by hunting through the list of + command names or special contexts (as described above for compdef) + given as STRINGs. The first completion function to be defined for + one of the contexts in the list is used to generate matches. + Typically, the last STRING is -default- to cause the function for + default completion to be used as a fallback. + + The function sets the parameter $service to the STRING being + tried, and sets the CONTEXT/COMMAND field (the fourth) of the + $curcontext parameter to the CONTEXT given as the first argument. + +_email_addresses [ -c ] [ -n PLUGIN ] + Complete email addresses. Addresses are provided by plugins. + + + -c + Complete bare localhost@domain.tld addresses, without a name + part or a comment. Without this option, RFC822 `FIRSTNAME + LASTNAME <ADDRESS>' strings are completed. + + -n PLUGIN + Complete aliases from PLUGIN. + + + The following plugins are available by default: _email-ldap (see + the filter style), _email-local (completes USER@HOSTNAME Unix + addresses), _email-mail (completes aliases from ~/.mailrc), + _email-mush, _email-mutt, and _email-pine. + + Addresses from the _email-FOO plugin are added under the tag + `email-FOO'. + + _Writing plugins_ + + Plugins are written as separate functions with names starting with + `_email-'. They are invoked with the -c option and compadd + options. They should either do their own completion or set the + $reply array to a list of `ALIAS:ADDRESS' elements and return 300. + New plugins will be picked up and run automatically. + +_files + The function _files is a wrapper around _path_files. It supports + all of the same functionality, with some enhancements -- notably, + it respects the list-dirs-first style, and it allows users to + override the behaviour of the -g and -/ options with the + file-patterns style. _files should therefore be preferred over + _path_files in most cases. + + This function accepts the full set of options allowed by + _path_files, described below. + +_gnu_generic + This function is a simple wrapper around the _arguments function + described above. It can be used to determine automatically the + long options understood by commands that produce a list when + passed the option `--help'. It is intended to be used as a + top-level completion function in its own right. For example, to + enable option completion for the commands foo and bar, use + + + compdef _gnu_generic foo bar + + after the call to compinit. + + The completion system as supplied is conservative in its use of + this function, since it is important to be sure the command + understands the option `--help'. + +_guard [ OPTIONS ] PATTERN DESCR + This function displays DESCR if PATTERN matches the string to be + completed. It is intended to be used in the ACTION for the + specifications passed to _arguments and similar functions. + + The return status is zero if the message was displayed and the + word to complete is not empty, and non-zero otherwise. + + The PATTERN may be preceded by any of the options understood by + compadd that are passed down from _description, namely -M, -J, -V, + -1, -2, -n, -F and -X. All of these options will be ignored. + This fits in conveniently with the argument-passing conventions of + actions for _arguments. + + As an example, consider a command taking the options -n and -none, + where -n must be followed by a numeric value in the same word. By + using: + + + _arguments '-n-: :_guard "[0-9]#" "numeric value"' '-none' + + _arguments can be made to both display the message `numeric value' + and complete options after `-n<TAB>'. If the `-n' is already + followed by one or more digits (the pattern passed to _guard) only + the message will be displayed; if the `-n' is followed by another + character, only options are completed. + +_message [ -r12 ] [ -VJ GROUP ] DESCR +_message -e [ TAG ] DESCR + The DESCR is used in the same way as the third argument to the + _description function, except that the resulting string will + always be shown whether or not matches were generated. This is + useful for displaying a help message in places where no + completions can be generated. + + The format style is examined with the messages tag to find a + message; the usual tag, descriptions, is used only if the style is + not set with the former. + + If the -r option is given, no style is used; the DESCR is taken + literally as the string to display. This is most useful when the + DESCR comes from a pre-processed argument list which already + contains an expanded description. Note that this option does not + disable the `%'-sequence parsing done by compadd. + + The -12VJ options and the GROUP are passed to compadd and hence + determine the group the message string is added to. + + The second -e form gives a description for completions with the tag + TAG to be shown even if there are no matches for that tag. This + form is called by _arguments in the event that there is no action + for an option specification. The tag can be omitted and if so the + tag is taken from the parameter $curtag; this is maintained by the + completion system and so is usually correct. Note that if there + are no matches at the time this function is called, + compstate[insert] is cleared, so additional matches generated + later are not inserted on the command line. + +_multi_parts [ -i ] SEP ARRAY + The argument SEP is a separator character. The ARRAY may be + either the name of an array parameter or a literal array in the + form `(foo bar)', a parenthesised list of words separated by + whitespace. The possible completions are the strings from the + array. However, each chunk delimited by SEP will be completed + separately. For example, the _tar function uses `_multi_parts / + PATHARRAY' to complete partial file paths from the given array of + complete file paths. + + The -i option causes _multi_parts to insert a unique match even if + that requires multiple separators to be inserted. This is not + usually the expected behaviour with filenames, but certain other + types of completion, for example those with a fixed set of + possibilities, may be more suited to this form. + + Like other utility functions, this function accepts the `-V', + `-J', `-1', `-2', `-n', `-f', `-X', `-M', `-P', `-S', `-r', `-R', + and `-q' options and passes them to the compadd builtin. + +_next_label [ -x ] [ -12VJ ] TAG NAME DESCR [ OPTION ... ] + This function is used to implement the loop over different tag + labels for a particular tag as described above for the tag-order + style. On each call it checks to see if there are any more tag + labels; if there is it returns status zero, otherwise non-zero. + As this function requires a current tag to be set, it must always + follow a call to _tags or _requested. + + The -x12VJ options and the first three arguments are passed to the + _description function. Where appropriate the TAG will be replaced + by a tag label in this call. Any description given in the + tag-order style is preferred to the DESCR passed to _next_label. + + The OPTIONs given after the DESCR are set in the parameter given + by NAME, and hence are to be passed to compadd or whatever + function is called to add the matches. + + Here is a typical use of this function for the tag foo. The call + to _requested determines if tag foo is required at all; the loop + over _next_label handles any labels defined for the tag in the + tag-order style. + + + local expl ret=1 + ... + if _requested foo; then + ... + while _next_label foo expl '...'; do + compadd "$expl[@]" ... && ret=0 + done + ... + fi + return ret + +_normal [ -P | -p PRECOMMAND ] + This is the standard function called to handle completion outside + any special -CONTEXT-. It is called both to complete the command + word and also the arguments for a command. In the second case, + _normal looks for a special completion for that command, and if + there is none it uses the completion for the -default- context. + + A second use is to reexamine the command line specified by the + $words array and the $CURRENT parameter after those have been + modified. For example, the function _precommand, which completes + after precommand specifiers such as nohup, removes the first word + from the words array, decrements the CURRENT parameter, then calls + `_normal -p $service'. The effect is that `nohup CMD ...' is + treated in the same way as `CMD ...'. + + + -P + Reset the list of precommands. This option should be used if + completing a command line which allows internal commands + (e.g. builtins and functions) regardless of prior precommands + (e.g. `zsh -c'). + + -p PRECOMMAND + Append PRECOMMAND to the list of precommands. This option + should be used in nearly all cases in which -P is not + applicable. + + + If the command name matches one of the patterns given by one of the + options -p or -P to compdef, the corresponding completion function + is called and then the parameter _compskip is checked. If it is + set completion is terminated at that point even if no matches have + been found. This is the same effect as in the -first- context. + +_options + This can be used to complete the names of shell options. It + provides a matcher specification that ignores a leading `no', + ignores underscores and allows upper-case letters to match their + lower-case counterparts (for example, `glob', `noglob', `NO_GLOB' + are all completed). Any arguments are propagated to the compadd + builtin. + +_options_set and _options_unset + These functions complete only set or unset options, with the same + matching specification used in the _options function. + + Note that you need to uncomment a few lines in the _main_complete + function for these functions to work properly. The lines in + question are used to store the option settings in effect before + the completion widget locally sets the options it needs. Hence + these functions are not generally used by the completion system. + +_parameters + This is used to complete the names of shell parameters. + + The option `-g PATTERN' limits the completion to parameters whose + type matches the PATTERN. The type of a parameter is that shown + by `print ${(t)PARAM}', hence judicious use of `*' in PATTERN is + probably necessary. + + All other arguments are passed to the compadd builtin. + +_path_files + This function is used throughout the completion system to complete + filenames. It allows completion of partial paths. For example, + the string `/u/i/s/sig' may be completed to + `/usr/include/sys/signal.h'. + + The options accepted by both _path_files and _files are: + + + -f + Complete all filenames. This is the default. + + -/ + Specifies that only directories should be completed. + + -g PATTERN + Specifies that only files matching the PATTERN should be + completed. + + -W PATHS + Specifies path prefixes that are to be prepended to the + string from the command line to generate the filenames but + that should not be inserted as completions nor shown in + completion listings. Here, PATHS may be the name of an array + parameter, a literal list of paths enclosed in parentheses or + an absolute pathname. + + -F IGNORED-FILES + This behaves as for the corresponding option to the compadd + builtin. It gives direct control over which filenames should + be ignored. If the option is not present, the + ignored-patterns style is used. + + + Both _path_files and _files also accept the following options + which are passed to compadd: `-J', `-V', `-1', `-2', `-n', `-X', + `-M', `-P', `-S', `-q', `-r', and `-R'. + + Finally, the _path_files function uses the styles expand, + ambiguous, special-dirs, list-suffixes and file-sort described + above. + +_pick_variant [ -b BUILTIN-LABEL ] [ -c COMMAND ] [ -r NAME ] + LABEL=PATTERN ... LABEL [ ARG ... ] + This function is used to resolve situations where a single command + name requires more than one type of handling, either because it + has more than one variant or because there is a name clash between + two different commands. + + The command to run is taken from the first element of the array + words unless this is overridden by the option -c. This command is + run and its output is compared with a series of patterns. + Arguments to be passed to the command can be specified at the end + after all the other arguments. The patterns to try in order are + given by the arguments LABEL=PATTERN; if the output of `COMMAND ARG + ...' contains PATTERN, then LABEL is selected as the label for the + command variant. If none of the patterns match, the final command + label is selected and status 1 is returned. + + If the `-b BUILTIN-LABEL' is given, the command is tested to see + if it is provided as a shell builtin, possibly autoloaded; if so, + the label BUILTIN-LABEL is selected as the label for the variant. + + If the `-r NAME' is given, the LABEL picked is stored in the + parameter named NAME. + + The results are also cached in the _cmd_variant associative array + indexed by the name of the command run. + +_regex_arguments NAME SPEC ... + This function generates a completion function NAME which matches + the specifications SPECs, a set of regular expressions as + described below. After running _regex_arguments, the function + NAME should be called as a normal completion function. The + pattern to be matched is given by the contents of the words array + up to the current cursor position joined together with null + characters; no quotation is applied. + + The arguments are grouped as sets of alternatives separated by `|', + which are tried one after the other until one matches. Each + alternative consists of a one or more specifications which are + tried left to right, with each pattern matched being stripped in + turn from the command line being tested, until all of the group + succeeds or until one fails; in the latter case, the next + alternative is tried. This structure can be repeated to arbitrary + depth by using parentheses; matching proceeds from inside to + outside. + + A special procedure is applied if no test succeeds but the + remaining command line string contains no null character (implying + the remaining word is the one for which completions are to be + generated). The completion target is restricted to the remaining + word and any ACTIONs for the corresponding patterns are executed. + In this case, nothing is stripped from the command line string. + The order of evaluation of the ACTIONs can be determined by the + tag-order style; the various formats supported by _alternative can + be used in ACTION. The DESCR is used for setting up the array + parameter expl. + + Specification arguments take one of following forms, in which + metacharacters such as `(', `)', `#' and `|' should be quoted. + + + /PATTERN/ [%LOOKAHEAD%] [-GUARD] [:TAG:DESCR:ACTION] + This is a single primitive component. The function tests + whether the combined pattern `(#b)((#B)PATTERN)LOOKAHEAD*' + matches the command line string. If so, `GUARD' is evaluated + and its return status is examined to determine if the test + has succeeded. The PATTERN string `[]' is guaranteed never + to match. The LOOKAHEAD is not stripped from the command + line before the next pattern is examined. + + The argument starting with : is used in the same manner as an + argument to _alternative. + + A component is used as follows: PATTERN is tested to see if + the component already exists on the command line. If it + does, any following specifications are examined to find + something to complete. If a component is reached but no such + pattern exists yet on the command line, the string containing + the ACTION is used to generate matches to insert at that + point. + + /PATTERN/+ [%LOOKAHEAD%] [-GUARD] [:TAG:DESCR:ACTION] + This is similar to `/PATTERN/ ...' but the left part of the + command line string (i.e. the part already matched by + previous patterns) is also considered part of the completion + target. + + /PATTERN/- [%LOOKAHEAD%] [-GUARD] [:TAG:DESCR:ACTION] + This is similar to `/PATTERN/ ...' but the ACTIONs of the + current and previously matched patterns are ignored even if + the following `PATTERN' matches the empty string. + + ( SPEC ) + Parentheses may be used to groups SPECs; note each parenthesis + is a single argument to _regex_arguments. + + SPEC # + This allows any number of repetitions of SPEC. + + SPEC SPEC + The two SPECs are to be matched one after the other as + described above. + + SPEC | SPEC + Either of the two SPECs can be matched. + + + The function _regex_words can be used as a helper function to + generate matches for a set of alternative words possibly with + their own arguments as a command line argument. + + Examples: + + + _regex_arguments _tst /$'[^\0]#\0'/ \ + /$'[^\0]#\0'/ :'compadd aaa' + + This generates a function _tst that completes aaa as its only + argument. The TAG and DESCRIPTION for the action have been + omitted for brevity (this works but is not recommended in normal + use). The first component matches the command word, which is + arbitrary; the second matches any argument. As the argument is + also arbitrary, any following component would not depend on aaa + being present. + + + _regex_arguments _tst /$'[^\0]#\0'/ \ + /$'aaa\0'/ :'compadd aaa' + + This is a more typical use; it is similar, but any following + patterns would only match if aaa was present as the first argument. + + + _regex_arguments _tst /$'[^\0]#\0'/ \( \ + /$'aaa\0'/ :'compadd aaa' \ + /$'bbb\0'/ :'compadd bbb' \) \# + + In this example, an indefinite number of command arguments may be + completed. Odd arguments are completed as aaa and even arguments + as bbb. Completion fails unless the set of aaa and bbb arguments + before the current one is matched correctly. + + + _regex_arguments _tst /$'[^\0]#\0'/ \ + \( /$'aaa\0'/ :'compadd aaa' \| \ + /$'bbb\0'/ :'compadd bbb' \) \# + + This is similar, but either aaa or bbb may be completed for any + argument. In this case _regex_words could be used to generate a + suitable expression for the arguments. + + + +_regex_words TAG DESCRIPTION SPEC ... + This function can be used to generate arguments for the + _regex_arguments command which may be inserted at any point where + a set of rules is expected. The TAG and DESCRIPTION give a + standard tag and description pertaining to the current context. + Each SPEC contains two or three arguments separated by a colon: + note that there is no leading colon in this case. + + Each SPEC gives one of a set of words that may be completed at + this point, together with arguments. It is thus roughly + equivalent to the _arguments function when used in normal + (non-regex) completion. + + The part of the SPEC before the first colon is the word to be + completed. This may contain a *; the entire word, before and after + the * is completed, but only the text before the * is required for + the context to be matched, so that further arguments may be + completed after the abbreviated form. + + The second part of SPEC is a description for the word being + completed. + + The optional third part of the SPEC describes how words following + the one being completed are themselves to be completed. It will be + evaluated in order to avoid problems with quoting. This means that + typically it contains a reference to an array containing previously + generated regex arguments. + + The option -t TERM specifies a terminator for the word instead of + the usual space. This is handled as an auto-removable suffix in + the manner of the option -s SEP to _values. + + The result of the processing by _regex_words is placed in the array + reply, which should be made local to the calling function. If the + set of words and arguments may be matched repeatedly, a # should + be appended to the generated array at that point. + + For example: + + + local -a reply + _regex_words mydb-commands 'mydb commands' \ + 'add:add an entry to mydb:$mydb_add_cmds' \ + 'show:show entries in mydb' + _regex_arguments _mydb "$reply[@]" + _mydb "$@" + + This shows a completion function for a command mydb which takes + two command arguments, add and show. show takes no arguments, + while the arguments for add have already been prepared in an array + mydb_add_cmds, quite possibly by a previous call to _regex_words. + +_requested [ -x ] [ -12VJ ] TAG [ NAME DESCR [ COMMAND [ ARG ... ] ] + This function is called to decide whether a tag already registered + by a call to _tags (see below) has been requested by the user and + hence completion should be performed for it. It returns status + zero if the tag is requested and non-zero otherwise. The function + is typically used as part of a loop over different tags as follows: + + + _tags foo bar baz + while _tags; do + if _requested foo; then + ... # perform completion for foo + fi + ... # test the tags bar and baz in the same way + ... # exit loop if matches were generated + done + + Note that the test for whether matches were generated is not + performed until the end of the _tags loop. This is so that the + user can set the tag-order style to specify a set of tags to be + completed at the same time. + + If NAME and DESCR are given, _requested calls the _description + function with these arguments together with the options passed to + _requested. + + If COMMAND is given, the _all_labels function will be called + immediately with the same arguments. In simple cases this makes it + possible to perform the test for the tag and the matching in one + go. For example: + + + local expl ret=1 + _tags foo bar baz + while _tags; do + _requested foo expl 'description' \ + compadd foobar foobaz && ret=0 + ... + (( ret )) || break + done + + If the COMMAND is not compadd, it must nevertheless be prepared to + handle the same options. + +_retrieve_cache CACHE_IDENTIFIER + This function retrieves completion information from the file given + by CACHE_IDENTIFIER, stored in a directory specified by the + cache-path style which defaults to ~/.zcompcache. The return + status is zero if retrieval was successful. It will only attempt + retrieval if the use-cache style is set, so you can call this + function without worrying about whether the user wanted to use the + caching layer. + + See _store_cache below for more details. + +_sep_parts + This function is passed alternating arrays and separators as + arguments. The arrays specify completions for parts of strings to + be separated by the separators. The arrays may be the names of + array parameters or a quoted list of words in parentheses. For + example, with the array `hosts=(ftp news)' the call `_sep_parts + '(foo bar)' @ hosts' will complete the string `f' to `foo' and + the string `b@n' to `bar@news'. + + This function accepts the compadd options `-V', `-J', `-1', `-2', + `-n', `-X', `-M', `-P', `-S', `-r', `-R', and `-q' and passes them + on to the compadd builtin used to add the matches. + +_sequence [ -s SEP ] [ -n MAX ] [ -d ] FUNCTION [ - ] ... + This function is a wrapper to other functions for completing items + in a separated list. The same function is used to complete each + item in the list. The separator is specified with the -s option. + If -s is omitted it will use `,'. Duplicate values are not matched + unless -d is specified. If there is a fixed or maximum number of + items in the list, this can be specified with the -n option. + + Common compadd options are passed on to the function. It is + possible to use compadd directly with _sequence, though _values may + be more appropriate in this situation. + +_setup TAG [ GROUP ] + This function sets up the special parameters used by the + completion system appropriately for the TAG given as the first + argument. It uses the styles list-colors, list-packed, + list-rows-first, last-prompt, accept-exact, menu and force-list. + + The optional GROUP supplies the name of the group in which the + matches will be placed. If it is not given, the TAG is used as + the group name. + + This function is called automatically from _description and hence + is not normally called explicitly. + +_store_cache CACHE_IDENTIFIER PARAM ... + This function, together with _retrieve_cache and _cache_invalid, + implements a caching layer which can be used in any completion + function. Data obtained by costly operations are stored in + parameters; this function then dumps the values of those + parameters to a file. The data can then be retrieved quickly from + that file via _retrieve_cache, even in different instances of the + shell. + + The CACHE_IDENTIFIER specifies the file which the data should be + dumped to. The file is stored in a directory specified by the + cache-path style which defaults to ~/.zcompcache. The remaining + PARAMs arguments are the parameters to dump to the file. + + The return status is zero if storage was successful. The function + will only attempt storage if the use-cache style is set, so you can + call this function without worrying about whether the user wanted + to use the caching layer. + + The completion function may avoid calling _retrieve_cache when it + already has the completion data available as parameters. However, + in that case it should call _cache_invalid to check whether the + data in the parameters and in the cache are still valid. + + See the _perl_modules completion function for a simple example of + the usage of the caching layer. + +_tags [ [ -C NAME ] TAG ... ] + If called with arguments, these are taken to be the names of tags + valid for completions in the current context. These tags are + stored internally and sorted by using the tag-order style. + + Next, _tags is called repeatedly without arguments from the same + completion function. This successively selects the first, second, + etc. set of tags requested by the user. The return status is zero + if at least one of the tags is requested and non-zero otherwise. + To test if a particular tag is to be tried, the _requested + function should be called (see above). + + If `-C NAME' is given, NAME is temporarily stored in the ARGUMENT + field (the fifth) of the context in the curcontext parameter + during the call to _tags; the field is restored on exit. This + allows _tags to use a more specific context without having to + change and reset the curcontext parameter (which has the same + effect). + +_tilde_files + Like _files, but resolve leading tildes according to the rules of + filename expansion, so the suggested completions don't start with + a `~' even if the filename on the command-line does. + +_values [ -O NAME ] [ -s SEP ] [ -S SEP ] [ -wC ] DESC SPEC ... + This is used to complete arbitrary keywords (values) and their + arguments, or lists of such combinations. + + If the first argument is the option `-O NAME', it will be used in + the same way as by the _arguments function. In other words, the + elements of the NAME array will be passed to compadd when + executing an action. + + If the first argument (or the first argument after `-O NAME') is + `-s', the next argument is used as the character that separates + multiple values. This character is automatically added after each + value in an auto-removable fashion (see below); all values + completed by `_values -s' appear in the same word on the command + line, unlike completion using _arguments. If this option is not + present, only a single value will be completed per word. + + Normally, _values will only use the current word to determine + which values are already present on the command line and hence are + not to be completed again. If the -w option is given, other + arguments are examined as well. + + The first non-option argument, DESC, is used as a string to print + as a description before listing the values. + + All other arguments describe the possible values and their + arguments in the same format used for the description of options by + the _arguments function (see above). The only differences are that + no minus or plus sign is required at the beginning, values can + have only one argument, and the forms of action beginning with an + equal sign are not supported. + + The character separating a value from its argument can be set + using the option -S (like -s, followed by the character to use as + the separator in the next argument). By default the equals sign + will be used as the separator between values and arguments. + + Example: + + + _values -s , 'description' \ + '*foo[bar]' \ + '(two)*one[number]:first count:' \ + 'two[another number]::second count:(1 2 3)' + + This describes three possible values: `foo', `one', and `two'. + The first is described as `bar', takes no argument and may appear + more than once. The second is described as `number', may appear + more than once, and takes one mandatory argument described as + `first count'; no action is specified, so it will not be + completed. The `(two)' at the beginning says that if the value + `one' is on the line, the value `two' will no longer be considered + a possible completion. Finally, the last value (`two') is + described as `another number' and takes an optional argument + described as `second count' for which the completions (to appear + after an `=') are `1', `2', and `3'. The _values function will + complete lists of these values separated by commas. + + Like _arguments, this function temporarily adds another context + name component to the arguments element (the fifth) of the current + context while executing the ACTION. Here this name is just the + name of the value for which the argument is completed. + + The style verbose is used to decide if the descriptions for the + values (but not those for the arguments) should be printed. + + The associative array val_args is used to report values and their + arguments; this works similarly to the opt_args associative array + used by _arguments. Hence the function calling _values should + declare the local parameters state, state_descr, line, context and + val_args: + + + local context state state_descr line + typeset -A val_args + + when using an action of the form `->STRING'. With this function + the context parameter will be set to the name of the value whose + argument is to be completed. Note that for _values, the state and + state_descr are scalars rather than arrays. Only a single + matching state is returned. + + Note also that _values normally adds the character used as the + separator between values as an auto-removable suffix (similar to a + `/' after a directory). However, this is not possible for a + `->STRING' action as the matches for the argument are generated by + the calling function. To get the usual behaviour, the calling + function can add the separator X as a suffix by passing the + options `-qS X' either directly or indirectly to compadd. + + The option -C is treated in the same way as it is by _arguments. + In that case the parameter curcontext should be made local instead + of context (as described above). + +_wanted [ -x ] [ -C NAME ] [ -12VJ ] TAG NAME DESCR COMMAND [ ARG ...] + In many contexts, completion can only generate one particular set + of matches, usually corresponding to a single tag. However, it is + still necessary to decide whether the user requires matches of + this type. This function is useful in such a case. + + The arguments to _wanted are the same as those to _requested, i.e. + arguments to be passed to _description. However, in this case the + COMMAND is not optional; all the processing of tags, including + the loop over both tags and tag labels and the generation of + matches, is carried out automatically by _wanted. + + Hence to offer only one tag and immediately add the corresponding + matches with the given description: + + + local expl + _wanted tag expl 'description' \ + compadd matches... + + Note that, as for _requested, the COMMAND must be able to accept + options to be passed down to compadd. + + Like _tags this function supports the -C option to give a + different name for the argument context field. The -x option has + the same meaning as for _description. + +_widgets [ -g PATTERN ] + This function completes names of zle widgets (see *Note Zle + Widgets::). The PATTERN, if present, is matched against values of + the $widgets special parameter, documented in *Note The + zsh/zleparameter Module::. + + + + +File: zsh.info, Node: Completion System Variables, Next: Completion Directories, Prev: Completion Functions, Up: Completion System + +20.7 Completion System Variables +================================ + + + +There are some standard variables, initialised by the _main_complete +function and then used from other functions. + +The standard variables are: + + +_comp_caller_options + The completion system uses setopt to set a number of options. This + allows functions to be written without concern for compatibility + with every possible combination of user options. However, + sometimes completion needs to know what the user's option + preferences are. These are saved in the _comp_caller_options + associative array. Option names, spelled in lowercase without + underscores, are mapped to one or other of the strings `on' and + `off'. + + + +_comp_priv_prefix + Completion functions such as _sudo can set the _comp_priv_prefix + array to a command prefix that may then be used by _call_program to + match the privileges when calling programs to generate matches. + + +Two more features are offered by the _main_complete function. The +arrays compprefuncs and comppostfuncs may contain names of functions +that are to be called immediately before or after completion has been +tried. A function will only be called once unless it explicitly +reinserts itself into the array. + + + + +File: zsh.info, Node: Completion Directories, Prev: Completion System Variables, Up: Completion System + +20.8 Completion Directories +=========================== + + + +In the source distribution, the files are contained in various +subdirectories of the Completion directory. They may have been +installed in the same structure, or into one single function directory. +The following is a description of the files found in the original +directory structure. If you wish to alter an installed file, you will +need to copy it to some directory which appears earlier in your fpath +than the standard directory where it appears. + + +Base + The core functions and special completion widgets automatically + bound to keys. You will certainly need most of these, though will + probably not need to alter them. Many of these are documented + above. + +Zsh + Functions for completing arguments of shell builtin commands and + utility functions for this. Some of these are also used by + functions from the Unix directory. + +Unix + Functions for completing arguments of external commands and suites + of commands. They may need modifying for your system, although in + many cases some attempt is made to decide which version of a + command is present. For example, completion for the mount command + tries to determine the system it is running on, while completion + for many other utilities try to decide whether the GNU version of + the command is in use, and hence whether the --help option is + supported. + +X, AIX, BSD, ... + Completion and utility function for commands available only on + some systems. These are not arranged hierarchically, so, for + example, both the Linux and Debian directories, as well as the X + directory, may be useful on your system. + + + +File: zsh.info, Node: Completion Using compctl, Next: Zsh Modules, Prev: Completion System, Up: Top + +21 Completion Using compctl +*************************** + + + +21.1 Types of completion +======================== + +This version of zsh has two ways of performing completion of words on +the command line. New users of the shell may prefer to use the newer +and more powerful system based on shell functions; this is described in +*Note Completion System::, and the basic shell mechanisms which support +it are described in *Note Completion Widgets::. This chapter describes +the older compctl command. + +21.2 Description +================ + + + +compctl [ -CDT ] OPTIONS [ COMMAND ... ] + +compctl [ -CDT ] OPTIONS [ -x PATTERN OPTIONS - ... -- ] + + [ + OPTIONS [ -x ... -- ] ... [+] ] [ COMMAND ... ] + +compctl -M MATCH-SPECS ... + +compctl -L [ -CDTM ] [ COMMAND ... ] + +compctl + COMMAND ... + + +Control the editor's completion behavior according to the supplied set +of OPTIONS. Various editing commands, notably expand-or-complete-word, +usually bound to tab, will attempt to complete a word typed by the +user, while others, notably delete-char-or-list, usually bound to ^D in +EMACS editing mode, list the possibilities; compctl controls what those +possibilities are. They may for example be filenames (the most common +case, and hence the default), shell variables, or words from a +user-specified list. + +* Menu: + +* Command Flags:: +* Option Flags:: +* Alternative Completion:: +* Extended Completion:: +* Example:: + + + +File: zsh.info, Node: Command Flags, Next: Option Flags, Up: Completion Using compctl + +21.3 Command Flags +================== + +Completion of the arguments of a command may be different for each +command or may use the default. The behavior when completing the +command word itself may also be separately specified. These correspond +to the following flags and arguments, all of which (except for -L) may +be combined with any combination of the OPTIONS described subsequently +in *Note Option Flags::: + + +COMMAND ... + controls completion for the named commands, which must be listed + last on the command line. If completion is attempted for a + command with a pathname containing slashes and no completion + definition is found, the search is retried with the last pathname + component. If the command starts with a =, completion is tried + with the pathname of the command. + + Any of the COMMAND strings may be patterns of the form normally + used for filename generation. These should be quoted to protect + them from immediate expansion; for example the command string + 'foo*' arranges for completion of the words of any command + beginning with foo. When completion is attempted, all pattern + completions are tried in the reverse order of their definition + until one matches. By default, completion then proceeds as + normal, i.e. the shell will try to generate more matches for the + specific command on the command line; this can be overridden by + including -tn in the flags for the pattern completion. + + Note that aliases are expanded before the command name is + determined unless the COMPLETE_ALIASES option is set. Commands + may not be combined with the -C, -D or -T flags. + +-C + controls completion when the command word itself is being + completed. If no compctl -C command has been issued, the names + of any executable command (whether in the path or specific to the + shell, such as aliases or functions) are completed. + +-D + controls default completion behavior for the arguments of commands + not assigned any special behavior. If no compctl -D command has + been issued, filenames are completed. + +-T + supplies completion flags to be used before any other processing is + done, even before processing for compctls defined for specific + commands. This is especially useful when combined with extended + completion (the -x flag, see *Note Extended Completion:: below). + Using this flag you can define default behavior which will apply + to all commands without exception, or you can alter the standard + behavior for all commands. For example, if your access to the + user database is too slow and/or it contains too many users (so + that completion after `~' is too slow to be usable), you can use + + + compctl -T -x 's[~] C[0,[^/]#]' -k friends -S/ -tn + + to complete the strings in the array friends after a `~'. The + C[...] argument is necessary so that this form of ~-completion is + not tried after the directory name is finished. + +-L + lists the existing completion behavior in a manner suitable for + putting into a start-up script; the existing behavior is not + changed. Any combination of the above forms, or the -M flag + (which must follow the -L flag), may be specified, otherwise all + defined completions are listed. Any other flags supplied are + ignored. + +_no argument_ + If no argument is given, compctl lists all defined completions in + an abbreviated form; with a list of OPTIONS, all completions with + those flags set (not counting extended completion) are listed. + + +If the + flag is alone and followed immediately by the COMMAND list, +the completion behavior for all the commands in the list is reset to +the default. In other words, completion will subsequently use the +options specified by the -D flag. + +The form with -M as the first and only option defines global matching +specifications (see *Note Completion Matching Control::). The match +specifications given will be used for every completion attempt (only +when using compctl, not with the new completion system) and are tried +in the order in which they are defined until one generates at least one +match. E.g.: + + + compctl -M '' 'm:{a-zA-Z}={A-Za-z}' + +This will first try completion without any global match specifications +(the empty string) and, if that generates no matches, will try case +insensitive completion. + + + + +File: zsh.info, Node: Option Flags, Next: Alternative Completion, Prev: Command Flags, Up: Completion Using compctl + +21.4 Option Flags +================= + + +[ -fcFBdeaRGovNAIOPZEnbjrzu/12 ] + +[ -k ARRAY ] [ -g GLOBSTRING ] [ -s SUBSTSTRING ] + +[ -K FUNCTION ] + +[ -Q ] [ -P PREFIX ] [ -S SUFFIX ] + +[ -W FILE-PREFIX ] [ -H NUM PATTERN ] + +[ -q ] [ -X EXPLANATION ] [ -Y EXPLANATION ] + +[ -y FUNC-OR-VAR ] [ -l CMD ] [ -h CMD ] [ -U ] + +[ -t CONTINUE ] [ -J NAME ] [ -V NAME ] + +[ -M MATCH-SPEC ] + + +The remaining OPTIONS specify the type of command arguments to look for +during completion. Any combination of these flags may be specified; +the result is a sorted list of all the possibilities. The options are +as follows. + +* Menu: + +* Simple Flags:: +* Flags with Arguments:: +* Control Flags:: + + + +File: zsh.info, Node: Simple Flags, Next: Flags with Arguments, Up: Option Flags + +21.4.1 Simple Flags +------------------- + +These produce completion lists made up by the shell itself: + + +-f + Filenames and file system paths. + +-/ + Just file system paths. + +-c + Command names, including aliases, shell functions, builtins and + reserved words. + +-F + Function names. + +-B + Names of builtin commands. + +-m + Names of external commands. + +-w + Reserved words. + +-a + Alias names. + +-R + Names of regular (non-global) aliases. + +-G + Names of global aliases. + +-d + This can be combined with -F, -B, -w, -a, -R and -G to get names + of disabled functions, builtins, reserved words or aliases. + +-e + This option (to show enabled commands) is in effect by default, but + may be combined with -d; -de in combination with -F, -B, -w, -a, + -R and -G will complete names of functions, builtins, reserved + words or aliases whether or not they are disabled. + +-o + Names of shell options (see *Note Options::). + +-v + Names of any variable defined in the shell. + +-N + Names of scalar (non-array) parameters. + +-A + Array names. + +-I + Names of integer variables. + +-O + Names of read-only variables. + +-p + Names of parameters used by the shell (including special + parameters). + +-Z + Names of shell special parameters. + +-E + Names of environment variables. + +-n + Named directories. + +-b + Key binding names. + +-j + Job names: the first word of the job leader's command line. This + is useful with the kill builtin. + +-r + Names of running jobs. + +-z + Names of suspended jobs. + +-u + User names. + + + + +File: zsh.info, Node: Flags with Arguments, Next: Control Flags, Prev: Simple Flags, Up: Option Flags + +21.4.2 Flags with Arguments +--------------------------- + +These have user supplied arguments to determine how the list of +completions is to be made up: + + +-k ARRAY + Names taken from the elements of $ARRAY (note that the `$' does + not appear on the command line). Alternatively, the argument + ARRAY itself may be a set of space- or comma-separated values in + parentheses, in which any delimiter may be escaped with a + backslash; in this case the argument should be quoted. For + example, + + + compctl -k "(cputime filesize datasize stacksize + coredumpsize resident descriptors)" limit + +-g GLOBSTRING + The GLOBSTRING is expanded using filename globbing; it should be + quoted to protect it from immediate expansion. The resulting + filenames are taken as the possible completions. Use `*(/)' + instead of `*/' for directories. The fignore special parameter is + not applied to the resulting files. More than one pattern may be + given separated by blanks. (Note that brace expansion is _not_ + part of globbing. Use the syntax `(either|or)' to match + alternatives.) + +-s SUBSTSTRING + The SUBSTSTRING is split into words and these words are than + expanded using all shell expansion mechanisms (see *Note + Expansion::). The resulting words are taken as possible + completions. The fignore special parameter is not applied to the + resulting files. Note that -g is faster for filenames. + +-K FUNCTION + Call the given function to get the completions. Unless the name + starts with an underscore, the function is passed two arguments: + the prefix and the suffix of the word on which completion is to be + attempted, in other words those characters before the cursor + position, and those from the cursor position onwards. The whole + command line can be accessed with the -c and -l flags of the read + builtin. The function should set the variable reply to an array + containing the completions (one completion per element); note that + reply should not be made local to the function. From such a + function the command line can be accessed with the -c and -l flags + to the read builtin. For example, + + + function whoson { reply=(`users`); } + compctl -K whoson talk + + completes only logged-on users after `talk'. Note that `whoson' + must return an array, so `reply=`users`' would be incorrect. + +-H NUM PATTERN + The possible completions are taken from the last NUM history + lines. Only words matching PATTERN are taken. If NUM is zero or + negative the whole history is searched and if PATTERN is the empty + string all words are taken (as with `*'). A typical use is + + + compctl -D -f + -H 0 '' + + which forces completion to look back in the history list for a + word if no filename matches. + + + + +File: zsh.info, Node: Control Flags, Prev: Flags with Arguments, Up: Option Flags + +21.4.3 Control Flags +-------------------- + +These do not directly specify types of name to be completed, but +manipulate the options that do: + + +-Q + This instructs the shell not to quote any metacharacters in the + possible completions. Normally the results of a completion are + inserted into the command line with any metacharacters quoted so + that they are interpreted as normal characters. This is + appropriate for filenames and ordinary strings. However, for + special effects, such as inserting a backquoted expression from a + completion array (-k) so that the expression will not be evaluated + until the complete line is executed, this option must be used. + +-P PREFIX + The PREFIX is inserted just before the completed string; any + initial part already typed will be completed and the whole PREFIX + ignored for completion purposes. For example, + + + compctl -j -P "%" kill + + inserts a `%' after the kill command and then completes job names. + +-S SUFFIX + When a completion is found the SUFFIX is inserted after the + completed string. In the case of menu completion the suffix is + inserted immediately, but it is still possible to cycle through the + list of completions by repeatedly hitting the same key. + +-W FILE-PREFIX + With directory FILE-PREFIX: for command, file, directory and + globbing completion (options -c, -f, -/, -g), the file prefix is + implicitly added in front of the completion. For example, + + + compctl -/ -W ~/Mail maildirs + + completes any subdirectories to any depth beneath the directory + ~/Mail, although that prefix does not appear on the command line. + The FILE-PREFIX may also be of the form accepted by the -k flag, + i.e. the name of an array or a literal list in parenthesis. In + this case all the directories in the list will be searched for + possible completions. + +-q + If used with a suffix as specified by the -S option, this causes + the suffix to be 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; this + the same rule used for the AUTO_REMOVE_SLASH option. The option + is most useful for list separators (comma, colon, etc.). + +-l CMD + This option restricts the range of command line words that are + considered to be arguments. If combined with one of the extended + completion patterns `p[...]', `r[...]', or `R[...]' (see *Note + Extended Completion:: below) the range is restricted to the range + of arguments specified in the brackets. Completion is then + performed as if these had been given as arguments to the CMD + supplied with the option. If the CMD string is empty the first + word in the range is instead taken as the command name, and + command name completion performed on the first word in the range. + For example, + + + compctl -x 'r[-exec,;]' -l '' -- find + + completes arguments between `-exec' and the following `;' (or the + end of the command line if there is no such string) as if they were + a separate command line. + +-h CMD + Normally zsh completes quoted strings as a whole. With this option, + completion can be done separately on different parts of such + strings. It works like the -l option but makes the completion code + work on the parts of the current word that are separated by + spaces. These parts are completed as if they were arguments to the + given CMD. If CMD is the empty string, the first part is completed + as a command name, as with -l. + +-U + Use the whole list of possible completions, whether or not they + actually match the word on the command line. The word typed so far + will be deleted. This is most useful with a function (given by the + -K option) which can examine the word components passed to it (or + via the read builtin's -c and -l flags) and use its own criteria + to decide what matches. If there is no completion, the original + word is retained. Since the produced possible completions seldom + have interesting common prefixes and suffixes, menu completion is + started immediately if AUTO_MENU is set and this flag is used. + +-y FUNC-OR-VAR + The list provided by FUNC-OR-VAR is displayed instead of the list + of completions whenever a listing is required; the actual + completions to be inserted are not affected. It can be provided + in two ways. Firstly, if FUNC-OR-VAR begins with a $ it defines a + variable, or if it begins with a left parenthesis a literal array, + which contains the list. A variable may have been set by a call + to a function using the -K option. Otherwise it contains the name + of a function which will be executed to create the list. The + function will be passed as an argument list all matching + completions, including prefixes and suffixes expanded in full, and + should set the array reply to the result. In both cases, the + display list will only be retrieved after a complete list of + matches has been created. + + Note that the returned list does not have to correspond, even in + length, to the original set of matches, and may be passed as a + scalar instead of an array. No special formatting of characters is + performed on the output in this case; in particular, newlines are + printed literally and if they appear output in columns is + suppressed. + +-X EXPLANATION + Print EXPLANATION when trying completion on the current set of + options. A `%n' in this string is replaced by the number of + matches that were added for this explanation string. The + explanation only appears if completion was tried and there was no + unique match, or when listing completions. Explanation strings + will be listed together with the matches of the group specified + together with the -X option (using the -J or -V option). If the + same explanation string is given to multiple -X options, the + string appears only once (for each group) and the number of + matches shown for the `%n' is the total number of all matches for + each of these uses. In any case, the explanation string will only + be shown if there was at least one match added for the explanation + string. + + The sequences %B, %b, %S, %s, %U, and %u specify output attributes + (bold, standout, and underline), %F, %f, %K, %k specify foreground + and background colours, and %{...%} can be used to include literal + escape sequences as in prompts. + +-Y EXPLANATION + Identical to -X, except that the EXPLANATION first undergoes + expansion following the usual rules for strings in double quotes. + The expansion will be carried out after any functions are called + for the -K or -y options, allowing them to set variables. + +-t CONTINUE + The CONTINUE-string contains a character that specifies which set + of completion flags should be used next. It is useful: + + (i) With -T, or when trying a list of pattern completions, when + compctl would usually continue with ordinary processing after + finding matches; this can be suppressed with `-tn'. + + (ii) With a list of alternatives separated by +, when compctl + would normally stop when one of the alternatives generates + matches. It can be forced to consider the next set of completions + by adding `-t+' to the flags of the alternative before the `+'. + + (iii) In an extended completion list (see below), when compctl + would normally continue until a set of conditions succeeded, then + use only the immediately following flags. With `-t-', compctl will + continue trying extended completions after the next `-'; with + `-tx' it will attempt completion with the default flags, in other + words those before the `-x'. + +-J NAME + This gives the name of the group the matches should be placed in. + Groups are listed and sorted separately; likewise, menu completion + will offer the matches in the groups in the order in which the + groups were defined. If no group name is explicitly given, the + matches are stored in a group named default. The first time a + group name is encountered, a group with that name is created. + After that all matches with the same group name are stored in that + group. + + This can be useful with non-exclusive alternative completions. For + example, in + + + compctl -f -J files -t+ + -v -J variables foo + + both files and variables are possible completions, as the -t+ + forces both sets of alternatives before and after the + to be + considered at once. Because of the -J options, however, all files + are listed before all variables. + +-V NAME + Like -J, but matches within the group will not be sorted in + listings nor in menu completion. These unsorted groups are in a + different name space from the sorted ones, so groups defined as -J + files and -V files are distinct. + +-1 + If given together with the -V option, makes only consecutive + duplicates in the group be removed. Note that groups with and + without this flag are in different name spaces. + +-2 + If given together with the -J or -V option, makes all duplicates + be kept. Again, groups with and without this flag are in different + name spaces. + +-M MATCH-SPEC + This defines additional matching control specifications that + should be used only when testing words for the list of flags this + flag appears in. The format of the MATCH-SPEC string is described + in *Note Completion Matching Control::. + + + + +File: zsh.info, Node: Alternative Completion, Next: Extended Completion, Prev: Option Flags, Up: Completion Using compctl + +21.5 Alternative Completion +=========================== + + +compctl [ -CDT ] OPTIONS + OPTIONS [ + ... ] [ + ] COMMAND ... + + +The form with `+' specifies alternative options. Completion is tried +with the options before the first `+'. If this produces no matches +completion is tried with the flags after the `+' and so on. If there +are no flags after the last `+' and a match has not been found up to +that point, default completion is tried. If the list of flags contains +a -t with a + character, the next list of flags is used even if the +current list produced matches. + + + + +File: zsh.info, Node: Extended Completion, Next: Example, Prev: Alternative Completion, Up: Completion Using compctl + +Additional options are available that restrict completion to some part +of the command line; this is referred to as `extended completion'. + + + +21.6 Extended Completion +======================== + + +compctl [ -CDT ] OPTIONS -x PATTERN OPTIONS - ... -- + + [ COMMAND ... ] + +compctl [ -CDT ] OPTIONS [ -x PATTERN OPTIONS - ... -- ] + + [ + OPTIONS [ -x ... -- ] ... [+] ] [ COMMAND ... ] + + +The form with `-x' specifies extended completion for the commands +given; as shown, it may be combined with alternative completion using +`+'. Each PATTERN is examined in turn; when a match is found, the +corresponding OPTIONS, as described in *Note Option Flags:: above, are +used to generate possible completions. If no PATTERN matches, the +OPTIONS given before the -x are used. + +Note that each pattern should be supplied as a single argument and +should be quoted to prevent expansion of metacharacters by the shell. + +A PATTERN is built of sub-patterns separated by commas; it matches if +at least one of these sub-patterns matches (they are `or'ed). These +sub-patterns are in turn composed of other sub-patterns separated by +white spaces which match if all of the sub-patterns match (they are +`and'ed). An element of the sub-patterns is of the form `C[...][...]', +where the pairs of brackets may be repeated as often as necessary, and +matches if any of the sets of brackets match (an `or'). The example +below makes this clearer. + +The elements may be any of the following: + + +s[STRING]... + Matches if the current word on the command line starts with one of + the strings given in brackets. The STRING is not removed and is + not part of the completion. + +S[STRING]... + Like s[STRING] except that the STRING is part of the completion. + +p[FROM,TO]... + Matches if the number of the current word is between one of the + FROM and TO pairs inclusive. The comma and TO are optional; TO + defaults to the same value as FROM. The numbers may be negative: + -N refers to the N'th last word on the line. + +c[OFFSET,STRING]... + Matches if the STRING matches the word offset by OFFSET from the + current word position. Usually OFFSET will be negative. + +C[OFFSET,PATTERN]... + Like c but using pattern matching instead. + +w[INDEX,STRING]... + Matches if the word in position INDEX is equal to the + corresponding STRING. Note that the word count is made after any + alias expansion. + +W[INDEX,PATTERN]... + Like w but using pattern matching instead. + +n[INDEX,STRING]... + Matches if the current word contains STRING. Anything up to and + including the INDEXth occurrence of this string will not be + considered part of the completion, but the rest will. INDEX may + be negative to count from the end: in most cases, INDEX will be 1 + or -1. For example, + + + compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk + + will usually complete usernames, but if you insert an @ after the + name, names from the array HOSTS (assumed to contain hostnames, + though you must make the array yourself) will be completed. Other + commands such as rcp can be handled similarly. + +N[INDEX,STRING]... + Like n except that the string will be taken as a character class. + Anything up to and including the INDEXth occurrence of any of the + characters in STRING will not be considered part of the completion. + +m[MIN,MAX]... + Matches if the total number of words lies between MIN and MAX + inclusive. + +r[STR1,STR2]... + Matches if the cursor is after a word with prefix STR1. If there + is also a word with prefix STR2 on the command line after the one + matched by STR1 it matches only if the cursor is before this word. + If the comma and STR2 are omitted, it matches if the cursor is + after a word with prefix STR1. + +R[STR1,STR2]... + Like r but using pattern matching instead. + +q[STR]... + Matches the word currently being completed is in single quotes and + the STR begins with the letter `s', or if completion is done in + double quotes and STR starts with the letter `d', or if completion + is done in backticks and STR starts with a `b'. + + + + +File: zsh.info, Node: Example, Prev: Extended Completion, Up: Completion Using compctl + +21.7 Example +============ + + + compctl -u -x 's[+] c[-1,-f],s[-f+]' \ + -g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail + +This is to be interpreted as follows: + +If the current command is mail, then + + + + if ((the current word begins with + and the previous word is -f) + or (the current word begins with -f+)), then complete the + non-directory part (the `:t' glob modifier) of files in the + directory ~/Mail; else + + if the current word begins with -f or the previous word was -f, + then complete any file; else + + complete user names. + + + +File: zsh.info, Node: Zsh Modules, Next: Calendar Function System, Prev: Completion Using compctl, Up: Top + +22 Zsh Modules +************** + + + +22.1 Description +================ + +Some optional parts of zsh are in modules, separate from the core of +the shell. Each of these modules may be linked in to the shell at +build time, or can be dynamically linked while the shell is running if +the installation supports this feature. Modules are linked at runtime +with the zmodload command, see *Note Shell Builtin Commands::. + +The modules that are bundled with the zsh distribution are: + + +zsh/attr + Builtins for manipulating extended attributes (xattr). + +zsh/cap + Builtins for manipulating POSIX.1e (POSIX.6) capability + (privilege) sets. + +zsh/clone + A builtin that can clone a running shell onto another terminal. + +zsh/compctl + The compctl builtin for controlling completion. + +zsh/complete + The basic completion code. + +zsh/complist + Completion listing extensions. + +zsh/computil + A module with utility builtins needed for the shell function based + completion system. + +zsh/curses + curses windowing commands + +zsh/datetime + Some date/time commands and parameters. + +zsh/db/gdbm + Builtins for managing associative array parameters tied to GDBM + databases. + +zsh/deltochar + A ZLE function duplicating EMACS' zap-to-char. + +zsh/example + An example of how to write a module. + +zsh/files + Some basic file manipulation commands as builtins. + +zsh/langinfo + Interface to locale information. + +zsh/mapfile + Access to external files via a special associative array. + +zsh/mathfunc + Standard scientific functions for use in mathematical evaluations. + +zsh/nearcolor + Map colours to the nearest colour in the available palette. + +zsh/newuser + Arrange for files for new users to be installed. + +zsh/parameter + Access to internal hash tables via special associative arrays. + +zsh/pcre + Interface to the PCRE library. + +zsh/param/private + Builtins for managing private-scoped parameters in function + context. + +zsh/regex + Interface to the POSIX regex library. + +zsh/sched + A builtin that provides a timed execution facility within the + shell. + +zsh/net/socket + Manipulation of Unix domain sockets + +zsh/stat + A builtin command interface to the stat system call. + +zsh/system + A builtin interface to various low-level system features. + +zsh/net/tcp + Manipulation of TCP sockets + +zsh/termcap + Interface to the termcap database. + +zsh/terminfo + Interface to the terminfo database. + +zsh/zftp + A builtin FTP client. + +zsh/zle + The Zsh Line Editor, including the bindkey and vared builtins. + +zsh/zleparameter + Access to internals of the Zsh Line Editor via parameters. + +zsh/zprof + A module allowing profiling for shell functions. + +zsh/zpty + A builtin for starting a command in a pseudo-terminal. + +zsh/zselect + Block and return when file descriptors are ready. + +zsh/zutil + Some utility builtins, e.g. the one for supporting configuration + via styles. + + +* Menu: + +* The zsh/attr Module:: +* The zsh/cap Module:: +* The zsh/clone Module:: +* The zsh/compctl Module:: +* The zsh/complete Module:: +* The zsh/complist Module:: +* The zsh/computil Module:: +* The zsh/curses Module:: +* The zsh/datetime Module:: +* The zsh/db/gdbm Module:: +* The zsh/deltochar Module:: +* The zsh/example Module:: +* The zsh/files Module:: +* The zsh/langinfo Module:: +* The zsh/mapfile Module:: +* The zsh/mathfunc Module:: +* The zsh/nearcolor Module:: +* The zsh/newuser Module:: +* The zsh/parameter Module:: +* The zsh/pcre Module:: +* The zsh/param/private Module:: +* The zsh/regex Module:: +* The zsh/sched Module:: +* The zsh/net/socket Module:: +* The zsh/stat Module:: +* The zsh/system Module:: +* The zsh/net/tcp Module:: +* The zsh/termcap Module:: +* The zsh/terminfo Module:: +* The zsh/zftp Module:: +* The zsh/zle Module:: +* The zsh/zleparameter Module:: +* The zsh/zprof Module:: +* The zsh/zpty Module:: +* The zsh/zselect Module:: +* The zsh/zutil Module:: + + +File: zsh.info, Node: The zsh/attr Module, Next: The zsh/cap Module, Up: Zsh Modules + +22.2 The zsh/attr Module +======================== + + + + The zsh/attr module is used for manipulating extended attributes. +The -h option causes all commands to operate on symbolic links instead +of their targets. The builtins in this module are: + + +zgetattr [ -h ] FILENAME ATTRIBUTE [ PARAMETER ] + Get the extended attribute ATTRIBUTE from the specified FILENAME. + If the optional argument PARAMETER is given, the attribute is set + on that parameter instead of being printed to stdout. + +zsetattr [ -h ] FILENAME ATTRIBUTE VALUE + Set the extended attribute ATTRIBUTE on the specified FILENAME to + VALUE. + +zdelattr [ -h ] FILENAME ATTRIBUTE + Remove the extended attribute ATTRIBUTE from the specified + FILENAME. + +zlistattr [ -h ] FILENAME [ PARAMETER ] + List the extended attributes currently set on the specified + FILENAME. If the optional argument PARAMETER is given, the list of + attributes is set on that parameter instead of being printed to + stdout. + + +zgetattr and zlistattr allocate memory dynamically. If the attribute +or list of attributes grows between the allocation and the call to get +them, they return 2. On all other errors, 1 is returned. This allows +the calling function to check for this case and retry. + + +File: zsh.info, Node: The zsh/cap Module, Next: The zsh/clone Module, Prev: The zsh/attr Module, Up: Zsh Modules + +22.3 The zsh/cap Module +======================= + + + + The zsh/cap module is used for manipulating POSIX.1e (POSIX.6) +capability sets. If the operating system does not support this +interface, the builtins defined by this module will do nothing. The +builtins in this module are: + + +cap [ CAPABILITIES ] + Change the shell's process capability sets to the specified + CAPABILITIES, otherwise display the shell's current capabilities. + +getcap FILENAME ... + This is a built-in implementation of the POSIX standard utility. + It displays the capability sets on each specified FILENAME. + +setcap CAPABILITIES FILENAME ... + This is a built-in implementation of the POSIX standard utility. + It sets the capability sets on each specified FILENAME to the + specified CAPABILITIES. + + + +File: zsh.info, Node: The zsh/clone Module, Next: The zsh/compctl Module, Prev: The zsh/cap Module, Up: Zsh Modules + +22.4 The zsh/clone Module +========================= + + + + The zsh/clone module makes available one builtin command: + + +clone TTY + Creates a forked instance of the current shell, attached to the + specified TTY. In the new shell, the PID, PPID and TTY special + parameters are changed appropriately. $! is set to zero in the new + shell, and to the new shell's PID in the original shell. + + The return status of the builtin is zero in both shells if + successful, and non-zero on error. + + The target of clone should be an unused terminal, such as an + unused virtual console or a virtual terminal created by + + + xterm -e sh -c 'trap : INT QUIT TSTP; tty; + while :; do sleep 100000000; done' + + Some words of explanation are warranted about this long xterm + command line: when doing clone on a pseudo-terminal, some other + session ("session" meant as a unix session group, or SID) is + already owning the terminal. Hence the cloned zsh cannot acquire + the pseudo-terminal as a controlling tty. That means two things: + + + * the job control signals will go to the sh-started-by-xterm + process group (that's why we disable INT QUIT and TSTP with + trap; otherwise the while loop could get suspended or killed) + + * the cloned shell will have job control disabled, and the job + control keys (control-C, control-\ and control-Z) will not + work. + + This does not apply when cloning to an _unused_ vc. + + Cloning to a used (and unprepared) terminal will result in two + processes reading simultaneously from the same terminal, with + input bytes going randomly to either process. + + clone is mostly useful as a shell built-in replacement for openvt. + + + +File: zsh.info, Node: The zsh/compctl Module, Next: The zsh/complete Module, Prev: The zsh/clone Module, Up: Zsh Modules + +22.5 The zsh/compctl Module +=========================== + + + + The zsh/compctl module makes available two builtin commands. compctl, +is the old, deprecated way to control completions for ZLE. See *Note +Completion Using compctl::. The other builtin command, compcall can be +used in user-defined completion widgets, see *Note Completion Widgets::. + + +File: zsh.info, Node: The zsh/complete Module, Next: The zsh/complist Module, Prev: The zsh/compctl Module, Up: Zsh Modules + +22.6 The zsh/complete Module +============================ + + + + The zsh/complete module makes available several builtin commands +which can be used in user-defined completion widgets, see *Note +Completion Widgets::. + + +File: zsh.info, Node: The zsh/complist Module, Next: The zsh/computil Module, Prev: The zsh/complete Module, Up: Zsh Modules + +22.7 The zsh/complist Module +============================ + + + + The zsh/complist module offers three extensions to completion +listings: the ability to highlight matches in such a list, the ability +to scroll through long lists and a different style of menu completion. + + + +22.7.1 Colored completion listings +---------------------------------- + +Whenever one of the parameters ZLS_COLORS or ZLS_COLOURS is set and the +zsh/complist module is loaded or linked into the shell, completion +lists will be colored. Note, however, that complist will not +automatically be loaded if it is not linked in: on systems with +dynamic loading, `zmodload zsh/complist' is required. + +The parameters ZLS_COLORS and ZLS_COLOURS describe how matches are +highlighted. To turn on highlighting an empty value suffices, in which +case all the default values given below will be used. The format of +the value of these parameters is the same as used by the GNU version of +the ls command: a colon-separated list of specifications of the form +`NAME=VALUE'. The NAME may be one of the following strings, most of +which specify file types for which the VALUE will be used. The strings +and their default values are: + + +no 0 + for normal text (i.e. when displaying something other than a + matched file) + +fi 0 + for regular files + +di 32 + for directories + +ln 36 + for symbolic links. If this has the special value target, + symbolic links are dereferenced and the target file used to + determine the display format. + +pi 31 + for named pipes (FIFOs) + +so 33 + for sockets + +bd 44;37 + for block devices + +cd 44;37 + for character devices + +or NONE + for a symlink to nonexistent file (default is the value defined + for ln) + +mi NONE + for a non-existent file (default is the value defined for fi); + this code is currently not used + +su 37;41 + for files with setuid bit set + +sg 30;43 + for files with setgid bit set + +tw 30;42 + for world writable directories with sticky bit set + +ow 34;43 + for world writable directories without sticky bit set + +sa NONE + for files with an associated suffix alias; this is only tested + after specific suffixes, as described below + +st 37;44 + for directories with sticky bit set but not world writable + +ex 35 + for executable files + +lc \e[ + for the left code (see below) + +rc m + for the right code + +tc 0 + for the character indicating the file type printed after + filenames if the LIST_TYPES option is set + +sp 0 + for the spaces printed after matches to align the next column + +ec NONE + for the end code + + +Apart from these strings, the NAME may also be an asterisk (`*') +followed by any string. The VALUE given for such a string will be used +for all files whose name ends with the string. The NAME may also be an +equals sign (`=') followed by a pattern; the EXTENDED_GLOB option will +be turned on for evaluation of the pattern. The VALUE given for this +pattern will be used for all matches (not just filenames) whose display +string are matched by the pattern. Definitions for the form with the +leading equal sign take precedence over the values defined for file +types, which in turn take precedence over the form with the leading +asterisk (file extensions). + +The leading-equals form also allows different parts of the displayed +strings to be colored differently. For this, the pattern has to use the +`(#b)' globbing flag and pairs of parentheses surrounding the parts of +the strings that are to be colored differently. In this case the VALUE +may consist of more than one color code separated by equal signs. The +first code will be used for all parts for which no explicit code is +specified and the following codes will be used for the parts matched by +the sub-patterns in parentheses. For example, the specification +`=(#b)(?)*(?)=0=3=7' will be used for all matches which are at least +two characters long and will use the code `3' for the first character, +`7' for the last character and `0' for the rest. + +All three forms of NAME may be preceded by a pattern in parentheses. +If this is given, the VALUE will be used only for matches in groups +whose names are matched by the pattern given in the parentheses. For +example, `(g*)m*=43' highlights all matches beginning with `m' in +groups whose names begin with `g' using the color code `43'. In case +of the `lc', `rc', and `ec' codes, the group pattern is ignored. + +Note also that all patterns are tried in the order in which they appear +in the parameter value until the first one matches which is then used. +Patterns may be matched against completions, descriptions (possibly +with spaces appended for padding), or lines consisting of a completion +followed by a description. For consistent coloring it may be necessary +to use more than one pattern or a pattern with backreferences. + +When printing a match, the code prints the value of lc, the value for +the file-type or the last matching specification with a `*', the value +of rc, the string to display for the match itself, and then the value +of ec if that is defined or the values of lc, no, and rc if ec is not +defined. + +The default values are ISO 6429 (ANSI) compliant and can be used on +vt100 compatible terminals such as xterms. On monochrome terminals the +default values will have no visible effect. The colors function from +the contribution can be used to get associative arrays containing the +codes for ANSI terminals (see *Note Other Functions::). For example, +after loading colors, one could use `$color[red]' to get the code for +foreground color red and `$color[bg-green]' for the code for background +color green. + +If the completion system invoked by compinit is used, these parameters +should not be set directly because the system controls them itself. +Instead, the list-colors style should be used (see *Note Completion +System Configuration::). + + + +22.7.2 Scrolling in completion listings +--------------------------------------- + +To enable scrolling through a completion list, the LISTPROMPT parameter +must be set. Its value will be used as the prompt; if it is the empty +string, a default prompt will be used. The value may contain escapes +of the form `%x'. It supports the escapes `%B', `%b', `%S', `%s', +`%U', `%u', `%F', `%f', `%K', `%k' and `%{...%}' used also in shell +prompts as well as three pairs of additional sequences: a `%l' or `%L' +is replaced by the number of the last line shown and the total number +of lines in the form `NUMBER/TOTAL'; a `%m' or `%M' is replaced with +the number of the last match shown and the total number of matches; and +`%p' or `%P' is replaced with `Top', `Bottom' or the position of the +first line shown in percent of the total number of lines, respectively. +In each of these cases the form with the uppercase letter will be +replaced with a string of fixed width, padded to the right with spaces, +while the lowercase form will not be padded. + +If the parameter LISTPROMPT is set, the completion code will not ask if +the list should be shown. Instead it immediately starts displaying the +list, stopping after the first screenful, showing the prompt at the +bottom, waiting for a keypress after temporarily switching to the +listscroll keymap. Some of the zle functions have a special meaning +while scrolling lists: + + +send-break + stops listing discarding the key pressed + +accept-line, down-history, down-line-or-history +down-line-or-search, vi-down-line-or-history + scrolls forward one line + +complete-word, menu-complete, expand-or-complete +expand-or-complete-prefix, menu-complete-or-expand + scrolls forward one screenful + +accept-search + stop listing but take no other action + + +Every other character stops listing and immediately processes the key +as usual. Any key that is not bound in the listscroll keymap or that +is bound to undefined-key is looked up in the keymap currently selected. + +As for the ZLS_COLORS and ZLS_COLOURS parameters, LISTPROMPT should not +be set directly when using the shell function based completion system. +Instead, the list-prompt style should be used. + + + +22.7.3 Menu selection +--------------------- + +The zsh/complist module also offers an alternative style of selecting +matches from a list, called menu selection, which can be used if the +shell is set up to return to the last prompt after showing a completion +list (see the ALWAYS_LAST_PROMPT option in *Note Options::). + +Menu selection can be invoked directly by the widget menu-select +defined by this module. This is a standard ZLE widget that can be +bound to a key in the usual way as described in *Note Zsh Line Editor::. + +Alternatively, the parameter MENUSELECT can be set to an integer, which +gives the minimum number of matches that must be present before menu +selection is automatically turned on. This second method requires that +menu completion be started, either directly from a widget such as +menu-complete, or due to one of the options MENU_COMPLETE or AUTO_MENU +being set. If MENUSELECT is set, but is 0, 1 or empty, menu selection +will always be started during an ambiguous menu completion. + +When using the completion system based on shell functions, the +MENUSELECT parameter should not be used (like the ZLS_COLORS and +ZLS_COLOURS parameters described above). Instead, the menu style +should be used with the select=... keyword. + +After menu selection is started, the matches will be listed. If there +are more matches than fit on the screen, only the first screenful is +shown. The matches to insert into the command line can be selected +from this list. In the list one match is highlighted using the value +for ma from the ZLS_COLORS or ZLS_COLOURS parameter. The default value +for this is `7' which forces the selected match to be highlighted using +standout mode on a vt100-compatible terminal. If neither ZLS_COLORS +nor ZLS_COLOURS is set, the same terminal control sequence as for the +`%S' escape in prompts is used. + +If there are more matches than fit on the screen and the parameter +MENUPROMPT is set, its value will be shown below the matches. It +supports the same escape sequences as LISTPROMPT, but the number of the +match or line shown will be that of the one where the mark is placed. +If its value is the empty string, a default prompt will be used. + +The MENUSCROLL parameter can be used to specify how the list is +scrolled. If the parameter is unset, this is done line by line, if it +is set to `0' (zero), the list will scroll half the number of lines of +the screen. If the value is positive, it gives the number of lines to +scroll and if it is negative, the list will be scrolled the number of +lines of the screen minus the (absolute) value. + +As for the ZLS_COLORS, ZLS_COLOURS and LISTPROMPT parameters, neither +MENUPROMPT nor MENUSCROLL should be set directly when using the shell +function based completion system. Instead, the select-prompt and +select-scroll styles should be used. + +The completion code sometimes decides not to show all of the matches in +the list. These hidden matches are either matches for which the +completion function which added them explicitly requested that they not +appear in the list (using the -n option of the compadd builtin command) +or they are matches which duplicate a string already in the list +(because they differ only in things like prefixes or suffixes that are +not displayed). In the list used for menu selection, however, even +these matches are shown so that it is possible to select them. To +highlight such matches the hi and du capabilities in the ZLS_COLORS and +ZLS_COLOURS parameters are supported for hidden matches of the first +and second kind, respectively. + +Selecting matches is done by moving the mark around using the zle +movement functions. When not all matches can be shown on the screen at +the same time, the list will scroll up and down when crossing the top or +bottom line. The following zle functions have special meaning during +menu selection. Note that the following always perform the same task +within the menu selection map and cannot be replaced by user defined +widgets, nor can the set of functions be extended: + + +accept-line, accept-search + accept the current match and leave menu selection (but do not + cause the command line to be accepted) + +send-break + leaves menu selection and restores the previous contents of the + command line + +redisplay, clear-screen + execute their normal function without leaving menu selection + +accept-and-hold, accept-and-menu-complete + accept the currently inserted match and continue selection + allowing to select the next match to insert into the line + +accept-and-infer-next-history + accepts the current match and then tries completion with menu + selection again; in the case of files this allows one to select a + directory and immediately attempt to complete files in it; if + there are no matches, a message is shown and one can use undo to + go back to completion on the previous level, every other key + leaves menu selection (including the other zle functions which are + otherwise special during menu selection) + +undo + removes matches inserted during the menu selection by one of the + three functions before + +down-history, down-line-or-history +vi-down-line-or-history, down-line-or-search + moves the mark one line down + +up-history, up-line-or-history +vi-up-line-or-history, up-line-or-search + moves the mark one line up + +forward-char, vi-forward-char + moves the mark one column right + +backward-char, vi-backward-char + moves the mark one column left + +forward-word, vi-forward-word +vi-forward-word-end, emacs-forward-word + moves the mark one screenful down + +backward-word, vi-backward-word, emacs-backward-word + moves the mark one screenful up + +vi-forward-blank-word, vi-forward-blank-word-end + moves the mark to the first line of the next group of matches + +vi-backward-blank-word + moves the mark to the last line of the previous group of matches + +beginning-of-history + moves the mark to the first line + +end-of-history + moves the mark to the last line + +beginning-of-buffer-or-history, beginning-of-line +beginning-of-line-hist, vi-beginning-of-line + moves the mark to the leftmost column + +end-of-buffer-or-history, end-of-line +end-of-line-hist, vi-end-of-line + moves the mark to the rightmost column + +complete-word, menu-complete, expand-or-complete +expand-or-complete-prefix, menu-expand-or-complete + moves the mark to the next match + +reverse-menu-complete + moves the mark to the previous match + +vi-insert + this toggles between normal and interactive mode; in interactive + mode the keys bound to self-insert and self-insert-unmeta insert + into the command line as in normal editing mode but without leaving + menu selection; after each character completion is tried again and + the list changes to contain only the new matches; the completion + widgets make the longest unambiguous string be inserted in the + command line and undo and backward-delete-char go back to the + previous set of matches + +history-incremental-search-forward +history-incremental-search-backward + this starts incremental searches in the list of completions + displayed; in this mode, accept-line only leaves incremental + search, going back to the normal menu selection mode + + +All movement functions wrap around at the edges; any other zle function +not listed leaves menu selection and executes that function. It is +possible to make widgets in the above list do the same by using the +form of the widget with a `.' in front. For example, the widget +`.accept-line' has the effect of leaving menu selection and accepting +the entire command line. + +During this selection the widget uses the keymap menuselect. Any key +that is not defined in this keymap or that is bound to undefined-key is +looked up in the keymap currently selected. This is used to ensure +that the most important keys used during selection (namely the cursor +keys, return, and TAB) have sensible defaults. However, keys in the +menuselect keymap can be modified directly using the bindkey builtin +command (see *Note The zsh/zle Module::). For example, to make the +return key leave menu selection without accepting the match currently +selected one could call + + + bindkey -M menuselect '^M' send-break + +after loading the zsh/complist module. + + +File: zsh.info, Node: The zsh/computil Module, Next: The zsh/curses Module, Prev: The zsh/complist Module, Up: Zsh Modules + +22.8 The zsh/computil Module +============================ + + + + The zsh/computil module adds several builtin commands that are used +by some of the completion functions in the completion system based on +shell functions (see *Note Completion System:: ). Except for compquote +these builtin commands are very specialised and thus not very +interesting when writing your own completion functions. In summary, +these builtin commands are: + + +comparguments + This is used by the _arguments function to do the argument and + command line parsing. Like compdescribe it has an option -i to do + the parsing and initialize some internal state and various options + to access the state information to decide what should be completed. + +compdescribe + This is used by the _describe function to build the displays for + the matches and to get the strings to add as matches with their + options. On the first call one of the options -i or -I should be + supplied as the first argument. In the first case, display + strings without the descriptions will be generated, in the second + case, the string used to separate the matches from their + descriptions must be given as the second argument and the + descriptions (if any) will be shown. All other arguments are like + the definition arguments to _describe itself. + + Once compdescribe has been called with either the -i or the -I + option, it can be repeatedly called with the -g option and the + names of four parameters as its arguments. This will step through + the different sets of matches and store the value of + compstate[list] in the first scalar, the options for compadd in + the second array, the matches in the third array, and the strings + to be displayed in the completion listing in the fourth array. + The arrays may then be directly given to compadd to register the + matches with the completion code. + +compfiles + Used by the _path_files function to optimize complex recursive + filename generation (globbing). It does three things. With the + -p and -P options it builds the glob patterns to use, including + the paths already handled and trying to optimize the patterns with + respect to the prefix and suffix from the line and the match + specification currently used. The -i option does the directory + tests for the ignore-parents style and the -r option tests if a + component for some of the matches are equal to the string on the + line and removes all other matches if that is true. + +compgroups + Used by the _tags function to implement the internals of the + group-order style. This only takes its arguments as names of + completion groups and creates the groups for it (all six types: + sorted and unsorted, both without removing duplicates, with + removing all duplicates and with removing consecutive duplicates). + +compquote [ -p ] NAMES ... + There may be reasons to write completion functions that have to add + the matches using the -Q option to compadd and perform quoting + themselves. Instead of interpreting the first character of the + all_quotes key of the compstate special association and using the + q flag for parameter expansions, one can use this builtin command. + The arguments are the names of scalar or array parameters and the + values of these parameters are quoted as needed for the innermost + quoting level. If the -p option is given, quoting is done as if + there is some prefix before the values of the parameters, so that + a leading equal sign will not be quoted. + + The return status is non-zero in case of an error and zero + otherwise. + +comptags +comptry + These implement the internals of the tags mechanism. + +compvalues + Like comparguments, but for the _values function. + + + +File: zsh.info, Node: The zsh/curses Module, Next: The zsh/datetime Module, Prev: The zsh/computil Module, Up: Zsh Modules + +22.9 The zsh/curses Module +========================== + + + + The zsh/curses module makes available one builtin command and +various parameters. + + + +22.9.1 Builtin +-------------- + + +zcurses init +zcurses end +zcurses addwin TARGETWIN NLINES NCOLS BEGIN_Y BEGIN_X [ PARENTWIN ] +zcurses delwin TARGETWIN +zcurses refresh [ TARGETWIN ... ] +zcurses touch TARGETWIN ... +zcurses move TARGETWIN NEW_Y NEW_X +zcurses clear TARGETWIN [ redraw | eol | bot ] +zcurses position TARGETWIN ARRAY +zcurses char TARGETWIN CHARACTER +zcurses string TARGETWIN STRING +zcurses border TARGETWIN BORDER +zcurses attr TARGETWIN [ [+|-]ATTRIBUTE | FG_COL/BG_COL ] [...] +zcurses bg TARGETWIN [ [+|-]ATTRIBUTE | FG_COL/BG_COL | @CHAR ] [...] +zcurses scroll TARGETWIN [ on | off | [+|-]LINES ] +zcurses input TARGETWIN [ PARAM [ KPARAM [ MPARAM ] ] ] +zcurses mouse [ delay NUM | [+|-]motion ] +zcurses timeout TARGETWIN INTVAL +zcurses querychar TARGETWIN [ PARAM ] +zcurses resize HEIGHT WIDTH [ endwin | nosave | endwin_nosave ] + Manipulate curses windows. All uses of this command should be + bracketed by `zcurses init' to initialise use of curses, and + `zcurses end' to end it; omitting `zcurses end' can cause the + terminal to be in an unwanted state. + + The subcommand addwin creates a window with NLINES lines and NCOLS + columns. Its upper left corner will be placed at row BEGIN_Y and + column BEGIN_X of the screen. TARGETWIN is a string and refers to + the name of a window that is not currently assigned. Note in + particular the curses convention that vertical values appear + before horizontal values. + + If addwin is given an existing window as the final argument, the + new window is created as a subwindow of PARENTWIN. This differs + from an ordinary new window in that the memory of the window + contents is shared with the parent's memory. Subwindows must be + deleted before their parent. Note that the coordinates of + subwindows are relative to the screen, not the parent, as with + other windows. + + Use the subcommand delwin to delete a window created with addwin. + Note that end does _not_ implicitly delete windows, and that + delwin does not erase the screen image of the window. + + The window corresponding to the full visible screen is called + stdscr; it always exists after `zcurses init' and cannot be delete + with delwin. + + The subcommand refresh will refresh window TARGETWIN; this is + necessary to make any pending changes (such as characters you have + prepared for output with char) visible on the screen. refresh + without an argument causes the screen to be cleared and redrawn. + If multiple windows are given, the screen is updated once at the + end. + + The subcommand touch marks the TARGETWINs listed as changed. This + is necessary before refreshing windows if a window that was in + front of another window (which may be stdscr) is deleted. + + The subcommand move moves the cursor position in TARGETWIN to new + coordinates NEW_Y and NEW_X. Note that the subcommand string (but + not the subcommand char) advances the cursor position over the + characters added. + + The subcommand clear erases the contents of TARGETWIN. One (and + no more than one) of three options may be specified. With the + option redraw, in addition the next refresh of TARGETWIN will + cause the screen to be cleared and repainted. With the option + eol, TARGETWIN is only cleared to the end of the current cursor + line. With the option bot, TARGETWIN is cleared to the end of the + window, i.e everything to the right and below the cursor is + cleared. + + The subcommand position writes various positions associated with + TARGETWIN into the array named ARRAY. These are, in order: + - + The y and x coordinates of the cursor relative to the top left + of TARGETWIN + + - + The y and x coordinates of the top left of TARGETWIN on the + screen + + - + The size of TARGETWIN in y and x dimensions. + + Outputting characters and strings are achieved by char and string + respectively. + + To draw a border around window TARGETWIN, use border. Note that + the border is not subsequently handled specially: in other words, + the border is simply a set of characters output at the edge of the + window. Hence it can be overwritten, can scroll off the window, + etc. + + The subcommand attr will set TARGETWIN's attributes or + foreground/background color pair for any successive character + output. Each ATTRIBUTE given on the line may be prepended by a + + to set or a - to unset that attribute; + is assumed if absent. The + attributes supported are blink, bold, dim, reverse, standout, and + underline. + + Each FG_COL/BG_COL attribute (to be read as `FG_COL on BG_COL') + sets the foreground and background color for character output. + The color default is sometimes available (in particular if the + library is ncurses), specifying the foreground or background color + with which the terminal started. The color pair default/default + is always available. To use more than the 8 named colors (red, + green, etc.) construct the FG_COL/BG_COL pairs where FG_COL and + BG_COL are decimal integers, e.g 128/200. The maximum color value + is 254 if the terminal supports 256 colors. + + bg overrides the color and other attributes of all characters in + the window. Its usual use is to set the background initially, but + it will overwrite the attributes of any characters at the time + when it is called. In addition to the arguments allowed with + attr, an argument @CHAR specifies a character to be shown in + otherwise blank areas of the window. Owing to limitations of + curses this cannot be a multibyte character (use of ASCII + characters only is recommended). As the specified set of + attributes override the existing background, turning attributes + off in the arguments is not useful, though this does not cause an + error. + + The subcommand scroll can be used with on or off to enabled or + disable scrolling of a window when the cursor would otherwise move + below the window due to typing or output. It can also be used + with a positive or negative integer to scroll the window up or + down the given number of lines without changing the current cursor + position (which therefore appears to move in the opposite + direction relative to the window). In the second case, if + scrolling is off it is temporarily turned on to allow the window + to be scrolled. + + The subcommand input reads a single character from the window + without echoing it back. If PARAM is supplied the character is + assigned to the parameter PARAM, else it is assigned to the + parameter REPLY. + + If both PARAM and KPARAM are supplied, the key is read in `keypad' + mode. In this mode special keys such as function keys and arrow + keys return the name of the key in the parameter KPARAM. The key + names are the macros defined in the curses.h or ncurses.h with the + prefix `KEY_' removed; see also the description of the parameter + zcurses_keycodes below. Other keys cause a value to be set in + PARAM as before. On a successful return only one of PARAM or + KPARAM contains a non-empty string; the other is set to an empty + string. + + If MPARAM is also supplied, input attempts to handle mouse input. + This is only available with the ncurses library; mouse handling + can be detected by checking for the exit status of `zcurses mouse' + with no arguments. If a mouse button is clicked (or double- or + triple-clicked, or pressed or released with a configurable delay + from being clicked) then kparam is set to the string MOUSE, and + MPARAM is set to an array consisting of the following elements: + - + An identifier to discriminate different input devices; this + is only rarely useful. + + - + The x, y and z coordinates of the mouse click relative to the + full screen, as three elements in that order (i.e. the y + coordinate is, unusually, after the x coordinate). The z + coordinate is only available for a few unusual input devices + and is otherwise set to zero. + + - + Any events that occurred as separate items; usually there + will be just one. An event consists of PRESSED, RELEASED, + CLICKED, DOUBLE_CLICKED or TRIPLE_CLICKED followed + immediately (in the same element) by the number of the button. + + - + If the shift key was pressed, the string SHIFT. + + - + If the control key was pressed, the string CTRL. + + - + If the alt key was pressed, the string ALT. + + Not all mouse events may be passed through to the terminal window; + most terminal emulators handle some mouse events themselves. Note + that the ncurses manual implies that using input both with and + without mouse handling may cause the mouse cursor to appear and + disappear. + + The subcommand mouse can be used to configure the use of the mouse. + There is no window argument; mouse options are global. `zcurses + mouse' with no arguments returns status 0 if mouse handling is + possible, else status 1. Otherwise, the possible arguments (which + may be combined on the same command line) are as follows. delay + NUM sets the maximum delay in milliseconds between press and + release events to be considered as a click; the value 0 disables + click resolution, and the default is one sixth of a second. + motion proceeded by an optional `+' (the default) or - turns on or + off reporting of mouse motion in addition to clicks, presses and + releases, which are always reported. However, it appears reports + for mouse motion are not currently implemented. + + The subcommand timeout specifies a timeout value for input from + TARGETWIN. If INTVAL is negative, `zcurses input' waits + indefinitely for a character to be typed; this is the default. If + INTVAL is zero, `zcurses input' returns immediately; if there is + typeahead it is returned, else no input is done and status 1 is + returned. If INTVAL is positive, `zcurses input' waits INTVAL + milliseconds for input and if there is none at the end of that + period returns status 1. + + The subcommand querychar queries the character at the current + cursor position. The return values are stored in the array named + PARAM if supplied, else in the array reply. The first value is + the character (which may be a multibyte character if the system + supports them); the second is the color pair in the usual + FG_COL/BG_COL notation, or 0 if color is not supported. Any + attributes other than color that apply to the character, as set + with the subcommand attr, appear as additional elements. + + The subcommand resize resizes stdscr and all windows to given + dimensions (windows that stick out from the new dimensions are + resized down). The underlying curses extension (resize_term call) + can be unavailable. To verify, zeroes can be used for HEIGHT and + WIDTH. If the result of the subcommand is 0, resize_term is + available (2 otherwise). Tests show that resizing can be normally + accomplished by calling zcurses end and zcurses refresh. The + resize subcommand is provided for versatility. Multiple system + configurations have been checked and zcurses end and zcurses + refresh are still needed for correct terminal state after resize. + To invoke them with resize, use ENDWIN argument. Using NOSAVE + argument will cause new terminal state to not be saved internally + by zcurses. This is also provided for versatility and should + normally be not needed. + + + +22.9.2 Parameters +----------------- + + +ZCURSES_COLORS + Readonly integer. The maximum number of colors the terminal + supports. This value is initialised by the curses library and is + not available until the first time zcurses init is run. + +ZCURSES_COLOR_PAIRS + Readonly integer. The maximum number of color pairs FG_COL/BG_COL + that may be defined in `zcurses attr' commands; note this limit + applies to all color pairs that have been used whether or not they + are currently active. This value is initialised by the curses + library and is not available until the first time zcurses init is + run. + +zcurses_attrs + Readonly array. The attributes supported by zsh/curses; available + as soon as the module is loaded. + +zcurses_colors + Readonly array. The colors supported by zsh/curses; available as + soon as the module is loaded. + +zcurses_keycodes + Readonly array. The values that may be returned in the second + parameter supplied to `zcurses input' in the order in which they + are defined internally by curses. Not all function keys are + listed, only F0; curses reserves space for F0 up to F63. + +zcurses_windows + Readonly array. The current list of windows, i.e. all windows that + have been created with `zcurses addwin' and not removed with + `zcurses delwin'. + + + +File: zsh.info, Node: The zsh/datetime Module, Next: The zsh/db/gdbm Module, Prev: The zsh/curses Module, Up: Zsh Modules + +22.10 The zsh/datetime Module +============================= + + + + The zsh/datetime module makes available one builtin command: + + +strftime [ -s SCALAR ] FORMAT [ EPOCHTIME [ NANOSECONDS ] ] +strftime -r [ -q ] [ -s SCALAR ] FORMAT TIMESTRING + Output the date in the FORMAT specified. With no EPOCHTIME, the + current system date/time is used; optionally, EPOCHTIME may be + used to specify the number of seconds since the epoch, and + NANOSECONDS may additionally be used to specify the number of + nanoseconds past the second (otherwise that number is assumed to + be 0). See man page strftime(3) for details. The zsh extensions + described in *Note Prompt Expansion:: are also available. + + + -q + Run quietly; suppress printing of all error messages + described below. Errors for invalid EPOCHTIME values are + always printed. + + -r + With the option -r (reverse), use FORMAT to parse the input + string TIMESTRING and output the number of seconds since the + epoch at which the time occurred. The parsing is implemented + by the system function strptime; see man page strptime(3). + This means that zsh format extensions are not available, but + for reverse lookup they are not required. + + In most implementations of strftime any timezone in the + TIMESTRING is ignored and the local timezone declared by the + TZ environment variable is used; other parameters are set to + zero if not present. + + If TIMESTRING does not match FORMAT the command returns + status 1 and prints an error message. If TIMESTRING matches + FORMAT but not all characters in TIMESTRING were used, the + conversion succeeds but also prints an error message. + + If either of the system functions strptime or mktime is not + available, status 2 is returned and an error message is + printed. + + -s SCALAR + Assign the date string (or epoch time in seconds if -r is + given) to SCALAR instead of printing it. + + + Note that depending on the system's declared integral time type, + strftime may produce incorrect results for epoch times greater than + 2147483647 which corresponds to 2038-01-19 03:14:07 +0000. + + +The zsh/datetime module makes available several parameters; all are +readonly: + + +EPOCHREALTIME + A floating point value representing the number of seconds since + the epoch. The notional accuracy is to nanoseconds if the + clock_gettime call is available and to microseconds otherwise, but + in practice the range of double precision floating point and shell + scheduling latencies may be significant effects. + +EPOCHSECONDS + An integer value representing the number of seconds since the + epoch. + +epochtime + An array value containing the number of seconds since the epoch in + the first element and the remainder of the time since the epoch in + nanoseconds in the second element. To ensure the two elements are + consistent the array should be copied or otherwise referenced as a + single substitution before the values are used. The following + idiom may be used: + + + for secs nsecs in $epochtime; do + ... + done + + + + +File: zsh.info, Node: The zsh/db/gdbm Module, Next: The zsh/deltochar Module, Prev: The zsh/datetime Module, Up: Zsh Modules + +22.11 The zsh/db/gdbm Module +============================ + + + + The zsh/db/gdbm module is used to create "tied" associative arrays +that interface to database files. If the GDBM interface is not +available, the builtins defined by this module will report an error. +This module is also intended as a prototype for creating additional +database interfaces, so the ztie builtin may move to a more generic +module in the future. + +The builtins in this module are: + + +ztie -d db/gdbm -f FILENAME [ -r ] ARRAYNAME + Open the GDBM database identified by FILENAME and, if successful, + create the associative array ARRAYNAME linked to the file. To + create a local tied array, the parameter must first be declared, + so commands similar to the following would be executed inside a + function scope: + + + local -A sampledb + ztie -d db/gdbm -f sample.gdbm sampledb + + The -r option opens the database file for reading only, creating a + parameter with the readonly attribute. Without this option, using + `ztie' on a file for which the user does not have write permission + is an error. If writable, the database is opened synchronously so + fields changed in ARRAYNAME are immediately written to FILENAME. + + Changes to the file modes FILENAME after it has been opened do not + alter the state of ARRAYNAME, but `typeset -r ARRAYNAME' works as + expected. + +zuntie [ -u ] ARRAYNAME ... + Close the GDBM database associated with each ARRAYNAME and then + unset the parameter. The -u option forces an unset of parameters + made readonly with `ztie -r'. + + This happens automatically if the parameter is explicitly unset or + its local scope (function) ends. Note that a readonly parameter + may not be explicitly unset, so the only way to unset a global + parameter created with `ztie -r' is to use `zuntie -u'. + +zgdbmpath PARAMETERNAME + Put path to database file assigned to PARAMETERNAME into REPLY + scalar. + +zgdbm_tied + Array holding names of all tied parameters. + + +The fields of an associative array tied to GDBM are neither cached nor +otherwise stored in memory, they are read from or written to the +database on each reference. Thus, for example, the values in a +readonly array may be changed by a second writer of the same database +file. + + +File: zsh.info, Node: The zsh/deltochar Module, Next: The zsh/example Module, Prev: The zsh/db/gdbm Module, Up: Zsh Modules + +22.12 The zsh/deltochar Module +============================== + + + + The zsh/deltochar module makes available two ZLE functions: + + +delete-to-char + Read a character from the keyboard, and delete from the cursor + position up to and including the next (or, with repeat count N, + the Nth) instance of that character. Negative repeat counts mean + delete backwards. + +zap-to-char + This behaves like delete-to-char, except that the final occurrence + of the character itself is not deleted. + + + +File: zsh.info, Node: The zsh/example Module, Next: The zsh/files Module, Prev: The zsh/deltochar Module, Up: Zsh Modules + +22.13 The zsh/example Module +============================ + + + + The zsh/example module makes available one builtin command: + + +example [ -flags ] [ ARGS ... ] + Displays the flags and arguments it is invoked with. + + +The purpose of the module is to serve as an example of how to write a +module. + + +File: zsh.info, Node: The zsh/files Module, Next: The zsh/langinfo Module, Prev: The zsh/example Module, Up: Zsh Modules + +22.14 The zsh/files Module +========================== + + + + The zsh/files module makes available some common commands for file +manipulation as builtins; these commands are probably not needed for +many normal situations but can be useful in emergency recovery +situations with constrained resources. The commands do not implement +all features now required by relevant standards committees. + +For all commands, a variant beginning zf_ is also available and loaded +automatically. Using the features capability of zmodload will let you +load only those names you want. Note that it's possible to load only +the builtins with zsh-specific names using the following command: + + + zmodload -m -F zsh/files b:zf_\* + +The commands loaded by default are: + + +chgrp [ -hRs ] GROUP FILENAME ... + Changes group of files specified. This is equivalent to chown with + a USER-SPEC argument of `:GROUP'. + +chmod [ -Rs ] MODE FILENAME ... + Changes mode of files specified. + + The specified MODE must be in octal. + + The -R option causes chmod to recursively descend into directories, + changing the mode of all files in the directory after changing the + mode of the directory itself. + + The -s option is a zsh extension to chmod functionality. It + enables paranoid behaviour, intended to avoid security problems + involving a chmod being tricked into affecting files other than + the ones intended. It will refuse to follow symbolic links, so + that (for example) ``chmod 600 /tmp/foo/passwd'' can't + accidentally chmod /etc/passwd if /tmp/foo happens to be a link to + /etc. It will also check where it is after leaving directories, + so that a recursive chmod of a deep directory tree can't end up + recursively chmoding /usr as a result of directories being moved + up the tree. + +chown [ -hRs ] USER-SPEC FILENAME ... + Changes ownership and group of files specified. + + The USER-SPEC can be in four forms: + + + USER + change owner to USER; do not change group + + USER:: + change owner to USER; do not change group + + USER: + change owner to USER; change group to USER's primary group + + USER:GROUP + change owner to USER; change group to GROUP + + :GROUP + do not change owner; change group to GROUP + + In each case, the `:' may instead be a `.'. The rule is that if + there is a `:' then the separator is `:', otherwise if there is a + `.' then the separator is `.', otherwise there is no separator. + + Each of USER and GROUP may be either a username (or group name, as + appropriate) or a decimal user ID (group ID). Interpretation as a + name takes precedence, if there is an all-numeric username (or + group name). + + If the target is a symbolic link, the -h option causes chown to set + the ownership of the link instead of its target. + + The -R option causes chown to recursively descend into directories, + changing the ownership of all files in the directory after + changing the ownership of the directory itself. + + The -s option is a zsh extension to chown functionality. It + enables paranoid behaviour, intended to avoid security problems + involving a chown being tricked into affecting files other than + the ones intended. It will refuse to follow symbolic links, so + that (for example) ``chown luser /tmp/foo/passwd'' can't + accidentally chown /etc/passwd if /tmp/foo happens to be a link to + /etc. It will also check where it is after leaving directories, + so that a recursive chown of a deep directory tree can't end up + recursively chowning /usr as a result of directories being moved + up the tree. + +ln [ -dfhins ] FILENAME DEST +ln [ -dfhins ] FILENAME ... DIR + Creates hard (or, with -s, symbolic) links. In the first form, the + specified DESTination is created, as a link to the specified + FILENAME. In the second form, each of the FILENAMEs is taken in + turn, and linked to a pathname in the specified DIRectory that has + the same last pathname component. + + Normally, ln will not attempt to create hard links to directories. + This check can be overridden using the -d option. Typically only + the super-user can actually succeed in creating hard links to + directories. This does not apply to symbolic links in any case. + + By default, existing files cannot be replaced by links. The -i + option causes the user to be queried about replacing existing + files. The -f option causes existing files to be silently + deleted, without querying. -f takes precedence. + + The -h and -n options are identical and both exist for + compatibility; either one indicates that if the target is a symlink + then it should not be dereferenced. Typically this is used in + combination with -sf so that if an existing link points to a + directory then it will be removed, instead of followed. If this + option is used with multiple filenames and the target is a + symbolic link pointing to a directory then the result is an error. + +mkdir [ -p ] [ -m MODE ] DIR ... + Creates directories. With the -p option, non-existing parent + directories are first created if necessary, and there will be no + complaint if the directory already exists. The -m option can be + used to specify (in octal) a set of file permissions for the + created directories, otherwise mode 777 modified by the current + umask (see man page umask(2)) is used. + +mv [ -fi ] FILENAME DEST +mv [ -fi ] FILENAME ... DIR + Moves files. In the first form, the specified FILENAME is moved + to the specified DESTination. In the second form, each of the + FILENAMEs is taken in turn, and moved to a pathname in the + specified DIRectory that has the same last pathname component. + + By default, the user will be queried before replacing any file + that the user cannot write to, but writable files will be silently + removed. The -i option causes the user to be queried about + replacing any existing files. The -f option causes any existing + files to be silently deleted, without querying. -f takes + precedence. + + Note that this mv will not move files across devices. Historical + versions of mv, when actual renaming is impossible, fall back on + copying and removing files; if this behaviour is desired, use cp + and rm manually. This may change in a future version. + +rm [ -dfiRrs ] FILENAME ... + Removes files and directories specified. + + Normally, rm will not remove directories (except with the -R or -r + options). The -d option causes rm to try removing directories + with unlink (see man page unlink(2)), the same method used for + files. Typically only the super-user can actually succeed in + unlinking directories in this way. -d takes precedence over -R + and -r. + + By default, the user will be queried before removing any file that + the user cannot write to, but writable files will be silently + removed. The -i option causes the user to be queried about + removing any files. The -f option causes files to be silently + deleted, without querying, and suppresses all error indications. + -f takes precedence. + + The -R and -r options cause rm to recursively descend into + directories, deleting all files in the directory before removing + the directory with the rmdir system call (see man page rmdir(2)). + + The -s option is a zsh extension to rm functionality. It enables + paranoid behaviour, intended to avoid common security problems + involving a root-run rm being tricked into removing files other + than the ones intended. It will refuse to follow symbolic links, + so that (for example) ``rm /tmp/foo/passwd'' can't accidentally + remove /etc/passwd if /tmp/foo happens to be a link to /etc. It + will also check where it is after leaving directories, so that a + recursive removal of a deep directory tree can't end up + recursively removing /usr as a result of directories being moved + up the tree. + +rmdir DIR ... + Removes empty directories specified. + +sync + Calls the system call of the same name (see man page sync(2)), + which flushes dirty buffers to disk. It might return before the + I/O has actually been completed. + + + +File: zsh.info, Node: The zsh/langinfo Module, Next: The zsh/mapfile Module, Prev: The zsh/files Module, Up: Zsh Modules + +22.15 The zsh/langinfo Module +============================= + + + + The zsh/langinfo module makes available one parameter: + + +langinfo + An associative array that maps langinfo elements to their values. + + Your implementation may support a number of the following keys: + + CODESET, D_T_FMT, D_FMT, T_FMT, RADIXCHAR, THOUSEP, YESEXPR, + NOEXPR, CRNCYSTR, ABDAY_{1..7}, DAY_{1..7}, ABMON_{1..12}, + MON_{1..12}, T_FMT_AMPM, AM_STR, PM_STR, ERA, ERA_D_FMT, + ERA_D_T_FMT, ERA_T_FMT, ALT_DIGITS + + + + +File: zsh.info, Node: The zsh/mapfile Module, Next: The zsh/mathfunc Module, Prev: The zsh/langinfo Module, Up: Zsh Modules + +22.16 The zsh/mapfile Module +============================ + + + + The zsh/mapfile module provides one special associative array +parameter of the same name. + + +mapfile + This associative array takes as keys the names of files; the + resulting value is the content of the file. The value is treated + identically to any other text coming from a parameter. The value + may also be assigned to, in which case the file in question is + written (whether or not it originally existed); or an element may + be unset, which will delete the file in question. For example, + `vared mapfile[myfile]' works as expected, editing the file + `myfile'. + + When the array is accessed as a whole, the keys are the names of + files in the current directory, and the values are empty (to save + a huge overhead in memory). Thus ${(k)mapfile} has the same + effect as the glob operator *(D), since files beginning with a dot + are not special. Care must be taken with expressions such as rm + ${(k)mapfile}, which will delete every file in the current + directory without the usual `rm *' test. + + The parameter mapfile may be made read-only; in that case, files + referenced may not be written or deleted. + + A file may conveniently be read into an array as one line per + element with the form `ARRAY=("${(f@)mapfile[FILENAME]}")'. The + double quotes and the `@' are necessary to prevent empty lines + from being removed. Note that if the file ends with a newline, + the shell will split on the final newline, generating an additional + empty field; this can be suppressed by using + `ARRAY=("${(f@)${mapfile[FILENAME]%$'\n'}}")'. + + + +22.16.1 Limitations +------------------- + +Although reading and writing of the file in question is efficiently +handled, zsh's internal memory management may be arbitrarily baroque; +however, mapfile is usually very much more efficient than anything +involving a loop. Note in particular that the whole contents of the +file will always reside physically in memory when accessed (possibly +multiple times, due to standard parameter substitution operations). In +particular, this means handling of sufficiently long files (greater +than the machine's swap space, or than the range of the pointer type) +will be incorrect. + +No errors are printed or flagged for non-existent, unreadable, or +unwritable files, as the parameter mechanism is too low in the shell +execution hierarchy to make this convenient. + +It is unfortunate that the mechanism for loading modules does not yet +allow the user to specify the name of the shell parameter to be given +the special behaviour. + + +File: zsh.info, Node: The zsh/mathfunc Module, Next: The zsh/nearcolor Module, Prev: The zsh/mapfile Module, Up: Zsh Modules + +22.17 The zsh/mathfunc Module +============================= + + + + The zsh/mathfunc module provides standard mathematical functions for +use when evaluating mathematical formulae. The syntax agrees with +normal C and FORTRAN conventions, for example, + + + (( f = sin(0.3) )) + +assigns the sine of 0.3 to the parameter f. + +Most functions take floating point arguments and return a floating point +value. However, any necessary conversions from or to integer type will +be performed automatically by the shell. Apart from atan with a second +argument and the abs, int and float functions, all functions behave as +noted in the manual page for the corresponding C function, except that +any arguments out of range for the function in question will be +detected by the shell and an error reported. + +The following functions take a single floating point argument: acos, +acosh, asin, asinh, atan, atanh, cbrt, ceil, cos, cosh, erf, erfc, exp, +expm1, fabs, floor, gamma, j0, j1, lgamma, log, log10, log1p, log2, +logb, sin, sinh, sqrt, tan, tanh, y0, y1. The atan function can +optionally take a second argument, in which case it behaves like the C +function atan2. The ilogb function takes a single floating point +argument, but returns an integer. + +The function signgam takes no arguments, and returns an integer, which +is the C variable of the same name, as described in man page gamma(3). +Note that it is therefore only useful immediately after a call to gamma +or lgamma. Note also that `signgam()' and `signgam' are distinct +expressions. + +The functions min, max, and sum are defined not in this module but in +the zmathfunc autoloadable function, described in *Note Mathematical +Functions::. + +The following functions take two floating point arguments: copysign, +fmod, hypot, nextafter. + +The following take an integer first argument and a floating point second +argument: jn, yn. + +The following take a floating point first argument and an integer second +argument: ldexp, scalb. + +The function abs does not convert the type of its single argument; it +returns the absolute value of either a floating point number or an +integer. The functions float and int convert their arguments into a +floating point or integer value (by truncation) respectively. + +Note that the C pow function is available in ordinary math evaluation +as the `**' operator and is not provided here. + +The function rand48 is available if your system's mathematical library +has the function erand48(3). It returns a pseudo-random floating point +number between 0 and 1. It takes a single string optional argument. + +If the argument is not present, the random number seed is initialised by +three calls to the rand(3) function -- this produces the same random +numbers as the next three values of $RANDOM. + +If the argument is present, it gives the name of a scalar parameter +where the current random number seed will be stored. On the first +call, the value must contain at least twelve hexadecimal digits (the +remainder of the string is ignored), or the seed will be initialised in +the same manner as for a call to rand48 with no argument. Subsequent +calls to rand48(PARAM) will then maintain the seed in the parameter +PARAM as a string of twelve hexadecimal digits, with no base signifier. +The random number sequences for different parameters are completely +independent, and are also independent from that used by calls to rand48 +with no argument. + +For example, consider + + + print $(( rand48(seed) )) + print $(( rand48() )) + print $(( rand48(seed) )) + +Assuming $seed does not exist, it will be initialised by the first +call. In the second call, the default seed is initialised; note, +however, that because of the properties of rand() there is a +correlation between the seeds used for the two initialisations, so for +more secure uses, you should generate your own 12-byte seed. The third +call returns to the same sequence of random numbers used in the first +call, unaffected by the intervening rand48(). + + +File: zsh.info, Node: The zsh/nearcolor Module, Next: The zsh/newuser Module, Prev: The zsh/mathfunc Module, Up: Zsh Modules + +22.18 The zsh/nearcolor Module +============================== + + + + The zsh/nearcolor module replaces colours specified as hex triplets +with the nearest colour in the 88 or 256 colour palettes that are widely +used by terminal emulators. By default, 24-bit true colour escape codes +are generated when colours are specified using hex triplets. These are +not supported by all terminals. The purpose of this module is to make +it easier to define colour preferences in a form that can work across a +range of terminal emulators. + +Aside from the default colour, the ANSI standard for terminal escape +codes provides for eight colours. The bright attribute brings this to +sixteen. These basic colours are commonly used in terminal applications +due to being widely supported. Expanded 88 and 256 colour palettes are +also common and, while the first sixteen colours vary somewhat between +terminals and configurations, these add a generally consistent and +predictable set of colours. + +In order to use the zsh/nearcolor module, it only needs to be loaded. +Thereafter, whenever a colour is specified using a hex triplet, it will +be compared against each of the available colours and the closest will +be selected. The first sixteen colours are never matched in this +process due to being unpredictable. + +It isn't possible to reliably detect support for true colour in the +terminal emulator. It is therefore recommended to be selective in +loading the zsh/nearcolor module. For example, the following checks the +COLORTERM environment variable: + + + [[ $COLORTERM = *(24bit|truecolor)* ]] || zmodload zsh/nearcolor + +Note that some terminals accept the true color escape codes but map +them internally to a more limited palette in a similar manner to the +zsh/nearcolor module. + + +File: zsh.info, Node: The zsh/newuser Module, Next: The zsh/parameter Module, Prev: The zsh/nearcolor Module, Up: Zsh Modules + +22.19 The zsh/newuser Module +============================ + + + + The zsh/newuser module is loaded at boot if it is available, the RCS +option is set, and the PRIVILEGED option is not set (all three are true +by default). This takes place immediately after commands in the global +zshenv file (typically /etc/zshenv), if any, have been executed. If +the module is not available it is silently ignored by the shell; the +module may safely be removed from $MODULE_PATH by the administrator if +it is not required. + +On loading, the module tests if any of the start-up files .zshenv, +.zprofile, .zshrc or .zlogin exist in the directory given by the +environment variable ZDOTDIR, or the user's home directory if that is +not set. The test is not performed and the module halts processing if +the shell was in an emulation mode (i.e. had been invoked as some other +shell than zsh). + +If none of the start-up files were found, the module then looks for the +file newuser first in a sitewide directory, usually the parent +directory of the site-functions directory, and if that is not found the +module searches in a version-specific directory, usually the parent of +the functions directory containing version-specific functions. (These +directories can be configured when zsh is built using the +-enable-site-scriptdir=DIR and -enable-scriptdir=DIR flags to +configure, respectively; the defaults are PREFIX/share/zsh and +PREFIX/share/zsh/$ZSH_VERSION where the default PREFIX is /usr/local.) + +If the file newuser is found, it is then sourced in the same manner as +a start-up file. The file is expected to contain code to install +start-up files for the user, however any valid shell code will be +executed. + +The zsh/newuser module is then unconditionally unloaded. + +Note that it is possible to achieve exactly the same effect as the +zsh/newuser module by adding code to /etc/zshenv. The module exists +simply to allow the shell to make arrangements for new users without +the need for intervention by package maintainers and system +administrators. + +The script supplied with the module invokes the shell function +zsh-newuser-install. This may be invoked directly by the user even if +the zsh/newuser module is disabled. Note, however, that if the module +is not installed the function will not be installed either. The +function is documented in *Note User Configuration Functions::. + + +File: zsh.info, Node: The zsh/parameter Module, Next: The zsh/pcre Module, Prev: The zsh/newuser Module, Up: Zsh Modules + +22.20 The zsh/parameter Module +============================== + + + + The zsh/parameter module gives access to some of the internal hash +tables used by the shell by defining some special parameters. + + +options + The keys for this associative array are the names of the options + that can be set and unset using the setopt and unsetopt builtins. + The value of each key is either the string on if the option is + currently set, or the string off if the option is unset. Setting + a key to one of these strings is like setting or unsetting the + option, respectively. Unsetting a key in this array is like + setting it to the value off. + +commands + This array gives access to the command hash table. The keys are the + names of external commands, the values are the pathnames of the + files that would be executed when the command would be invoked. + Setting a key in this array defines a new entry in this table in + the same way as with the hash builtin. Unsetting a key as in `unset + "commands[foo]"' removes the entry for the given key from the + command hash table. + +functions + This associative array maps names of enabled functions to their + definitions. Setting a key in it is like defining a function with + the name given by the key and the body given by the value. + Unsetting a key removes the definition for the function named by + the key. + +dis_functions + Like functions but for disabled functions. + +functions_source + This readonly associative array maps names of enabled functions to + the name of the file containing the source of the function. + + For an autoloaded function that has already been loaded, or marked + for autoload with an absolute path, or that has had its path + resolved with `functions -r', this is the file found for + autoloading, resolved to an absolute path. + + For a function defined within the body of a script or sourced file, + this is the name of that file. In this case, this is the exact + path originally used to that file, which may be a relative path. + + For any other function, including any defined at an interactive + prompt or an autoload function whose path has not yet been + resolved, this is the empty string. However, the hash element is + reported as defined just so long as the function is present: the + keys to this hash are the same as those to $functions. + +dis_functions_source + Like functions_source but for disabled functions. + +builtins + This associative array gives information about the builtin commands + currently enabled. The keys are the names of the builtin commands + and the values are either `undefined' for builtin commands that + will automatically be loaded from a module if invoked or `defined' + for builtin commands that are already loaded. + +dis_builtins + Like builtins but for disabled builtin commands. + +reswords + This array contains the enabled reserved words. + +dis_reswords + Like reswords but for disabled reserved words. + +patchars + This array contains the enabled pattern characters. + +dis_patchars + Like patchars but for disabled pattern characters. + +aliases + This maps the names of the regular aliases currently enabled to + their expansions. + +dis_aliases + Like aliases but for disabled regular aliases. + +galiases + Like aliases, but for global aliases. + +dis_galiases + Like galiases but for disabled global aliases. + +saliases + Like raliases, but for suffix aliases. + +dis_saliases + Like saliases but for disabled suffix aliases. + +parameters + The keys in this associative array are the names of the parameters + currently defined. The values are strings describing the type of + the parameter, in the same format used by the t parameter flag, see + *Note Parameter Expansion:: . Setting or unsetting keys in this + array is not possible. + +modules + An associative array giving information about modules. The keys + are the names of the modules loaded, registered to be autoloaded, + or aliased. The value says which state the named module is in and + is one of the strings `loaded', `autoloaded', or `alias:NAME', + where NAME is the name the module is aliased to. + + Setting or unsetting keys in this array is not possible. + +dirstack + A normal array holding the elements of the directory stack. Note + that the output of the dirs builtin command includes one more + directory, the current working directory. + +history + This associative array maps history event numbers to the full + history lines. Although it is presented as an associative array, + the array of all values (${history[@]}) is guaranteed to be + returned in order from most recent to oldest history event, that + is, by decreasing history event number. + +historywords + A special array containing the words stored in the history. These + also appear in most to least recent order. + +jobdirs + This associative array maps job numbers to the directories from + which the job was started (which may not be the current directory + of the job). + + The keys of the associative arrays are usually valid job numbers, + and these are the values output with, for example, ${(k)jobdirs}. + Non-numeric job references may be used when looking up a value; + for example, ${jobdirs[%+]} refers to the current job. + +jobtexts + This associative array maps job numbers to the texts of the + command lines that were used to start the jobs. + + Handling of the keys of the associative array is as described for + jobdirs above. + +jobstates + This associative array gives information about the states of the + jobs currently known. The keys are the job numbers and the values + are strings of the form `JOB-STATE:MARK:PID=STATE...'. The + JOB-STATE gives the state the whole job is currently in, one of + `running', `suspended', or `done'. The MARK is `+' for the current + job, `-' for the previous job and empty otherwise. This is + followed by one `:PID=STATE' for every process in the job. The + PIDs are, of course, the process IDs and the STATE describes the + state of that process. + + Handling of the keys of the associative array is as described for + jobdirs above. + +nameddirs + This associative array maps the names of named directories to the + pathnames they stand for. + +userdirs + This associative array maps user names to the pathnames of their + home directories. + +usergroups + This associative array maps names of system groups of which the + current user is a member to the corresponding group identifiers. + The contents are the same as the groups output by the id command. + +funcfiletrace + This array contains the absolute line numbers and corresponding + file names for the point where the current function, sourced file, + or (if EVAL_LINENO is set) eval command was called. The array is + of the same length as funcsourcetrace and functrace, but differs + from funcsourcetrace in that the line and file are the point of + call, not the point of definition, and differs from functrace in + that all values are absolute line numbers in files, rather than + relative to the start of a function, if any. + +funcsourcetrace + This array contains the file names and line numbers of the points + where the functions, sourced files, and (if EVAL_LINENO is set) + eval commands currently being executed were defined. The line + number is the line where the `function NAME' or `NAME ()' started. + In the case of an autoloaded function the line number is + reported as zero. The format of each element is FILENAME:LINENO. + + For functions autoloaded from a file in native zsh format, where + only the body of the function occurs in the file, or for files + that have been executed by the source or `.' builtins, the trace + information is shown as FILENAME:0, since the entire file is the + definition. The source file name is resolved to an absolute path + when the function is loaded or the path to it otherwise resolved. + + Most users will be interested in the information in the + funcfiletrace array instead. + +funcstack + This array contains the names of the functions, sourced files, and + (if EVAL_LINENO is set) eval commands. currently being executed. + The first element is the name of the function using the parameter. + + The standard shell array zsh_eval_context can be used to determine + the type of shell construct being executed at each depth: note, + however, that is in the opposite order, with the most recent item + last, and it is more detailed, for example including an entry for + toplevel, the main shell code being executed either interactively + or from a script, which is not present in $funcstack. + +functrace + This array contains the names and line numbers of the callers + corresponding to the functions currently being executed. The + format of each element is NAME:LINENO. Callers are also shown for + sourced files; the caller is the point where the source or `.' + command was executed. + + + +File: zsh.info, Node: The zsh/pcre Module, Next: The zsh/param/private Module, Prev: The zsh/parameter Module, Up: Zsh Modules + +22.21 The zsh/pcre Module +========================= + + + + The zsh/pcre module makes some commands available as builtins: + + +pcre_compile [ -aimxs ] PCRE + Compiles a perl-compatible regular expression. + + Option -a will force the pattern to be anchored. Option -i will + compile a case-insensitive pattern. Option -m will compile a + multi-line pattern; that is, ^ and $ will match newlines within + the pattern. Option -x will compile an extended pattern, wherein + whitespace and # comments are ignored. Option -s makes the dot + metacharacter match all characters, including those that indicate + newline. + +pcre_study + Studies the previously-compiled PCRE which may result in faster + matching. + +pcre_match [ -v VAR ] [ -a ARR ] [ -n OFFSET ] [ -b ] STRING + Returns successfully if string matches the previously-compiled + PCRE. + + Upon successful match, if the expression captures substrings + within parentheses, pcre_match will set the array match to those + substrings, unless the -a option is given, in which case it will + set the array ARR. Similarly, the variable MATCH will be set to + the entire matched portion of the string, unless the -v option is + given, in which case the variable VAR will be set. No variables + are altered if there is no successful match. A -n option starts + searching for a match from the byte OFFSET position in STRING. If + the -b option is given, the variable ZPCRE_OP will be set to an + offset pair string, representing the byte offset positions of the + entire matched portion within the STRING. For example, a ZPCRE_OP + set to "32 45" indicates that the matched portion began on byte + offset 32 and ended on byte offset 44. Here, byte offset position + 45 is the position directly after the matched portion. Keep in + mind that the byte position isn't necessarily the same as the + character position when UTF-8 characters are involved. + Consequently, the byte offset positions are only to be relied on + in the context of using them for subsequent searches on STRING, + using an offset position as an argument to the -n option. This is + mostly used to implement the "find all non-overlapping matches" + functionality. + + A simple example of "find all non-overlapping matches": + + + string="The following zip codes: 78884 90210 99513" + pcre_compile -m "\d{5}" + accum=() + pcre_match -b -- $string + while [[ $? -eq 0 ]] do + b=($=ZPCRE_OP) + accum+=$MATCH + pcre_match -b -n $b[2] -- $string + done + print -l $accum + + +The zsh/pcre module makes available the following test condition: + + +EXPR -pcre-match PCRE + Matches a string against a perl-compatible regular expression. + + For example, + + + [[ "$text" -pcre-match ^d+$ ]] && + print text variable contains only "d's". + + If the REMATCH_PCRE option is set, the =~ operator is equivalent to + -pcre-match, and the NO_CASE_MATCH option may be used. Note that + NO_CASE_MATCH never applies to the pcre_match builtin, instead use + the -i switch of pcre_compile. + + + +File: zsh.info, Node: The zsh/param/private Module, Next: The zsh/regex Module, Prev: The zsh/pcre Module, Up: Zsh Modules + +22.22 The zsh/param/private Module +================================== + + + + The zsh/param/private module is used to create parameters whose scope +is limited to the current function body, and _not_ to other functions +called by the current function. + +This module provides a single autoloaded builtin: + +private [ {+|-}AHUahlprtux ] [ {+|-}EFLRZi [ N ] ] [ NAME[=VALUE] ... ] + The private builtin accepts all the same options and arguments as + local (*Note Shell Builtin Commands::) except for the `-T' option. + Tied parameters may not be made private. + + If used at the top level (outside a function scope), private + creates a normal parameter in the same manner as declare or + typeset. A warning about this is printed if WARN_CREATE_GLOBAL is + set (*Note Options::). Used inside a function scope, private + creates a local parameter similar to one declared with local, + except having special properties noted below. + + Special parameters which expose or manipulate internal shell + state, such as ARGC, argv, COLUMNS, LINES, UID, EUID, IFS, PROMPT, + RANDOM, SECONDS, etc., cannot be made private unless the `-h' + option is used to hide the special meaning of the parameter. This + may change in the future. + + +As with other typeset equivalents, private is both a builtin and a +reserved word, so arrays may be assigned with parenthesized word list +NAME=(VALUE...) syntax. However, the reserved word `private' is not +available until zsh/param/private is loaded, so care must be taken with +order of execution and parsing for function definitions which use +private. To compensate for this, the module also adds the option `-P' +to the `local' builtin to declare private parameters. + +For example, this construction fails if zsh/param/private has not yet +been loaded when `bad_declaration' is defined: + bad_declaration() { + zmodload zsh/param/private + private array=( one two three ) + } + +This construction works because local is already a keyword, and the +module is loaded before the statement is executed: + good_declaration() { + zmodload zsh/param/private + local -P array=( one two three ) + } + +The following is usable in scripts but may have trouble with autoload: + zmodload zsh/param/private + iffy_declaration() { + private array=( one two three ) + } + +The private builtin may always be used with scalar assignments and for +declarations without assignments. + +Parameters declared with private have the following properties: + + * Within the function body where it is declared, the parameter + behaves as a local, except as noted above for tied or special + parameters. + + * The type of a parameter declared private cannot be changed in the + scope where it was declared, even if the parameter is unset. Thus + an array cannot be assigned to a private scalar, etc. + + * Within any other function called by the declaring function, the + private parameter does _NOT_ hide other parameters of the same + name, so for example a global parameter of the same name is + visible and may be assigned or unset. This includes calls to + anonymous functions, although that may also change in the future. + + * An exported private remains in the environment of inner scopes but + appears unset for the current shell in those scopes. Generally, + exporting private parameters should be avoided. + +Note that this differs from the static scope defined by compiled +languages derived from C, in that the a new call to the same function +creates a new scope, i.e., the parameter is still associated with the +call stack rather than with the function definition. It differs from +ksh `typeset -S' because the syntax used to define the function has no +bearing on whether the parameter scope is respected. + + +File: zsh.info, Node: The zsh/regex Module, Next: The zsh/sched Module, Prev: The zsh/param/private Module, Up: Zsh Modules + +22.23 The zsh/regex Module +========================== + + + + The zsh/regex module makes available the following test condition: + + +EXPR -regex-match REGEX + Matches a string against a POSIX extended regular expression. On + successful match, matched portion of the string will normally be + placed in the MATCH variable. If there are any capturing + parentheses within the regex, then the match array variable will + contain those. If the match is not successful, then the variables + will not be altered. + + For example, + + + [[ alphabetical -regex-match ^a([^a]+)a([^a]+)a ]] && + print -l $MATCH X $match + + If the option REMATCH_PCRE is not set, then the =~ operator will + automatically load this module as needed and will invoke the + -regex-match operator. + + If BASH_REMATCH is set, then the array BASH_REMATCH will be set + instead of MATCH and match. + + + +File: zsh.info, Node: The zsh/sched Module, Next: The zsh/net/socket Module, Prev: The zsh/regex Module, Up: Zsh Modules + +22.24 The zsh/sched Module +========================== + + + + The zsh/sched module makes available one builtin command and one +parameter. + + +sched [-o] [+]HH:MM[:SS] COMMAND ... +sched [-o] [+]SECONDS COMMAND ... +sched [ -ITEM ] + Make an entry in the scheduled list of commands to execute. The + time may be specified in either absolute or relative time, and + either as hours, minutes and (optionally) seconds separated by a + colon, or seconds alone. An absolute number of seconds indicates + the time since the epoch (1970/01/01 00:00); this is useful in + combination with the features in the zsh/datetime module, see + *Note The zsh/datetime Module::. + + With no arguments, prints the list of scheduled commands. If the + scheduled command has the -o flag set, this is shown at the start + of the command. + + With the argument `-ITEM', removes the given item from the list. + The numbering of the list is continuous and entries are in time + order, so the numbering can change when entries are added or + deleted. + + Commands are executed either immediately before a prompt, or while + the shell's line editor is waiting for input. In the latter case + it is useful to be able to produce output that does not interfere + with the line being edited. Providing the option -o causes the + shell to clear the command line before the event and redraw it + afterwards. This should be used with any scheduled event that + produces visible output to the terminal; it is not needed, for + example, with output that updates a terminal emulator's title bar. + + To effect changes to the editor buffer when an event executes, use + the `zle' command with no arguments to test whether the editor is + active, and if it is, then use `zle WIDGET' to access the editor + via the named WIDGET. + + The sched builtin is not made available by default when the shell + starts in a mode emulating another shell. It can be made available + with the command `zmodload -F zsh/sched b:sched'. + + + +zsh_scheduled_events + A readonly array corresponding to the events scheduled by the + sched builtin. The indices of the array correspond to the numbers + shown when sched is run with no arguments (provided that the + KSH_ARRAYS option is not set). The value of the array consists of + the scheduled time in seconds since the epoch (see *Note The + zsh/datetime Module:: for facilities for using this number), + followed by a colon, followed by any options (which may be empty + but will be preceded by a `-' otherwise), followed by a colon, + followed by the command to be executed. + + The sched builtin should be used for manipulating the events. Note + that this will have an immediate effect on the contents of the + array, so that indices may become invalid. + + + +File: zsh.info, Node: The zsh/net/socket Module, Next: The zsh/stat Module, Prev: The zsh/sched Module, Up: Zsh Modules + +22.25 The zsh/net/socket Module +=============================== + + + + The zsh/net/socket module makes available one builtin command: + + +zsocket [ -altv ] [ -d FD ] [ ARGS ] + zsocket is implemented as a builtin to allow full use of shell + command line editing, file I/O, and job control mechanisms. + + + +22.25.1 Outbound Connections +---------------------------- + + + + +zsocket [ -v ] [ -d FD ] FILENAME + Open a new Unix domain connection to FILENAME. The shell + parameter REPLY will be set to the file descriptor associated with + that connection. Currently, only stream connections are supported. + + If -d is specified, its argument will be taken as the target file + descriptor for the connection. + + In order to elicit more verbose output, use -v. + + File descriptors can be closed with normal shell syntax when no + longer needed, for example: + + + exec {REPLY}>&- + + + +22.25.2 Inbound Connections +--------------------------- + + + + +zsocket -l [ -v ] [ -d FD ] FILENAME + zsocket -l will open a socket listening on FILENAME. The shell + parameter REPLY will be set to the file descriptor associated with + that listener. The file descriptor remains open in subshells and + forked external executables. + + If -d is specified, its argument will be taken as the target file + descriptor for the connection. + + In order to elicit more verbose output, use -v. + +zsocket -a [ -tv ] [ -d TARGETFD ] LISTENFD + zsocket -a will accept an incoming connection to the socket + associated with LISTENFD. The shell parameter REPLY will be set + to the file descriptor associated with the inbound connection. + The file descriptor remains open in subshells and forked external + executables. + + If -d is specified, its argument will be taken as the target file + descriptor for the connection. + + If -t is specified, zsocket will return if no incoming connection + is pending. Otherwise it will wait for one. + + In order to elicit more verbose output, use -v. + + + +File: zsh.info, Node: The zsh/stat Module, Next: The zsh/system Module, Prev: The zsh/net/socket Module, Up: Zsh Modules + +22.26 The zsh/stat Module +========================= + + + + The zsh/stat module makes available one builtin command under two +possible names: + + +zstat [ -gnNolLtTrs ] [ -f FD ] [ -H HASH ] [ -A ARRAY ] [ -F FMT ] + [ +ELEMENT ] [ FILE ... ] +stat ... + The command acts as a front end to the stat system call (see man + page stat(2)). The same command is provided with two names; as + the name stat is often used by an external command it is + recommended that only the zstat form of the command is used. This + can be arranged by loading the module with the command `zmodload + -F zsh/stat b:zstat'. + + If the stat call fails, the appropriate system error message + printed and status 1 is returned. The fields of struct stat give + information about the files provided as arguments to the command. + In addition to those available from the stat call, an extra + element `link' is provided. These elements are: + + + device + The number of the device on which the file resides. + + inode + The unique number of the file on this device (`_inode_' + number). + + mode + The mode of the file; that is, the file's type and access + permissions. With the -s option, this will be returned as a + string corresponding to the first column in the display of + the ls -l command. + + nlink + The number of hard links to the file. + + uid + The user ID of the owner of the file. With the -s option, + this is displayed as a user name. + + gid + The group ID of the file. With the -s option, this is + displayed as a group name. + + rdev + The raw device number. This is only useful for special + devices. + + size + The size of the file in bytes. + + atime + mtime + ctime + The last access, modification and inode change times of the + file, respectively, as the number of seconds since midnight + GMT on 1st January, 1970. With the -s option, these are + printed as strings for the local time zone; the format can be + altered with the -F option, and with the -g option the times + are in GMT. + + blksize + The number of bytes in one allocation block on the device on + which the file resides. + + block + The number of disk blocks used by the file. + + link + If the file is a link and the -L option is in effect, this + contains the name of the file linked to, otherwise it is + empty. Note that if this element is selected (``zstat + +link'') then the -L option is automatically used. + + + A particular element may be selected by including its name + preceded by a `+' in the option list; only one element is allowed. + The element may be shortened to any unique set of leading + characters. Otherwise, all elements will be shown for all files. + + Options: + + + -A ARRAY + Instead of displaying the results on standard output, assign + them to an ARRAY, one struct stat element per array element + for each file in order. In this case neither the name of the + element nor the name of the files appears in ARRAY unless the + -t or -n options were given, respectively. If -t is given, + the element name appears as a prefix to the appropriate array + element; if -n is given, the file name appears as a separate + array element preceding all the others. Other formatting + options are respected. + + -H HASH + Similar to -A, but instead assign the values to HASH. The + keys are the elements listed above. If the -n option is + provided then the name of the file is included in the hash + with key name. + + -f FD + Use the file on file descriptor FD instead of named files; no + list of file names is allowed in this case. + + -F FMT + Supplies a strftime (see man page strftime(3)) string for the + formatting of the time elements. The format string supports + all of the zsh extensions described in *Note Prompt + Expansion::. The -s option is implied. + + -g + Show the time elements in the GMT time zone. The -s option + is implied. + + -l + List the names of the type elements (to standard output or an + array as appropriate) and return immediately; arguments, and + options other than -A, are ignored. + + -L + Perform an lstat (see man page lstat(2)) rather than a stat + system call. In this case, if the file is a link, information + about the link itself rather than the target file is returned. + This option is required to make the link element useful. + It's important to note that this is the exact opposite from + man page ls(1), etc. + + -n + Always show the names of files. Usually these are only shown + when output is to standard output and there is more than one + file in the list. + + -N + Never show the names of files. + + -o + If a raw file mode is printed, show it in octal, which is + more useful for human consumption than the default of + decimal. A leading zero will be printed in this case. Note + that this does not affect whether a raw or formatted file + mode is shown, which is controlled by the -r and -s options, + nor whether a mode is shown at all. + + -r + Print raw data (the default format) alongside string data + (the -s format); the string data appears in parentheses after + the raw data. + + -s + Print mode, uid, gid and the three time elements as strings + instead of numbers. In each case the format is like that of + ls -l. + + -t + Always show the type names for the elements of struct stat. + Usually these are only shown when output is to standard + output and no individual element has been selected. + + -T + Never show the type names of the struct stat elements. + + + + +File: zsh.info, Node: The zsh/system Module, Next: The zsh/net/tcp Module, Prev: The zsh/stat Module, Up: Zsh Modules + +22.27 The zsh/system Module +=========================== + + + + The zsh/system module makes available various builtin commands and +parameters. + + + +22.27.1 Builtins +---------------- + + +syserror [ -e ERRVAR ] [ -p PREFIX ] [ ERRNO | ERRNAME ] + This command prints out the error message associated with ERRNO, a + system error number, followed by a newline to standard error. + + Instead of the error number, a name ERRNAME, for example ENOENT, + may be used. The set of names is the same as the contents of the + array errnos, see below. + + If the string PREFIX is given, it is printed in front of the error + message, with no intervening space. + + If ERRVAR is supplied, the entire message, without a newline, is + assigned to the parameter names ERRVAR and nothing is output. + + A return status of 0 indicates the message was successfully printed + (although it may not be useful if the error number was out of the + system's range), a return status of 1 indicates an error in the + parameters, and a return status of 2 indicates the error name was + not recognised (no message is printed for this). + +sysopen [ -arw ] [ -m PERMISSIONS ] [ -o OPTIONS ] + -u FD FILE + This command opens a file. The -r, -w and -a flags indicate + whether the file should be opened for reading, writing and + appending, respectively. The -m option allows the initial + permissions to use when creating a file to be specified in octal + form. The file descriptor is specified with -u. Either an + explicit file descriptor in the range 0 to 9 can be specified or a + variable name can be given to which the file descriptor number + will be assigned. + + The -o option allows various system specific options to be + specified as a comma-separated list. The following is a list of + possible options. Note that, depending on the system, some may not + be available. + cloexec + mark file to be closed when other programs are executed (else + the file descriptor remains open in subshells and forked + external executables) + + create + creat + create file if it does not exist + + excl + create file, error if it already exists + + noatime + suppress updating of the file atime + + nofollow + fail if FILE is a symbolic link + + sync + request that writes wait until data has been physically + written + + truncate + trunc + truncate file to size 0 + + + To close the file, use one of the following: + + + exec {FD}<&- + exec {FD}>&- + +sysread [ -c COUNTVAR ] [ -i INFD ] [ -o OUTFD ] + [ -s BUFSIZE ] [ -t TIMEOUT ] [ PARAM ] + Perform a single system read from file descriptor INFD, or zero if + that is not given. The result of the read is stored in PARAM or + REPLY if that is not given. If COUNTVAR is given, the number of + bytes read is assigned to the parameter named by COUNTVAR. + + The maximum number of bytes read is BUFSIZE or 8192 if that is not + given, however the command returns as soon as any number of bytes + was successfully read. + + If TIMEOUT is given, it specifies a timeout in seconds, which may + be zero to poll the file descriptor. This is handled by the poll + system call if available, otherwise the select system call if + available. + + If OUTFD is given, an attempt is made to write all the bytes just + read to the file descriptor OUTFD. If this fails, because of a + system error other than EINTR or because of an internal zsh error + during an interrupt, the bytes read but not written are stored in + the parameter named by PARAM if supplied (no default is used in + this case), and the number of bytes read but not written is stored + in the parameter named by COUNTVAR if that is supplied. If it was + successful, COUNTVAR contains the full number of bytes transferred, + as usual, and PARAM is not set. + + The error EINTR (interrupted system call) is handled internally so + that shell interrupts are transparent to the caller. Any other + error causes a return. + + The possible return statuses are + 0 + At least one byte of data was successfully read and, if + appropriate, written. + + 1 + There was an error in the parameters to the command. This is + the only error for which a message is printed to standard + error. + + 2 + There was an error on the read, or on polling the input file + descriptor for a timeout. The parameter ERRNO gives the + error. + + 3 + Data were successfully read, but there was an error writing + them to OUTFD. The parameter ERRNO gives the error. + + 4 + The attempt to read timed out. Note this does not set ERRNO + as this is not a system error. + + 5 + No system error occurred, but zero bytes were read. This + usually indicates end of file. The parameters are set + according to the usual rules; no write to OUTFD is attempted. + + +sysseek [ -u FD ] [ -w start|end|current ] OFFSET + The current file position at which future reads and writes will + take place is adjusted to the specified byte offset. The OFFSET is + evaluated as a math expression. The -u option allows the file + descriptor to be specified. By default the offset is specified + relative to the start or the file but, with the -w option, it is + possible to specify that the offset should be relative to the + current position or the end of the file. + +syswrite [ -c COUNTVAR ] [ -o OUTFD ] DATA + The data (a single string of bytes) are written to the file + descriptor OUTFD, or 1 if that is not given, using the write + system call. Multiple write operations may be used if the first + does not write all the data. + + If COUNTVAR is given, the number of byte written is stored in the + parameter named by COUNTVAR; this may not be the full length of + DATA if an error occurred. + + The error EINTR (interrupted system call) is handled internally by + retrying; otherwise an error causes the command to return. For + example, if the file descriptor is set to non-blocking output, an + error EAGAIN (on some systems, EWOULDBLOCK) may result in the + command returning early. + + The return status may be 0 for success, 1 for an error in the + parameters to the command, or 2 for an error on the write; no + error message is printed in the last case, but the parameter ERRNO + will reflect the error that occurred. + +zsystem flock [ -t TIMEOUT ] [ -f VAR ] [-er] FILE +zsystem flock -u FD_EXPR + The builtin zsystem's subcommand flock performs advisory file + locking (via the man page fcntl(2) system call) over the entire + contents of the given file. This form of locking requires the + processes accessing the file to cooperate; its most obvious use is + between two instances of the shell itself. + + In the first form the named FILE, which must already exist, is + locked by opening a file descriptor to the file and applying a + lock to the file descriptor. The lock terminates when the shell + process that created the lock exits; it is therefore often + convenient to create file locks within subshells, since the lock + is automatically released when the subshell exits. Note that use + of the print builtin with the -u option will, as a side effect, + release the lock, as will redirection to the file in the shell + holding the lock. To work around this use a subshell, e.g. + `(print message) >> FILE'. Status 0 is returned if the lock + succeeds, else status 1. + + In the second form the file descriptor given by the arithmetic + expression FD_EXPR is closed, releasing a lock. The file + descriptor can be queried by using the `-f VAR' form during the + lock; on a successful lock, the shell variable VAR is set to the + file descriptor used for locking. The lock will be released if the + file descriptor is closed by any other means, for example using + `exec {VAR}>&-'; however, the form described here performs a + safety check that the file descriptor is in use for file locking. + + By default the shell waits indefinitely for the lock to succeed. + The option -t TIMEOUT specifies a timeout for the lock in seconds; + currently this must be an integer. The shell will attempt to lock + the file once a second during this period. If the attempt times + out, status 2 is returned. + + If the option -e is given, the file descriptor for the lock is + preserved when the shell uses exec to start a new process; + otherwise it is closed at that point and the lock released. + + If the option -r is given, the lock is only for reading, otherwise + it is for reading and writing. The file descriptor is opened + accordingly. + +zsystem supports SUBCOMMAND + The builtin zsystem's subcommand supports tests whether a given + subcommand is supported. It returns status 0 if so, else status + 1. It operates silently unless there was a syntax error (i.e. the + wrong number of arguments), in which case status 255 is returned. + Status 1 can indicate one of two things: SUBCOMMAND is known but + not supported by the current operating system, or SUBCOMMAND is + not known (possibly because this is an older version of the shell + before it was implemented). + + + +22.27.2 Math Functions +---------------------- + + +systell(FD) + The systell math function returns the current file position for + the file descriptor passed as an argument. + + + +22.27.3 Parameters +------------------ + + +errnos + A readonly array of the names of errors defined on the system. + These are typically macros defined in C by including the system + header file errno.h. The index of each name (assuming the option + KSH_ARRAYS is unset) corresponds to the error number. Error + numbers NUM before the last known error which have no name are + given the name ENUM in the array. + + Note that aliases for errors are not handled; only the canonical + name is used. + +sysparams + A readonly associative array. The keys are: + + + pid + Returns the process ID of the current process, even in + subshells. Compare $$, which returns the process ID of the + main shell process. + + ppid + Returns the process ID of the parent of the current process, + even in subshells. Compare $PPID, which returns the process + ID of the parent of the main shell process. + + procsubstpid + Returns the process ID of the last process started for process + substitution, i.e. the <(...) and >(...) expansions. + + + + +File: zsh.info, Node: The zsh/net/tcp Module, Next: The zsh/termcap Module, Prev: The zsh/system Module, Up: Zsh Modules + +22.28 The zsh/net/tcp Module +============================ + + + + The zsh/net/tcp module makes available one builtin command: + + +ztcp [ -acflLtv ] [ -d FD ] [ ARGS ] + ztcp is implemented as a builtin to allow full use of shell + command line editing, file I/O, and job control mechanisms. + + If ztcp is run with no options, it will output the contents of its + session table. + + If it is run with only the option -L, it will output the contents + of the session table in a format suitable for automatic parsing. + The option is ignored if given with a command to open or close a + session. The output consists of a set of lines, one per session, + each containing the following elements separated by spaces: + + + File descriptor + The file descriptor in use for the connection. For normal + inbound (I) and outbound (O) connections this may be read and + written by the usual shell mechanisms. However, it should + only be close with `ztcp -c'. + + Connection type + A letter indicating how the session was created: + + + Z + A session created with the zftp command. + + L + A connection opened for listening with `ztcp -l'. + + I + An inbound connection accepted with `ztcp -a'. + + O + An outbound connection created with `ztcp HOST ...'. + + + + The local host + This is usually set to an all-zero IP address as the address + of the localhost is irrelevant. + + The local port + This is likely to be zero unless the connection is for + listening. + + The remote host + This is the fully qualified domain name of the peer, if + available, else an IP address. It is an all-zero IP address + for a session opened for listening. + + The remote port + This is zero for a connection opened for listening. + + + + +22.28.1 Outbound Connections +---------------------------- + + + + +ztcp [ -v ] [ -d FD ] HOST [ PORT ] + Open a new TCP connection to HOST. If the PORT is omitted, it + will default to port 23. The connection will be added to the + session table and the shell parameter REPLY will be set to the + file descriptor associated with that connection. + + If -d is specified, its argument will be taken as the target file + descriptor for the connection. + + In order to elicit more verbose output, use -v. + + + +22.28.2 Inbound Connections +--------------------------- + + + + +ztcp -l [ -v ] [ -d FD ] PORT + ztcp -l will open a socket listening on TCP PORT. The socket will + be added to the session table and the shell parameter REPLY will + be set to the file descriptor associated with that listener. + + If -d is specified, its argument will be taken as the target file + descriptor for the connection. + + In order to elicit more verbose output, use -v. + +ztcp -a [ -tv ] [ -d TARGETFD ] LISTENFD + ztcp -a will accept an incoming connection to the port associated + with LISTENFD. The connection will be added to the session table + and the shell parameter REPLY will be set to the file descriptor + associated with the inbound connection. + + If -d is specified, its argument will be taken as the target file + descriptor for the connection. + + If -t is specified, ztcp will return if no incoming connection is + pending. Otherwise it will wait for one. + + In order to elicit more verbose output, use -v. + + + +22.28.3 Closing Connections +--------------------------- + + + + +ztcp -cf [ -v ] [ FD ] +ztcp -c [ -v ] [ FD ] + ztcp -c will close the socket associated with FD. The socket will + be removed from the session table. If FD is not specified, ztcp + will close everything in the session table. + + Normally, sockets registered by zftp (see *Note The zsh/zftp + Module:: ) cannot be closed this way. In order to force such a + socket closed, use -f. + + In order to elicit more verbose output, use -v. + + + +22.28.4 Example +--------------- + +Here is how to create a TCP connection between two instances of zsh. We +need to pick an unassigned port; here we use the randomly chosen 5123. + +On host1, + zmodload zsh/net/tcp + ztcp -l 5123 + listenfd=$REPLY + ztcp -a $listenfd + fd=$REPLY + The second from last command blocks until there is an incoming +connection. + +Now create a connection from host2 (which may, of course, be the same +machine): + zmodload zsh/net/tcp + ztcp host1 5123 + fd=$REPLY + +Now on each host, $fd contains a file descriptor for talking to the +other. For example, on host1: + print This is a message >&$fd + and on host2: + read -r line <&$fd; print -r - $line + prints `This is a message'. + +To tidy up, on host1: + ztcp -c $listenfd + ztcp -c $fd + and on host2 + ztcp -c $fd + + +File: zsh.info, Node: The zsh/termcap Module, Next: The zsh/terminfo Module, Prev: The zsh/net/tcp Module, Up: Zsh Modules + +22.29 The zsh/termcap Module +============================ + + + + The zsh/termcap module makes available one builtin command: + + +echotc CAP [ ARG ... ] + Output the termcap value corresponding to the capability CAP, with + optional arguments. + + +The zsh/termcap module makes available one parameter: + + +termcap + An associative array that maps termcap capability codes to their + values. + + + +File: zsh.info, Node: The zsh/terminfo Module, Next: The zsh/zftp Module, Prev: The zsh/termcap Module, Up: Zsh Modules + +22.30 The zsh/terminfo Module +============================= + + + + The zsh/terminfo module makes available one builtin command: + + +echoti CAP [ ARG ] + Output the terminfo value corresponding to the capability CAP, + instantiated with ARG if applicable. + + +The zsh/terminfo module makes available one parameter: + + +terminfo + An associative array that maps terminfo capability names to their + values. + + + +File: zsh.info, Node: The zsh/zftp Module, Next: The zsh/zle Module, Prev: The zsh/terminfo Module, Up: Zsh Modules + +22.31 The zsh/zftp Module +========================= + + + + The zsh/zftp module makes available one builtin command: + + +zftp SUBCOMMAND [ ARGS ] + The zsh/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 a more powerful + interface; a set is provided with the zsh distribution and is + described in *Note Zftp Function System::. However, the zftp + command is entirely usable in its own right. + + All commands consist of the command name zftp followed by the name + of a subcommand. These are listed below. The return status of + each subcommand is supposed to reflect the success or failure of + the remote operation. See a description of the variable + ZFTP_VERBOSE for more information on how responses from the server + may be printed. + + + +22.31.1 Subcommands +------------------- + + + + +open HOST[:PORT] [ USER [ PASSWORD [ ACCOUNT ] ] ] + Open a new FTP session to HOST, which may be the name of a TCP/IP + connected host or an IP number in the standard dot notation. If + the argument is in the form HOST:PORT, open a connection to TCP + port PORT instead of the standard FTP port 21. This may be the + name of a TCP service or a number: see the description of + ZFTP_PORT below for more information. + + If IPv6 addresses in colon format are used, the HOST should be + surrounded by quoted square brackets to distinguish it from the + PORT, for example '[fe80::203:baff:fe02:8b56]'. For consistency + this is allowed with all forms of HOST. + + Remaining arguments are passed to the login subcommand. Note that + if no arguments beyond HOST are supplied, open will _not_ + automatically call login. If no arguments at all are supplied, + open will use the parameters set by the params subcommand. + + After a successful open, the shell variables ZFTP_HOST, ZFTP_PORT, + ZFTP_IP and ZFTP_SYSTEM are available; see `Variables' below. + +login [ NAME [ PASSWORD [ ACCOUNT ] ] ] +user [ NAME [ PASSWORD [ ACCOUNT ] ] ] + Login the user NAME with parameters PASSWORD and ACCOUNT. Any of + the parameters can be omitted, and will be read from standard + input if needed (NAME is always needed). If standard input is a + terminal, a prompt for each one will be printed on standard error + and PASSWORD will not be echoed. If any of the parameters are not + used, a warning message is printed. + + After a successful login, the shell variables ZFTP_USER, + ZFTP_ACCOUNT and ZFTP_PWD are available; see `Variables' below. + + This command may be re-issued when a user is already logged in, and + the server will first be reinitialized for a new user. + +params [ HOST [ USER [ PASSWORD [ ACCOUNT ] ] ] ] +params - + Store the given parameters for a later open command with no + arguments. Only those given on the command line will be + remembered. If no arguments are given, the parameters currently + set are printed, although the password will appear as a line of + stars; the return status is one if no parameters were set, zero + otherwise. + + Any of the parameters may be specified as a `?', which may need to + be quoted to protect it from shell expansion. In this case, the + appropriate parameter will be read from stdin as with the login + subcommand, including special handling of PASSWORD. If the `?' is + followed by a string, that is used as the prompt for reading the + parameter instead of the default message (any necessary + punctuation and whitespace should be included at the end of the + prompt). The first letter of the parameter (only) may be quoted + with a `\'; hence an argument "\\$word" guarantees that the string + from the shell parameter $word will be treated literally, whether + or not it begins with a `?'. + + If instead a single `-' is given, the existing parameters, if any, + are deleted. In that case, calling open with no arguments will + cause an error. + + The list of parameters is not deleted after a close, however it + will be deleted if the zsh/zftp module is unloaded. + + For example, + + + zftp params ftp.elsewhere.xx juser '?Password for juser: ' + + will store the host ftp.elsewhere.xx and the user juser and then + prompt the user for the corresponding password with the given + prompt. + +test + Test the connection; if the server has reported that it has closed + the connection (maybe due to a timeout), return status 2; if no + connection was open anyway, return status 1; else return status 0. + The test subcommand is silent, apart from messages printed by the + $ZFTP_VERBOSE mechanism, or error messages if the connection + closes. There is no network overhead for this test. + + The test is only supported on systems with either the select(2) or + poll(2) system calls; otherwise the message `not supported on this + system' is printed instead. + + The test subcommand will automatically be called at the start of + any other subcommand for the current session when a connection is + open. + +cd DIRECTORY + Change the remote directory to DIRECTORY. Also alters the shell + variable ZFTP_PWD. + +cdup + Change the remote directory to the one higher in the directory + tree. Note that cd .. will also work correctly on non-UNIX + systems. + +dir [ ARG ... ] + Give a (verbose) listing of the remote directory. The ARGs are + passed directly to the server. The command's behaviour is + implementation dependent, but a UNIX server will typically + interpret ARGs as arguments to the ls command and with no + arguments return the result of `ls -l'. The directory is listed to + standard output. + +ls [ ARG ... ] + Give a (short) listing of the remote directory. With no ARG, + produces a raw list of the files in the directory, one per line. + Otherwise, up to vagaries of the server implementation, behaves + similar to dir. + +type [ TYPE ] + Change the type for the transfer to TYPE, or print the current type + if TYPE is absent. The allowed values are `A' (ASCII), `I' + (Image, i.e. binary), or `B' (a synonym for `I'). + + The FTP default for a transfer is ASCII. However, if zftp finds + that the remote host is a UNIX machine with 8-bit byes, it will + automatically switch to using binary for file transfers upon open. + This can subsequently be overridden. + + The transfer type is only passed to the remote host when a data + connection is established; this command involves no network + overhead. + +ascii + The same as type A. + +binary + The same as type I. + +mode [ S | B ] + Set the mode type to stream (S) or block (B). Stream mode is the + default; block mode is not widely supported. + +remote FILE ... +local [ FILE ... ] + Print the size and last modification time of the remote or local + files. If there is more than one item on the list, the name of the + file is printed first. The first number is the file size, the + second is the last modification time of the file in the format + CCYYMMDDhhmmSS consisting of year, month, date, hour, minutes and + seconds in GMT. Note that this format, including the length, is + guaranteed, so that time strings can be directly compared via the + [[ builtin's < and > operators, even if they are too long to be + represented as integers. + + Not all servers support the commands for retrieving this + information. In that case, the remote command will print nothing + and return status 2, compared with status 1 for a file not found. + + The local command (but not remote) may be used with no arguments, + in which case the information comes from examining file descriptor + zero. This is the same file as seen by a put command with no + further redirection. + +get FILE ... + Retrieve all FILEs from the server, concatenating them and sending + them to standard output. + +put FILE ... + For each FILE, read a file from standard input and send that to + the remote host with the given name. + +append FILE ... + As put, but if the remote FILE already exists, data is appended to + it instead of overwriting it. + +getat FILE POINT +putat FILE POINT +appendat FILE POINT + Versions of get, put and append which will start the transfer at + the given POINT in the remote FILE. This is useful for appending + to an incomplete local file. However, note that this ability is + not universally supported by servers (and is not quite the + behaviour specified by the standard). + +delete FILE ... + Delete the list of files on the server. + +mkdir DIRECTORY + Create a new directory DIRECTORY on the server. + +rmdir DIRECTORY + Delete the directory DIRECTORY on the server. + +rename OLD-NAME NEW-NAME + Rename file OLD-NAME to NEW-NAME on the server. + +site ARG ... + Send a host-specific command to the server. You will probably + only need this if instructed by the server to use it. + +quote ARG ... + Send the raw FTP command sequence to the server. You should be + familiar with the FTP command set as defined in RFC959 before doing + this. Useful commands may include STAT and HELP. Note also the + mechanism for returning messages as described for the variable + ZFTP_VERBOSE below, in particular that all messages from the + control connection are sent to standard error. + +close +quit + Close the current data connection. This unsets the shell + parameters ZFTP_HOST, ZFTP_PORT, ZFTP_IP, ZFTP_SYSTEM, ZFTP_USER, + ZFTP_ACCOUNT, ZFTP_PWD, ZFTP_TYPE and ZFTP_MODE. + +session [ SESSNAME ] + Allows multiple FTP sessions to be used at once. The name of the + session is an arbitrary string of characters; the default session + is called `default'. If this command is called without an + argument, it will list all the current sessions; with an argument, + it will either switch to the existing session called SESSNAME, or + create a new session of that name. + + Each session remembers the status of the connection, the set of + connection-specific shell parameters (the same set as are unset + when a connection closes, as given in the description of close), + and any user parameters specified with the params subcommand. + Changing to a previous session restores those values; changing to + a new session initialises them in the same way as if zftp had just + been loaded. The name of the current session is given by the + parameter ZFTP_SESSION. + +rmsession [ SESSNAME ] + Delete a session; if a name is not given, the current session is + deleted. If the current session is deleted, the earliest existing + session becomes the new current session, otherwise the current + session is not changed. If the session being deleted is the only + one, a new session called `default' is created and becomes the + current session; note that this is a new session even if the + session being deleted is also called `default'. It is recommended + that sessions not be deleted while background commands which use + zftp are still active. + + + +22.31.2 Parameters +------------------ + +The following shell parameters are used by zftp. Currently none of +them are special. + + +ZFTP_TMOUT + Integer. The time in seconds to wait for a network operation to + complete before returning an error. If this is not set when the + module is loaded, it will be given the default value 60. A value + of zero turns off timeouts. If a timeout occurs on the control + connection it will be closed. Use a larger value if this occurs + too frequently. + +ZFTP_IP + Readonly. The IP address of the current connection in dot + notation. + +ZFTP_HOST + Readonly. The hostname of the current remote server. If the host + was opened as an IP number, ZFTP_HOST contains that instead; this + saves the overhead for a name lookup, as IP numbers are most + commonly used when a nameserver is unavailable. + +ZFTP_PORT + Readonly. The number of the remote TCP port to which the + connection is open (even if the port was originally specified as a + named service). Usually this is the standard FTP port, 21. + + In the unlikely event that your system does not have the + appropriate conversion functions, this appears in network byte + order. If your system is little-endian, the port then consists of + two swapped bytes and the standard port will be reported as 5376. + In that case, numeric ports passed to zftp open will also need to + be in this format. + +ZFTP_SYSTEM + Readonly. The system type string returned by the server in + response to an FTP SYST request. The most interesting case is a + string beginning "UNIX Type: L8", which ensures maximum + compatibility with a local UNIX host. + +ZFTP_TYPE + Readonly. The type to be used for data transfers , either `A' or + `I'. Use the type subcommand to change this. + +ZFTP_USER + Readonly. The username currently logged in, if any. + +ZFTP_ACCOUNT + Readonly. The account name of the current user, if any. Most + servers do not require an account name. + +ZFTP_PWD + Readonly. The current directory on the server. + +ZFTP_CODE + Readonly. The three digit code of the last FTP reply from the + server as a string. This can still be read after the connection + is closed, and is not changed when the current session changes. + +ZFTP_REPLY + Readonly. The last line of the last reply sent by the server. + This can still be read after the connection is closed, and is not + changed when the current session changes. + +ZFTP_SESSION + Readonly. The name of the current FTP session; see the + description of the session subcommand. + +ZFTP_PREFS + A string of preferences for altering aspects of zftp's behaviour. + Each preference is a single character. The following are defined: + + + P + Passive: attempt to make the remote server initiate data + transfers. This is slightly more efficient than sendport + mode. If the letter S occurs later in the string, zftp will + use sendport mode if passive mode is not available. + + S + Sendport: initiate transfers by the FTP PORT command. If + this occurs before any P in the string, passive mode will + never be attempted. + + D + Dumb: use only the bare minimum of FTP commands. This + prevents the variables ZFTP_SYSTEM and ZFTP_PWD from being + set, and will mean all connections default to ASCII type. It + may prevent ZFTP_SIZE from being set during a transfer if the + server does not send it anyway (many servers do). + + + If ZFTP_PREFS is not set when zftp is loaded, it will be set to a + default of `PS', i.e. use passive mode if available, otherwise + fall back to sendport mode. + +ZFTP_VERBOSE + A string of digits between 0 and 5 inclusive, specifying which + responses from the server should be printed. All responses go to + standard error. If any of the numbers 1 to 5 appear in the string, + raw responses from the server with reply codes beginning with that + digit will be printed to standard error. The first digit of the + three digit reply code is defined by RFC959 to correspond to: + + + 1. + A positive preliminary reply. + + 2. + A positive completion reply. + + 3. + A positive intermediate reply. + + 4. + A transient negative completion reply. + + 5. + A permanent negative completion reply. + + + It should be noted that, for unknown reasons, the reply `Service + not available', which forces termination of a connection, is + classified as 421, i.e. `transient negative', an interesting + interpretation of the word `transient'. + + The code 0 is special: it indicates that all but the last line of + multiline replies read from the server will be printed to standard + error in a processed format. By convention, servers use this + mechanism for sending information for the user to read. The + appropriate reply code, if it matches the same response, takes + priority. + + If ZFTP_VERBOSE is not set when zftp is loaded, it will be set to + the default value 450, i.e., messages destined for the user and + all errors will be printed. A null string is valid and specifies + that no messages should be printed. + + + +22.31.3 Functions +----------------- + + + + +zftp_chpwd + If this function is set by the user, it is called every time the + directory changes on the server, including when a user is logged + in, or when a connection is closed. In the last case, $ZFTP_PWD + will be unset; otherwise it will reflect the new directory. + +zftp_progress + If this function is set by the user, it will be called during a + get, put or append operation each time sufficient data has been + received from the host. During a get, the data is sent to + standard output, so it is vital that this function should write to + standard error or directly to the terminal, _not_ to standard + output. + + When it is called with a transfer in progress, the following + additional shell parameters are set: + + + ZFTP_FILE + The name of the remote file being transferred from or to. + + ZFTP_TRANSFER + A G for a get operation and a P for a put operation. + + ZFTP_SIZE + The total size of the complete file being transferred: the + same as the first value provided by the remote and local + subcommands for a particular file. If the server cannot + supply this value for a remote file being retrieved, it will + not be set. If input is from a pipe the value may be + incorrect and correspond simply to a full pipe buffer. + + ZFTP_COUNT + The amount of data so far transferred; a number between zero + and $ZFTP_SIZE, if that is set. This number is always + available. + + + The function is initially called with ZFTP_TRANSFER set + appropriately and ZFTP_COUNT set to zero. After the transfer is + finished, the function will be called one more time with + ZFTP_TRANSFER set to GF or PF, in case it wishes to tidy up. It + is otherwise never called twice with the same value of ZFTP_COUNT. + + Sometimes the progress meter may cause disruption. It is up to the + user to decide whether the function should be defined and to use + unfunction when necessary. + + + +22.31.4 Problems +---------------- + + + +A connection may not be opened in the left hand side of a pipe as this +occurs in a subshell and the file information is not updated in the main +shell. In the case of type or mode changes or closing the connection +in a subshell, the information is returned but variables are not +updated until the next call to zftp. Other status changes in subshells +will not be reflected by changes to the variables (but should be +otherwise harmless). + +Deleting sessions while a zftp command is active in the background can +have unexpected effects, even if it does not use the session being +deleted. This is because all shell subprocesses share information on +the state of all connections, and deleting a session changes the +ordering of that information. + +On some operating systems, the control connection is not valid after a +fork(), so that operations in subshells, on the left hand side of a +pipeline, or in the background are not possible, as they should be. +This is presumably a bug in the operating system. + + +File: zsh.info, Node: The zsh/zle Module, Next: The zsh/zleparameter Module, Prev: The zsh/zftp Module, Up: Zsh Modules + +22.32 The zsh/zle Module +======================== + + + + The zsh/zle module contains the Zsh Line Editor. See *Note Zsh Line +Editor::. + + +File: zsh.info, Node: The zsh/zleparameter Module, Next: The zsh/zprof Module, Prev: The zsh/zle Module, Up: Zsh Modules + +22.33 The zsh/zleparameter Module +================================= + + + + The zsh/zleparameter module defines two special parameters that can +be used to access internal information of the Zsh Line Editor (see +*Note Zsh Line Editor::). + + +keymaps + This array contains the names of the keymaps currently defined. + +widgets + This associative array contains one entry per widget. The name of + the widget is the key and the value gives information about the + widget. It is either the string `builtin' for builtin widgets, + a string of the form `user:NAME' for user-defined widgets, + where NAME is the name of the shell function implementing the + widget, a string of the form `completion:TYPE:NAME' for + completion widgets, or a null value if the widget is not yet + fully defined. In the penultimate case, TYPE is the name of the + builtin widget the completion widget imitates in its behavior and + NAME is the name of the shell function implementing the completion + widget. + + + +File: zsh.info, Node: The zsh/zprof Module, Next: The zsh/zpty Module, Prev: The zsh/zleparameter Module, Up: Zsh Modules + +22.34 The zsh/zprof Module +========================== + + + + When loaded, the zsh/zprof causes shell functions to be profiled. +The profiling results can be obtained with the zprof builtin command +made available by this module. There is no way to turn profiling off +other than unloading the module. + + +zprof [ -c ] + Without the -c option, zprof lists profiling results to standard + output. The format is comparable to that of commands like gprof. + + At the top there is a summary listing all functions that were + called at least once. This summary is sorted in decreasing order + of the amount of time spent in each. The lines contain the number + of the function in order, which is used in other parts of the list + in suffixes of the form `[NUM]', then the number of calls made to + the function. The next three columns list the time in + milliseconds spent in the function and its descendants, the average + time in milliseconds spent in the function and its descendants per + call and the percentage of time spent in all shell functions used + in this function and its descendants. The following three columns + give the same information, but counting only the time spent in the + function itself. The final column shows the name of the function. + + After the summary, detailed information about every function that + was invoked is listed, sorted in decreasing order of the amount of + time spent in each function and its descendants. Each of these + entries consists of descriptions for the functions that called the + function described, the function itself, and the functions that + were called from it. The description for the function itself has + the same format as in the summary (and shows the same + information). The other lines don't show the number of the + function at the beginning and have their function named indented to + make it easier to distinguish the line showing the function + described in the section from the surrounding lines. + + The information shown in this case is almost the same as in the + summary, but only refers to the call hierarchy being displayed. + For example, for a calling function the column showing the total + running time lists the time spent in the described function and + its descendants only for the times when it was called from that + particular calling function. Likewise, for a called function, + this columns lists the total time spent in the called function and + its descendants only for the times when it was called from the + function described. + + Also in this case, the column showing the number of calls to a + function also shows a slash and then the total number of + invocations made to the called function. + + As long as the zsh/zprof module is loaded, profiling will be done + and multiple invocations of the zprof builtin command will show the + times and numbers of calls since the module was loaded. With the + -c option, the zprof builtin command will reset its internal + counters and will not show the listing. + + + +File: zsh.info, Node: The zsh/zpty Module, Next: The zsh/zselect Module, Prev: The zsh/zprof Module, Up: Zsh Modules + +22.35 The zsh/zpty Module +========================= + + + + The zsh/zpty module offers one builtin: + + +zpty [ -e ] [ -b ] NAME [ ARG ... ] + The arguments following NAME are concatenated with spaces between, + then executed as a command, as if passed to the eval builtin. The + command runs under a newly assigned pseudo-terminal; this is + useful for running commands non-interactively which expect an + interactive environment. The NAME is not part of the command, but + is used to refer to this command in later calls to zpty. + + With the -e option, the pseudo-terminal is set up so that input + characters are echoed. + + With the -b option, input to and output from the pseudo-terminal + are made non-blocking. + + The shell parameter REPLY is set to the file descriptor assigned to + the master side of the pseudo-terminal. This allows the terminal + to be monitored with ZLE descriptor handlers (see *Note Zle + Builtins::) or manipulated with sysread and syswrite (see *Note + The zsh/system Module::). _Warning_: Use of sysread and syswrite + is _not_ recommended; use zpty -r and zpty -w unless you know + exactly what you are doing. + +zpty -d [ NAME ... ] + The second form, with the -d option, is used to delete commands + previously started, by supplying a list of their NAMEs. If no + NAME is given, all commands are deleted. Deleting a command causes + the HUP signal to be sent to the corresponding process. + +zpty -w [ -n ] NAME [ STRING ... ] + The -w option can be used to send the to command NAME the given + STRINGs as input (separated by spaces). If the -n option is _not_ + given, a newline is added at the end. + + If no STRING is provided, the standard input is copied to the + pseudo-terminal; this may stop before copying the full input if the + pseudo-terminal is non-blocking. The exact input is always copied: + the -n option is not applied. + + Note that the command under the pseudo-terminal sees this input as + if it were typed, so beware when sending special tty driver + characters such as word-erase, line-kill, and end-of-file. + +zpty -r [ -mt ] NAME [ PARAM [ PATTERN ] ] + The -r option can be used to read the output of the command NAME. + With only a NAME argument, the output read is copied to the + standard output. Unless the pseudo-terminal is non-blocking, + copying continues until the command under the pseudo-terminal + exits; when non-blocking, only as much output as is immediately + available is copied. The return status is zero if any output is + copied. + + When also given a PARAM argument, at most one line is read and + stored in the parameter named PARAM. Less than a full line may be + read if the pseudo-terminal is non-blocking. The return status is + zero if at least one character is stored in PARAM. + + If a PATTERN is given as well, output is read until the whole + string read matches the PATTERN, even in the non-blocking case. + The return status is zero if the string read matches the pattern, + or if the command has exited but at least one character could + still be read. If the option -m is present, the return status is + zero only if the pattern matches. As of this writing, a maximum + of one megabyte of output can be consumed this way; if a full + megabyte is read without matching the pattern, the return status + is non-zero. + + In all cases, the return status is non-zero if nothing could be + read, and is 2 if this is because the command has finished. + + If the -r option is combined with the -t option, zpty tests + whether output is available before trying to read. If no output is + available, zpty immediately returns the status 1. When used with + a PATTERN, the behaviour on a failed poll is similar to when the + command has exited: the return value is zero if at least one + character could still be read even if the pattern failed to match. + +zpty -t NAME + The -t option without the -r option can be used to test whether + the command NAME is still running. It returns a zero status if + the command is running and a non-zero value otherwise. + +zpty [ -L ] + The last form, without any arguments, is used to list the commands + currently defined. If the -L option is given, this is done in the + form of calls to the zpty builtin. + + + +File: zsh.info, Node: The zsh/zselect Module, Next: The zsh/zutil Module, Prev: The zsh/zpty Module, Up: Zsh Modules + +22.36 The zsh/zselect Module +============================ + + + + The zsh/zselect module makes available one builtin command: + + +zselect [ -rwe ] [ -t TIMEOUT ] [ -a ARRAY ] [ -A ASSOC ] [ FD ... ] + The zselect builtin is a front-end to the `select' system call, + which blocks until a file descriptor is ready for reading or + writing, or has an error condition, with an optional timeout. If + this is not available on your system, the command prints an error + message and returns status 2 (normal errors return status 1). For + more information, see your systems documentation for man page + select(3). Note there is no connection with the shell builtin of + the same name. + + Arguments and options may be intermingled in any order. Non-option + arguments are file descriptors, which must be decimal integers. By + default, file descriptors are to be tested for reading, i.e. + zselect will return when data is available to be read from the + file descriptor, or more precisely, when a read operation from the + file descriptor will not block. After a -r, -w and -e, the given + file descriptors are to be tested for reading, writing, or error + conditions. These options and an arbitrary list of file + descriptors may be given in any order. + + (The presence of an `error condition' is not well defined in the + documentation for many implementations of the select system call. + According to recent versions of the POSIX specification, it is + really an _exception_ condition, of which the only standard + example is out-of-band data received on a socket. So zsh users + are unlikely to find the -e option useful.) + + The option `-t TIMEOUT' specifies a timeout in hundredths of a + second. This may be zero, in which case the file descriptors will + simply be polled and zselect will return immediately. It is + possible to call zselect with no file descriptors and a non-zero + timeout for use as a finer-grained replacement for `sleep'; note, + however, the return status is always 1 for a timeout. + + The option `-a ARRAY' indicates that ARRAY should be set to + indicate the file descriptor(s) which are ready. If the option is + not given, the array reply will be used for this purpose. The + array will contain a string similar to the arguments for zselect. + For example, + + + zselect -t 0 -r 0 -w 1 + + might return immediately with status 0 and $reply containing `-r 0 + -w 1' to show that both file descriptors are ready for the + requested operations. + + The option `-A ASSOC' indicates that the associative array ASSOC + should be set to indicate the file descriptor(s) which are ready. + This option overrides the option -a, nor will reply be modified. + The keys of assoc are the file descriptors, and the corresponding + values are any of the characters `rwe' to indicate the condition. + + The command returns status 0 if some file descriptors are ready for + reading. If the operation timed out, or a timeout of 0 was given + and no file descriptors were ready, or there was an error, it + returns status 1 and the array will not be set (nor modified in + any way). If there was an error in the select operation the + appropriate error message is printed. + + + +File: zsh.info, Node: The zsh/zutil Module, Prev: The zsh/zselect Module, Up: Zsh Modules + +22.37 The zsh/zutil Module +========================== + + + + The zsh/zutil module only adds some builtins: + + +zstyle [ -L [ METAPATTERN [ STYLE ] ] ] +zstyle [ -e | - | -- ] PATTERN STYLE STRING ... +zstyle -d [ PATTERN [ STYLE ... ] ] +zstyle -g NAME [ PATTERN [ STYLE ] ] +zstyle -{a|b|s} CONTEXT STYLE NAME [ SEP ] +zstyle -{T|t} CONTEXT STYLE [ STRING ... ] +zstyle -m CONTEXT STYLE PATTERN + This builtin command is used to define and lookup styles. Styles + are pairs of names and values, where the values consist of any + number of strings. They are stored together with patterns and + lookup is done by giving a string, called the `_context_', which + is matched against the patterns. The definition stored for the + most specific pattern that matches will be returned. + + A pattern is considered to be more specific than another if it + contains more components (substrings separated by colons) or if + the patterns for the components are more specific, where simple + strings are considered to be more specific than patterns and + complex patterns are considered to be more specific than the + pattern `*'. A `*' in the pattern will match zero or more + characters in the context; colons are not treated specially in + this regard. If two patterns are equally specific, the tie is + broken in favour of the pattern that was defined first. + + _Example_ + + For example, to define your preferred form of precipitation + depending on which city you're in, you might set the following in + your zshrc: + + + zstyle ':weather:europe:*' preferred-precipitation rain + zstyle ':weather:europe:germany:* preferred-precipitation none + zstyle ':weather:europe:germany:*:munich' preferred-precipitation snow + + Then, the fictional `weather' plugin might run under the hood a + command such as + + + zstyle -s ":weather:${continent}:${country}:${county}:${city}" preferred-precipitation REPLY + + in order to retrieve your preference into the scalar variable + $REPLY. + + _Usage_ + + The forms that operate on patterns are the following. + + + zstyle [ -L [ METAPATTERN [ STYLE ] ] ] + Without arguments, lists style definitions. Styles are shown + in alphabetic order and patterns are shown in the order + zstyle will test them. + + If the -L option is given, listing is done in the form of + calls to zstyle. The optional first argument, METAPATTERN, + is a pattern which will be matched against the string + supplied as PATTERN when the style was defined. Note: this + means, for example, `zstyle -L ":completion:*"' will match + any supplied pattern beginning `:completion:', not just + ":completion:*": use ':completion:\*' to match that. The + optional second argument limits the output to a specific + STYLE (not a pattern). -L is not compatible with any other + options. + + zstyle [ - | -- | -e ] PATTERN STYLE STRING ... + Defines the given STYLE for the PATTERN with the STRINGs as + the value. If the -e option is given, the STRINGs will be + concatenated (separated by spaces) and the resulting string + will be evaluated (in the same way as it is done by the eval + builtin command) when the style is looked up. In this case + the parameter `reply' must be assigned to set the strings + returned after the evaluation. Before evaluating the value, + reply is unset, and if it is still unset after the + evaluation, the style is treated as if it were not set. + + zstyle -d [ PATTERN [ STYLE ... ] ] + Delete style definitions. Without arguments all definitions + are deleted, with a PATTERN all definitions for that pattern + are deleted and if any STYLEs are given, then only those + styles are deleted for the PATTERN. + + zstyle -g NAME [ PATTERN [ STYLE ] ] + Retrieve a style definition. The NAME is used as the name of + an array in which the results are stored. Without any further + arguments, all patterns defined are returned. With a PATTERN + the styles defined for that pattern are returned and with + both a PATTERN and a STYLE, the value strings of that + combination is returned. + + + The other forms can be used to look up or test styles for a given + context. + + + zstyle -s CONTEXT STYLE NAME [ SEP ] + The parameter NAME is set to the value of the style + interpreted as a string. If the value contains several + strings they are concatenated with spaces (or with the SEP + string if that is given) between them. + + Return 0 if the style is set, 1 otherwise. + + zstyle -b CONTEXT STYLE NAME + The value is stored in NAME as a boolean, i.e. as the string + `yes' if the value has only one string and that string is + equal to one of `yes', `true', `on', or `1'. If the value is + any other string or has more than one string, the parameter + is set to `no'. + + Return 0 if NAME is set to `yes', 1 otherwise. + + zstyle -a CONTEXT STYLE NAME + The value is stored in NAME as an array. If NAME is declared + as an associative array, the first, third, etc. strings are + used as the keys and the other strings are used as the values. + + Return 0 if the style is set, 1 otherwise. + + zstyle -t CONTEXT STYLE [ STRING ... ] + zstyle -T CONTEXT STYLE [ STRING ... ] + Test the value of a style, i.e. the -t option only returns a + status (sets $?). Without any STRING the return status is + zero if the style is defined for at least one matching + pattern, has only one string in its value, and that is equal + to one of `true', `yes', `on' or `1'. If any STRINGs are + given the status is zero if and only if at least one of the + STRINGs is equal to at least one of the strings in the value. + If the style is defined but doesn't match, the return status + is 1. If the style is not defined, the status is 2. + + The -T option tests the values of the style like -t, but it + returns status zero (rather than 2) if the style is not + defined for any matching pattern. + + zstyle -m CONTEXT STYLE PATTERN + Match a value. Returns status zero if the PATTERN matches at + least one of the strings in the value. + + +zformat -f PARAM FORMAT SPEC ... +zformat -a ARRAY SEP SPEC ... + This builtin provides two different forms of formatting. The first + form is selected with the -f option. In this case the FORMAT + string will be modified by replacing sequences starting with a + percent sign in it with strings from the SPECs. Each SPEC should + be of the form `CHAR:STRING' which will cause every appearance of + the sequence `%CHAR' in FORMAT to be replaced by the STRING. The + `%' sequence may also contain optional minimum and maximum field + width specifications between the `%' and the `CHAR' in the form + `%MIN.MAXc', i.e. the minimum field width is given first and if + the maximum field width is used, it has to be preceded by a dot. + Specifying a minimum field width makes the result be padded with + spaces to the right if the STRING is shorter than the requested + width. Padding to the left can be achieved by giving a negative + minimum field width. If a maximum field width is specified, the + STRING will be truncated after that many characters. After all + `%' sequences for the given SPECs have been processed, the + resulting string is stored in the parameter PARAM. + + The %-escapes also understand ternary expressions in the form used + by prompts. The % is followed by a `(' and then an ordinary + format specifier character as described above. There may be a set + of digits either before or after the `('; these specify a test + number, which defaults to zero. Negative numbers are also + allowed. An arbitrary delimiter character follows the format + specifier, which is followed by a piece of `true' text, the + delimiter character again, a piece of `false' text, and a closing + parenthesis. The complete expression (without the digits) thus + looks like `%(X.TEXT1.TEXT2)', except that the `.' character is + arbitrary. The value given for the format specifier in the + CHAR:STRING expressions is evaluated as a mathematical expression, + and compared with the test number. If they are the same, TEXT1 is + output, else TEXT2 is output. A parenthesis may be escaped in + TEXT2 as %). Either of TEXT1 or TEXT2 may contain nested + %-escapes. + + For example: + + + zformat -f REPLY "The answer is '%3(c.yes.no)'." c:3 + + outputs "The answer is 'yes'." to REPLY since the value for the + format specifier c is 3, agreeing with the digit argument to the + ternary expression. + + The second form, using the -a option, can be used for aligning + strings. Here, the SPECs are of the form `LEFT:RIGHT' where + `LEFT' and `RIGHT' are arbitrary strings. These strings are + modified by replacing the colons by the SEP string and padding the + LEFT strings with spaces to the right so that the SEP strings in + the result (and hence the RIGHT strings after them) are all + aligned if the strings are printed below each other. All strings + without a colon are left unchanged and all strings with an empty + RIGHT string have the trailing colon removed. In both cases the + lengths of the strings are not used to determine how the other + strings are to be aligned. A colon in the LEFT string can be + escaped with a backslash. The resulting strings are stored in the + ARRAY. + +zregexparse + This implements some internals of the _regex_arguments function. + +zparseopts [ -D -E -F -K -M ] [ -a ARRAY ] [ -A ASSOC ] [ - ] SPEC ... + This builtin simplifies the parsing of options in positional + parameters, i.e. the set of arguments given by $*. Each SPEC + describes one option and must be of the form `OPT[=ARRAY]'. If an + option described by OPT is found in the positional parameters it + is copied into the ARRAY specified with the -a option; if the + optional `=ARRAY' is given, it is instead copied into that array, + which should be declared as a normal array and never as an + associative array. + + Note that it is an error to give any SPEC without an `=ARRAY' + unless one of the -a or -A options is used. + + Unless the -E option is given, parsing stops at the first string + that isn't described by one of the SPECs. Even with -E, parsing + always stops at a positional parameter equal to `-' or `--'. See + also -F. + + The OPT description must be one of the following. Any of the + special characters can appear in the option name provided it is + preceded by a backslash. + + + NAME + NAME+ + The NAME is the name of the option without the leading `-'. + To specify a GNU-style long option, one of the usual two + leading `-' must be included in NAME; for example, a `--file' + option is represented by a NAME of `-file'. + + If a `+' appears after NAME, the option is appended to ARRAY + each time it is found in the positional parameters; without + the `+' only the _last_ occurrence of the option is preserved. + + If one of these forms is used, the option takes no argument, + so parsing stops if the next positional parameter does not + also begin with `-' (unless the -E option is used). + + NAME: + NAME:- + NAME:: + If one or two colons are given, the option takes an argument; + with one colon, the argument is mandatory and with two colons + it is optional. The argument is appended to the ARRAY after + the option itself. + + An optional argument is put into the same array element as + the option name (note that this makes empty strings as + arguments indistinguishable). A mandatory argument is added + as a separate element unless the `:-' form is used, in which + case the argument is put into the same element. + + A `+' as described above may appear between the NAME and the + first colon. + + + In all cases, option-arguments must appear either immediately + following the option in the same positional parameter or in the + next one. Even an optional argument may appear in the next + parameter, unless it begins with a `-'. There is no special + handling of `=' as with GNU-style argument parsers; given the SPEC + `-foo:', the positional parameter `--foo=bar' is parsed as `--foo' + with an argument of `=bar'. + + When the names of two options that take no arguments overlap, the + longest one wins, so that parsing for the SPECs `-foo -foobar' + (for example) is unambiguous. However, due to the aforementioned + handling of option-arguments, ambiguities may arise when at least + one overlapping SPEC takes an argument, as in `-foo: -foobar'. In + that case, the last matching SPEC wins. + + The options of zparseopts itself cannot be stacked because, for + example, the stack `-DEK' is indistinguishable from a SPEC for the + GNU-style long option `--DEK'. The options of zparseopts itself + are: + + + -a ARRAY + As described above, this names the default array in which to + store the recognised options. + + -A ASSOC + If this is given, the options and their values are also put + into an associative array with the option names as keys and + the arguments (if any) as the values. + + -D + If this option is given, all options found are removed from + the positional parameters of the calling shell or shell + function, up to but not including any not described by the + SPECs. If the first such parameter is `-' or `--', it is + removed as well. This is similar to using the shift builtin. + + -E + This changes the parsing rules to _not_ stop at the first + string that isn't described by one of the SPECs. It can be + used to test for or (if used together with -D) extract + options and their arguments, ignoring all other options and + arguments that may be in the positional parameters. As + indicated above, parsing still stops at the first `-' or `--' + not described by a SPEC, but it is not removed when used with + -D. + + -F + If this option is given, zparseopts immediately stops at the + first option-like parameter not described by one of the + SPECs, prints an error message, and returns status 1. + Removal (-D) and extraction (-E) are not performed, and + option arrays are not updated. This provides basic + validation for the given options. + + Note that the appearance in the positional parameters of an + option without its required argument always aborts parsing + and returns an error as described above regardless of whether + this option is used. + + -K + With this option, the arrays specified with the -a option and + with the `=ARRAY' forms are kept unchanged when none of the + SPECs for them is used. Otherwise the entire array is + replaced when any of the SPECs is used. Individual elements + of associative arrays specified with the -A option are + preserved by -K. This allows assignment of default values to + arrays before calling zparseopts. + + -M + This changes the assignment rules to implement a map among + equivalent option names. If any SPEC uses the `=ARRAY' form, + the string ARRAY is interpreted as the name of another SPEC, + which is used to choose where to store the values. If no + other SPEC is found, the values are stored as usual. This + changes only the way the values are stored, not the way $* is + parsed, so results may be unpredictable if the `NAME+' + specifier is used inconsistently. + + + For example, + + + set -- -a -bx -c y -cz baz -cend + zparseopts a=foo b:=bar c+:=bar + + will have the effect of + + + foo=(-a) + bar=(-b x -c y -c z) + + The arguments from `baz' on will not be used. + + As an example for the -E option, consider: + + + set -- -a x -b y -c z arg1 arg2 + zparseopts -E -D b:=bar + + will have the effect of + + + bar=(-b y) + set -- -a x -c z arg1 arg2 + + I.e., the option -b and its arguments are taken from the + positional parameters and put into the array bar. + + The -M option can be used like this: + + + set -- -a -bx -c y -cz baz -cend + zparseopts -A bar -M a=foo b+: c:=b + + to have the effect of + + + foo=(-a) + bar=(-a '' -b xyz) + + + +File: zsh.info, Node: Calendar Function System, Next: TCP Function System, Prev: Zsh Modules, Up: Top + +23 Calendar Function System +*************************** + + + +23.1 Description +================ + +The shell is supplied with a series of functions to replace and enhance +the traditional Unix calendar programme, which warns the user of +imminent or future events, details of which are stored in a text file +(typically calendar in the user's home directory). The version +provided here includes a mechanism for alerting the user when an event +is due. + +In addition functions age, before and after are provided that can be +used in a glob qualifier; they allow files to be selected based on +their modification times. + +The format of the calendar file and the dates used there in and in the +age function are described first, then the functions that can be called +to examine and modify the calendar file. + +The functions here depend on the availability of the zsh/datetime +module which is usually installed with the shell. The library function +strptime() must be available; it is present on most recent operating +systems. + + + +* Menu: + +* Calendar File and Date Formats:: +* Calendar System User Functions:: +* Calendar Styles:: +* Calendar Utility Functions:: +* Calendar Bugs:: + + + +File: zsh.info, Node: Calendar File and Date Formats, Next: Calendar System User Functions, Up: Calendar Function System + +23.2 File and Date Formats +========================== + + + +23.2.1 Calendar File Format +--------------------------- + +The calendar file is by default ~/calendar. This can be configured by +the calendar-file style, see *Note Calendar Styles::. The basic format +consists of a series of separate lines, with no indentation, each +including a date and time specification followed by a description of +the event. + +Various enhancements to this format are supported, based on the syntax +of Emacs calendar mode. An indented line indicates a continuation line +that continues the description of the event from the preceding line +(note the date may not be continued in this way). An initial ampersand +(&) is ignored for compatibility. + +An indented line on which the first non-whitespace character is # is +not displayed with the calendar entry, but is still scanned for +information. This can be used to hide information useful to the +calendar system but not to the user, such as the unique identifier used +by calendar_add. + +The Emacs extension that a date with no description may refer to a +number of succeeding events at different times is not supported. + +Unless the done-file style has been altered, any events which have been +processed are appended to the file with the same name as the calendar +file with the suffix .done, hence ~/calendar.done by default. + +An example is shown below. + + + +23.2.2 Date Format +------------------ + +The format of the date and time is designed to allow flexibility without +admitting ambiguity. (The words `date' and `time' are both used in the +documentation below; except where specifically noted this implies a +string that may include both a date and a time specification.) Note +that there is no localization support; month and day names must be in +English and separator characters are fixed. Matching is case +insensitive, and only the first three letters of the names are +significant, although as a special case a form beginning "month" does +not match "Monday". Furthermore, time zones are not handled; all times +are assumed to be local. + +It is recommended that, rather than exploring the intricacies of the +system, users find a date format that is natural to them and stick to +it. This will avoid unexpected effects. Various key facts should be +noted. + + + * In particular, note the confusion between MONTH/DAY/YEAR and + DAY/MONTH/YEAR when the month is numeric; these formats should be + avoided if at all possible. Many alternatives are available. + + * The year must be given in full to avoid confusion, and only years + from 1900 to 2099 inclusive are matched. + +The following give some obvious examples; users finding here a format +they like and not subject to vagaries of style may skip the full +description. As dates and times are matched separately (even though +the time may be embedded in the date), any date format may be mixed +with any format for the time of day provide the separators are clear +(whitespace, colons, commas). + + + 2007/04/03 13:13 + 2007/04/03:13:13 + 2007/04/03 1:13 pm + 3rd April 2007, 13:13 + April 3rd 2007 1:13 p.m. + Apr 3, 2007 13:13 + Tue Apr 03 13:13:00 2007 + 13:13 2007/apr/3 + +More detailed rules follow. + +Times are parsed and extracted before dates. They must use colons to +separate hours and minutes, though a dot is allowed before seconds if +they are present. This limits time formats to the following: + + + * HH:MM[:SS[.FFFFF]] [am|pm|a.m.|p.m.] + + * HH:MM.SS[.FFFFF] [am|pm|a.m.|p.m.] + +Here, square brackets indicate optional elements, possibly with +alternatives. Fractions of a second are recognised but ignored. For +absolute times (the normal format require by the calendar file and the +age, before and after functions) a date is mandatory but a time of day +is not; the time returned is at the start of the date. One variation +is allowed: if a.m. or p.m. or one of their variants is present, an +hour without a minute is allowed, e.g. 3 p.m.. + +Time zones are not handled, though if one is matched following a time +specification it will be removed to allow a surrounding date to be +parsed. This only happens if the format of the timezone is not too +unusual. The following are examples of forms that are understood: + + + +0100 + GMT + GMT-7 + CET+1CDT + +Any part of the timezone that is not numeric must have exactly three +capital letters in the name. + +Dates suffer from the ambiguity between DD/MM/YYYY and MM/DD/YYYY. It +is recommended this form is avoided with purely numeric dates, but use +of ordinals, eg. 3rd/04/2007, will resolve the ambiguity as the ordinal +is always parsed as the day of the month. Years must be four digits +(and the first two must be 19 or 20); 03/04/08 is not recognised. Other +numbers may have leading zeroes, but they are not required. The +following are handled: + + + * YYYY/MM/DD + + * YYYY-MM-DD + + * YYYY/MNM/DD + + * YYYY-MNM-DD + + * DD[th|st|rd] MNM[,] [ YYYY ] + + * MNM DD[th|st|rd][,] [ YYYY ] + + * DD[th|st|rd]/MM[,] YYYY + + * DD[th|st|rd]/MM/YYYY + + * MM/DD[th|st|rd][,] YYYY + + * MM/DD[th|st|rd]/YYYY + +Here, MNM is at least the first three letters of a month name, matched +case-insensitively. The remainder of the month name may appear but its +contents are irrelevant, so janissary, febrile, martial, apricot, +maybe, junta, etc. are happily handled. + +Where the year is shown as optional, the current year is assumed. There +are only two such cases, the form Jun 20 or 14 September (the only two +commonly occurring forms, apart from a "the" in some forms of English, +which isn't currently supported). Such dates will of course become +ambiguous in the future, so should ideally be avoided. + +Times may follow dates with a colon, e.g. 1965/07/12:09:45; this is in +order to provide a format with no whitespace. A comma and whitespace +are allowed, e.g. 1965/07/12, 09:45. Currently the order of these +separators is not checked, so illogical formats such as 1965/07/12, : +,09:45 will also be matched. For simplicity such variations are not +shown in the list above. Otherwise, a time is only recognised as being +associated with a date if there is only whitespace in between, or if the +time was embedded in the date. + +Days of the week are not normally scanned, but will be ignored if they +occur at the start of the date pattern only. However, in contexts +where it is useful to specify dates relative to today, days of the week +with no other date specification may be given. The day is assumed to +be either today or within the past week. Likewise, the words yesterday, +today and tomorrow are handled. All matches are case-insensitive. +Hence if today is Monday, then Sunday is equivalent to yesterday, +Monday is equivalent to today, but Tuesday gives a date six days ago. +This is not generally useful within the calendar file. Dates in this +format may be combined with a time specification; for example Tomorrow, +8 p.m.. + +For example, the standard date format: + + + Fri Aug 18 17:00:48 BST 2006 + +is handled by matching HH:MM:SS and removing it together with the +matched (but unused) time zone. This leaves the following: + + + Fri Aug 18 2006 + +Fri is ignored and the rest is matched according to the standard rules. + + + +23.2.3 Relative Time Format +--------------------------- + +In certain places relative times are handled. Here, a date is not +allowed; instead a combination of various supported periods are +allowed, together with an optional time. The periods must be in order +from most to least significant. + +In some cases, a more accurate calculation is possible when there is an +anchor date: offsets of months or years pick the correct day, rather +than being rounded, and it is possible to pick a particular day in a +month as `(1st Friday)', etc., as described in more detail below. + +Anchors are available in the following cases. If one or two times are +passed to the function calendar, the start time acts an anchor for the +end time when the end time is relative (even if the start time is +implicit). When examining calendar files, the scheduled event being +examined anchors the warning time when it is given explicitly by means +of the WARN keyword; likewise, the scheduled event anchors a repetition +period when given by the RPT keyword, so that specifications such as +RPT 2 months, 3rd Thursday are handled properly. Finally, the -R +argument to calendar_scandate directly provides an anchor for relative +calculations. + +The periods handled, with possible abbreviations are: + + +Years + years, yrs, ys, year, yr, y, yearly. A year is 365.25 days unless + there is an anchor. + +Months + months, mons, mnths, mths, month, mon, mnth, mth, monthly. Note + that m, ms, mn, mns are ambiguous and are _not_ handled. A month + is a period of 30 days rather than a calendar month unless there + is an anchor. + +Weeks + weeks, wks, ws, week, wk, w, weekly + +Days + days, dys, ds, day, dy, d, daily + +Hours + hours, hrs, hs, hour, hr, h, hourly + +Minutes + minutes, mins, minute, min, but _not_ m, ms, mn or mns + +Seconds + seconds, secs, ss, second, sec, s + + +Spaces between the numbers are optional, but are required between items, +although a comma may be used (with or without spaces). + +The forms yearly to hourly allow the number to be omitted; it is +assumed to be 1. For example, 1 d and daily are equivalent. Note that +using those forms with plurals is confusing; 2 yearly is the same as 2 +years, _not_ twice yearly, so it is recommended they only be used +without numbers. + +When an anchor time is present, there is an extension to handle regular +events in the form of the Nth SOMEday of the month. Such a +specification must occur immediately after any year and month +specification, but before any time of day, and must be in the form +N(th|st|rd) DAY, for example 1st Tuesday or 3rd Monday. As in other +places, days are matched case insensitively, must be in English, and +only the first three letters are significant except that a form +beginning `month' does not match `Monday'. No attempt is made to +sanitize the resulting date; attempts to squeeze too many occurrences +into a month will push the day into the next month (but in the obvious +fashion, retaining the correct day of the week). + +Here are some examples: + + + 30 years 3 months 4 days 3:42:41 + 14 days 5 hours + Monthly, 3rd Thursday + 4d,10hr + + +23.2.4 Example +-------------- + +Here is an example calendar file. It uses a consistent date format, as +recommended above. + + + Feb 1, 2006 14:30 Pointless bureaucratic meeting + Mar 27, 2006 11:00 Mutual recrimination and finger pointing + Bring water pistol and waterproofs + Mar 31, 2006 14:00 Very serious managerial pontification + # UID 12C7878A9A50 + Apr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins + May 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday + +The second entry has a continuation line. The third entry has a +continuation line that will not be shown when the entry is displayed, +but the unique identifier will be used by the calendar_add function when +updating the event. The fourth entry will produce a warning 30 minutes +before the event (to allow you to equip yourself appropriately). The +fifth entry repeats after a month on the 3rd Thursday, i.e. June 15, +2006, at the same time. + + + |