Documentation for Atop and Over

1 files changed, 53 insertions, 0 deletions

diff --git a/doc/compose.md b/doc/compose.md
new file mode 100644
index 00000000..c848b9d5
--- /dev/null
+++ b/doc/compose.md
@@ -0,0 +1,53 @@
+*View this file with results and syntax highlighting [here](https://mlochbaum.github.io/BQN/doc/compose.html).*
+
+# Atop and Over
+
+<!--GEN combinator.bqn
+DrawComp ≍"∘○"
+-->
+
+Atop and Over are 2-modifiers that extend the idea of "apply this, then that" in two different ways. They're modelled after the mathematical notation f∘g to compose two functions, and both do the same thing when there's one argument: `F∘G x` or `F○G x` is `F G x`.
+
+| `Cmp` | `Cmp 𝕩` | `𝕨 Cmp 𝕩`      | Unified     | On list
+|-------|---------|:--------------:|:-----------:|:-------:
+| `F∘G` | `F G 𝕩` | `F 𝕨 G 𝕩`      | `{𝔽𝕨𝔾𝕩}`    | `F G´𝕩`
+| `F○G` | `F G 𝕩` | `(G 𝕨) F G 𝕩`  | `{(𝔾𝕨)𝔽𝔾𝕩}` | `F´G¨𝕩`
+
+When there are two arguments, we might say Atop treats the right operand `𝔾` as primary and Over treats `𝔽` as primary—the primary operand becomes dyadic while the other is always monadic. Atop applies `𝔾` directly, making it more like mathematical composition if we suppose that `𝔾` is a function that can take a pair of arguments. Over instead makes two calls to apply `𝔾` separately to both arguments, then passes the results to `𝔽`.
+
+## Atop
+
+Of the two modifiers on this page, Atop is more common but less impactful. The composition `F∘G` is equivalent to the 2-[train](train.md) `F G` (the trains page has hints on when you'd choose one or the other). Its definition `{F𝕨G𝕩}` means that `G` is applied to one or two arguments and `F` is applied monadically to the result. It could be considered a "default way" to compose two functions. Keeps [tacit](tacit.md) programming syntax running smoothly, without making noise about it. Not like that busybody `⊸`. Some examples:
+
+`↕∘≠` is useful with one argument: `↕≠l` is a list of indices for `l`.
+
+`⌊∘÷` is useful with two arguments: `⌊a÷b` is the integer part when dividing `a` by `b`, often paired with the [remainder](arithmetic.md#additional-arithmetic) `b|a`.
+
+`⊔∘⊐` is useful with one or two arguments. From right to left, we have [Classify](selfcmp.md#classify)/[Index-of](search.md#index-of) (`⊐`) to convert values to indices, and [Group Indices](group.md) to group the indices. Er, that sounds good but what it *actually* does is to group indices of Group's argument, which correspond to indices of the original `𝕩`, according to their values as returned by `⊐`. Without a left argument, this means indices of `𝕩` are grouped corresponding to `⍷𝕩`, and if `𝕨` is provided the groups correspond to `𝕨` instead.
+
+        ⊔∘⊐ "bbeabee"
+
+        "abcde" ⊔∘⊐ "bbeabee"
+
+## Over
+
+Once you get used to Over, it's painful to go without it. I'd use it all the time in C if I could.
+
+Usually Over is used just for the dyadic meaning. If you have a composition that only works with one argument it's typical to write it with Atop (`∘`). And cases that work with one or two arguments do come up from time to time, but they're fairly rare, so the examples below are just for two arguments.
+
+A classic is the function `≡○∧`, which tests whether `𝕨` is a reordering of `𝕩`. The idea is to sort both arrays with `∧` to remove the ordering information
+
+        "BQN" ≡○∧ "QNB"
+        "BQN" ≡○∧ "BBQ"
+
+Another example is `/○⥊`, used to filter elements in a high-rank array. Alone, `/` won't do this because there's no automatic choice of ordering for the results. Applying [Deshape](reshape.md) (`⥊`) to both chooses index order.
+
+        ⊢ a ← "qBrs"≍"QtuN"
+
+        a < 'a'  # Capital letters
+
+        (a<'a') / a  # Not allowed
+
+        (a<'a') /○⥊ a
+
+Over is closely connected with the Under modifier, which performs all the same steps but then undoes `𝔾` afterwards.