Adding documentation to regexper.js and some minor tweaks

This commit is contained in:
Jeff Avallone 2015-04-12 16:56:49 -04:00
parent 7de958dc25
commit d918f956ef

View File

@ -1,3 +1,6 @@
// The Regexper class manages the top-level behavior for the entire
// application. This includes event handlers for all user interactions.
import util from './util.js';
import Parser from './parser/javascript.js';
import _ from 'lodash';
@ -17,7 +20,9 @@ export default class Regexper {
this.svgContainer = root.querySelector('#regexp-render');
}
// Event handler for key presses in the regular expression form field.
keypressListener(event) {
// Pressing Shift-Enter displays the expression.
if (event.shiftKey && event.keyCode === 13) {
event.returnValue = false;
if (event.preventDefault) {
@ -28,12 +33,16 @@ export default class Regexper {
}
}
// Event handler for key presses while focused anywhere in the application.
documentKeypressListener(event) {
// Pressing escape will cancel a currently running render.
if (event.keyCode === 27 && this.running) {
this.running.cancel();
}
}
// Event handler for submission of the regular expression. Changes the URL
// hash which leads to the expression being rendered.
submitListener(event) {
event.returnValue = false;
if (event.preventDefault) {
@ -44,13 +53,14 @@ export default class Regexper {
this._setHash(this.field.value);
}
catch(e) {
// Most likely failed to set the URL has (probably because the expression
// is too long). Turn off the permalink and just show the expression
// Failed to set the URL hash (probably because the expression is too
// long). Turn off display of the permalink and just show the expression.
this.permalinkEnabled = false;
this.showExpression(this.field.value);
}
}
// Event handler for URL hash changes. Starts rendering of the expression.
hashchangeListener() {
var expr = this._getHash();
@ -64,6 +74,7 @@ export default class Regexper {
}
}
// Binds all event listeners.
bindListeners() {
this.field.addEventListener('keypress', this.keypressListener.bind(this));
this.form.addEventListener('submit', this.submitListener.bind(this));
@ -71,10 +82,15 @@ export default class Regexper {
window.addEventListener('hashchange', this.hashchangeListener.bind(this));
}
// Set the URL hash. This method exists to facilitate automated testing
// (since changing the URL can throw off most JavaScript testing tools).
_setHash(hash) {
location.hash = encodeURIComponent(hash);
}
// Retrieve the current URL hash. This method is also mostly for supporting
// automated testing, but also does some basic error handling for malformed
// URLs.
_getHash() {
try {
return decodeURIComponent(location.hash.slice(1));
@ -84,6 +100,11 @@ export default class Regexper {
}
}
// Currently state of the application. Useful values are:
// - `''` - State of the application when the page initially loads
// - `'is-loading'` - Displays the loading indicator
// - `'has-error'` - Displays the error message
// - `'has-results'` - Displays rendered results
set state(state) {
this.root.className = state;
}
@ -92,6 +113,9 @@ export default class Regexper {
return this.root.className;
}
// Start the rendering of a regular expression.
//
// - __expression__ - Regular expression to display.
showExpression(expression) {
this.field.value = expression;
this.state = '';
@ -101,25 +125,32 @@ export default class Regexper {
}
}
// Creates a blob URL for linking to a rendered regular expression image.
//
// - __content__ - SVG image markup.
buildBlobURL(content) {
var blob = new Blob([content], { type: 'image/svg+xml' });
window.blob = blob; // Blob object has to stick around for IE
return URL.createObjectURL(blob);
// Blob object has to stick around for IE, so the instance is stored on the
// `window` object.
window.blob = new Blob([content], { type: 'image/svg+xml' });
return URL.createObjectURL(window.blob);
}
// Update the URLs of the 'download' and 'permalink' links.
updateLinks() {
var classes = _.without(this.links.className.split(' '), ['hide-download', 'hide-permalink']);
// Create the 'download' image URL.
try {
this.download.parentNode.style.display = null;
this.download.href = this.buildBlobURL(this.svgContainer.querySelector('.svg').innerHTML);
}
catch(e) {
// Blobs or URLs created from them don't work here.
// Giving up on the download link
// Blobs or URLs created from a blob URL don't work in the current
// browser. Giving up on the download link.
classes.push('hide-download');
}
// Create the 'permalink' URL.
if (this.permalinkEnabled) {
this.permalink.parentNode.style.display = null;
this.permalink.href = location.toString();
@ -130,20 +161,28 @@ export default class Regexper {
this.links.className = classes.join(' ');
}
// Display any warnings that were generated while rendering a regular expression.
//
// - __warnings__ - Array of warning messages to display.
displayWarnings(warnings) {
this.warnings.innerHTML = _.map(warnings, warning => {
return `<li class="oi with-text" data-glyph="warning">${warning}</li>`;
}).join('');
}
// Render regular expression
//
// - __expression__ - Regular expression to render
renderRegexp(expression) {
var parseError = false,
startTime, endTime;
// When a render is already in progress, cancel it and try rendering again
// after a short delay (canceling a render is not instantaneous).
if (this.running) {
this.running.cancel();
util.wait(10).then(() => {
return util.wait(10).then(() => {
return this.renderRegexp(expression);
});
}
@ -155,7 +194,9 @@ export default class Regexper {
this.running = new Parser(this.svgContainer);
return this.running
// Parse the expression.
.parse(expression)
// Display any error messages from the parser and abort the render.
.catch(message => {
this.state = 'has-error';
this.error.innerHTML = '';
@ -165,9 +206,14 @@ export default class Regexper {
throw message;
})
// When parsing is successful, render the parsed expression.
.then(parser => {
return parser.render();
})
// Once rendering is complete:
// - Update links
// - Display any warnings
// - Track the completion of the render and how long it took
.then(() => {
this.state = 'has-results';
this.updateLinks();
@ -177,6 +223,9 @@ export default class Regexper {
endTime = new Date().getTime();
window._gaq.push(['_trackTiming', 'visualization', 'total time', endTime - startTime]);
})
// Handle any errors that happened during the rendering pipeline.
// Swallows parse errors and render cancellations. Any other exceptions
// are allowed to continue on to be tracked by the global error handler.
.catch(message => {
if (message === 'Render cancelled') {
window._gaq.push(['_trackEvent', 'visualization', 'cancelled']);
@ -187,6 +236,8 @@ export default class Regexper {
throw message;
}
})
// Finally, mark rendering as complete (and pass along any exceptions
// that were thrown).
.then(
() => {
this.running = false;