Document sum types for hackers (#647)

* Document sum types for hackers

So you don't have to learn rust to configure xplr.

* Fix typos

docs/en/src/SUMMARY.md

@@ -10,6 +10,7 @@
   - [Layouts][9]
   - [Modes][7]
 - [Concept][32]
+  - [Sum Type][42]
   - [Key Bindings][27]
     - [Configure Key Bindings][28]
     - [Default Key Bindings][14]
@@ -81,3 +82,4 @@
 [39]: input-operation.md
 [40]: xplr.util.md
 [41]: searching.md
+[42]: sum-type.md

docs/en/src/borders.md

@@ -4,21 +4,21 @@ xplr allows customizing the shape and style of the borders.
 
 ### Border
 
-A border can be one of the following:
+A border is a [sum type][2] that can be one of the following:
 
-- Top
-- Right
-- Bottom
-- Left
+- "Top"
+- "Right"
+- "Bottom"
+- "Left"
 
 ### Border Type
 
-A border can be one of the following:
+A border type is a [sum type][2] that can be one of the following:
 
-- Plain
-- Rounded
-- Double
-- Thick
+- "Plain"
+- "Rounded"
+- "Double"
+- "Thick"
 
 ### Border Style
 
@@ -34,3 +34,4 @@ xplr.config.general.panel_ui.default.border_style.bg = "Gray"
 ```
 
 [1]: style.md#style
+[2]: sum-type.md

docs/en/src/configure-key-bindings.md

@@ -86,7 +86,7 @@ Default action to perform in case if a keyboard input not mapped via any of the
 
 ## Key
 
-A key can be one of the following:
+A key is a [sum type][36] can be one of the following:
 
 - 0, 1, ... 9
 - a, b, ... z
@@ -230,3 +230,4 @@ Visit [Awesome Plugins][27] for more [integration][28] options.
 [33]: #on_character
 [34]: #on_navigation
 [35]: #on_function
+[36]: sum-type.md

docs/en/src/filtering.md

@@ -25,7 +25,7 @@ It contains the following information:
 
 ### filter
 
-A filter can be one of the following:
+A filter is a [sum type][5] that can be one of the following:
 
 - "RelativePathIs"
 - "RelativePathIsNot"
@@ -90,3 +90,4 @@ Here, `ToggleNodeFilter` is a [message][4] that adds or removes
 [2]: #filter
 [3]: #input
 [4]: message.md
+[5]: sum-type.md

docs/en/src/input-operation.md

@@ -1,6 +1,6 @@
 # Input Operation
 
-Cursor based input operation can be one of the following:
+Cursor based input operation is a [sum type][3] can be one of the following:
 
 - { SetCursor = int }
 - { InsertCharacter = str }
@@ -24,3 +24,4 @@ Cursor based input operation can be one of the following:
 
 [1]: message.md
 [2]: messages.md
+[3]: sum-type.md

docs/en/src/layout.md

@@ -24,7 +24,7 @@ xplr.config.layouts.builtin.default = {
 }
 ```
 
-A layout can be one of the following:
+A layout is a [sum type][56] can be one of the following:
 
 - [Nothing][8]
 - [Table][9]
@@ -145,7 +145,7 @@ The constraints applied on the layout.
 
 ## Constraint
 
-A constraint can be one of the following:
+A constraint is a [sum type][56] can be one of the following:
 
 - { Percentage = int }
 - { Ratio = { int, int } }
@@ -173,7 +173,7 @@ The list of child layouts to fit into the parent layout.
 
 ## Custom Panel
 
-Custom panel can be one of the following:
+Custom panel is a [sum type][56] can be one of the following:
 
 - [CustomParagraph][29]
 - [CustomList][30]
@@ -462,3 +462,4 @@ Hence, only the following fields are available.
 [53]: lua-function-calls.md#initial_pwd
 [54]: borders.md#border-type
 [55]: #customlayout
+[56]: sum-type.md

docs/en/src/message.md

@@ -1,7 +1,9 @@
 # Message
 
 You can think of xplr as a server. Just like web servers listen to HTTP
-requests, xplr listens to [messages][1].
+requests, xplr listens to messages.
+
+A message is a [sum type][9] that can have [these possible values][1].
 
 You can send these messages to an xplr session in the following ways:
 
@@ -54,3 +56,4 @@ For example:
 [6]: http://yaml.org/
 [7]: https://www.json.org
 [8]: https://github.com/sayanarijit/jf
+[9]: sum-type.md

docs/en/src/sorting.md

@@ -27,7 +27,7 @@ It contains the following information:
 
 ### sorter
 
-A sorter can be one of the following:
+A sorter is a [sum type][4] that can be one of the following:
 
 - "ByRelativePath"
 - "ByIRelativePath"
@@ -82,3 +82,4 @@ This snippet defines the initial sorting logic to be applied when xplr loads.
 [1]: #node-sorter-applicable
 [2]: #sorter
 [3]: #reverse
+[4]: sum-type.md

docs/en/src/style.md

@@ -33,7 +33,7 @@ Modifiers to remove.
 
 ## Color
 
-Color can be one of the following:
+Color is a [sum type][7] that can be one of the following:
 
 - "Reset"
 - "Black"
@@ -57,7 +57,7 @@ Color can be one of the following:
 
 ## Modifier
 
-Modifier can be one of the following:
+Modifier is a [sum type][7] that can be one of the following:
 
 - "Bold"
 - "Dim"
@@ -84,3 +84,4 @@ xplr.config.general.prompt.style.sub_modifiers = { "Hidden" }
 [4]: #sub_modifiers
 [5]: #color
 [6]: #modifier
+[7]: sum-type.md

docs/en/src/sum-type.md

@@ -0,0 +1,72 @@
+# Sum Type
+
+> This section isn't specific to xplr. However, since xplr configuration makes
+> heavy use of this particular data type, even though it isn't available in
+> most of the mainstream programming languages (yet), making it a wild or
+> unfamilier concept for many, it's worth doing a quick introduction here.
+>
+> If you're already familiar with [Sum Type / Tagged Union][1] (e.g. Rust's
+> enum), you can skip ahead.
+
+While reading this doc, you'll come across some data types like [Layout][2],
+[Color][4], [Message][3] etc. that says something like "x can be any of the
+following", and then you'll see a list of strings and/or lua tables just below.
+
+Yes, they are actually sum types, i.e. they can be any of the finite set of
+values listed there.
+
+Note the word "finite". Many conventional programming languages have only two
+kinds of data types with finite set of values:
+
+- `null` - aka "unit type", can be only one thing - i.e. `null`.
+- `bool` - can be one of the two possible values - `true` or `false`.
+
+Other types like `integer`, `float`, `string` etc. can have infinite number of
+possible values (ideally).
+
+Many popular programming languages come with the concept of `enum`, which lets
+us define a type with finite set of possible values like:
+
+```rust
+enum Result {
+    Ok,
+    Err,
+}
+```
+
+Here, `Result` has only two possible values (just like `bool`): `Ok` and `Err`.
+
+We'd document it here as:
+
+> Result is a sum type that can be one of the following:
+>
+> - "Ok"
+> - "Err"
+
+But some languages (like Rust, Haskell, Elm etc.) go even further, allowing us
+to associate each branch of the enum with further nested types like:
+
+```rust
+enum Result {
+    Ok(bool),
+    Err(String),
+}
+```
+
+We'd document it here as:
+
+> Result is a sum type that can be one of the following:
+>
+> - { Ok = bool }
+> - { Err = "string" }
+
+Here, `Result` still has only two possibilities, but unlike bool, each
+possibility here has further finite or infinite set of possible values.
+
+And there you go. This is exactly what sum types are - glorified enums that can
+have nested types in each branch.
+
+[1]: https://en.wikipedia.org/wiki/Tagged_union
+[2]: layout.md
+[3]: message.md
+[4]: style.md#color