Re: [PATCH 3/3] Documentation for named references

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Bart Schaefer wrote on Mon, Feb 06, 2023 at 19:25:03 -0800:
> On Mon, Feb 6, 2023 at 4:57 PM Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx> wrote:
> >
> > Bart Schaefer wrote on Sun, Feb 05, 2023 at 18:26:50 -0800:
> 
> > > +tt(-n).  The var(name) assigned-to may not be an array element nor use
> >
> > s/assigned-to/assigned to/
> 
> I did that on purpose to remove any ambiguity about what object "to" acts upon.

I see.

> I've used s/assigned-to/so created/

+1

> > > +When both a named reference and the `tt((P))' flag appear, the named
> > > +reference is resolved before `tt((P))' is applied.
> >
> > Add a test for this last sentence?
> 
> I can't think of a way to do so.  Given ${(P)ptr}, there are two possibilities:
> 1) ptr is a scalar, in which case we're not testing the right thing
> 2) ptr is a reference, so any other order of expansion is meaningless
> 

I'm not sure I follow what would be "meaningless" here.  I guess you
mean that ${(P)foo} requires foo to be a scalar's name and expands to
a list of words, so trying to expand ${(P)} first to a list of words and
then treating that as a nameref wouldn't be implementable.  Is that
what you mean?

Anyway, would it be worthwhile to add a few simple tests of the
combination of (P) and namerefs?  I have these:

 pointee=value
 typeset -n nr=pointee
 myscalar=nr
 echo ${(P)myscalar}
0:named references with (P), as ${(P)name_of_nameref}
*>value

 pointee=value
 myscalar=pointee
 typeset -n nr=myscalar
 echo ${(P)nr}
0:named references with (P), as ${(P)nameref}
*>value

(the asterisks are so MUAs don't treat the ">" as a quote)

> If ptr is a reference, a working test of ${ptr} implies that ${(P)ptr}
> also works. [...]

That doesn't seem to be the case in the following:

% ary=( 'bry[1]' 'bry[2]' )  
% bry=( lorem ipsum )
% typeset -n nr='ary[2]' 
% echo $nr
bry[2]
% echo ${(P)nr} 
zsh: bad substitution

I expected this to expand to "ipsum".

I also expected $nr and ${nr} to behave identically to each other, but:

% ary=( foo bar )
% typeset -n nr='ary[2]' 
% echo ${nr}
zsh: bad substitution
% echo $nr  
bar
% 

>


> > WDYT of documenting somewhere in the manual namerefs are new in 5.10?
> 
> I was going to add something to NEWS and README eventually ... also, I
> wasn't sure we'd landed on a version number yet.  I suppose (once we
> do) a mention wouldn't hurt since the docs are likely to end up on
> line.

That's one argument, yes.  Furthermore, I think stating version numbers
would be useful even in the locally-installed versions of the manual,
since someone might run a bleeding edge distro and write code that
targets LTS distros.

> > >  texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Local Parameters)(Parameters)
> > >  sect(Parameters Set By The Shell)
> >
> > s/Local Parameters/Named References/
> 
> Thanks, thought I'd caught all of those ... it was nice when the older
> version of yodl complained about those incorrect references.

The yodl macro is a thin wrapper around the texinfo macro.  Perhaps
texinfo warns about this somewhere in its output?