unisonweb/unison
1
0
Fork 0
mirror of https://github.com/unisonweb/unison.git synced 2024-08-15 21:40:50 +03:00
Code Issues Projects Releases Wiki Activity

remove outdated stuff from README, move elm-editor related stuff to elm-editor/README rather than polluting main

Browse Source
This commit is contained in:
Paul Chiusano 2015-07-07 22:12:25 -04:00
parent e304522ad4
commit e9213a8b7f
2 changed files with 121 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
README.md
View File

@ -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
View 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.