API documentation for `Prism` and `Traversal`

[marick]

This provides top-of-page summary documentation for Prism and Traversal. It also contains documentation for many Prism and Traversal functions (not all).

[paf31]

Law abiding prisms only apply to types which are isomorphic to sums. I wonder if that could be brought out here. Maybe it's not that important though.

[marick]

Generally, I'd prefer to have all laws explained in one file, because the law differences between different optics are instructive.

In this particular case, I envision that the sum-type-specific examples file will be joined with a file about using prisms on things isomorphic to sum types.

[paf31]

Might be worth commenting on the Either t bit here? Specifically, it wasn't obvious to me why there was a t there at all.

[paf31]

Also, it might be worth talking about the prism laws briefly here?

[marick]

I don't understand why it's Either t a instead of Either somethingElse a, so I can't explain it.

Regarding laws: I do cover laws in Lenses for the Mere Mortal, in more detail than can be done in an API document. Provided I continue to make it free, that seems a better place to talk about laws.

[paf31]

I think you could explain it succinctly as

_Note_: The matching function returns a result wrapped in `Either t` so as to allow for type-changing prisms in the case where the input does not match.

What do you think?

[paf31]

I disagree about the laws actually. I think they ought to be documented with the types themselves, like we do for type classes in Prelude.

[paf31]

This isn't to say we need to add them here now, just that I'd like to eventually, and that redirecting readers to an external resource from doc comments doesn't strike me as ideal.

[marick]

I do refer to the laws section of the Haskell lens fairly often, so I take your point.

I tend to explain laws in words, then equational and example style:

set-get:

: `view` retrieves what `set` puts in. 
  
  {lang=haskell}
  ~~~~~~~~~~~~~~
  set lens >>> view lens ≡ id
  
  > set first "NEW" (Tuple 1 2) # view first
  "NEW"
  ~~~~~~~~~~~~~~

That OK?

[paf31]

Yeah I like that.

[marick]

How do I explain the Traversal laws? The Haskell traversal laws don't translate into profunctor lenses, and it seems odd to write:

traverseOf traversed pure ≡ pure

[marick]

over traversed pure ≡ map pure

?

[paf31]

What do you think about calling this a matching function? I compare it to pattern matching on the constructor.

[marick]

I'll do that.

[paf31]

In order for this to work as a law-abiding prism, the predicate should identify only the value passed it. It's identifying the one value as a summand of the whole.

[paf31]

For example, lens in Haskell uses nearly [] null as an example. Note that [] is the only value for which null evaluates to true.

[paf31]

Actually, this also applies to only, since Eq isn't necessarily going to give definitional equality. That might be worth commenting on briefly as well.

[marick]

I don't understand "identify only the value passed it".

[marick]

I'll make explicit only's dependence on Eq.

[marick]

What would be a use of nearly that would make an ill-behaved prism?

[paf31]

I don't understand "identify only the value passed it".

I mean that f a can only hold when a = x and not otherwise.

I'll make explicit only's dependence on Eq.

It's not just the dependence on Eq, but that that instance must be definitional equality: eq x y if and only if x = y definitionally.

What would be a use of nearly that would make an ill-behaved prism?

Your example gives a prism which does not obey the second prism law. Extracted from the lens docs:

If preview l s ≡ Just a then review l a ≡ s

i.e. if predicate s then const (Solid referenceColor) = s. This obviously only holds for one value of s, not all of them.

[marick]

I completely misunderstood the purpose of nearly if there's only one possible s that can satisfy the predicate. Is it then the case that the difference between nearly and only just that the latter uses Eq whereas the former uses the given predicate to detect the one-and-only-one value that's allowed?

[paf31]

That's right. Per the lens docs:

To comply with the Prism laws the arguments you supply to nearly a p are somewhat constrained.

We assume p x holds iff x ≡ a. Under that assumption then this is a valid Prism.

[paf31]

Not necessarily a Functor, but something isomorphic to a Traversable functor (just a Functor gives a Setter actually). For example, I can traverse the chars in a string.

[marick]

I'll just say "Traversable functor". My goal here is to allow people to use Traversal without having to first know Traversable (not in all cases, but the simple ones).

[paf31]

The String/Char example does not involve a Traversable functor though. I think simply removing the word functor would be enough.

[paf31]

Maybe could add something like

This is called an "affine traversal", _which means that the result focuses on one or zero (if the index is out of range) results_.

[marick]

Will do.

[paf31]

Thanks! Looks really good, most of my comments are nitpicks, with the one exception of the comment on nearly where I think we need to be a bit more precise about the laws.

[marick]

I believe I've addressed all the earlier comments.

The only thing that's missing is Traversal laws, because I don't understand them.

[paf31]

Thanks very much! Looks great, please feel free to merge.

[paf31]

Thanks very much! Looks great, please feel free to merge.