From 8cd54df86f18c8f8c2d556d6a3dc85005bfb9745 Mon Sep 17 00:00:00 2001 From: Harry Sarson Date: Tue, 13 Aug 2019 15:15:30 +0100 Subject: [PATCH 1/5] begin to document all kernel function in elm/core --- docs/core/kernel-code.md | 62 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/core/kernel-code.md diff --git a/docs/core/kernel-code.md b/docs/core/kernel-code.md new file mode 100644 index 00000000..e360ebd0 --- /dev/null +++ b/docs/core/kernel-code.md @@ -0,0 +1,62 @@ +# Kernel functions in `elm/core` + +This documents lists all kernel functions defined in JavaScript files contained within `src/Elm/Kernel/`. +Each row in the table corresponds to a function, each kernel module (a JavaScript file) will span multiple rows, one for each function defined in that module. + +These kernel functions are private to `elm/core` and thus they can only be called by other functions in `elm/core`. +The last column of the table contains a best effort to exhustively list all the places that call each kernel function. + +# List of all kernel functions + +| Module | Function | Notes | Used by | +| ------------------------- | ------------- | ------------- | ------------- | +| `Elm.Kernel.Basics` | `add` | [1](###1) | `Basics.add` | +| | `sub` | [1](###1) | `Basics.sub` | +| | `mul` | [1](###1) | `Basics.mul` | +| | `fdiv` | [1](###1) | `Basics.fdiv` | +| | `idiv` | [1](###1) | `Basics.idiv` | +| | `pow` | [1](###1) | `Basics.pow` | +| | `pow` | todo... | +| | `remainderBy` | todo... | +| | `modBy` | todo... | +| | `pi` | todo... | +| | `e` | todo... | +| | `cos` | todo... | +| | `sin` | todo... | +| | `tan` | todo... | +| | `acos` | todo... | +| | `asin` | todo... | +| | `atan` | todo... | +| | `atan2` | todo... | +| | `toFloat` | todo... | +| | `truncate` | todo... | +| | `isInfinite` | todo... | +| | `ceiling` | todo... | +| | `floor` | todo... | +| | `round` | todo... | +| | `sqrt` | todo... | +| | `log` | todo... | +| | `isNaN` | todo... | +| | `not` | todo... | +| | `and` | todo... | +| | `or` | todo... | +| | `xor` | todo... | +| `Elm.Kernel.Bitwise` | todo... | +| `Elm.Kernel.Char` | todo... | +| `Elm.Kernel.Debug` | todo... | +| `Elm.Kernel.JsArray` | todo... | +| `Elm.Kernel.List` | todo... | +| `Elm.Kernel.Platform` | todo... | +| `Elm.Kernel.Process` | todo... | +| `Elm.Kernel.Scheduler` | todo... | +| `Elm.Kernel.String` | todo... | +| `Elm.Kernel.Utils` | todo... | + +## Notes + +### 1 + +For elm code like `x + y` or `time / 60`, the official compiler generates javascript using the operators directly. +These functions will only be called if the user does `add x y` or `fdiv time 60`. +I (Harry Sarson) belive that `Basics.add` calls `Elm.Kernel.Basics.add` entirely so that the type resolution part of the compiler can treat `(+)` as an operator defined by `infix left 6 (+) = add`. +The code generation part of the compiler then special cases these operators. From 1aebc7829855b14055e95772450ff280ad7236ca Mon Sep 17 00:00:00 2001 From: Harry Sarson Date: Tue, 13 Aug 2019 16:23:44 +0200 Subject: [PATCH 2/5] Add bitwise functions --- docs/core/kernel-code.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/core/kernel-code.md b/docs/core/kernel-code.md index e360ebd0..aaf86e94 100644 --- a/docs/core/kernel-code.md +++ b/docs/core/kernel-code.md @@ -41,7 +41,13 @@ The last column of the table contains a best effort to exhustively list all the | | `and` | todo... | | | `or` | todo... | | | `xor` | todo... | -| `Elm.Kernel.Bitwise` | todo... | +| `Elm.Kernel.Bitwise` | `and` | todo... | +| | `or` | todo... | +| | `xor` | todo... | +| | `complement` | todo... | +| | `shiftLeftBy` | todo... | +| | `shiftRightBy` | todo... | +| | `shiftRightZfBy` | todo... | | `Elm.Kernel.Char` | todo... | | `Elm.Kernel.Debug` | todo... | | `Elm.Kernel.JsArray` | todo... | From 4c04bb7104d757feb8e1ee2fbdcdddcf9e3cbb00 Mon Sep 17 00:00:00 2001 From: Harry Sarson Date: Wed, 14 Aug 2019 16:07:33 +0200 Subject: [PATCH 3/5] begin to document platform module --- docs/core/kernel-code.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/core/kernel-code.md b/docs/core/kernel-code.md index aaf86e94..082ab23d 100644 --- a/docs/core/kernel-code.md +++ b/docs/core/kernel-code.md @@ -52,7 +52,31 @@ The last column of the table contains a best effort to exhustively list all the | `Elm.Kernel.Debug` | todo... | | `Elm.Kernel.JsArray` | todo... | | `Elm.Kernel.List` | todo... | -| `Elm.Kernel.Platform` | todo... | +| `Elm.Kernel.Platform` | `worker` | | `Platform.worker` | +| | `initialize` | | `Elm.Kernel.Browser.document`, `Elm.Kernel.Browser.element` in `elm/browser` | +| | `registerPreload` | [Preload](###Preload) | Never used. | +| | `setupEffects` | | `Elm.Kernel.Platform.Initialize` | +| | `createManager` | | Compiler generated JavaScript for event managers. | | +| | `instantiateManager` | | `Elm.Kernel.Platform.setupEffects` | +| | `sendToApp` | | `Platform.sendToApp` | +| | `sendToSelf` | | `Platform.sendToSelf` | +| | `leaf` | | `Elm.Kernel.Platform.outgoingPort`, `Elm.Kernel.incomingPort`, Compiler generated JavaScript for event managers. | +| | `batch` | | `Platform.Cmd.batch`, `Platform.Sub.batch` | +| | `map` | | `Platform.Cmd.map`, `Platform.Sub.map` | +| | `dispatchEffects` | | todo... | +| | `gatherEffects` | | todo... | +| | `toEffect` | | todo... | +| | `insert` | | todo... | +| | `checkPortName` | | todo... | +| | `outgoingPort` | | todo... | +| | `outgoingPortMap` | | todo... | +| | `setupOutgoingPort` | | todo... | +| | `incomingPort` | | todo... | +| | `incomingPortMap` | | todo... | +| | `setupIncomingPort` | | todo... | +| | `export` | | todo... | +| | `mergeExportsProd` | | todo... | +| | `mergeExportsDebug` | | todo... | `Elm.Kernel.Process` | todo... | | `Elm.Kernel.Scheduler` | todo... | | `Elm.Kernel.String` | todo... | From 14522201bdfb5657d230495c608d81ccbd486197 Mon Sep 17 00:00:00 2001 From: Harry Sarson Date: Wed, 14 Aug 2019 16:51:26 +0200 Subject: [PATCH 4/5] remove prod/debug --- docs/core/kernel-code.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/core/kernel-code.md b/docs/core/kernel-code.md index 082ab23d..e54c98fc 100644 --- a/docs/core/kernel-code.md +++ b/docs/core/kernel-code.md @@ -75,8 +75,7 @@ The last column of the table contains a best effort to exhustively list all the | | `incomingPortMap` | | todo... | | | `setupIncomingPort` | | todo... | | | `export` | | todo... | -| | `mergeExportsProd` | | todo... | -| | `mergeExportsDebug` | | todo... +| | `mergeExports` | | todo... | | `Elm.Kernel.Process` | todo... | | `Elm.Kernel.Scheduler` | todo... | | `Elm.Kernel.String` | todo... | From 8e017fb09c7a97679ab81aabd3df51514170ee95 Mon Sep 17 00:00:00 2001 From: Harry Sarson Date: Thu, 15 Aug 2019 14:19:35 +0100 Subject: [PATCH 5/5] add global mutable variables info --- docs/core/kernel-code.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/core/kernel-code.md b/docs/core/kernel-code.md index e54c98fc..9ea6fe01 100644 --- a/docs/core/kernel-code.md +++ b/docs/core/kernel-code.md @@ -81,6 +81,13 @@ The last column of the table contains a best effort to exhustively list all the | `Elm.Kernel.String` | todo... | | `Elm.Kernel.Utils` | todo... | +## List of all global mutable state + +| Module | Variable name | Notes | Used by | +| ------------------------- | ------------------ | ------------------------ | --------------------- | +| `Elm.Kernel.Platform` | `preload` | [Preload](###Preload) | Never used. | +| `Elm.Kernel.Platform` | `effectManagers` | [Effects](###Effects) | todo... | + ## Notes ### 1 @@ -89,3 +96,11 @@ For elm code like `x + y` or `time / 60`, the official compiler generates javasc These functions will only be called if the user does `add x y` or `fdiv time 60`. I (Harry Sarson) belive that `Basics.add` calls `Elm.Kernel.Basics.add` entirely so that the type resolution part of the compiler can treat `(+)` as an operator defined by `infix left 6 (+) = add`. The code generation part of the compiler then special cases these operators. + +### Preload + +Looks like something that was introduced during the exploration of server side rendering. + +### Effects + +Todo...