[PATCH 0/1] zsh/random module

[PATCH 0/1] zsh/random module

[Clinton Bunch]

This is a resurrection of a module to provide an interface into the 
kernel random pool for the shell.

It provides a ro parameter SRANDOM (32-bit random integer)

It provides 2 math functions zrand_float() and zrand_int

zrand_int takes 0-3 arguments, an exclusive upper bound, a lower bound, 
a flag to make the upper bound inclusive.  It is equivalent to SRANDOM 
with no arguments.

zrand_float takes no arguments and returns a floating point number 
between 0 and 1, inclusive.

I am still working on the test harness.  I'm thinking about using a C 
program for analysis of shell output, but no current test harness does 
anything like that.  (long double would really be helpful for larger 
bounds, 1-20 works, 1-100 causes overflows)

This version has no builtins.  Though I still think some could be 
useful, I have to admit that what I have in mind for them *can* be 
accomplished in shell by someone with moderate experience, if less 
efficiently.

Re: [PATCH 0/1] zsh/random module

[Bart Schaefer]

On Sun, Mar 24, 2024 at 7:11 AM Clinton Bunch <cdb_zsh@zentaur.org> wrote:
>
> zrand_int takes 0-3 arguments, an exclusive upper bound, a lower bound,
> a flag to make the upper bound inclusive.

Documentation remarks:

+optional.  If none are specified it is equivilent to

Typo: "equivalent'

+tt(inclusive) is a flag to determine whether the result can ever equal
+tt(upper).  By default it can not. If this argument is set to a non-zero value
+then it can.

Something about the use of "can" in those sentences strikes me as odd.
  a flag that controls whether the result is ever equal to
  by default it is not
  then it may be
??

+possible return values 0-15, in order to use it as an array index which goes
+from 1-16 you need to add one.  Since it can return zero, you don't want it
+to return 16.

It took me a few re-readings to figure out that "16" is meant as an
example result of $#a from the previous two expressions.  The switch
to addressing the reader as in "you need" / "you don't want" threw me
off.  Perhaps adding:
  For example, if $#a is 16,
and then end sentence and start again:
  values 0-15.  Thus in order
I might also change "Since" to "Because".

Re: [PATCH 0/1] zsh/random module

[Clinton Bunch]

On 3/24/2024 21:34, Bart Schaefer wrote:
> On Sun, Mar 24, 2024 at 7:11 AM Clinton Bunch <cdb_zsh@zentaur.org> wrote:
>> zrand_int takes 0-3 arguments, an exclusive upper bound, a lower bound,
>> a flag to make the upper bound inclusive.
> Documentation remarks:
>
> +optional.  If none are specified it is equivilent to
>
> Typo: "equivalent'
>
> +tt(inclusive) is a flag to determine whether the result can ever equal
> +tt(upper).  By default it can not. If this argument is set to a non-zero value
> +then it can.
>
> Something about the use of "can" in those sentences strikes me as odd.
>    a flag that controls whether the result is ever equal to
>    by default it is not
>    then it may be
> ??
>
> +possible return values 0-15, in order to use it as an array index which goes
> +from 1-16 you need to add one.  Since it can return zero, you don't want it
> +to return 16.
>
> It took me a few re-readings to figure out that "16" is meant as an
> example result of $#a from the previous two expressions.  The switch
> to addressing the reader as in "you need" / "you don't want" threw me
> off.  Perhaps adding:
>    For example, if $#a is 16,
> and then end sentence and start again:
>    values 0-15.  Thus in order
> I might also change "Since" to "Because".
>
Does this work better:

tt(inclusive) is a flag that controls whether the result is ever equal to
tt(upper).  By default it is not. If this argument is set to a non-zero 
value
then it may be.

