[PATCH] Add consistency to documentation and behavior of typeset builtins

[Philippe Altherr <philippe.altherr@xxxxxxxxx>]

This patch mainly adds consistency to the documentation of builtins of the 'typeset' family. It also includes a few small code changes to add consistency to the behavior of these builtins. Here is a more detailed list of the changes:

- Enables tagged named references. That's nothing particularly useful but it removes an unnecessary discrepancy between different types of parameters; parameters of any type can now be tagged.

- Removes '-f' from the supported flags of 'export'. Currently 'export -f' prints all functions, which doesn't make much sense given that 'export' is about marking parameters for export. Other function only flags, like '-k' or '-z' are already forbidden.

- Adds '-A' to the supported flags of 'export'. Arrays and associative arrays can be marked for export with 'typeset' but 'export' currently only supports the former.

- Removes '-f' from the supported flags of 'readonly'. Like for 'export', supporting '-f' doesn't make much sense.

- Adds support for '-p n' to 'readonly'. Currently 'readonly' only supports '-p' but not '-p 1', while all other builtins of the 'typeset' family support both.

- Adds support for '-H', '-h', '-n', '-p 1', '-t', and '+' options to 'nameref'. I added '-n' because 'integer' supports '-i', 'float' supports '-E', and ksh's 'nameref' supports '-n'. The other additions are for consistency with the other 'typeset' builtins and to reflect the latest changes.

- Documents that the '-m' option isn't supported by most of the 'typeset' builtins.

- Updates the 'float', 'integer', and 'nameref' synopses to match their implementations.

- Clears the 'local' synopsis to avoid duplicating three quarters of the 'typeset' synopsis. Synopses for 'declare' or 'readonly' already do the same.

Shouldn't 'nameref' support BINF_MAGICEQUALS and BINF_PSPECIAL like all the other 'typeset' builtins? Why that difference? What is the meaning of these flags?

- Add consistency to documentation and behavior of typeset builtins

Philippe

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 51c994e98..b31bb9ff6 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -706,10 +706,11 @@ for some possibly unexpected interactions
 of the tt(exit) command with jobs.
 )
 findex(export)
-item(tt(export) [ var(name)[tt(=)var(value)] ... ])(
-The specified var(name)s are marked for automatic export
+item(tt(export))(
+Same as `tt(typeset -gx)?, except that the tt(-m) option and ones
+irrelevant to exported parameters are not permitted.
+All specified parameters are marked for automatic export
 to the environment of subsequently executed commands.
-Equivalent to tt(typeset -gx).
 If a parameter specified does not
 already exist, it is created in the global scope.
 )
@@ -847,10 +848,11 @@ Bring each specified var(job) in turn to the foreground.
 If no var(job) is specified, resume the current job.
 )
 findex(float)
-item(tt(float) [ {tt(PLUS())|tt(-)}tt(Hghlprtux) ] \
-[ {tt(PLUS())|tt(-)}tt(EFLRZ) [ var(n) ] ] [ var(name)[tt(=)var(value)] ... ])(
-Equivalent to tt(typeset -E), except that options irrelevant to floating
-point numbers are not permitted.
+item(tt(float) [ {tt(PLUS())|tt(-)}tt(Hghlrtux) ] \
+[ {tt(PLUS())|tt(-)}tt(EFLRZp) [ var(n) ] ] \
+[ tt(+) ] [ var(name)[tt(=)var(value)] ... ])(
+Same as `tt(typeset -E)', except that the tt(-m) option and ones
+irrelevant to floating point numbers are not permitted.
 )
 findex(functions)
 xitem(tt(functions) [ {tt(PLUS())|tt(-)}tt(UkmtTuWz) ] [ tt(-x) var(num) ] [ var(name) ... ])
@@ -1092,10 +1094,11 @@ the form of a call to hash.
 )
 alias(history)(fc -l)
 findex(integer)
