From 4c51f0affeea9ba419c53d4c05530314bf03b6fe Mon Sep 17 00:00:00 2001 From: Arijit Basu Date: Thu, 13 Jul 2023 18:42:21 +0530 Subject: [PATCH] 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 | 2 + docs/en/src/borders.md | 21 ++++---- docs/en/src/configure-key-bindings.md | 3 +- docs/en/src/filtering.md | 3 +- docs/en/src/input-operation.md | 3 +- docs/en/src/layout.md | 7 +-- docs/en/src/message.md | 5 +- docs/en/src/sorting.md | 3 +- docs/en/src/style.md | 5 +- docs/en/src/sum-type.md | 72 +++++++++++++++++++++++++++ 10 files changed, 104 insertions(+), 20 deletions(-) create mode 100644 docs/en/src/sum-type.md diff --git a/docs/en/src/SUMMARY.md b/docs/en/src/SUMMARY.md index b3a8abc..210136c 100644 --- a/docs/en/src/SUMMARY.md +++ b/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 diff --git a/docs/en/src/borders.md b/docs/en/src/borders.md index 3ed204f..dcaab62 100644 --- a/docs/en/src/borders.md +++ b/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 diff --git a/docs/en/src/configure-key-bindings.md b/docs/en/src/configure-key-bindings.md index a637d50..7d8a437 100644 --- a/docs/en/src/configure-key-bindings.md +++ b/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 diff --git a/docs/en/src/filtering.md b/docs/en/src/filtering.md index 69bc2a9..a2f2dd5 100644 --- a/docs/en/src/filtering.md +++ b/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 diff --git a/docs/en/src/input-operation.md b/docs/en/src/input-operation.md index fa33075..6ba95cd 100644 --- a/docs/en/src/input-operation.md +++ b/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 diff --git a/docs/en/src/layout.md b/docs/en/src/layout.md index 15295c0..2a74878 100644 --- a/docs/en/src/layout.md +++ b/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 diff --git a/docs/en/src/message.md b/docs/en/src/message.md index 87b0600..dea4bb4 100644 --- a/docs/en/src/message.md +++ b/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 diff --git a/docs/en/src/sorting.md b/docs/en/src/sorting.md index 671e82f..1795a7f 100644 --- a/docs/en/src/sorting.md +++ b/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 diff --git a/docs/en/src/style.md b/docs/en/src/style.md index fd3b240..96db16c 100644 --- a/docs/en/src/style.md +++ b/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 diff --git a/docs/en/src/sum-type.md b/docs/en/src/sum-type.md new file mode 100644 index 0000000..b5adf4c --- /dev/null +++ b/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