Add skippable type

[Tarmil]

As requested by @cmeeren: https://github.com/Tarmil/FSharp.SystemTextJson/issues/24#issuecomment-576616674

It is sometimes necessary to distinguish between a null field and the absence of a field. This can be represented as follows:

type Skippable<'T> =
  | Skip
  | Include of 'T

type Example =
  { a: int option Skippable }

"{}" <=> { a = Skip }
"""{"a":null}""" <=> { a = Include None }
"""{"a":42}""" <=> { a = Include (Some 42) }

Technically it's isomorphic to 'T option option, but a separate type makes the intention clear.

[cmeeren]

Technically it's isomorphic to 'T option option, but a separate type makes the intention clear.

More importantly, while 'T option option clearly means "nullable and skippable", there's no way to tell if 'T option means nullable but not skippable, or skippable but not nullable.

[cmeeren]

By the way, feel free to copy whatever you want from https://github.com/cmeeren/FSharp.JsonSkippable/blob/master/src/FSharp.JsonSkippable/Skippable.fs

[cmeeren]

Thanks! :) Would you be able to document the usage and behavior also?

[Tarmil]

Yeah, there's a whole bunch of stuff that needs to be documented. A bit of reorganization is probably in order too, maybe moving to the wiki, otherwise the readme will become quite long and hard to browse.

[cmeeren]

A bit of reorganization is probably in order too, maybe moving to the wiki, otherwise the readme will become quite long and hard to browse.

Since you mention it, I disagree; single-file documentation (done right) is great. Here's an example. But do whatever you want, of course. :)

(Even for the single-file case, uou don't have to put it in the actual readme, of course.)

[Tarmil]

I find browsers' handling of the interaction between scrolling and history too dodgy. I want to be able to use my back/forward buttons (or Alt+left/right keys), and in a single-file documentation, that sends me to the middle of nowhere half the time.