-item(tt(integer) [ {tt(PLUS())|tt(-)}tt(Hghlprtux) ] \
-[ {tt(PLUS())|tt(-)}tt(LRZi) [ var(n) ] ] [ var(name)[tt(=)var(value)] ... ])(
-Equivalent to tt(typeset -i), except that options irrelevant to
-integers are not permitted.
+item(tt(integer) [ {tt(PLUS())|tt(-)}tt(Hghlrtux) ] \
+[ {tt(PLUS())|tt(-)}tt(LRZip) [ var(n) ] ] \
+[ tt(+) ] [ var(name)[tt(=)var(value)] ... ])(
+Same as `tt(typeset -i)', except that the tt(-m) option and ones
+irrelevant to integers are not permitted.
 )
 findex(jobs)
 xitem(tt(jobs) [ tt(-dlprs) ] [ var(job) ... ])
@@ -1257,11 +1260,10 @@ shell starts in a mode emulating another shell.  It can be made available
 with the command `tt(zmodload -F zsh/rlimits b:limit)'.
 )
 findex(local)
-item(tt(local) [ {tt(PLUS())|tt(-)}tt(AHUahlprtux) ] \
-[ {tt(PLUS())|tt(-)}tt(EFLRZi) [ var(n) ] ] [ var(name)[tt(=)var(value)] ... ])(
-Same as tt(typeset), except that the options tt(-g), and
+item(tt(local))(
+Same as tt(typeset), except that the options tt(-g), tt(-m), and
 tt(-f) are not permitted.  In this case the tt(-x) option does not force
-the use of tt(-g), i.e. exported variables will be local to functions.
+the use of tt(-g), i.e., exported variables will be local to functions.
 )
 findex(logout)
 item(tt(logout) [ var(n) ])(
@@ -1632,8 +1634,9 @@ The tt(-c) or tt(-l) flags cancel any and all of tt(-kpquz).
 findex(readonly)
 cindex(parameters, marking readonly)
 item(tt(readonly))(
-Same as tt(typeset -r).  With the tt(POSIX_BUILTINS) option set, same
-as tt(typeset -gr).
+Same as `tt(typeset -r)' (`tt(typeset -gr)', with the
+tt(POSIX_BUILTINS) option set), except that the tt(-m) option and ones
+irrelevant to readonly parameters are not permitted.
 )
 alias(rehash)(hash -r)
 findex(return)
@@ -1920,7 +1923,7 @@ redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ ))ifnztexi(        )))
 xitem(tt(typeset )[ {tt(PLUS())|tt(-)}tt(AHUaghlmrtux) ] \
 [ {tt(PLUS())|tt(-)}tt(EFLRZip) [ var(n) ] ] \
 [ tt(+) ] [ var(name)[tt(=)var(value)] ... ])