This is to facilitate a construct like tt($a[zrand_int($#a)+1]) rather
than tt($a[zrand_int+LPAR()$#a-1+RPAR()+1]).
For example, if $#a is 16, you would use tt(zrand_int+LPAR()16RPAR()) 
which has
16 possible return values 0-15, in order to use it as an array index 
which goes
from 1-16 you need to add one.  Because the function can return zero, it 
would
be an array index range error for it to also potentially return 16 
($#a). You
could, however, use the construct tt(zrand_int+LPAR()16,1,1+RPAR()) 
instead of
adding 1 to achieve the same result, but it is more verbose.

Most statistics algorithms seem to also expect 0 to tt(upper)-1, so this was
deemed the most commonly desired case and chosen as the default.

Re: [PATCH 0/1] zsh/random module

[Clinton Bunch]

On 3/26/2024 07:47, Clinton Bunch wrote:
> On 3/24/2024 21:34, Bart Schaefer wrote:
>> On Sun, Mar 24, 2024 at 7:11 AM Clinton Bunch <cdb_zsh@zentaur.org> 
>> wrote:
>>> zrand_int takes 0-3 arguments, an exclusive upper bound, a lower bound,
>>> a flag to make the upper bound inclusive.
>> Documentation remarks:
>>
>> +optional.  If none are specified it is equivilent to
>>
>> Typo: "equivalent'
>>
>> +tt(inclusive) is a flag to determine whether the result can ever equal
>> +tt(upper).  By default it can not. If this argument is set to a 
>> non-zero value
>> +then it can.
>>
>> Something about the use of "can" in those sentences strikes me as odd.
>>    a flag that controls whether the result is ever equal to
>>    by default it is not
>>    then it may be
>> ??
>>
>> +possible return values 0-15, in order to use it as an array index 
>> which goes
>> +from 1-16 you need to add one.  Since it can return zero, you don't 
>> want it
>> +to return 16.
>>
>> It took me a few re-readings to figure out that "16" is meant as an
>> example result of $#a from the previous two expressions.  The switch
>> to addressing the reader as in "you need" / "you don't want" threw me
>> off.  Perhaps adding:
>>    For example, if $#a is 16,
>> and then end sentence and start again:
>>    values 0-15.  Thus in order
>> I might also change "Since" to "Because".
>>
> Does this work better:
>
> tt(inclusive) is a flag that controls whether the result is ever equal to
> tt(upper).  By default it is not. If this argument is set to a 
> non-zero value
> then it may be.
>
> This is to facilitate a construct like tt($a[zrand_int($#a)+1]) rather
> than tt($a[zrand_int+LPAR()$#a-1+RPAR()+1]).
> For example, if $#a is 16, you would use tt(zrand_int+LPAR()16RPAR()) 
> which has
> 16 possible return values 0-15, in order to use it as an array index 
> which goes
> from 1-16 you need to add one.  Because the function can return zero, 
> it would
> be an array index range error for it to also potentially return 16 
> ($#a). You
> could, however, use the construct tt(zrand_int+LPAR()16,1,1+RPAR()) 
> instead of
> adding 1 to achieve the same result, but it is more verbose.
>
> Most statistics algorithms seem to also expect 0 to tt(upper)-1, so 
> this was
> deemed the most commonly desired case and chosen as the default.
>
>
Also added a statement that the default values of upper and lower are 
also their limits.

tt(upper) is the upper bound on the resultant number and defaults to
4,294,967,295.

tt(lower) is the lower bound and defaults to 0.

The defaults of these two arguments are also the maximum and minimum to 
which
either can be set.

Re: [PATCH 0/1] zsh/random module

[Bart Schaefer]

On Tue, Mar 26, 2024 at 5:47 AM Clinton Bunch <cdb_zsh@zentaur.org> wrote:
>
> Does this work better:
>
> tt(inclusive) is a flag that controls whether the result is ever equal to
> tt(upper).  By default it is not. If this argument is set to a non-zero
> value
> then it may be.

Fine.

> For example, if $#a is 16, you would use tt(zrand_int+LPAR()16RPAR())
> which has
> 16 possible return values 0-15, in order to use it as an array index
> which goes
> from 1-16 you need to add one.  Because the function can return zero, it
> would
> be an array index range error for it to also potentially return 16
> ($#a).

I probably spot-checked this one incorrectly.  I was looking for something like:

 ... which has 16 possible return values 0-15.  Because the function can return
 zero, in order to use it as an array index from 1-16 you need to add one.  It
 would be an array index range error for it to also potentially return 16
 (tt($#a)).

> You
> could, however, use the construct tt(zrand_int+LPAR()16,1,1+RPAR())
> instead of
> adding 1 to achieve the same result, but it is more verbose.

Sure.

> Most statistics algorithms seem to also expect 0 to tt(upper)-1, so this was
> deemed the most commonly desired case and chosen as the default.

Also fine.

Re: [PATCH 0/1] zsh/random module

[Clinton Bunch]

On 3/24/2024 09:11, Clinton Bunch wrote:
>
>
> I am still working on the test harness.  I'm thinking about using a C 
> program for analysis of shell output, but no current test harness does 
> anything like that.  (long double would really be helpful for larger 
> bounds, 1-20 works, 1-100 causes overflows)
>
I'm struggling with a test for this module.  I thought about doing a 
statistical analysis (chi-square) of output, but I can't get a 
successful p-value nearly 10% of the time.  I tried doing the same with 
return values from the base library functions and got similar bias, so 
it appears I'd just be testing the randomness of the kernel PRNG rather 
than compilation of code.

Anyone else have any ideas?

Re: [PATCH 0/1] zsh/random module

[Clinton Bunch]

On 4/5/2024 21:41, Clinton Bunch wrote:
> On 3/24/2024 09:11, Clinton Bunch wrote:
>>
>>
>> I am still working on the test harness.  I'm thinking about using a C 
>> program for analysis of shell output, but no current test harness 
>> does anything like that.  (long double would really be helpful for 
>> larger bounds, 1-20 works, 1-100 causes overflows)
>>
> I'm struggling with a test for this module.  I thought about doing a 
> statistical analysis (chi-square) of output, but I can't get a 
> successful p-value nearly 10% of the time.  I tried doing the same 
> with return values from the base library functions and got similar 
> bias, so it appears I'd just be testing the randomness of the kernel 
> PRNG rather than compilation of code.
>
> Anyone else have any ideas?
>
>
>
Another question:  The math function names.

Would something like srandom_int and srandom_float be better to show the 
association with the SRANDOM parameter?

Or maybe call the parameter ZRANDOM with SRANDOM as an alias for Bash 
compatibility?