From c4090f44e1e2980bc1dd03ddce7eb40d4cb4c8f9 Mon Sep 17 00:00:00 2001 From: Philip Monk Date: Fri, 19 Apr 2019 18:00:39 -0700 Subject: [PATCH] add docs for ph monad --- lib/ph.hoon | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/lib/ph.hoon b/lib/ph.hoon index 3070655df6..4db7f393c8 100644 --- a/lib/ph.hoon +++ b/lib/ph.hoon @@ -1,6 +1,38 @@ +:: Defines the ph monad. +:: +:: A complete ph test has type data:(ph ,~). This is a function that +:: accepts a new unix-effect and produces a list of ph-events to inject +:: back into the system. It also produces one of four "next steps": +:: +:: %wait: no change; on next unix-effect call this same function. +:: %cont: swap out this test for another one. Mainly useful for +:: the implementation of +bind. +:: %fail: the test has failed. +:: %done: the test has finished successfully. +:: +:: When producing %done, you may specify a value. The ph app assumes +:: the value of each whole test will be ~. During the test, though, it +:: may be useful to produce intermediate values. +:: +:: We define two additional functions. +return takes a value and +:: produces a test which immediately produces a %done with that value. +:: +:: +bind takes a test and a function from the output type of that test +:: to another test. This is useful to link tests together. See +:: lib/ph/tests.hoon for examples of usage. +:: +:: You may recognize monad terminology. These functions satisfy the +:: monad laws: If `f` and `g` are the sort of function that go in the +:: second argument to bind and `m` is a test, then: +:: +:: (cork return (curr bind f)) = f +:: (bind m return) = m +:: ((bind m f) g) = (bind m (bind f g)) +:: +:: Maintaining these laws requires a particular interpretation of the +:: monad, which the ph app implements in +diff-aqua-effects. Thus, +:: within the ph app the monad laws hold. :: -:::: /hoon/ph/lib - :: /- aquarium =, aquarium |%