Add Char generators

[pete-ts]

Overview

This unison pull request aims to add Generators in the base.test.v1.Char namespace.

All functions have documentation linked, as well as author and license. In lieu of test cases, the documentation contains the exhausted source'd outputs of each generator

Code review

pull-request.load https://github.com/unisonweb/base https://github.com/pete-ts/base:.prs.charGenerators

Added definitions:

 test.v1.gen.Char.alpha                     : '{Gen} Char (+3 metadata)
 test.v1.gen.Char.alpha.doc                 : Doc
 test.v1.gen.Char.alpha.sampled             : [Char]
 test.v1.gen.Char.ascii                     : '{Gen} Char (+3 metadata)
 test.v1.gen.Char.ascii.doc                 : Doc
 test.v1.gen.Char.ascii.sampled             : [Char]
 test.v1.gen.Char.asciiNonPrintable         : '{Gen} Char (+3 metadata)
 test.v1.gen.Char.asciiNonPrintable.doc     : Doc
 test.v1.gen.Char.asciiNonPrintable.sampled : [Char]
 test.v1.gen.Char.asciiPrintable            : '{Gen} Char (+3 metadata)
 test.v1.gen.Char.asciiPrintable.doc        : Doc
 test.v1.gen.Char.asciiPrintable.sampled    : [Char]
 test.v1.gen.Char.digit                     : '{Gen} Char (+3 metadata)
 test.v1.gen.Char.digit.doc                 : Doc
 test.v1.gen.Char.digit.sampled             : [Char]
 test.v1.gen.Char.hexDigit                  : '{Gen} Char (+3 metadata)
 test.v1.gen.Char.hexDigit.doc              : Doc (+1 metadata)
 test.v1.gen.Char.hexDigit.sampled          : [Char]
 test.v1.gen.Char.lower                     : '{Gen} Char (+3 metadata)
 test.v1.gen.Char.lower.doc                 : Doc
 test.v1.gen.Char.lower.sampled             : [Char]
 test.v1.gen.Char.upper                     : '{Gen} Char (+2 metadata)
 test.v1.gen.Char.upper.doc                 : Doc
 test.v1.gen.Char.upper.sampled             : [Char]

 patch test.v1.gen.Char.patch (added 14 updates)

[pchiusano]

@pete-ts sorry for delay reviewing. Code looks good but I spotted some missing license info - the examples and the docs are unlicensed and Gen.char.upper has an Author but no license. I'll fix this up when merging but just need your consent to do so, can you just reply and say: "I agree to license all the definitions listed in this PR with the MIT license", then I'll merge and fix things up.

Thanks!

[pete-ts]

"I agree to license all the definitions listed in this PR with the MIT license"

[pchiusano]

Okay, great! I merged in 8c92abcb which is Unison hash jhvodutal8ee1mf

A couple comments:

• I added Gen.append : '{Gen} a -> '{Gen} a -> '{Gen} a and used that in one place, get.Char.alpha but there might be some other places that could use it instead of assigning a cost to the thing you want to appear second (which is somewhat fragile).
• For the docs, no need to include the source unless the source is particularly short or insightful and makes for good docs. User can always do view to check out the source.
• For the docs, I'd avoid manually typing in the function name - that will become out of date if the function gets renamed or aliased. Instead, either avoid mentioning the function name, or use @ to reference the function directly. Example below for the Gen.append docs:

  test.v1.Gen.append.doc : Doc
  test.v1.Gen.append.doc =
    [: 
    `@Gen.append g1 g2` generates all values in `g1` then `g2`, for example:

      @[source] examples.ex1
      ↳ @[evaluate] examples.ex1

    When sampling from the resulting generator, if the number of samples is less than the number of
    samples needed to exhaust the first generator, the second generator is not consulted, for example:

      @[source] examples.ex2
      ↳ @[evaluate] examples.ex2
    :]

Renders as:

  `Gen.append g1 g2` generates all values in `g1` then `g2`, for example:

    test.v1.Gen.append.examples.ex1 = v1.sample 10 <| Gen.append (natIn 0 3) (natIn 3 5)
    ↳ [0, 1, 2, 3, 4]

  When sampling from the resulting generator, if the number of samples is less than the number of samples
  needed to exhaust the first generator, the second generator is not consulted, for example:

    test.v1.Gen.append.examples.ex2 = v1.sample 3 <| Gen.append (natIn 0 4) (natIn 100 130)
    ↳ [0, 1, 2]