diff options
Diffstat (limited to 'Doc/Zsh/builtins.yo')
| -rw-r--r-- | Doc/Zsh/builtins.yo | 211 |
1 files changed, 150 insertions, 61 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 1fcc7c2b7..5bbe7e70b 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -662,8 +662,8 @@ findex(fc) cindex(history, editing) cindex(editing history) redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ ))ifnztexi( ))) -xitem(tt(fc) [ tt(-e) var(ename) ] [-L] [ tt(-m) var(match) ] [ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ]) -xitem(tt(fc -l )[ tt(-LnrdfEiD) ] [ tt(-t) var(timefmt) ] [ tt(-m) var(match) ]) +xitem(tt(fc) [ tt(-e) var(ename) ] [ tt(-LI) ] [ tt(-m) var(match) ] [ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ]) +xitem(tt(fc -l )[ tt(-LI) ] [ tt(-nrdfEiD) ] [ tt(-t) var(timefmt) ] [ tt(-m) var(match) ]) xitem(SPACES()[ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ]) xitem(tt(fc -p )[ tt(-a) ] [ var(filename) [ var(histsize) [ var(savehistsize) ] ] ]) xitem(tt(fc) tt(-P)) @@ -674,31 +674,24 @@ shell is interactive. Usually this is detected automatically, but it can be forced by setting the tt(interactive) option when starting the shell. -Select a range of commands from var(first) to var(last) from the -history list. -The arguments var(first) and var(last) may be specified as a -number or as a string. A negative number is used as an offset -to the current history event number. -A string specifies the most recent event beginning with the given string. -All substitutions var(old)tt(=)var(new), if any, are then performed -on the commands. +The first two forms of this command select a range of events from +var(first) to var(last) from the history list. The arguments var(first) +and var(last) may be specified as a number or as a string. A negative +number is used as an offset to the current history event number. A string +specifies the most recent event beginning with the given string. All +substitutions var(old)tt(=)var(new), if any, are then performed on the +text of the events. -If the tt(-L) flag is given, only the local history is considered (see +In addition to the the number range, +startsitem() +sitem(tt(-I))(restricts to only internal events (not from tt($HISTFILE))) +sitem(tt(-L))(restricts to only local events (not from other shells, see tt(SHARE_HISTORY) in ifzman(zmanref(zshoptions))\ -ifnzman(noderef(Description of Options))). -If the tt(-m) flag is given, the first argument is taken as a -pattern (should be quoted) and only the history events matching this -pattern are considered. - -When the tt(-l) flag is given, the resulting commands are listed on -standard output. -Otherwise the editor program var(ename) is invoked on a file containing -these history events. If var(ename) is not given, the value -of the parameter tt(FCEDIT) is used; if that is not set the value of the -parameter tt(EDITOR) is used; if that is not set a builtin default, usually -`tt(vi)' is used. If var(ename) is `tt(-)', -no editor is invoked. When editing is complete, the edited -command is executed. +ifnzman(noderef(Description of Options)) -- note that tt($HISTFILE) is +considered local when read at startup)) +sitem(tt(-m))(takes the first argument as a pattern (should be quoted) and +only the history events matching this pattern are considered) +endsitem() If var(first) is not specified, it will be set to -1 (the most recent event), or to -16 if the tt(-l) flag is given. @@ -708,32 +701,39 @@ However, if the current event has added entries to the history with `tt(print -s)' or `tt(fc -R)', then the default var(last) for tt(-l) includes all new history entries since the current event began. -The flag tt(-r) reverses the order of the commands and the -flag tt(-n) suppresses command numbers when listing. +When the tt(-l) flag is given, the resulting events are listed on +standard output. Otherwise the editor program var(ename) is invoked on a +file containing these history events. If var(ename) is not given, the +value of the parameter tt(FCEDIT) is used; if that is not set the value of +the parameter tt(EDITOR) is used; if that is not set a builtin default, +usually `tt(vi)' is used. If var(ename) is `tt(-)', no editor is invoked. +When editing is complete, the edited command is executed. + +The flag tt(-r) reverses the order of the events and the +flag tt(-n) suppresses event numbers when listing. Also when listing, startsitem() -sitem(tt(-d))(prints timestamps for each command) +sitem(tt(-d))(prints timestamps for each event) sitem(tt(-f))(prints full time-date stamps in the US -`var(MM)tt(/)var(DD)tt(/)var(YY) var(hh):var(mm)' format) +`var(MM)tt(/)var(DD)tt(/)var(YY) var(hh)tt(:)var(mm)' format) sitem(tt(-E))(prints full time-date stamps in the European -`var(dd)tt(.)var(mm)tt(.)var(yyyy) var(hh):var(mm)' format) +`var(dd)tt(.)var(mm)tt(.)var(yyyy) var(hh)tt(:)var(mm)' format) sitem(tt(-i))(prints full time-date stamps in ISO8601 -`var(yyyy)tt(-)var(mm)tt(-)var(dd) var(hh):var(mm)' format) +`var(yyyy)tt(-)var(mm)tt(-)var(dd) var(hh)tt(:)var(mm)' format) sitem(tt(-t) var(fmt))(prints time and date stamps in the given format; var(fmt) is formatted with the strftime function with the zsh extensions described for the tt(%D{)var(string)tt(}) prompt format in ifzman(the section EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\ ifnzman(noderef(Prompt Expansion)). The resulting formatted string must be -no more than 256 characters or will not be printed. +no more than 256 characters or will not be printed ) sitem(tt(-D))(prints elapsed times; may be combined with one of the -options above.) +options above) endsitem() cindex(history, stack) cindex(stack, history) - `tt(fc -p)' pushes the current history list onto a stack and switches to a new history list. If the tt(-a) option is also specified, this history list will be automatically popped when the current function scope is exited, which @@ -791,11 +791,18 @@ Equivalent to tt(typeset -E), except that options irrelevant to floating point numbers are not permitted. ) findex(functions) -xitem(tt(functions) [ {tt(PLUS())|tt(-)}tt(UkmtTuz) ] [ var(name) ... ]) +xitem(tt(functions) [ {tt(PLUS())|tt(-)}tt(UkmtTuz) ] [ tt(-x) var(num) ] [ var(name) ... ]) xitem(tt(functions -M) var(mathfn) [ var(min) [ var(max) [ var(shellfn) ] ] ]) xitem(tt(functions -M) [ tt(-m) var(pattern) ... ]) item(tt(functions +M) [ tt(-m) ] var(mathfn) ... )( -Equivalent to tt(typeset -f), with the exception of the tt(-M) option. +Equivalent to tt(typeset -f), with the exception of the tt(-x) and +tt(-M) options. + +The tt(-x) option indicates that any functions output will have +each leading tab for indentation, added by the shell to show syntactic +structure, expanded to the given number var(num) of spaces. var(num) +can also be 0 to suppress all indentation. + Use of the tt(-M) option may not be combined with any of the options handled by tt(typeset -f). @@ -1106,7 +1113,7 @@ tt(popd) that do not change the environment seen by an interactive user. ) findex(print) xitem(tt(print )[ tt(-abcDilmnNoOpPrsSz) ] [ tt(-u) var(n) ] [ tt(-f) var(format) ] [ tt(-C) var(cols) ]) -item(SPACES()[ tt(-R) [ tt(-en) ]] [ var(arg) ... ])( +item(SPACES()[ tt(-xX) var(tab-stop) ] [ tt(-R) [ tt(-en) ]] [ var(arg) ... ])( With the `tt(-f)' option the arguments are printed as described by tt(printf). With no flags or with the flag `tt(-)', the arguments are printed on the standard output as described by tt(echo), with the following differences: @@ -1201,6 +1208,27 @@ tt(HIST_LEX_WORDS) option active. item(tt(-u) var(n))( Print the arguments to file descriptor var(n). ) +item(tt(-x) var(tab-stop))( +Expand leading tabs on each line of output in the printed string +assuming a tab stop every var(tab-stop) characters. This is appropriate +for formatting code that may be indented with tabs. Note that leading +tabs of any argument to print, not just the first, are expanded, even if +tt(print) is using spaces to separate arguments (the column count +is maintained across arguments but may be incorrect on output +owing to previous unexpanded tabs). + +The start of the output of each print command is assumed to be aligned +with a tab stop. Widths of multibyte characters are handled if the +option tt(MULTIBYTE) is in effect. This option is ignored if other +formatting options are in effect, namely column alignment or +tt(printf) style, or if output is to a special location such as shell +history or the command line editor. +) +item(tt(-X) var(tab-stop))( +This is similar to tt(-x), except that all tabs in the printed string +are expanded. This is appropriate if tabs in the arguments are +being used to produce a table format. +) item(tt(-z))( Push the arguments onto the editing buffer stack, separated by spaces. ) @@ -1699,10 +1727,10 @@ cindex(parameters, declaring) redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ ))ifnztexi( ))) xitem(tt(typeset )[ {tt(PLUS())|tt(-)}tt(AHUaghlmprtux) ] \ [ {tt(PLUS())|tt(-)}tt(EFLRZi) [ var(n) ] ]) -xitem(SPACES()[ tt(+) | var(name)[tt(=)var(value)] ... ]) +xitem(SPACES()[ tt(+) ] [ var(name)[tt(=)var(value)] ... ]) xitem(tt(typeset )tt(-T) [ {tt(PLUS())|tt(-)}tt(Uglprux) ] [ {tt(PLUS())|tt(-)}tt(LRZ) [ var(n) ] ]) -xitem(SPACES()[ tt(+) | var(SCALAR)[tt(=)var(value)] var(array) [ var(sep) ] ]) -item(tt(typeset) tt(-f) [ {tt(PLUS())|tt(-)}tt(TUkmtuz) ] [ tt(+) | var(name) ... ])( +xitem(SPACES()[ tt(+) | var(SCALAR)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(RPAR())] [ var(sep) ] ]) +item(tt(typeset) tt(-f) [ {tt(PLUS())|tt(-)}tt(TUkmtuz) ] [ tt(+) ] [ var(name) ... ])( Set or display attributes and values for shell parameters. A parameter is created for each var(name) that does not already refer @@ -1715,22 +1743,72 @@ ifnzman(noderef(Local Parameters))\ retain their special attributes when made local. For each var(name)tt(=)var(value) assignment, the parameter -var(name) is set to var(value). Note that arrays currently cannot be -assigned in tt(typeset) expressions, only scalars and integers. Unless -the option tt(KSH_TYPESET) is set, normal expansion rules apply to -assignment arguments, so var(value) may be split into separate words; if -the option is set, assignments which can be recognised when expansion is -performed are treated as single words. For example the command -tt(typeset vbl=$(echo one two)) is treated as having one argument if -tt(KSH_TYPESET) is set, but otherwise is treated as having the two arguments -tt(vbl=one) and tt(two). +var(name) is set to var(value). All forms of the command +handle scalar assignment. + +If any of the reserved words tt(declare), tt(export), tt(float), +tt(integer), tt(local), tt(readonly) or tt(typeset) is matched when the +line is parsed (N.B. not when it is executed) the shell will try to parse +arguments as assignments, except that the `tt(+=)' syntax and the +tt(GLOB_ASSIGN) option are not supported. This has two major differences +from normal command line argument parsing: array assignment is possible, +and scalar values after tt(=) are not split further into words even if +expanded (regardless of the setting of the tt(KSH_TYPESET) option; this +option is obsolete). Here is an example: + +example(# Reserved word parsing +typeset svar=$(echo one word) avar=(several words)) + +The above creates a scalar parameter tt(svar) and an array +parameter tt(avar) as if the assignments had been + +example(svar="one word" +avar=(several words)) + +On the other hand: + +example(# Normal builtin interface +builtin typeset svar=$(echo two words)) + +The tt(builtin) keyword causes the above to use the standard builtin +interface to tt(typeset) in which argument parsing is perfomed in the same +way as for other commands. This example creates a scalar tt(svar) +containing the value tt(two) and another scalar parameter tt(words) with +no value. An array value in this case would either cause an error or be +treated as an obscure set of glob qualifiers. + +Arbitrary arguments are allowed if they take the form of assignments +after command line expansion; however, these only perform scalar +assignment: + +example(var='svar=val' +typeset $var) + +The above sets the scalar parameter tt(svar) to the value tt(val). +Parentheses around the value within tt(var) would not cause array +assignment as they will be treated as ordinary characters when tt($var) +is substituted. Any non-trivial expansion in the name part of the +assignment causes the argument to be treated in this fashion: + +example(typeset {var1,var2,var3}=name) + +The above syntax is valid, and has the expected effect of setting the +three parameters to the same value, but the command line is parsed as +a set of three normal command line arguments to tt(typeset) after +expansion. Hence it is not possible to assign to multiple arrays by +this means. + +Note that each interface to any of the commands my be disabled +separately. For example, `tt(disable -r typeset)' disables the reserved +word interface to tt(typeset), exposing the builtin interface, while +`tt(disable typeset)' disables the builtin. If the shell option tt(TYPESET_SILENT) is not set, for each remaining -var(name) that refers to a parameter that is set, the name and value of the -parameter are printed in the form of an assignment. Nothing is printed for -newly-created parameters, or when any attribute flags listed below are -given along with the var(name). Using `tt(PLUS())' instead of minus to -introduce an attribute turns it off. +var(name) that refers to a parameter that is already set, the name and +value of the parameter are printed in the form of an assignment. +Nothing is printed for newly-created parameters, or when any attribute +flags listed below are given along with the var(name). Using +`tt(PLUS())' instead of minus to introduce an attribute turns it off. If no var(name) is present, the names and values of all parameters are printed. In this case the attribute flags restrict the display to only @@ -1801,7 +1879,7 @@ the current state, readonly specials (whose values cannot be changed) are not shown and assignments to arrays are shown before the tt(typeset) rendering the array readonly. ) -item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array) [ var(sep) ] ])( +item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(RPAR())] [ var(sep) ] ])( This flag has a different meaning when used with tt(-f); see below. Otherwise the tt(-T) option requires zero, two, or three arguments to be present. With no arguments, the list of parameters created in this @@ -1811,10 +1889,13 @@ together in the manner of tt($PATH) and tt($path). The optional third argument is a single-character separator which will be used to join the elements of the array to form the scalar; if absent, a colon is used, as with tt($PATH). Only the first character of the separator is significant; -any remaining characters are ignored. +any remaining characters are ignored. Multibyte characters are not +yet supported. + +Only one of the scalar and array parameters may be assigned an initial +value (the restrictions on assignment forms described above also apply). -Only the scalar parameter may be assigned an initial value. Both the -scalar and the array may otherwise be manipulated as normal. If one is +Both the scalar and the array may be manipulated as normal. If one is unset, the other will automatically be unset too. There is no way of untying the variables without unsetting them, nor of converting the type of one of them with another tt(typeset) command; tt(+T) does not work, @@ -1906,6 +1987,9 @@ function is first referenced; see noderef(Functions). The tt(-k) and tt(-z) flags make the function be loaded using ksh-style or zsh-style autoloading respectively. If neither is given, the setting of the tt(KSH_AUTOLOAD) option determines how the function is loaded. + +Note that the builtin tt(functions) provides the same basic capabilities +as tt(typeset -f) but gives access to a few extra options. ) item(tt(-h))( Hide: only useful for special parameters (those marked `<S>' in the table in @@ -2159,7 +2243,7 @@ the user is potentially interested in both, so this problem is intrinsic to process IDs. ) findex(whence) -item(tt(whence) [ tt(-vcwfpamsS) ] var(name) ...)( +item(tt(whence) [ tt(-vcwfpamsS) ] [ tt(-x) var(num) ] var(name) ...)( For each var(name), indicate how it would be interpreted if used as a command name. @@ -2212,14 +2296,19 @@ As tt(-s), but if the pathname had to be resolved by following multiple symlinks, the intermediate steps are printed, too. The symlink resolved at each step might be anywhere in the path. ) +item(tt(-x) var(num))( +Expand tabs when outputting shell functions using the tt(-c) option. +This has the same effect as the tt(-x) option to the tt(functions) +builtin. +) enditem() ) findex(where) -item(tt(where) [ tt(-wpmsS) ] var(name) ...)( +item(tt(where) [ tt(-wpmsS) ] [ tt(-x) var(num) ] var(name) ...)( Equivalent to tt(whence -ca). ) findex(which) -item(tt(which) [ tt(-wpamsS) ] var(name) ...)( +item(tt(which) [ tt(-wpamsS) ] [ tt(-x) var(num) ] var(name) ...)( Equivalent to tt(whence -c). ) findex(zcompile) |