mirror of
https://github.com/unisonweb/unison.git
synced 2024-09-11 10:35:57 +03:00
remove outdated stuff from README, move elm-editor related stuff to elm-editor/README rather than polluting main
This commit is contained in:
parent
e304522ad4
commit
e9213a8b7f
149
README.md
149
README.md
@ -11,82 +11,50 @@ Since Unison isn't terribly useful in its current form, the rest of this README
|
||||
|
||||
Still here? All right then! Let's get to it.
|
||||
|
||||
### Build intructions
|
||||
|
||||
Building the project is easy. You do not need to have anything set up in advance. Here are complete instructions:
|
||||
|
||||
```
|
||||
$ git clone https://github.com/unisonweb/platform.git unisonweb
|
||||
$ cd unisonweb
|
||||
$ # If you don't have Nix 1.8+ or later (see note below)
|
||||
$ ./nix-install.sh
|
||||
...
|
||||
$ cd node
|
||||
$ ./shell.sh
|
||||
$ cabal run node # cabal repl, cabal test also work
|
||||
Running node...
|
||||
Setting phasers to stun... (port 8080) (ctrl-c to quit)
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
* Unison uses the [Nix package manager](https://nixos.org/nix/) to ensure the project can be built with a consistent, stable set of dependencies. Run `nix-install.sh` if you don't already have nix 1.8 or later installed. Or you can install Nix manually if you like.
|
||||
* The first time you do this, Nix to download and install all third-party dependencies, including the right version the Haskell compiler. These will be added to your Nix package manager store and won't conflict with any other versions you might have installed on your system.
|
||||
* That last line is a message from [Scotty](https://hackage.haskell.org/package/scotty) telling you that the node HTTP server is running. Leave that running for now.
|
||||
* If you're working on `shared` or `editor`, `cd node`, then `./shell.sh`. Then use cabal as normal.
|
||||
|
||||
|
||||
Next, the _editor_. For this you'll need to install [Elm 0.15](http://elm-lang.org/Install.elm) first.
|
||||
|
||||
```
|
||||
$ cd editor-elm
|
||||
$ elm make src/Unison/Editor.elm
|
||||
Some new packages are needed. Here is the upgrade plan.
|
||||
|
||||
Install:
|
||||
elm-lang/core 2.0.1
|
||||
evancz/elm-http 1.0.0
|
||||
|
||||
Do you approve of this plan? (y/n) y
|
||||
Downloading elm-lang/core
|
||||
Downloading evancz/elm-http
|
||||
Packages configured successfully!
|
||||
Compiled 62 files
|
||||
Successfully generated elm.js
|
||||
$ elm reactor
|
||||
Elm Reactor 0.3.1 (Elm Platform 0.15)
|
||||
Listening on http://0.0.0.0:8000/
|
||||
```
|
||||
|
||||
Now open up a browser and go to `http://0.0.0.0:8000/`. Navigate to `src/Unison/Editor.elm`. You should see the Unison expression editor, initially consisting of a single `_`. You can navigate around with the keyboard or mouse. Use `<Enter>` or a click to open a node for editing. Some other keyboard commands:
|
||||
|
||||
* `<Enter>` accepts the current selection in the explorer, and arrow keys or the mouse navigate.
|
||||
* When the explorer is closed:
|
||||
* `'s'` performs linking + 1 beta reduction of the selected expression.
|
||||
* `'e'` evaluates the selected expression to weak head normal form.
|
||||
* `'a'` wraps the current selection in a function call, initially blank
|
||||
* `'v'` switches between the 'raw' and interpreted view
|
||||
|
||||
Somewhat annoying---when the explorer pops up, it doesn't get focus. Hit tab once to make the focus active, or click in the text box. You might notice some other minor issues.
|
||||
|
||||
If you have the elm reactor running, you can make edits to the code, save, and refresh the page to see them.
|
||||
|
||||
### A brief code tour
|
||||
|
||||
First, a bit of orientation. Here's the directory structure:
|
||||
|
||||
```
|
||||
editor-elm/
|
||||
shared/
|
||||
node/
|
||||
editor/
|
||||
editor-elm/
|
||||
```
|
||||
|
||||
The `editor-elm/` directory is the current Elm implementation of the Unison editor. So what's with the directory structure? Well, Elm is being phased out, and the editor is likely getting a rewrite in Haskell, with the code compiled via [GHCJS](https://github.com/ghcjs/ghcjs). The `shared/` directory has Haskell code that will be shared between the editor and node, the `node/` directory has code specific to the node, and `editor/` is currently empty but will house the Haskell version of the editor.
|
||||
The `editor-elm/` directory is the current Elm implementation of the Unison editor. It's being phased out, in favor of a Unison editor written in Haskell and compiled to Javascript via [GHCJS](https://github.com/ghcjs/ghcjs). Thus, we can share code between the editor and Unison node backend. So what's with the directory structure? . The `shared/` directory has Haskell code that will be shared between the editor and node, the `node/` directory has code specific to the node, and `editor/` is the currently-in-development Haskell version of the editor, which also depends on `shared/`.
|
||||
|
||||
Though the rewrite hasn't happened yet, having a stable directory structure means development can easily proceed concurrently on both the new editor and other stuff like the typechecker, the language, the standard library, etc.
|
||||
The dependencies are what you'd expect---`shared/` has minimal external dependencies, and `node/` and `editor/` depend on `shared`. Thus, it should be very obvious and explicit what code and external dependencies are going to be compiled to JS.
|
||||
|
||||
The dependencies are what you'd expect---`shared/` has minimal external dependencies, and `node/` (and later `editor/`) depend on `shared`. Thus, it should be very obvious and explicit what code and external dependencies are going to be compiled to JS.
|
||||
### Build intructions
|
||||
|
||||
Building the project is easy. You do not need to have anything installed or set up in advance. Here are complete instructions:
|
||||
|
||||
```
|
||||
$ git clone https://github.com/unisonweb/platform.git unisonweb
|
||||
$ cd unisonweb
|
||||
$ # If you don't have Nix 1.8 or later (see note below)
|
||||
$ ./install-nix.sh
|
||||
```
|
||||
|
||||
After install completes, you'll see instructions about starting a fresh terminal session or sourcing the given command. Do that, then:
|
||||
|
||||
```
|
||||
$ cd node
|
||||
$ ./shell.sh
|
||||
```
|
||||
|
||||
Each subproject has a `shell.sh` file to download and build any needed dependencies, and drop you into a shell where you can use cabal as normal. So there's `node/shell.nix`, `shared/shell.nix`, and `editor/shell.nix`. You'll see lots of output the first time you run one of these, as they use Nix to download and build dependencies, and you may see some warnings about Haddock documentation that you can ignore. Subsequent launches will be snappy since you'll have all the dependencies in your Nix store.
|
||||
|
||||
Once that's done, you'll be in a Nix shell and can use cabal as normal:
|
||||
|
||||
```
|
||||
$ cabal run node # cabal repl, cabal test also work
|
||||
Running node...
|
||||
Setting phasers to stun... (port 8080) (ctrl-c to quit)
|
||||
```
|
||||
|
||||
That last line is a message from [Scotty](https://hackage.haskell.org/package/scotty) telling you that the node HTTP server is running.
|
||||
|
||||
### A brief code tour of the Haskell code
|
||||
|
||||
@ -106,57 +74,4 @@ Now, where to begin? Everyone learns differently. You might prefer to read the c
|
||||
|
||||
If instead, you'd rather work from the 'outside in' (or perhaps 'top down'), you could start with `Unison.NodeServer` and work your way back the other direction to modules like `Term`, `Type`, and `ABT`. Since the entire point of the node codebase is to expose an API over HTTP, `Unison.NodeServer` will end up referencing directly or indirectly all the code in the node, and all the Unison language and typechecker.
|
||||
|
||||
### A brief code tour of the current Unison editor
|
||||
|
||||
The Unison editor, living in the `editor-elm/` subdirectory, and written in Elm, is also not much code right now:
|
||||
|
||||
```
|
||||
$ cd editor-elm
|
||||
$ find src -name '*.elm' | xargs wc -l
|
||||
24 src/Elmz/Distance.elm
|
||||
80 src/Elmz/Json/Decoder.elm
|
||||
109 src/Elmz/Json/Encoder.elm
|
||||
50 src/Elmz/Json/Request.elm
|
||||
292 src/Elmz/Layout.elm
|
||||
8 src/Elmz/List.elm
|
||||
54 src/Elmz/Matcher.elm
|
||||
48 src/Elmz/Maybe.elm
|
||||
83 src/Elmz/Mealy.elm
|
||||
107 src/Elmz/Moore.elm
|
||||
115 src/Elmz/Movement.elm
|
||||
148 src/Elmz/Parser.elm
|
||||
8 src/Elmz/Result.elm
|
||||
76 src/Elmz/Selection1D.elm
|
||||
211 src/Elmz/Signal.elm
|
||||
75 src/Elmz/Trie.elm
|
||||
6 src/Elmz/Void.elm
|
||||
39 src/Unison/Action.elm
|
||||
131 src/Unison/EditableTerm.elm
|
||||
314 src/Unison/Editor.elm
|
||||
17 src/Unison/Hash.elm
|
||||
93 src/Unison/Metadata.elm
|
||||
149 src/Unison/Node.elm
|
||||
119 src/Unison/Path.elm
|
||||
43 src/Unison/Reference.elm
|
||||
98 src/Unison/Scope.elm
|
||||
87 src/Unison/SearchboxParser.elm
|
||||
231 src/Unison/Styles.elm
|
||||
54 src/Unison/Symbol.elm
|
||||
329 src/Unison/Term.elm
|
||||
311 src/Unison/TermExplorer.elm
|
||||
47 src/Unison/Terms.elm
|
||||
130 src/Unison/Type.elm
|
||||
380 src/Unison/View.elm
|
||||
4066 total
|
||||
```
|
||||
|
||||
Since most of this code will likely be getting a rewrite when moving away Elm, we'll avoid going into too much detail. At a high level:
|
||||
|
||||
* The `Elmz` package has various utility modules, not specific to Unison.
|
||||
* The `Unison.Editor` module is the main entry point for the editor.
|
||||
* Many of the modules in the `Unison` package mirror their counterparts in Haskell. The representation of terms and types is a bit different from the Haskell side. Unfortunately, Elm's type system cannot represent abstract binding trees, so the the JSON encoders/decoders in Elm convert both terms and types to and from simpler, more Elm-friendly represenations.
|
||||
* There are a few modules which get used a lot:
|
||||
* `Elmz.Layout`, which I'm calling an 'annotated layout tree'. It's a pretty simple idea that lets us use regular pure functions to do hit testing, compute selection highlight regions, and so on. There's a description of the technique and some discussion [in this blog post](http://pchiusano.github.io/2014-12-10/wormhole-antipattern.html). The editor uses this in lots of places.
|
||||
* `Elmz.Moore` and `Elmz.Mealy` are pure state machine types, with the minor twist that they may drop events. Most of the components of the editor UI are defined as some `Moore i o`, where `i` will be some type which is the union of all events that component can receive, and where `o` might be a view and some other values to pass along. `Moore` and `Mealy` values can be assembled using various combinators, created with recursion, and fed explicitly. This all works out okay and is pretty simple, but it also requires some manual plumbing.
|
||||
|
||||
That's all for now!
|
||||
|
89
editor-elm/README.md
Normal file
89
editor-elm/README.md
Normal file
@ -0,0 +1,89 @@
|
||||
This is the Elm version of the Unison editor. It is no longer being maintained and will be replaced by a Haskell version, currently in development (see the `editor/`) directory.
|
||||
|
||||
If you want to run this, you'll need to install [Elm 0.15](http://elm-lang.org/Install.elm) first. Make sure you have a node running (via a `cabal run node` in the `node/` subproject shell) as well, since the editor has to talk to the node.
|
||||
|
||||
```
|
||||
$ cd editor-elm
|
||||
$ elm make src/Unison/Editor.elm
|
||||
Some new packages are needed. Here is the upgrade plan.
|
||||
|
||||
Install:
|
||||
elm-lang/core 2.0.1
|
||||
evancz/elm-http 1.0.0
|
||||
|
||||
Do you approve of this plan? (y/n) y
|
||||
Downloading elm-lang/core
|
||||
Downloading evancz/elm-http
|
||||
Packages configured successfully!
|
||||
Compiled 62 files
|
||||
Successfully generated elm.js
|
||||
$ elm reactor
|
||||
Elm Reactor 0.3.1 (Elm Platform 0.15)
|
||||
Listening on http://0.0.0.0:8000/
|
||||
```
|
||||
|
||||
Now open up a browser and go to `http://0.0.0.0:8000/`. Navigate to `src/Unison/Editor.elm`. You should see the Unison expression editor, initially consisting of a single `_`. You can navigate around with the keyboard or mouse. Use `<Enter>` or a click to open a node for editing. Some other keyboard commands:
|
||||
|
||||
* `<Enter>` accepts the current selection in the explorer, and arrow keys or the mouse navigate.
|
||||
* When the explorer is closed:
|
||||
* `'s'` performs linking + 1 beta reduction of the selected expression.
|
||||
* `'e'` evaluates the selected expression to weak head normal form.
|
||||
* `'a'` wraps the current selection in a function call, initially blank
|
||||
* `'v'` switches between the 'raw' and interpreted view
|
||||
|
||||
Somewhat annoying---when the explorer pops up, it doesn't get focus. Hit tab once to make the focus active, or click in the text box. You might notice some other minor issues.
|
||||
|
||||
If you have the elm reactor running, you can make edits to the code, save, and refresh the page to see them.
|
||||
|
||||
### A brief code tour
|
||||
|
||||
The Elm-based Unison editor is not much code:
|
||||
|
||||
```
|
||||
$ cd editor-elm
|
||||
$ find src -name '*.elm' | xargs wc -l
|
||||
24 src/Elmz/Distance.elm
|
||||
80 src/Elmz/Json/Decoder.elm
|
||||
109 src/Elmz/Json/Encoder.elm
|
||||
50 src/Elmz/Json/Request.elm
|
||||
292 src/Elmz/Layout.elm
|
||||
8 src/Elmz/List.elm
|
||||
54 src/Elmz/Matcher.elm
|
||||
48 src/Elmz/Maybe.elm
|
||||
83 src/Elmz/Mealy.elm
|
||||
107 src/Elmz/Moore.elm
|
||||
115 src/Elmz/Movement.elm
|
||||
148 src/Elmz/Parser.elm
|
||||
8 src/Elmz/Result.elm
|
||||
76 src/Elmz/Selection1D.elm
|
||||
211 src/Elmz/Signal.elm
|
||||
75 src/Elmz/Trie.elm
|
||||
6 src/Elmz/Void.elm
|
||||
39 src/Unison/Action.elm
|
||||
131 src/Unison/EditableTerm.elm
|
||||
314 src/Unison/Editor.elm
|
||||
17 src/Unison/Hash.elm
|
||||
93 src/Unison/Metadata.elm
|
||||
149 src/Unison/Node.elm
|
||||
119 src/Unison/Path.elm
|
||||
43 src/Unison/Reference.elm
|
||||
98 src/Unison/Scope.elm
|
||||
87 src/Unison/SearchboxParser.elm
|
||||
231 src/Unison/Styles.elm
|
||||
54 src/Unison/Symbol.elm
|
||||
329 src/Unison/Term.elm
|
||||
311 src/Unison/TermExplorer.elm
|
||||
47 src/Unison/Terms.elm
|
||||
130 src/Unison/Type.elm
|
||||
380 src/Unison/View.elm
|
||||
4066 total
|
||||
```
|
||||
|
||||
Since most of this code will likely be getting a rewrite when moving away Elm, we'll avoid going into too much detail. At a high level:
|
||||
|
||||
* The `Elmz` package has various utility modules, not specific to Unison.
|
||||
* The `Unison.Editor` module is the main entry point for the editor.
|
||||
* Many of the modules in the `Unison` package mirror their counterparts in Haskell. The representation of terms and types is a bit different from the Haskell side. Unfortunately, Elm's type system cannot represent abstract binding trees, so the the JSON encoders/decoders in Elm convert both terms and types to and from simpler, more Elm-friendly represenations.
|
||||
* There are a few modules which get used a lot:
|
||||
* `Elmz.Layout`, which I'm calling an 'annotated layout tree'. It's a pretty simple idea that lets us use regular pure functions to do hit testing, compute selection highlight regions, and so on. There's a description of the technique and some discussion [in this blog post](http://pchiusano.github.io/2014-12-10/wormhole-antipattern.html). The editor uses this in lots of places.
|
||||
* `Elmz.Moore` and `Elmz.Mealy` are pure state machine types, with the minor twist that they may drop events. Most of the components of the editor UI are defined as some `Moore i o`, where `i` will be some type which is the union of all events that component can receive, and where `o` might be a view and some other values to pass along. `Moore` and `Mealy` values can be assembled using various combinators, created with recursion, and fed explicitly. This all works out okay and is pretty simple, but it also requires some manual plumbing.
|
Loading…
Reference in New Issue
Block a user