github/semantic
1
1
Fork 0
mirror of https://github.com/github/semantic.git synced 2024-12-22 06:11:49 +03:00
Code Issues Projects Releases Wiki Activity

Hard wrap FDoc comments for readability

Browse Source
This commit is contained in:
Timothy Clem 2016-12-09 08:33:34 -08:00
parent 686b0dffff
commit bab1f677ff
3 changed files with 48 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
src/FDoc/NatExample.hs
View File

@ -17,7 +17,8 @@ type Nat = Fix NatF
zero' :: Nat
zero' = Fix ZeroF
-- This is a partially applied type (has kind * -> *). The recursive bit is used by recursion schemes and is referred to as the "carrier" functor.
-- This is a partially applied type (has kind * -> *). The recursive bit is used
-- by recursion schemes and is referred to as the "carrier" functor.
succ' :: Nat -> Nat
succ' = Fix . SuccF
@ -37,7 +38,8 @@ intToNatAna num = ana coalgebra num
0 -> ZeroF
_ -> SuccF (num - 1)
-- Hylomorphism: first apply an anamorphism and then a catamorphism in the shape of Nat.
-- Hylomorphism: first apply an anamorphism and then a catamorphism in the shape
-- of Nat.
natHylo :: Int -> Int
natHylo num = hylo algebra coalgebra num
where
@ -48,7 +50,8 @@ natHylo num = hylo algebra coalgebra num
0 -> ZeroF
_ -> SuccF (num - 1)
-- Paramorphism: primitive recursion maintaining the original value along with its computed value.
-- Paramorphism: primitive recursion maintaining the original value along with
-- its computed value.
natPara :: Nat -> Int
natPara nats = para algebra nats
where

44
src/FDoc/RecursionSchemes.hs
View File

