search

purescript / purescript-record

Functions for working with records and polymorphic labels
BSD 3-Clause "New" or "Revised" License
70 stars 31 forks source link

Explain how the Record Builder is safe #44

Closed chexxor closed 6 years ago

chexxor commented 6 years ago

despite appearing to cheat by using the FFI to effect effectful behavior.

I had to ask in the chat room how this "cheating" can be considered as safe. This builder seems to handle these effectful operations like ST does - by wrapping/hiding the effectful stuff in a HKT, and ensuring the types are correct.

MonoidMusician commented 6 years ago

Good idea :) I think I would just talk about mutation here instead of effects, especially since that explains why copying the record at the start makes it safe, you know?

justinwoo commented 6 years ago

I think it's otherwise important that people know you can't access the "intermediate" states and that it actually does make a clone to build to. Maybe some short explanation like this is missing: https://twitter.com/jusrin00/status/988414714093948929

In addition, how do you teach people about "operations with evidence" overall?

chexxor commented 6 years ago

Thanks for the review! I think the tweet is roughly equivalent to the docs I wrote here, but the info in the tweet is more verbose (I like to be concise, for better or worse).

hdgarrood commented 6 years ago

See https://github.com/purescript/purescript-record/issues/32. I think this is possibly to do with the fact that all of the operations which are exposed as Builder values are linear (they use their argument exactly once). I don't know this well enough to be able to review this PR, though.

LiamGoodacre commented 6 years ago

This sounds good. I'd prefer them to be doc-comments: either for the module or integrated into the existing doc-comment for the Builder type.

chexxor commented 6 years ago

I think that's a great idea.

I moved to doc-comments for the Builder type, and I also simplified the explanation. I hope it didn't lose too much of the information I had before. I think the difference between the new docs and the previous docs I had written is that the new docs just say "this is safe because X" whereas the previous docs said "this is safe because X. They are only used in builder function, and also worth noting is blah-blah."

chexxor commented 6 years ago

Thanks for maintaining, @LiamGoodacre and @kRITZCREEK !