mirror of
https://github.com/zsh-users/zsh
synced 2024-10-14 03:42:34 +00:00
45183: Improve documentation examples
This commit is contained in:
Stephane Chazelas
dana
parent
ac964897f4
commit
da19b67388
|
|
@ -1,3 +1,8 @@
|
|||
2020-01-01 dana <dana@dana.is>
|
||||
|
||||
* Stephane: 45183: Doc/Zsh/builtins.yo, Doc/Zsh/contrib.yo,
|
||||
Doc/Zsh/expn.yo: Improve documentation examples
|
||||
|
||||
2020-01-01 Daniel Shahaf <danielsh@apache.org>
|
||||
|
||||
* unposted: Test/D04parameter.ztst: Add some tests for ${(S)},
|
||||
|
|
|
|||
|
|
@ -39,11 +39,11 @@ be familiar to most command line users.
|
|||
|
||||
Typically, options are single letters preceded by a hyphen (tt(-)).
|
||||
Options that take an argument accept it either immediately following the
|
||||
option letter or after white space, for example `tt(print -C3 *)' or
|
||||
`tt(print -C 3 *)' are equivalent. Arguments to options are not the
|
||||
option letter or after white space, for example `tt(print -C3 {1..9})' or
|
||||
`tt(print -C 3 {1..9})' are equivalent. Arguments to options are not the
|
||||
same as arguments to the command; the documentation indicates which is
|
||||
which. Options that do not take an argument may be combined in a single
|
||||
word, for example `tt(print -ca *)' and `tt(print -c -a *)' are
|
||||
word, for example `tt(print -rca -- *)' and `tt(print -r -c -a -- *)' are
|
||||
equivalent.
|
||||
|
||||
Some shell builtin commands also take options that begin with `tt(+)'
|
||||
|
|
@ -54,14 +54,14 @@ Options (together with their individual arguments, if any) must appear
|
|||
in a group before any non-option arguments; once the first non-option
|
||||
argument has been found, option processing is terminated.
|
||||
|
||||
All builtin commands other than precommand modifiers, even those that
|
||||
have no options, can be given the argument `tt(-)tt(-)' to terminate option
|
||||
processing. This indicates that the following words are non-option
|
||||
arguments, but is otherwise ignored. This is useful in cases where
|
||||
arguments to the command may begin with `tt(-)'. For historical
|
||||
reasons, most builtin commands also recognize a single `tt(-)' in a
|
||||
separate word for this purpose; note that this is less standard and
|
||||
use of `tt(-)tt(-)' is recommended.
|
||||
All builtin commands other than `tt(echo)' and precommand modifiers,
|
||||
even those that have no options, can be given the argument `tt(-)tt(-)'
|
||||
to terminate option processing. This indicates that the following words
|
||||
are non-option arguments, but is otherwise ignored. This is useful in
|
||||
cases where arguments to the command may begin with `tt(-)'. For
|
||||
historical reasons, most builtin commands (including `tt(echo)') also
|
||||
recognize a single `tt(-)' in a separate word for this purpose; note
|
||||
that this is less standard and use of `tt(-)tt(-)' is recommended.
|
||||
|
||||
startitem()
|
||||
prefix(-)
|
||||
|
|
@ -114,9 +114,9 @@ var(text) is any non-empty string, it is replaced by the text
|
|||
a literal string, not a pattern. A trailing space in var(value) is not
|
||||
special in this case. For example,
|
||||
|
||||
example(alias -s ps=gv)
|
||||
example(alias -s ps='gv --')
|
||||
|
||||
will cause the command `tt(*.ps)' to be expanded to `tt(gv *.ps)'. As
|
||||
will cause the command `tt(*.ps)' to be expanded to `tt(gv -- *.ps)'. As
|
||||
alias expansion is carried out earlier than globbing, the `tt(*.ps)' will
|
||||
then be expanded. Suffix aliases constitute a different name space from
|
||||
other aliases (so in the above example it is still possible
|
||||
|
|
@ -1258,7 +1258,10 @@ If given together with tt(-o) or tt(-O), sorting is performed
|
|||
case-independently.
|
||||
)
|
||||
item(tt(-l))(
|
||||
Print the arguments separated by newlines instead of spaces.
|
||||
Print the arguments separated by newlines instead of spaces. Note: if
|
||||
the list of arguments is empty, tt(print -l) will still output one empty
|
||||
line. To print a possibly-empty list of arguments one per line, use
|
||||
tt(print -C1), as in `tt(print -rC1 -- "$list[@]")'.
|
||||
)
|
||||
item(tt(-m))(
|
||||
Take the first argument as a pattern (should be quoted), and remove
|
||||
|
|
@ -1269,7 +1272,9 @@ item(tt(-n))(
|
|||
Do not add a newline to the output.
|
||||
)
|
||||
item(tt(-N))(
|
||||
Print the arguments separated and terminated by nulls.
|
||||
Print the arguments separated and terminated by nulls. Again,
|
||||
tt(print -rNC1 -- "$list[@]") is a canonical way to print an
|
||||
arbitrary list as null-delimited records.
|
||||
)
|
||||
item(tt(-o))(
|
||||
Print the arguments sorted in ascending order.
|
||||
|
|
|
|||
|
|
@ -4418,24 +4418,28 @@ the elements from the tt(input) list in each run. If no var(command) is
|
|||
provided, then no var(arg) list may be provided, and in that event the
|
||||
default command is `tt(print)' with arguments `tt(-r -)tt(-)'.
|
||||
|
||||
For example, to get a long tt(ls) listing of all plain files in the
|
||||
current directory or its subdirectories:
|
||||
For example, to get a long tt(ls) listing of all non-hidden plain files
|
||||
in the current directory or its subdirectories:
|
||||
|
||||
example(autoload -U zargs
|
||||
zargs -- **/*(.) -- ls -l)
|
||||
zargs -- **/*(.) -- ls -ld --)
|
||||
|
||||
Note that `tt(-)tt(-)' is used both to mark the end of the var(option)
|
||||
list and to mark the end of the var(input) list, so it must appear twice
|
||||
whenever the var(input) list may be empty. If there is guaranteed to be
|
||||
at least one var(input) and the first var(input) does not begin with a
|
||||
`tt(-)', then the first `tt(-)tt(-)' may be omitted.
|
||||
The first and third occurrences of `tt(-)tt(-)' are used to mark the end
|
||||
of options for tt(zargs) and tt(ls) respectively to guard against
|
||||
filenames starting with `tt(-)', while the second is used to separate the
|
||||
list of files from the command to run (`tt(ls -ld --)').
|
||||
|
||||
The first `tt(-)tt(-)' would also be needed if there was a chance the
|
||||
list might be empty as in:
|
||||
|
||||
example(zargs -r -- ./*.back(#qN) -- rm -f)
|
||||
|
||||
In the event that the string `tt(-)tt(-)' is or may be an var(input), the
|
||||
tt(-e) option may be used to change the end-of-inputs marker. Note that
|
||||
this does em(not) change the end-of-options marker. For example, to use
|
||||
`tt(..)' as the marker:
|
||||
|
||||
example(zargs -e.. -- **/*(.) .. ls -l)
|
||||
example(zargs -e.. -- **/*(.) .. ls -ld --)
|
||||
|
||||
This is a good choice in that example because no plain file can be named
|
||||
`tt(..)', but the best end-marker depends on the circumstances.
|
||||
|
|
|
|||
|
|
@ -400,7 +400,7 @@ backslashes.
|
|||
For example, the following piece of filename generation code
|
||||
with the tt(EXTENDED_GLOB) option:
|
||||
|
||||
example(print *.c+LPAR()#q:s/#%+LPAR()#b+RPAR()s+LPAR()*+RPAR().c/'S${match[1]}.C'/+RPAR())
|
||||
example(print -r -- *.c+LPAR()#q:s/#%+LPAR()#b+RPAR()s+LPAR()*+RPAR().c/'S${match[1]}.C'/+RPAR())
|
||||
|
||||
takes the expansion of tt(*.c) and applies the glob qualifiers in the
|
||||
tt(LPAR()#q)var(...)tt(RPAR()) expression, which consists of a substitution
|
||||
|
|
@ -2522,11 +2522,11 @@ therefore matches files in the current directory as well as
|
|||
subdirectories.
|
||||
Thus:
|
||||
|
||||
example(ls (*/)#bar)
|
||||
example(ls -ld -- (*/)#bar)
|
||||
|
||||
or
|
||||
|
||||
example(ls **/bar)
|
||||
example(ls -ld -- **/bar)
|
||||
|
||||
does a recursive directory search for files named `tt(bar)' (potentially
|
||||
including the file `tt(bar)' in the current directory). This form does not
|
||||
|
|
@ -2541,11 +2541,11 @@ they are treated as if both a tt(/) plus a further tt(*) are present.
|
|||
Hence:
|
||||
|
||||
example(setopt GLOBSTARSHORT
|
||||
ls **.c)
|
||||
ls -ld -- **.c)
|
||||
|
||||
is equivalent to
|
||||
|
||||
example(ls **/*.c)
|
||||
example(ls -ld -- **/*.c)
|
||||
subsect(Glob Qualifiers)
|
||||
cindex(globbing, qualifiers)
|
||||
cindex(qualifiers, globbing)
|
||||
|
|
@ -2737,7 +2737,7 @@ appropriate test. For example,
|
|||
|
||||
example(nt+LPAR()RPAR() { [[ $REPLY -nt $NTREF ]] }
|
||||
NTREF=reffile
|
||||
ls -l *(+nt))
|
||||
ls -ld -- *(+nt))
|
||||
|
||||
lists all files in the directory that have been modified more recently than
|
||||
tt(reffile).
|
||||
|
|
@ -2928,36 +2928,36 @@ is performed, although note that the presence of the parentheses
|
|||
causes the entire expression to be subjected to any global pattern matching
|
||||
options such as tt(NULL_GLOB). Thus:
|
||||
|
||||
example(ls *(-/))
|
||||
example(ls -ld -- *(-/))
|
||||
|
||||
lists all directories and symbolic links that point to directories,
|
||||
and
|
||||
|
||||
example(ls *(-@))
|
||||
example(ls -ld -- *(-@))
|
||||
|
||||
lists all broken symbolic links, and
|
||||
|
||||
example(ls *(%W))
|
||||
example(ls -ld -- *(%W))
|
||||
|
||||
lists all world-writable device files in the current directory, and
|
||||
|
||||
example(ls *(W,X))
|
||||
example(ls -ld -- *(W,X))
|
||||
|
||||
lists all files in the current directory that are
|
||||
world-writable or world-executable, and
|
||||
|
||||
example(echo /tmp/foo*(u0^@:t))
|
||||
example(print -rC1 /tmp/foo*(u0^@:t))
|
||||
|
||||
outputs the basename of all root-owned files beginning with the string
|
||||
`tt(foo)' in tt(/tmp), ignoring symlinks, and
|
||||
|
||||
example(ls *.*~(lex|parse).[ch](^D^l1))
|
||||
example(ls -ld -- *.*~(lex|parse).[ch](^D^l1))
|
||||
|
||||
lists all files having a link count of one whose names contain a dot
|
||||
(but not those starting with a dot, since tt(GLOB_DOTS) is explicitly
|
||||
switched off) except for tt(lex.c), tt(lex.h), tt(parse.c) and tt(parse.h).
|
||||
|
||||
example(print b*.pro+LPAR()#q:s/pro/shmo/+RPAR()(#q.:s/builtin/shmiltin/))
|
||||
example(print -rC1 b*.pro+LPAR()#q:s/pro/shmo/+RPAR()(#q.:s/builtin/shmiltin/))
|
||||
|
||||
demonstrates how colon modifiers and other qualifiers may be chained
|
||||
together. The ordinary qualifier `tt(.)' is applied first, then the colon
|
||||
|
|
|
|||
Loading…
Reference in a new issue