Convert Examples into Rescript Syntax

[Lomand]

Code examples converted to Rescript syntax, following these guidelines:

• Native-specific documentation is removed
• Data is moved from the last to the first argument
• prints are replaced with Js.logs
• native-only functions are removed
• All infix operators replaced with regular functions since Rescript heavily discorages them.

All samples were compiled and executed, and it turns out there are a ton of errors & typos. There are a lot of lists in place of arrays both in native and rescript version, some functions have changed their names and some modules (looks like Tuple was renamed to Tuple2 at some point) do not exist at all.

PS: Changes from #242 should be merged first, most changes here now are duplicated from that PR.

PSPS: Old Tuple naming felt more appropriate, just sain :)

PSPSPS: Originally I was for removing ~f from the Rescript functions, but after looking at examples for so long my mind was changed: ~f does introduce a lot of clarity when you have a lambda function.

Current Status of conversion: ✅ TableclothArray ✅ TableclothBool ✅ TableclothChar ✅ TableclothComparator ✅ TableclothFloat ✅ TableclothFun ✅ TableclothInt ✅ TableclothList ✅ TableclothMap ✅ TableclothOption ✅ TableclothResult ✅ TableclothSet ✅ TableclothString ✅ TableclothTuple2 ✅ TableclothTuple3

[Lomand]

Bool, Char, Float were converted. More typos and uncompilable examples are fixed both in rescript/native. Rescript's Float.fromString was not working as described in examples at all, fixed its implementation, added tests.

[pbiggar]

Wonderful, thanks. This is looking great.

[Lomand]

I've finished converting the rest of the modules. More typos, errors in examples, etc fixed. The project achieved an important milestone: the docs now actually compile :D

I guess now the disclaimer from the README.md about alpha quality software can be dropped, the modules are covered with tests, and the docs are actually good.

Few remarks:

• There were no Int.( /. ) as a function available, and since all infix operators are dropped from the Rescript version, there is now Int.divideFloat to take its place. The corresponding Int.divide_float is also in the native version
• Bool.and_ now exists for the same reason
• String.get now has documentation
• Tuple2.from_array and Tuple3.from_array were acting differently both from the from_list versions and contradicting to the docs, now the implementation is fixed.
• Rescript versions of Fun.compose is now left to right, following Rescript conventions
• Map.Of, Set.Of are delited since Rescript does not support inline apply syntax for functors
• .compare and .equal of Array, List, Map, Result, Option and Set are now t-first (alongside with many other functions)
• Since making them t-first breaks .compare use when using Comparator.Make (it expects comparison function(s) as first argument(s)), .compare for Array, List, Map, Result, Option and Set now has named argument(s) (~f ~g ~h). Native version also has named arguments for API parity.
• Not actually sure about this. Now .equal looks kinda out of place with its positional comparison function (it is the only function like this). Should I also add named argument for it for consistency, or just revert back and accept that .compare and .equal will be t-last?
• Some of the String functions are now not limited to ASCII characters (they use native JS functions instead of Ocaml stdlib). I'll try to look if Char module can also break free of ASCII charset.

PS: CI fails due to this bug

[Lomand]

One other thing:

The next version of Tablecloth will follow the conventions of the target language (snake_case in Ocaml, camelCase is Rescript). Shouldn't this also affect lists/arrays as the default iterable? Array.groupBy, Result.values, Result.combine, String.split, Map.keys, Map.values return their result as a list.

That seems counterintuitive in Rescript, and if you would not mind, I'll change the Rescript implementation to return arrays.

[pbiggar]

Great, thanks! I'll take a look at your questions this week.

That seems counterintuitive in Rescript, and if you would not mind, I'll change the Rescript implementation to return arrays.

So the issue here is that arrays are mutable. Rescript favors using Arrays because of the intersection with JS, which makes a bit of sense (though I think it's a huge mistake, since immutability is the best thing about FP, but anyway). However, F# and OCaml don't really use arrays because they prefer immutability.

That means if we change the rescript functions to use arrays we end up with significant divergence between the various platforms: it's one thing to have slightly different types or positioning of the t, but differing in immutability changes how you would use a function at all.

Honestly, I don't know what to do here. Half tempted to change arrays to be immutable, as it kinda seems like the only consistent thing to do. But obviously that has problems too.

Any thoughts?

[Lomand]

I think making arrays immutable by default is quite a desirable feature (and also would favorably differentiate Belt and Tablecloth). However, there are still quite a number of scenarios where having mutable arrays is desirable.

To cover both of the use-cases I would suggest dealing with this by:

• Making all top-level Array methods immutable
• Having submodule Array.Mutate where methods will result in mutations, with most of the methods duplicating top-level Array functionality. This way it will be clear for the end-user when a mutation is introduced, where the function will return a new array, and where it will be mutated.

If you will find such an approach desirable, I'll open an issue with a detailed plan of the implementation.

[pbiggar]

This is a great approach! Reminds me of Belt actually where all the collections except Array are immutable, and they have a MutableMap, MutableSet, MutableQueue, etc

[pbiggar]

All that conversation aside, I think we want to merge this as is, right?

Just reran the CI to see if that'll get the build green.

[Lomand]

Well, I guess it can be considered done now.

Some notable typos:

• Every single "emphasize" tag was ignored on the docs page, making some examples just hilarious:

You {e cannot } add an [int] and a [float]

turned into 

You add [int] and a [float]

It Looks like it was that way literally for years. Now fixed.

• Rescript dropped support for odoc comments. The documentation in vscode looks a bit rough, and the examples section with constant {[ ]} noise is not making things better. To sweeten the pill the examples were formated to have only one pair of code brackets per section.
• Some functions were not formatted properly, fixed.
• The search was case-sensitive, fixed.
• The CI is fixed by downgrading to Ubuntu LTS 20.04
• The size of the documentation page was reduced from 1.78Mb (96K gzipped) to 602Kb (55Kb gzipped) just by stripping spaces and newlines from the model.json before parsing it in Gatsby.

[pbiggar]

Wow, this is phenomenal! Thank you so much.