Skip to content

Commit

Permalink
This is a big change to client side libraries API.
Browse files Browse the repository at this point in the history 
Editor.js is now split among cursor.js, menu-builder.js, forest.js
Event listener is used across libraries to notify each other of events.
See reference.md for better description.
  • Loading branch information
@yangit
yangit committed Nov 7, 2014
1 parent 41ea672 commit ff21837
Show file tree
Hide file tree
Showing 20 changed files with 1,187 additions and 1,150 deletions.
35 changes: 23 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,22 +27,33 @@ Please refer to the [./doc](./doc) for features, architecture, contributing, etc

## Quick Start

Install:

$ npm install
Run:

$ npm start
###Install:

cd puddle-server
npm install
cd ..
cd puddle-editor
npm install

###Run:
Two terminal windows:

One:

cd puddle-server
npm run develop # Ctrl-C to stop

Two:

cd puddle-editor
npm run develop # Ctrl-C to stop

Then navigate to <http://localhost:34934/>

## Develop mode:

$ npm run develop-editor # Ctrl-C to stop
In another terminal
## Deploy mode:

Same as above but you can use `npm start` istead of `npm run develop`

$ npm run develop-server # Ctrl-C to stop



Expand Down
173 changes: 63 additions & 110 deletions doc/reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,18 @@
* [Server socket.io API](#server-socketio)
* [Client `TODO.js`](#todojs)
* [Client `assert.js`](#assertjs)
* [Client `log.js`](#logjs)
* [Client `keycode.js`](#keycodejs)
* [Client `test.js`](#testjs)
* [Client `trace.js`](#tracejs)
* [Client `corpus.js`](#corpusjs)
* [Client `navigate.js`](#navigatejs)
* [Client `forest.js`](#forestjs)
* [Client `cursor.js`](#cursorjs)
* [Client `view.js`](#viewjs)
* [Client `menu.js`](#menujs)
* [Client `editor.js`](#editorjs)
* [Client `main.js`](#mainjs)
* [Client `menu-builder.js`](#menubuilder)
* [Client `menu-renderer.js`](#menurenderer)

Related documentation:

* [puddle-syntax](https://github.com/fritzo/puddle-syntax)
* [pomagma client](https://github.com/fritzo/pomagma/blob/master/doc/client.md)
* [puddle-syntax](https://github.com/pomagma/puddle-syntax)
* [pomagma client](https://github.com/pomagma/blob/master/doc/client.md)

## Server

Expand Down Expand Up @@ -131,118 +129,73 @@ Related documentation:
var assert = require('./assert');
assert(condition, message);
assert.equal(actual, expected);
assert.forward(fwd, listOfPairs); // fwd(x) === y for each pair [x, y]
assert.backward(bwd, listOfPairs); // x === bwd(y) for each pair [x, y]
assert.inverses(fwd, bwd, listOfPairs); // fwd(x) === y && x === bwd(y)

### `log.js` <a name="logjs"/>
### `trace.js` <a name="tracejs"/>

var log = require('./log');
log('just like console.log, bug works in web workers');
Convenience method for debugging.
Allows to quikly show trace and arguments passed into function.

### `keycode.js` <a name="keycodejs"/>

Just a static dictionary of ascii key codes.

{
'backspace': 8,
'tab': 9,
'enter': 13,
'shift': 16,
...
}

### `test.js` <a name="testjs"/>

Unit testing library.

var test = require('./test');

test('test title', callback); // declares synchronous test
test.async('test title', callback); // declares async test
test.runAll(); // run all unit tests

console.log(test.testing()); // prints whether tests are being run
console.log(test.hasRun()); // prints whether tests have finished
console.log(test.testCount()); // prints cumulative test count
console.log(test.failCount()); // prints cumulative failed test count

Utilities for performing functions on trees.

var root = arborist.getRoot(indexed);
var varList = arborist.getBoundAbove(term); // -> ['a', 'b']
var varSet = arborist.getVars(term); // -> {'a': null, 'b': null}
var name = arborist.getFresh(term); // -> 'c'
var debug = require('debug')('puddle:editor');
var trace = require('./trace')(debug);

//Will output to console 'puddle:editor Hello'
//arguments converted to array.
//if third parameter is true will do console.trace() as well.
//Second and third arguments are optional
trace('Hello', arguments, true)


### `corpus.js` <a name="corpusjs"/>

Uses puddle-socket to fetch data from server
Stores corpus as `lines` internally
Provides knowledge of defenitions/occurrences
Fetches validities, emits 'updateValidity' event.
Exposes CRUD API and emits CRUD events for corpus lines.
Handles checkin/checkout of lines (w/o real blocking on server yet)
Does not care about any other modules.


### `forest.js` <a name="forestjs"/>

Stores corpus as trees internally
Keeps trees sorted
Listens for CRUD events from Corpus and reemits them as trees


### `cursor.js` <a name="cursorjs"/>

Stores/shares pointer to node in a Forest.
Does not affect nodes in any way.
Exposes various methods to move itself between nodes of Forest
Notifies corpus of check-ins, check-outs
Exposes .replaceBelow to alter trees.
Listens to Forest changes to avoid being in orphan nodes.
Emits `move` event.

Editor's view of the server-side corpus.
Each client stores an in-memory copy.

var corpus = require('./corpus');
corpus.ready(cb); // calls cb after client loads corpus from server
corpus.validate(); // validates corpus, throws AssertError if invalid
var line = corpus.findLine(id);
var lines = corpus.findAllLines();
var names = corpus.findAllNames();
var id = corpus.findDefinition(name);
if (corpus.canDefine(name)) {
// we can create a new definition of name
}
var ids = corpus.findOccurrences(name);
if (corpus.hasOccurrences(name)) {
// we cannot delete the definition of name
}
corpus.insert(line, done, fail);
corpus.update(newLine);
corpus.remove(id);

### `navigate.js` <a name="navigatejs"/>

var navigate = require('./navagate');
navigate.on(name, callback, description); // add callback
navigate.off(); // clear callbacks
navigate.trigger(event);

// search for global variable
navigate.search(rankedStrings, acceptMatch, cancel, renderString);

// create new global variable name
navigate.choose(isValidFilter, acceptName, cancel);

### `view.js` <a name="viewjs"/>

The view object is the pane on the left showing the corpus.

var view = require('./view');
view.init({
getLine: ...,
getValidity: ...,
lines: ...
});

view.insertAfter(prevId, id);
view.update(id);
view.remove(id);

### `menu.js` <a name="menujs"/>

The menu object is the pane on the right.
It rebuilds itself at every action.
The menu is the sole form of input to puddle, by design.
The view object is the pane on the left showing the corpus.
Renders corpus using trees from Forest
Listens for forest CRUD events.
Listens for cursor moves.
Listens for validities update.
Uses DOM as internal state.
Does not have API

var menu = require('./menu');
menu.init({
actions = {...}, // callbacks bound to actions
getCursor = function () {...} // returns cursor
});

### `editor.js` <a name="editorjs"/>
### `menu-builder.js` <a name="menubuilder"/>

Aware of cursor position in a forest
Knows mapping of keys <=> UI actions
Builds UI action functions using Forest and Cursor API and module.exports them
Logs every user action to server via socket.io
Does not have internal state.

var editor = require('./editor');
editor.main(); // start puddle editor

### `main.js` <a name="mainjs"/>
### `menu-renderer.js` <a name="menurenderer"/>

Main entry point, either starts unit tests or starts editor,
depending on whether `location.hash === '#test'`.
Takes array of actions/keys from menu-builder and renders it into HTML with onKeyPress events.
Listens for Cursor 'move' event to rerender menu.
Does not have internal state or API
5 changes: 1 addition & 4 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,7 @@
"description": "A responsive editor built on Pomagma",
"main": "",
"scripts": {
"test": "cd $MODULE; npm install; npm test;",
"start": "cd puddle-server; npm start",
"develop-server": "cd puddle-server; DEBUG='puddle:*' npm run develop",
"develop-editor": "cd puddle-editor; npm run develop"
"test": "cd $MODULE; npm install; npm test;"
},
"repository": {
"type": "git",
Expand Down
4 changes: 2 additions & 2 deletions puddle-editor/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ HTML app to be served by puddle-server

###Features:

[ ] Working version of editor, navigator using same render as before
[ ] Built on top of puddle-hub
[X] Working version of editor, navigator using same render as before
[X] Built on top of puddle-hub


###Installation:
Expand Down
Loading

0 comments on commit ff21837

Please sign in to comment.