Adding more documentation

This commit is contained in:
Jeff Avallone 2015-04-16 17:52:50 -04:00
parent 5917d2b035
commit b2e7bade04
3 changed files with 51 additions and 2 deletions

View File

@ -1,3 +1,9 @@
// Entry point for the JavaScript-flavor regular expression parsing and
// rendering. Actual parsing code is in
// [parser.js](./javascript/parser.html) and the grammar file. Rendering code
// is contained in the various subclasses of
// [Node](./javascript/node.html)
import Snap from 'snapsvg'; import Snap from 'snapsvg';
import _ from 'lodash'; import _ from 'lodash';
@ -6,6 +12,10 @@ import javascript from './javascript/parser.js';
import ParserState from './javascript/parser_state.js'; import ParserState from './javascript/parser_state.js';
export default class Parser { export default class Parser {
// - __container__ - DOM node that will contain the rendered expression
// - __options.keepContent__ - Boolean indicating if content of the container
// should be preserved after rendering. Defaults to false (don't keep
// contents)
constructor(container, options) { constructor(container, options) {
this.options = options || {}; this.options = options || {};
_.defaults(this.options, { _.defaults(this.options, {
@ -14,9 +24,15 @@ export default class Parser {
this.container = container; this.container = container;
// The [ParserState](./javascript/parser_state.html) instance is used to
// communicate between the parser and a running render, and to update the
// progress bar for the running render.
this.state = new ParserState(this.container.querySelector('.progress div')); this.state = new ParserState(this.container.querySelector('.progress div'));
} }
// DOM node that will contain the rendered expression. Setting this will add
// the base markup necessary for rendering the expression, and set the
// `svg-container` class
set container(cont) { set container(cont) {
this._container = cont; this._container = cont;
this._container.innerHTML = [ this._container.innerHTML = [
@ -30,23 +46,28 @@ export default class Parser {
return this._container; return this._container;
} }
// Helper method to simplify adding classes to the container.
_addClass(className) { _addClass(className) {
this.container.className = _(this.container.className.split(' ')) this.container.className = _(this.container.className.split(' '))
.union([className]) .union([className])
.value()
.join(' '); .join(' ');
} }
// Helper method to simplify removing classes from the container.
_removeClass(className) { _removeClass(className) {
this.container.className = _(this.container.className.split(' ')) this.container.className = _(this.container.className.split(' '))
.without(className) .without(className)
.value()
.join(' '); .join(' ');
} }
// Parse a regular expression into a tree of
// [Nodes](./javascript/node.html) that can then be used to render an SVG.
// - __expression__ - Regular expression to parse.
parse(expression) { parse(expression) {
this._addClass('loading'); this._addClass('loading');
// Allow the browser to repaint before parsing so that the loading bar is
// displayed before the (possibly lengthy) parsing begins.
return util.tick().then(() => { return util.tick().then(() => {
javascript.Parser.SyntaxNode.state = this.state; javascript.Parser.SyntaxNode.state = this.state;
@ -55,10 +76,13 @@ export default class Parser {
}); });
} }
// Render the parsed expression to an SVG.
render() { render() {
var svg = Snap(this.container.querySelector('svg')); var svg = Snap(this.container.querySelector('svg'));
return this.parsed.render(svg.group()) return this.parsed.render(svg.group())
// Once rendering is complete, the rendered expression is positioned and
// the SVG resized to create some padding around the image contents.
.then(result => { .then(result => {
var box = result.getBBox(); var box = result.getBBox();
@ -69,16 +93,19 @@ export default class Parser {
height: box.height + 20 height: box.height + 20
}); });
}) })
// Stop and remove loading indicator after render is totally complete.
.then(() => { .then(() => {
this._removeClass('loading'); this._removeClass('loading');
this.container.removeChild(this.container.querySelector('.progress')); this.container.removeChild(this.container.querySelector('.progress'));
}); });
} }
// Cancels any currently in-progress render.
cancel() { cancel() {
this.state.cancelRender = true; this.state.cancelRender = true;
} }
// Returns any warnings that may have been set during the rendering process.
get warnings() { get warnings() {
return this.state.warnings; return this.state.warnings;
} }

View File

@ -1,3 +1,7 @@
// Sets up the parser generated by canopy to use the
// [Node](./javascript/node.html) subclasses in the generated tree. This is all
// a bit of a hack that is dependent on how canopy creates nodes in its parse
// tree.
import parser from './grammar.peg'; import parser from './grammar.peg';
import Node from './node.js'; import Node from './node.js';
@ -18,7 +22,15 @@ import RepeatOptional from './repeat_optional.js';
import RepeatRequired from './repeat_required.js'; import RepeatRequired from './repeat_required.js';
import RepeatSpec from './repeat_spec.js'; import RepeatSpec from './repeat_spec.js';
// Canopy creates an instance of SyntaxNode for each element in the tree, then
// adds any necessary fields to that instance. In this case, we're replacing
// the default class with the Node class.
parser.Parser.SyntaxNode = Node; parser.Parser.SyntaxNode = Node;
// Once the SyntaxNode instance is created, the specific node type object is
// overlayed onto it. This causes the module attribute on the Node to be set,
// which updates the Node instance into the more specific "subclass" that is
// used for rendering.
parser.Parser.Root = { module: Root }; parser.Parser.Root = { module: Root };
parser.Parser.Regexp = { module: Regexp }; parser.Parser.Regexp = { module: Regexp };
parser.Parser.Match = { module: Match }; parser.Parser.Match = { module: Match };

View File

@ -1,13 +1,23 @@
// State tracking for an in-progress parse and render.
export default class ParserState { export default class ParserState {
// - __progress__ - DOM node to update to indicate completion progress.
constructor(progress) { constructor(progress) {
// Tracks the number of capture groups in the expression.
this.groupCounter = 1; this.groupCounter = 1;
// Cancels the in-progress render when set to true.
this.cancelRender = false; this.cancelRender = false;
// Warnings that have been generated while rendering.
this.warnings = []; this.warnings = [];
// Used to display the progress indicator
this._renderCounter = 0; this._renderCounter = 0;
this._maxCounter = 0; this._maxCounter = 0;
this._progress = progress; this._progress = progress;
} }
// Counts the number of in-progress rendering steps. As the counter goes up,
// a maximum value is also tracked. The maximum value and current render
// counter are used to calculate the completion process.
get renderCounter() { get renderCounter() {
return this._renderCounter; return this._renderCounter;
} }