# polysemy-methodology polysemy-methodology provides an algebra for domain modelling in polysemy. A simple program might look something like this: ``` prog :: Members '[ Input a , Methodology a b , Output b] => Sem r () prog = input @a >>= process @a @b >>= output @b ``` That is, this program transforms an `Input a` into an `Output b` by way of a `Methodology a b` that turns `a` into `b`. We can then type apply `a` and `b` and connect this to `main`. If we have a solution readily available, we can consume a `Methodology` by running one of the interpreters `runMethodologyPure` or `runMethodologySem`. Otherwise, we can use the other interpreters in this package to break the problem down into components or branches and solve each section separately. Each interpreter will produce a new set of `Methodology`s to be solved. This allows you to work up a solution to a domain problem backwards, by running the program you intend to solve directly and using holes to guide the requirements. ## Worked example A worked example of this approach can be found in the [flashblast](https://gitlab.com/homotopic-tech/flashblast) repository. In this we want to take a configuration, and process it in some way an output of flashcards. We might model this as such: ``` -- Domain.hs import Polysemy import Polysemy.Input import Polysemy.Tagged import Polysemy.Methodology import Polysemy.Output -- | A `DeckConfiguration` indicates how we create cards. data DeckConfiguration -- | A `CollectionsPackage` indicates the desired output format. data CollectionsPackage -- | The Construction Methodology for flashblast. data ConstructionMethodology -- | `flashblast` is a program that takes a `DeckConfiguration` and outputs a `CollectionsPackage`. flashblast :: Members '[ Tagged DeckConfiguration (Input a) , Tagged ConstructionMethodology (Methodology a b) , Tagged CollectionsPackage (Output b)] r => Sem r () flashblast = do x <- tag @DeckConfiguration input k <- tag @ConstructionMethodology $ process x tag @CollectionsPackage $ output k ``` Notice that this is an abstract domain model. We have not committed to a particular representation of any of the three elements of this program. In fact, this file depends only on polysemy modules, which allows us to isolate the domain model from anything resembling real code. However, we would also like to claim that what we say the program *should* do in abstraction is *actually* what we run for real. So it would be reassuring to be able to simply interpret this into real functions. We commit to a concrete representation for the config and for the output only in the main application file, where we iterate over the decks. ``` -- Config.hs data Spec = Pronunciation [PronunciationSpec] | Excerpt [ExcerptSpec] | BasicReversed [BasicReversedCard] | MinimalReversed [MinimalReversedCard] deriving stock Generic makePrisms ''Spec data Deck = Deck { _resourceDirs :: ResourceDirs , _exportDirs :: ExportDirs , _parts :: [Spec] } deriving stock Generic ``` ``` -- Main.hs data Deck = Deck { notes :: Map (Path Rel File) Text , media :: [Path Rel File] } deriving stock (Eq, Show, Generic) deriving Semigroup via GenericSemigroup Deck deriving Monoid via GenericMonoid Deck main = do decks <- ... forM_ decks $ \x -> do flashblast @Config.Deck @Deck & runM ``` Here we will be told that we need to satisfy the `Input`, `Output` and `Methodology` effects. The `Config.Deck` is divided into several different specs. We could simply write one giant function to solve the `Methodology` and annihilate the `Methodology` effect using `runMethodologySem`. ``` soln :: Members '[...] r => Config.Deck -> Sem r Deck soln = ... -- runMethodologySem @Config.Deck @Deck soln ``` But this would conflate our concerns - the different specs require different effects to execute, and having this single function require all effects wouuld be maintenance should we choose to remove any functionality. It would also increase our testing surface. * The `MinimalReversedCard`s and `BasicReversedCard`s are direct representations of what the output cards should look like, and so can be purely transformed. * `ExcerptSpec`s need to be transformed into cards by way of processing the specified video and subtitle track via ffmpeg. * `PronunciationSpec` need to fetch the pronunciation data for the target words from a remote API. What would be nice is if we could reach a point where we can make functions for each of with their respective effects isolated but without having to agglomerate all the effects into a single solution function. It makes sense then to take our `Methodology` and break it down into sub `Methodology`s that can be reasoned about independently, rather than trying to satisfy the program with one function built up from parts. This way we can break the program down using only type applications and interpreters, and we only need to write any code once we are happy that the problem is sufficiently decomposed. The interpreters in this library aree operations that consume a `Methodology` and turn it into parts. `cutMethodology` breaks the `Methodology` into two pieces, and will then require interpreters for each. So if we start with a `Methodology b d`, we can break it into `Methodology b c` and `Methodology c d`, each of which will require some solution. This is essentially reverse arrow composition. ``` b -----> d ===> (b ---> c), (c ---> d) ``` `divideMethodology` breaks the target into a pair, and connects the source to both of them, producing three `Methodology`s we need to solve. This is reverse fanout. ``` b ----> d ==> (b ---> c), (b ---> c'), ((c,c') ----> d) ``` `decideMethodology` breaks the source into an `Either`, allowing us to choose a `Methodology` to run as the result of another `Methodology` based on the source. This is reverse fanin. ``` b ----> d ===> (b---> Either c c'), (c ---> d), (c ---> d) ``` `decomposeMethodology` is `cutMethodology` specialised to `HList` as the center argument. This allows us to cut the `Methodology` into multiple parallel tracks. ``` /-----c-----\ b ----> d ===> b------d------f \-----e-----/ ``` Back to our example, we need to decompose our `Config` into the problems concerning each type of spec, then turn each of those into a `Deck` of its own, then collect the produced decks monoidally into the final output. Dealing with HLists is a little awkward but the approach that will work is to deal with each strand individually, and use `separateMethodologyInitial` or `separateMethodologyTerminal` depending on whether the strand appears before or after the `HList`, which will separate the element of the `HList` into its own `Methodology`. Then, decompose this further or solve it. ``` main = do forM_ decks $ \x -> do flashblast @Config.Deck @Deck & untag @ConstructionMethodology & decomposeMethodology @Config.Deck @DeckSplit @Deck -- We pull out `Config.Deck -> [Config.MinimalReversedCard]` as its own `Methodology`. & separateMethodologyInitial @Config.Deck @[Config.MinimalReversedCard]) -- And then immediately solve it purely. & runMethodologyPure _ & separateMethodologyInitial @Config.Deck @[Config.BasicReversedCard] & runMethodologyPure _ & separateMethodologyInitial @Config.Deck @[Config.ExcerptSpec] & runMethodologyPure _ & separateMethodologyInitial @Config.Deck @[Config.PronunciationSpec] & runMethodologyPure _ & endMethodologyInitial & separateMethodologyTerminal @[Config.MinimalReversedCard] @Deck & runMethodologyPure _ & separateMethodologyTerminal @[Config.BasicReversedCard] @Deck & runMethodologyPure _ & separateMethodologyTerminal @[Config.ExcerptSpec] @Deck & runMethodologySem _ & separateMethodologyTerminal @[Config.PronunciationSpec] @Deck & runMethodologySem _ ``` We have left holes that polysemy will now tell us need to be filled by nice clean `a -> b` or `a -> Sem r b` functions. Any effects we add here we can deal with after this block, or we can decompose this even further (see flashblast for more details). ## Logging You can also surround `Methodology`s with logging using the `traceMethodologyStart`, `traceMethodologyEnd` and `traceMethodologyAround` functions. ``` & decomposeMethodology @Config.Deck @DeckSplit @Deck & traceMethodologyAround @Config.Deck @(HList DeckSplit) (const $ T.unpack $ "Analysing Deck") (const $ T.unpack $ "Finished Analysing Deck") & separateMethodologyInitial @Config.Deck @[Config.MinimalReversedCard] & traceMethodologyAround @Config.Deck @[Config.MinimalReversedCard] (const "Extracting Minimal Reversed Card Specs") (\c -> "Found " <> show (length c) <> " Minimal Card specs.") ``` ## Notes There are intended to be less boilerplatey ways to deal with separation, as a very common pattern is simply to separate a strand out and then immediately solve it, but this library is early and I didn't want to jump the gun with too many functions.