AlON-diff

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

No 'category' field.
No 'synopsis' field.

Please see the README on GitHub at https://github.com/githubuser/AlON-diff#readme

[Skip to Readme]

Properties

Versions	0
Change log	ChangeLog.md
Dependencies	aeson, AlON-diff, atomic-primops, base (>=4.7 && <5), base16-bytestring, base64, bytes, bytestring, concurrent-extra, containers, cryptohash, directory, filepath, fsnotify, html-entities, html-parse, memory, text, word8 [details]
License	BSD-3-Clause
Copyright	2018 xkcd inc.
Author	Conor Stokes
Maintainer	conor.stokes@burningcandle.io
Home page	https://github.com/githubuser/AlON-diff#readme
Bug tracker	https://github.com/githubuser/AlON-diff/issues
Source repo	head: git clone https://github.com/githubuser/AlON-diff
Uploaded	by davean at 2020-01-17T00:25:12Z

Modules

ALON
- Diff
  - ALON.Diff.HTML

Downloads

AlON-diff-0.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

davean

For package maintainers and hackage trustees

edit package information

Readme for AlON-diff-0

[back to package description]

## AlON-diff AlON-diff is a set of libraries and utilities that allow deltas between HTML pages to be constructed on a server, then applied dynamically in the web-browser.

There are two main libraries:

A back-end library (AlON.Diff.HTML), written in Haskell, that allows the construction of the deltas (as well as some support functions). It is located in the src directory of the repository.
A front-end library, written in TypeScript (compiled to JavaScript), that allows dynamic patching of a web-page in the browser (using as few DOM updates as possible) using the JSON serialized delta generated by the back-end. Note, the front-end source is entirely located in the frontend directory of the repository.

There are also some utilities and a library test-suite written in Haskell. The utilities include:

AlON-diff-watcher, located in the watcher directory in the repository, which watches a HTML file for changes and produces deltas automatically.
AlON-diff-differ, located in the differ directory in the repository, which allows manual creation of a diff between two pages, outputting the JSON serialized diff to stdout.
AlON-diff-chunktree, located in the chunktree directory in the repository, which outputs the content defined Merkle tree intermediate representation that is used to build deltas to stdout.

As well as this, there is a demonstration, which allows live-updates to a web-page as changes are saved. This has a front-end component (demo.html and alOn-diff-watcher.ts) and uses AlON-diff-watcher as the back-end component.

Building the Back-end

The back-end library, test suite and utilities are currently built with stack. Stack will automatically download the build tools and dependencies required for building.

You can build all the back-end library utilities with the command, in the root of the repository:

stack build

Note, it is also possible to run the back-end test suite using the command:

stack test

Building the Front-end

The front-end requires npm and the TypeScript compiler to build. Note, the pre-built JavaScript files are in the repository, so the TypeScript compiler is not required unless you intend to modify the code, or re-build the JavaScript files with modified settings.

First install npm, then install the TypeScript compiler using this command (note, this command might require administrator/super user privileges):

npm install -g typescript

Then, navigate to the frontend directory in the repository and run the following command, to download the TypeScript type dependencies and JavaScript dependencies required for the frontend/demo:

npm install

If you wish to build the TypeScript project, to compile it into JavaScript, navigate to the frontend directory and run the command:

tsc -b

Running the Live-Update Demo

The repository contains the components for a live-update demo, that enables you to edit a file (frontend/demo.html) and have it live-update in a browser with minimal updates.

To run the back-end side of the demo (after you have installed the dependencies for the front-end), and after building the back-end, run the following command from the repository root:

stack exec AlON-diff-watcher ./frontend/demo.html

This will watch the demo.html file for changes. If you update this file and save it, it will automatically generate patches, as long as the watcher is running. Note, even if you stop the watcher running, you can still run the demo and previously existing patches will be applied on the client side, but no new patches will be generated. Each time you run the watcher however, previous patches are cleaned up and the watcher starts from a new baseline.

To see the demo in action, serve the frontend directory on a web-server, and navigate to frontend/base.html. The base.html file is a copy of the demo.html file made when the watcher is initially run, to create a base-line state, which the entire sequence of patches can be applied to.

A quick way to create a web-server to serve the directory with npm already being installed is installing the npm http-server module, which can be installed with the following command (note, it may require administrator/super user privileges):

sudo npm install http-server -g

Then the following command run from the root of the repository will start a server on port 5125, so you can navigate to http://localhost:5125/frontend/base.html to see the live updates:

http-server -p 5125

Note, for the demo to work successfully at live-updating, both the watcher and the web-server should be running at the same time.

Currently, the demo has been tested with Chrome (69.0.3497.100), Firefox (62.0.2), Edge (42.17134.1.0), Opera (56.0.3051.36), Android Chrome (69.0.3497.100).