Read/write table data to a file

[jmfayard]

Resolves #3179

See the discussion in the README

I'm starting with readme-oriented programming, documenting how the end result should look like to make sure it makes sense.

Update 1st september needs refactoring but most features are there I think.

Documentation needs updates:

• it's now file.writeTable(headers, rows) and only works for RowN<String, String, ..., String>
• use table.mapRows { } if you are using RowN with types other than String
• map.toTable() is a quick way to produce a table from a map
• table(headers, list.map { row(...) }) is a quick way to produce a table from a list

[jmfayard]

@Kantis probably need some refactoring and handle variants with 20 generic types, but I think I cover the main use cases now. ouch was lots of work :)

[Kantis]

Nice work! 🤘 Added various suggestions. Would like a third pair of eyes on this once it's ready 👀

[Kantis]

Would it make sense to throw IllegalArgumentExceptions instead? No assertion has been made at this point, I think?

[jmfayard]

you can decide. Personally I don't like exceptions since they don't work well with assertSoftly for example.

   test("invalid file") {
      val file = resourcesDir.resolve("invalid.table") 
      val table = table(headers, file, transform) // implicit assertion that the file exists
      table shouldBe expectedTable
   }

[Kantis]

I think there's a difference between an assertion (E.g. validating the output of production code) and a bug in test code. IMO this AssertionError would indicate a fault in the test code, not the main code and I think the distinction is clearer when output as an exception. What do you think?

[jmfayard]

@Kantis Would like a third pair of eyes on this once it's ready 👀

It's ready-ish now.
I just added the versions with 1 to 9 generic arguments. Fun :)
Who can provide a third pair of eyes?

Also

• The CI is still in mode 2 workflows awaiting approval
• locally ./gradlew allTests throws an error org.gradle.api.GradleException: Could not evaluate onlyIf predicate for task ':kotest-common:jsIrGenerateExternalsIntegrated'. which doesn't seems related to anything I did

[sksamuel]

@Kantis I'm happy if you are.

[Kantis]

There's a chance we'll try to get #3264 out tonight, so disabled auto-merge for now.

[Kantis]

Thanks @jmfayard 💯

[jmfayard]

amazing, thanks!

[polarene]

This is a very cool feature, why isn't it documented? I stumbled upon it randomly while digging through the source code.

[Kantis]

@polarene It was documented but only in the 5.4 version of the docs. Fixed in 7b29815

[polarene]

Thank you! I found out about it because I was trying to come up with something similar, either using Markdown tables or with a DSL (I did a nice hack but it doesn't work if the first value is a number, due to standard lib operators).

But is the page released? Still can't find it in the docs... maybe the index needs to be updated as well?

[polarene]

Mhh yes, it seems to be missing from these sidebar files:

kotest/documentation/versioned_sidebars/version-5.8-sidebars.json

Line 48 in 7b29815

"assertions": [