From: Bart Schaefer <schaefer@brasslantern.com>
To: Zsh hackers list <zsh-workers@zsh.org>
Subject: [PATCH] Documentation for namespace syntax
Date: Sun, 5 Mar 2023 15:41:26 -0800 [thread overview]
Message-ID: <CAH+w=7Z3p5x3CiyXC6_zcVBaNXYC3rH6pN3-SApd7mf3R2QYFA@mail.gmail.com> (raw)
[-- Attachment #1: Type: text/plain, Size: 139 bytes --]
I wasn't sure how often to repeat that a leading dot suppresses output
in "set" et al., so it's only mentioned in params.yo at this point.
[-- Attachment #2: namespace-doc.txt --]
[-- Type: text/plain, Size: 3005 bytes --]
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index ef01794e6..19f5909ea 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -604,6 +604,16 @@ and other operators, such as `tt(${PREFIX:-"/usr/local"})'. Parameter
expansions can also be nested. These topics will be introduced below.
The full rules are complicated and are noted at the end.
+cindex(namespace)
+Parameter expansions may optionally include a em(namespace) prefix in
+the format `tt(.)var(identifier)tt(.)' This currently has no special
+meaning to the shell, but provides a convenient means of grouping
+related parameters. Expansions using a namespace em(must) include
+braces (tt({) and tt(})) as shown in the descriptions below, and
+only one namespace prefix is allowed. Note that, for support of
+possible future features, the first `tt(.)' is optional, but omitting
+it is discouraged.
+
In the expansions discussed below that require a pattern, the form of
the pattern is the same as that used for filename generation;
see noderef(Filename Generation). Note that these patterns, along with
@@ -616,6 +626,8 @@ substitution on the expansion of parameter tt($i).
In the following descriptions, `var(word)' refers to a single word
substituted on the command line, not necessarily a space delimited word.
+The reference to `var(name)' in each description presumes any optional
+namespace prefix.
startitem()
item(tt(${)var(name)tt(}))(
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 946c00793..528c27f93 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -52,6 +52,20 @@ cindex(assignment)
ifzman()
indent(var(name)tt(=)var(value))
+cindex(namespace)
+The var(name) in an assignment may optionally include a em(namespace)
+prefix:
+ifzman()
+indent(tt(.)var(namespace)tt(.)var(parameter)tt(=)var(value))
+
+Namespaces have no special meaning to the shell except that parameters
+with a `tt(.)' prefix are not listed by the `tt(set)' builtin, nor
+shown by the `tt(typeset)' builtin unless explicitly named or the
+`tt(-m)' option is used. They provide a convenient way to group
+related variables. Note that, for support of possible future features,
+the first `tt(.)' is optional, but omitting it is discouraged. Unlike
+ksh, a namespace need not be declared before it is referenced.
+
In scalar assignment, var(value) is expanded as a single string, in
which the elements of arrays are joined together; filename expansion is
not performed unless the option tt(GLOB_ASSIGN) is set.
@@ -70,7 +84,8 @@ change its type to integer or float, and with tt(GLOB_ASSIGN) assigning a
pattern to a variable may change its type to an array.
To reference the value of a parameter, write `tt($)var(name)' or
-`tt(${)var(name)tt(})'. See
+`tt(${)var(name)tt(})'. The latter form is required when var(name)
+includes a namespace prefix. See
ifzman(em(Parameter Expansion) in zmanref(zshexpn))\
ifnzman(noderef(Parameter Expansion))
for complete details. That section also explains the effect
reply other threads:[~2023-03-05 23:41 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAH+w=7Z3p5x3CiyXC6_zcVBaNXYC3rH6pN3-SApd7mf3R2QYFA@mail.gmail.com' \
--to=schaefer@brasslantern.com \
--cc=zsh-workers@zsh.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.vuxu.org/mirror/zsh/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).