Updated tBRegExp docs and tests (v1.9.0.0)

[GCuser99]

Closed all failures from tB docs test reporting
Updated/improved documentation
Updated test suite for new handling of failed searches

[KubaO]

Observations to address/respond to:

• The protection against runaway patterns is weaker now. The budget used to grow with the length of the string. It looks to me like now it grows with its square. So a pattern like (a+)+b gets far more steps before it is stopped. On 3,000 characters it now runs 90M steps where it used to run 15M. Your own test comment says about 25 seconds per 100M steps, so that is roughly 20 seconds of blocking before the error. On 30 characters it is still about a third of a second. The trade (no more giving up early on ordinary patterns, at the cost of slower giving up on bad ones) may be fine, but the pages only describe the benefit.

• “Finishes at any length a search is likely to be given” isn’t true it looks like. \d+x costs about 2.25 * n^2 steps, so it hits the 100M cap at about 6,700 characters. A 10 KB string raises the error. The next paragraph on the same page then tells the reader to set the limit when the cap is reached, which contradicts it.

• Three test checks can’t fail. In the *_KeepsNothing cases, the check m Is Nothing / s = "" / c Is Nothing always passes when the call raises, because the assignment never happens. Those checks test VB’s behaviour, not the package’s.

Nitpicks

• Two different cost figures are on one page. The text says \d+x on 1,000 digits needs about 2,250,000 steps. The quoted error message says about 3,000,000, and the “2,700 for thirty characters” figure is 3 * n^2. A reader sees two different numbers for the same search.

It looks like the tooling hasn't been ran, so there are some mechanical checks that fail:

• tbRegExp: the sample template references 1.8.0.0, the section documents 1.9.0.0
• tbRegExp: Sources/Expect.twin is a copy: the shared one is used
• tbRegExp: expect.json is for version 1.9.0.0, the section documents 1.8.0.0
• tbRegExp: Sources/RunAll.twin is out of date: run node scripts/package_tests.mjs tbRegExp
• test/example-projects/contributed-tbRegExp/Settings still names version 1.8. So examples.bat would compile the new samples against 1.8, and the SearchStepLimit ones would fail.
• The indexer snapshot wasn’t updated. indexer/snapshots/contributed/tbRegExp/api.json is still 1.8.0.0 (it still has SearchAborted and no SearchStepLimit), and builder/package-api.json wasn’t regenerated.
• test/package-tests/tbRegExp/tbRegExpTests.twinproj (41 KB) was committed by mistake. The build generates the published copy itself.

I will deal with the mechanical part myself, and write up exactly how to go about it in another comment.

[KubaO]

In check_run samples, the tooling runs the code and compares the output to what's in the comments. One of the comments reads ' 0 -- nothing left in Err, but the output is just 0.

Since such comments are helpful, the tooling will now ignore -- and everything after it in a check_run sample's comment.

[KubaO]

Tooling use:

Once per clone

1. Run npm install, then git config core.hooksPath .githooks.
2. Have the newest twinBASIC BETA installed as twinBASIC_IDE_BETA_<n> on the Desktop, or point the TB_IDE environment variable at it.

For each new version of the package

The authoring documentation is probably clear as mud on this, I apologize. For quick reference, here are the magical steps:

1. Publish the version to TWINSERV first. The tooling fetches the package from there.
2. Update the API snapshot and see what changed:

   node indexer/twin-index.mjs sync --package tbRegExp
   node indexer/twin-index.mjs analyze --package tbRegExp

   sync rewrites indexer/snapshots/contributed/tbRegExp/api.json. analyze lists the public symbols to add or remove, and the callouts labelled with the old version that need checking again. (It says "audit mode" until the new snapshot is committed; that's expected.)
3. Edit the pages. Bump indexed_from: and the **Version:** line on the landing page. Then move each callout's version label to the new version, or remove the callout if it no longer applies.
4. Bump the sample template's version in test/example-projects/contributed-tbRegExp/Settings (versionMajor, versionMinor, versionBuild, versionRevision).
5. Edit the test cases in test/package-tests/tbRegExp/Sources/:
   • Don't add Expect.twin; the shared copy is used.
   • Don't commit a .twinproj; the build makes the published one.
   • Don't edit RunAll.twin or expect.json by hand.
6. Run the cases on both architectures. This also rewrites RunAll.twin:

   package-tests.bat tbRegExp

   If a case now passes or fails differently, run it again with --update, which rewrites expect.json. Then read every entry it writes, because each one claims the package has a defect.
7. Run the samples:

   examples.bat --only "Contributed/tbRegExp"

8. Run the gates:

   build.bat && check.bat && test.bat

   If the build says the page baseline was raised, commit builder/page-baseline.json too.
9. Commit everything together: the pages, the snapshot, the template's Settings, the test sources, RunAll.twin, expect.json and the page baseline. Paste the examples.bat summary line into the pull request description.

I'm adding it as a checklist to docs/Documentation, so the next person will have an easier time. Again, my apologies.

[KubaO]

Merged in #239. I'd still appreciate your view of the 3 observations made.

[GCuser99]

I'll get back to you on your observations in a couple of days - I need a break! I can imagine that is true for you x 10! Thanks for your help.