@ -19,7 +19,9 @@ ana :: (a -> Base t a) -- a (Base t)-coalgebra
-> a -- seed
-> t -- resulting fixed point
Anamorphism as a recursion scheme "builds up" a recursive structure. Anamorphisms work by using a coalgebra, which maps a seed value to a fixed point structure.
Anamorphism as a recursion scheme "builds up" a recursive structure.
Anamorphisms work by using a coalgebra, which maps a seed value to a fixed point
structure.
The example below adds a new field to the `Record` fields.
-}
@ -35,19 +37,23 @@ cata :: (Base t a -> a) -- a (Base t)-algebra
-> t -- fixed point
-> a -- result
Catamorphism as a recursion scheme "tears down" a recursive structure. Catamorphisms work by using an algebra, which maps a shape in our fixed point structure to a new shape.
Catamorphism as a recursion scheme "tears down" a recursive structure.
Catamorphisms work by using an algebra, which maps a shape in our fixed point
structure to a new shape.
The example below adds a new field to the `Record` fields.
-}
indexedTermCata :: [leaf] -> Term (Syntax leaf) (Record '[NewField, Range, Category])
indexedTermCata childrenLeaves = cata algebra (indexedTerm childrenLeaves)
where
algebra :: CofreeF f (Record t) (Cofree f (Record (NewField : t))) -> Cofree f (Record (NewField : t))
algebra term = cofree $ (NewField .: (headF term)) :< tailF term
{-
Anamorphism -- construct a Term from a string
The example below shows how to build up a recursive Term structure from a string representation.
The example below shows how to build up a recursive Term structure from a string
representation.
Example usage:
@ -64,13 +70,17 @@ stringToTermAna "indexed" =>
CofreeT (Identity ( (Range 1 10 .: Category.MethodCall .: RNil) :< Indexed ["leaf1", "leaf2", "leaf3"] ) )
While building up the `Indexed` structure, we continue to recurse over the `Indexed` terms ["leaf1", "leaf2", "leaf3"]. These are pattern matched using the catch all `_` and default to `Leaf` Syntax shapes:
While building up the `Indexed` structure, we continue to recurse over the
`Indexed` terms ["leaf1", "leaf2", "leaf3"]. These are pattern matched using
the catch all `_` and default to `Leaf` Syntax shapes:
CofreeT (Identity ( (Range 1 10 .: Category.MethodCall .: RNil) :< Leaf "leaf1" ) )
CofreeT (Identity ( (Range 1 10 .: Category.MethodCall .: RNil) :< Leaf "leaf2" ) )
CofreeT (Identity ( (Range 1 10 .: Category.MethodCall .: RNil) :< Leaf "leaf3" ) )
These structures are substituted in place of ["leaf1", "leaf2", "leaf3"] in the new cofree `Indexed` structure, resulting in a expansion of all possible string terms.
These structures are substituted in place of ["leaf1", "leaf2", "leaf3"] in
the new cofree `Indexed` structure, resulting in a expansion of all possible
string terms.
-}
stringToTermAna :: String -> Term (Syntax String) (Record '[Range, Category])
stringToTermAna = ana coalgebra
@ -82,7 +92,8 @@ stringToTermAna = ana coalgebra
{-
Catamorphism -- construct a list of Strings from a recursive Term structure.
The example below shows how to tear down a recursive Term structure into a list of String representation.
The example below shows how to tear down a recursive Term structure into a list
of String representation.
-}
termToStringCata :: Term (Syntax String) (Record '[Range, Category]) -> [String]
termToStringCata = cata algebra
@ -100,9 +111,13 @@ hylo :: Functor f => (f b -> b) -- an algebra
-> a -- seed value
-> b -- result
Hylomorphisms work by first applying a coalgebra (anamorphism) to build up a structure. An algebra (catamorphism) is then applied to this structure. Because of fusion the anamorphism and catamorphism occur in a single pass rather than two separate traversals.
Hylomorphisms work by first applying a coalgebra (anamorphism) to build up a
structure. An algebra (catamorphism) is then applied to this structure. Because
of fusion the anamorphism and catamorphism occur in a single pass rather than
two separate traversals.
The example below shows how our algebra and coalgebra defined in the termToStringCata and stringToTermAna can be utilized as a hylomorphism.
The example below shows how our algebra and coalgebra defined in the
termToStringCata and stringToTermAna can be utilized as a hylomorphism.
Example Usage:
stringTermHylo "indexed" => ["indexed", "leaf1", "leaf2", "leaf3"]
@ -126,9 +141,18 @@ para :: (Base t (t, a) -> a) -- an algebra that takes a tuple of the last input
-> t -- fixed point
-> a -- result
Paramorphisms, like all recursion schemes, work via a bottom up traversal (leaves to root), in which an algebra is applied to every node in the recursive structure. The difference between paramorphisms and catamorphisms is the algebra receives a tuple of the original subobject and its computed value (t, a) where `t` is the original suboject and `a` is the computed value.
Paramorphisms, like all recursion schemes, work via a bottom up traversal
(leaves to root), in which an algebra is applied to every node in the recursive
structure. The difference between paramorphisms and catamorphisms is the algebra
receives a tuple of the original subobject and its computed value (t, a) where
`t` is the original suboject and `a` is the computed value.
The example implementation below calculates a string representation for each Syntax type, flattening the recursive structure into a one dimensional list to tuples. The tuple contains the original syntax subobject, and its computed string representation. This example aims to showcase how paramorphisms work by returning a final list of tuples that mimics the intermediate tuple shapes the algebra receives throughout the bottom up traversal.
The example implementation below calculates a string representation for each
Syntax type, flattening the recursive structure into a one dimensional list to
tuples. The tuple contains the original syntax subobject, and its computed
string representation. This example aims to showcase how paramorphisms work by
returning a final list of tuples that mimics the intermediate tuple shapes the
algebra receives throughout the bottom up traversal.
Example Usage:
let terms = indexedTerm ["leaf1", "leaf2", "leaf3"]

10
src/FDoc/Term.hs
View File

@ -17,7 +17,10 @@ This is in the TermF shape: CofreeF f a b where
a is the annotation (Record '[Range, Category])
b is the same type of functor defined by f
Two common convenience operations when working with CofreeF (for docs, see Control.Comonad.Trans.Cofree.Types.CofreeF) are `headF` and `tailF`. `headF` return the annotation portion of the CofreeF structure, and `tailF` returns the functor portion (Syntax).
Two common convenience operations when working with CofreeF (for docs, see
Control.Comonad.Trans.Cofree.Types.CofreeF) are `headF` and `tailF`. `headF`
return the annotation portion of the CofreeF structure, and `tailF` returns the
functor portion (Syntax).
Example (from GHCi):
@ -40,7 +43,10 @@ This is in the Term shape: Cofree f a where
f is the functor (Syntax.Leaf `leaf`)
a is the annotation (Record '[Range, Category])
Two common convenience operations when working with Cofree (for docs, see Control.Comonad.Trans.Cofree.Types.Cofree) are `extract` and `unwrap`. `extract` returns the annotation portion of the Cofree structure, and `unwrap` returns the functor portion (Syntax).
Two common convenience operations when working with Cofree (for docs, see
Control.Comonad.Trans.Cofree.Types.Cofree) are `extract` and `unwrap`. `extract`
returns the annotation portion of the Cofree structure, and `unwrap` returns the
functor portion (Syntax).
Example (from GHCi):