From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 27551 invoked from network); 29 Aug 2000 06:23:15 -0000 Received: from sunsite.auc.dk (130.225.51.30) by ns1.primenet.com.au with SMTP; 29 Aug 2000 06:23:15 -0000 Received: (qmail 9287 invoked by alias); 29 Aug 2000 06:22:34 -0000 Mailing-List: contact zsh-workers-help@sunsite.auc.dk; run by ezmlm Precedence: bulk X-No-Archive: yes X-Seq: 12716 Received: (qmail 9277 invoked from network); 29 Aug 2000 06:22:31 -0000 From: "Bart Schaefer" Message-Id: <1000829062210.ZM16288@candle.brasslantern.com> Date: Tue, 29 Aug 2000 06:22:10 +0000 X-Mailer: Z-Mail (5.0.0 30July97) To: zsh-workers@sunsite.auc.dk Subject: PATCH: Document REPLY/reply, misc. other parameter indexing MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii I noticed that the REPLY documentation was out of place in the section on the read builtin (it applies to any read, not just -l/-c) and in the course of fixing that I noticed that REPLY wasn't in the variables index. That in turn caused me to notice that PROMPT et al. were out of alphabetical order, probably so they'd show up after PS1 -- but what's psvar doing in the middle between PROMPT4 and prompt? So I just alphabetized them. Finally, I thought that some of the variables passed around heavily by name in the completion system deserved at least some mention in the index. There are probably others that I didn't catch. I wish I could figure out when the docs are intended to use `tt(foo)' and when just tt(foo) without the ticks. (The difficulty is that in info the typewriter face is lost and you can't see the emphasis without the `...'.) I chose to make nearby paragraphs consistent with each other, even if things aren't consistent across more widely separated uses. Index: Doc/Zsh/builtins.yo =================================================================== @@ -752,11 +752,15 @@ vindex(IFS, use of) item(tt(read) [ tt(-rzpqAclneEt) ] [ tt(-k) [ var(num) ] ] \ [ tt(-u)var(n) ] [ var(name)[tt(?)var(prompt)] ] [ var(name) ... ])( +vindex(REPLY, use of) +vindex(reply, use of) Read one line and break it into fields using the characters in tt($IFS) as separators, except as noted below. The first field is assigned to the first var(name), the second field to the second var(name), etc., with leftover fields assigned to the last var(name). +If var(name) is omitted then +tt(REPLY) is used for scalars and tt(reply) for arrays. startitem() item(tt(-r))( @@ -805,8 +809,7 @@ tt(compctl)). If the tt(-c) flag is given, the words of the current command are read. If the tt(-l) flag is given, the whole line is assigned as a scalar. If both flags are present, tt(-l) -is used and tt(-c) is ignored. If var(name) is omitted then -tt(REPLY) is used for scalars and tt(reply) for arrays. +is used and tt(-c) is ignored. ) item(tt(-n))( Together with tt(-c), the number of the word the cursor is on is Index: Doc/Zsh/compctl.yo =================================================================== @@ -305,6 +305,7 @@ resulting files. Note that tt(-g) is faster for filenames. ) item(tt(-K) var(function))( +vindex(reply, use of) 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 @@ -431,6 +432,7 @@ set and this flag is used. ) item(tt(-y) var(func-or-var))( +vindex(reply, use of) The list provided by var(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 @@ -441,7 +443,7 @@ 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 var(reply) to the result. In both cases, the display list will +array tt(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 Index: Doc/Zsh/compsys.yo =================================================================== @@ -2963,6 +2963,9 @@ The matches will be listed together with their descriptions if the tt(description) style for the tt(values) tag is set. +vindex(context, use of) +vindex(line, use of) +vindex(opt_args, use of) An var(action) of the form `tt(->)var(string)' is used by functions that implement a state machine. In this case, the `var(string)'s (with all leading and trailing spaces and tabs removed) of all actions that @@ -2983,6 +2986,7 @@ This will ensure that tt(_arguments) does not create unused global parameters. +vindex(expl, use of) A string in braces is evaluated to generate the matches and if the var(action) does not begin with an opening parentheses or brace, it is also split into separate words and executed. If the var(action) @@ -2991,7 +2995,7 @@ first word which can be given as arguments to the tt(compadd) builtin command and which make sure that the var(message) given in the description will be shown above the matches. These arguments -are taken from the array parameter tt(expl) which will be set up +are taken from the array parameter `tt(expl)' which will be set up before executing the var(action) and hence may be used in it (normally in an expansion like `tt($expl[@])'). Index: Doc/Zsh/expn.yo =================================================================== @@ -1623,6 +1623,8 @@ matches itself. Note that expansions must be quoted in the var(string) to prevent them from being expanded before globbing is done. +vindex(REPLY, use of) +vindex(reply, use of) During the execution of var(string) the filename currently being tested is available in the parameter tt(REPLY); the parameter may be altered to a string to be inserted into the list instead of the original Index: Doc/Zsh/grammar.yo =================================================================== @@ -203,6 +203,7 @@ cindex(selection, user) item(tt(select) var(name) [ tt(in) var(word) ... var(term) ] tt(do) var(list) tt(done))( where var(term) is one or more newline or tt(;) to terminate the var(word)s. +vindex(REPLY, use of) Print the set of var(word)s, each preceded by a number. If the tt(in) var(word) is omitted, use the positional parameters. The tt(PROMPT3) prompt is printed and a line is read from the line editor Index: Doc/Zsh/mod_zutil.yo =================================================================== @@ -36,6 +36,7 @@ startitem() item(tt(zstyle) [ tt(-) | tt(-)tt(-) | tt(-e) ] var(pattern) var(style) var(strings) ...)( +vindex(reply, use of) Defines the given var(style) for the var(pattern) with the var(strings) as the value. If the tt(-e) option is given, the var(strings) will be concatenated (separated by spaces) and the resulting string will be Index: Doc/Zsh/params.yo =================================================================== @@ -679,6 +679,21 @@ This string is output whenever the line editor exits. It usually contains termcap strings to reset the terminal. ) +vindex(PROMPT) +xitem(tt(PROMPT) ) +vindex(PROMPT2) +xitem(tt(PROMPT2) ) +vindex(PROMPT3) +xitem(tt(PROMPT3) ) +vindex(PROMPT4) +item(tt(PROMPT4) )( +Same as tt(PS1), tt(PS2), tt(PS3) and tt(PS4), +respectively. +) +vindex(prompt) +item(tt(prompt) )( +Same as tt(PS1). +) vindex(PS1) item(tt(PS1) )( The primary prompt string, printed before a command is read. @@ -705,17 +720,6 @@ the name of the current shell structure and the line number within it. In sh or ksh emulation, the default is `tt(PLUS() )'. ) -vindex(PROMPT) -xitem(tt(PROMPT) ) -vindex(PROMPT2) -xitem(tt(PROMPT2) ) -vindex(PROMPT3) -xitem(tt(PROMPT3) ) -vindex(PROMPT4) -item(tt(PROMPT4) )( -Same as tt(PS1), tt(PS2), tt(PS3) and tt(PS4), -respectively. -) vindex(psvar) vindex(PSVAR) item(tt(psvar) (tt(PSVAR) ))( @@ -723,10 +727,6 @@ tt(PROMPT) strings. Setting tt(psvar) also sets tt(PSVAR), and vice versa. ) -vindex(prompt) -item(tt(prompt) )( -Same as tt(PS1). -) vindex(READNULLCMD) item(tt(READNULLCMD) )( The command name to assume if a single input redirection @@ -737,6 +737,19 @@ If nonnegative, commands whose combined user and system execution times (measured in seconds) are greater than this value have timing statistics printed for them. +) +vindex(REPLY) +item(tt(REPLY))( +This parameter is reserved by convention to pass string values between +shell scripts and shell builtins in situations where a function call or +redirection are impossible or undesirable. The tt(read) builtin and the +tt(select) complex command may set tt(REPLY), and filename generation both +sets and examines its value when evaluating certain expressions. Some +modules also employ tt(REPLY) for similar purposes. +) +vindex(reply) +item(tt(reply))( +As tt(REPLY), but for array values rather than strings. ) vindex(RPROMPT) xitem(tt(RPROMPT) ) -- Bart Schaefer Brass Lantern Enterprises http://www.well.com/user/barts http://www.brasslantern.com Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net