-xitem(tt(typeset ){tt(PLUS())|tt(-)}tt(n) [ {tt(PLUS())|tt(-)}tt(Hghru) ] \
+xitem(tt(typeset ){tt(PLUS())|tt(-)}tt(n) [ {tt(PLUS())|tt(-)}tt(Hghrtu) ] \
 [ {tt(PLUS())|tt(-)}tt(p) [ var(n) ] ] \
 [ tt(+) ] [ var(name)[tt(=)var(value)] ... ])
 xitem(tt(typeset )tt(-T) [ {tt(PLUS())|tt(-)}tt(Uglrux) ] [ {tt(PLUS())|tt(-)}tt(LRZp) [ var(n) ] ])
diff --git a/Doc/Zsh/mod_ksh93.yo b/Doc/Zsh/mod_ksh93.yo
index a99592c8e..3fe366fd6 100644
--- a/Doc/Zsh/mod_ksh93.yo
+++ b/Doc/Zsh/mod_ksh93.yo
@@ -12,8 +12,11 @@ The single builtin provided by this module is:
 startitem()
 findex(nameref)
 cindex(named references, creating)
-item(tt(nameref) [ tt(-gpur) ] var(pname)[tt(=)var(rname)])(
-Equivalent to tt(typeset -n )var(pname)tt(=)var(rname)
+item(tt(nameref )[ {tt(PLUS())|tt(-)}tt(Hghnrtu) ] \
+[ {tt(PLUS())|tt(-)}tt(p) [ var(n) ] ] \
+[ tt(+) ] [ var(pname)[tt(=)var(rname)] ... ])(
+Same as `tt(typeset -n)', except that the tt(-m) option and ones
+irrelevant to named references are not permitted.
 
 However, tt(nameref) is a builtin command rather than a reserved word,
 so handling of assigments in the argument list may differ.
diff --git a/Src/Modules/ksh93.c b/Src/Modules/ksh93.c
index 5204ab8cc..6d1d15e04 100644
--- a/Src/Modules/ksh93.c
+++ b/Src/Modules/ksh93.c
@@ -38,7 +38,7 @@
  */
 
 static struct builtin bintab[] = {
-    BUILTIN("nameref", BINF_ASSIGN, (HandlerFunc)bin_typeset, 0, -1, 0, "gpru", "n")
+    BUILTIN("nameref", BINF_PLUSOPTS | BINF_ASSIGN, (HandlerFunc)bin_typeset, 0, -1, 0, "Hghnp:%rtu", "n")
 };
 
 #include "zsh.mdh"
diff --git a/Src/builtin.c b/Src/builtin.c
index 64a27511f..586f7cffc 100644
--- a/Src/builtin.c
+++ b/Src/builtin.c
@@ -64,7 +64,7 @@ static struct builtin builtins[] =
     BUILTIN("enable", 0, bin_enable, 0, -1, BIN_ENABLE, "afmprs", NULL),
     BUILTIN("eval", BINF_PSPECIAL, bin_eval, 0, -1, BIN_EVAL, NULL, NULL),
     BUILTIN("exit", BINF_PSPECIAL, bin_break, 0, 1, BIN_EXIT, NULL, NULL),
-    BUILTIN("export", BINF_PLUSOPTS | BINF_MAGICEQUALS | BINF_PSPECIAL | BINF_ASSIGN, (HandlerFunc)bin_typeset, 0, -1, BIN_EXPORT, "E:%F:%HL:%R:%TUZ:%afhi:%lp:%rtu", "xg"),
+    BUILTIN("export", BINF_PLUSOPTS | BINF_MAGICEQUALS | BINF_PSPECIAL | BINF_ASSIGN, (HandlerFunc)bin_typeset, 0, -1, BIN_EXPORT, "AE:%F:%HL:%R:%TUZ:%ahi:%lp:%rtu", "xg"),
     BUILTIN("false", 0, bin_false, 0, -1, 0, NULL, NULL),
     /*
      * We used to behave as if the argument to -e was optional.
@@ -107,7 +107,7 @@ static struct builtin builtins[] =
     BUILTIN("pwd", 0, bin_pwd, 0, 0, 0, "rLP", NULL),
     BUILTIN("r", 0, bin_fc, 0, -1, BIN_R, "IlLnr", NULL),
     BUILTIN("read", 0, bin_read, 0, -1, 0, "cd:ek:%lnpqrst:%zu:AE", NULL),
-    BUILTIN("readonly", BINF_PLUSOPTS | BINF_MAGICEQUALS | BINF_PSPECIAL | BINF_ASSIGN, (HandlerFunc)bin_typeset, 0, -1, BIN_READONLY, "AE:%F:%HL:%R:%TUZ:%afghi:%lptux", "r"),
+    BUILTIN("readonly", BINF_PLUSOPTS | BINF_MAGICEQUALS | BINF_PSPECIAL | BINF_ASSIGN, (HandlerFunc)bin_typeset, 0, -1, BIN_READONLY, "AE:%F:%HL:%R:%TUZ:%aghi:%lp:%tuxn", "r"),
     BUILTIN("rehash", 0, bin_hash, 0, 0, 0, "df", "r"),
     BUILTIN("return", BINF_PSPECIAL, bin_break, 0, 1, BIN_RETURN, NULL, NULL),
     BUILTIN("set", BINF_PSPECIAL | BINF_HANDLES_OPTS, bin_set, 0, -1, 0, NULL, NULL),
@@ -2711,14 +2711,14 @@ bin_typeset(char *name, char **argv, LinkList assigns, Options ops, int func)
 	else
 	    continue;
 	if (OPT_MINUS(ops,'n')) {
-	    if (bit & ~(PM_READONLY|PM_UPPER|PM_HIDEVAL|PM_HIDE)) {
+	    if (bit & ~(PM_READONLY|PM_UPPER|PM_HIDEVAL|PM_HIDE|PM_TAGGED)) {
 		zwarnnam(name, "-%c not allowed with -n", optval);
 		/* return 1; */
 	    }
 	}
     }
     if (OPT_MINUS(ops,'n')) {
-	if ((on|off) & ~(PM_READONLY|PM_UPPER|PM_HIDEVAL|PM_HIDE)) {
+	if ((on|off) & ~(PM_READONLY|PM_UPPER|PM_HIDEVAL|PM_HIDE|PM_TAGGED)) {
 	    /* zwarnnam(name, "no other attributes allowed with -n"); */
 	    return 1;
 	}