Provide information about packages required by TeX string.

The `check` function now returns `<foo>_required` fields to indicate
whether certain TeX packages are required to format the given string.

The change in commit 36a7aec which
changed the return value of the `parse` method was reverted, since
the extra information was added to `check` instead of `parse`.

Author: cscott

CHANGELOG.md

@@ -1,7 +1,5 @@
 # texvcjs x.x.x (not yet released)
 
-* Changed return value of low-level `parse` API to allow providing
-  more detailed information about the TeX functions encountered.
 * Switch to text mode before emitting \AA and \textvisiblespace.
 * Require mandatory argument for \overbrace, \overleftarrow,
   \overleftrightarrow, \overline, \overrightarrow, \underbrace, and
@@ -10,6 +8,8 @@
 * Be stricter when parsing \color, \definecolor, and \pagecolor.
 * Add `contains_func` to the API, to test for the presence of specific
   TeX functions in the validated/translated input string.
+* Return `<foo>_required` fields in the result of `check` to provide
+  more detailed information about the TeX functions encountered.
 
 # texvcjs 0.2.0 (2014-07-23)
 

README.md

@@ -63,6 +63,12 @@ in the `line`, `column` and `offset` fields of the result.  More information
 about the problem can be found in the `details` field of the result, which
 is a string.
 
+The fields `ams_required`, `cancel_required`, `color_required`,
+`euro_required`, and `teubner_required` are set to `true` iff the input
+string requires the use of the corresponding LaTeX packages.
+The `ams_required` field requires the use of the `amsmath` and `amssymb`
+packages.
+
 ### Low-level API
 
 The low level parser, abstract syntax tree (AST), and renderer are also

bin/texvcjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+var PACKAGES = ['ams', 'cancel', 'color', 'euro', 'teubner'];
+
 var program = require('commander');
 var util = require('util');
 
@@ -12,6 +14,16 @@ program
     .option('-v, --verbose', 'Show verbose error information')
     .option('-D, --debug', 'Show stack trace on failure');
 
+PACKAGES.forEach(function(pkg) {
+    var msg = 'Fail validation if input requires the ';
+    if (pkg === 'ams') {
+        msg += 'ams* packages';
+    } else {
+        msg += pkg + ' package';
+    }
+    program.option('--no-'+pkg, msg);
+});
+
 program.parse(process.argv);
 
 var input = program.args.join(' ');
@@ -22,11 +34,21 @@ if (program.rebuild) {
 
 var texvcjs = require('../');
 var result = texvcjs.check(input, { debug: program.debug });
+
+// check required packages
+PACKAGES.forEach(function(pkg) {
+    if (result[pkg+'_required'] && !program[pkg]) {
+        result.status = 'F';
+        result.details = result[pkg+'_required'];
+    };
+});
+
+// output result
 if (result.status === '+') {
     util.print(result.status + (result.output || ''));
 } else if (result.status === 'F' || program.verbose) {
     util.print(result.status + (result.details || ''));
 } else {
     util.print(result.status);
 }
-process.exit(result.status);
+process.exit(result.status === '+' ? 0 : 1);

lib/ast.js

@@ -31,8 +31,10 @@ var type2str = function(type) {
 // vaguely based on:
 // https://github.com/rauschma/enums/blob/master/enums.js
 var Enum = function(name, fields, proto) {
-    Object.defineProperty(this, 'name', { value: name }); /* not enumerable */
     proto = proto || {};
+    // Non-enumerable properties 'name' and 'prototype'
+    Object.defineProperty(this, 'name', { value: name });
+    Object.defineProperty(this, 'prototype', { value: proto });
     Object.keys(fields).forEach(function(fname) {
         var args = fields[fname].args || [];
         var self = this;

lib/astutil.js

@@ -5,30 +5,44 @@
 
 var ast = require("./ast");
 
+// like Array#some, but returns the non-falsy value, rather than the
+// boolean constant `true`.
+var some = function(array, testfunc) {
+    var i, b;
+    for (i=0; i<array.length; i++) {
+        b = testfunc(array[i], i, array);
+        if (b) { return b; } // return the non-falsy value
+    }
+    return false;
+};
+
+// Matches a string against an string, array, or set target.
+// Returns the matching value, or `false`.
 var match = function(target, str) {
     if (Array.isArray(target)) {
-        return target.some(function(t) { return match(t, str); });
+        return some(target, function(t) { return match(t, str); });
     }
     if (typeof(target)==='string') {
-        return target === str;
+        return target === str ? str : false;
     }
-    return !!target[str];
+    return target[str] ? str : false;
 };
 
+// Check if any of the array of AST nodes contains `target`.
 var arr_contains_func = function(array, target) {
-    return array.some(function(t) { return t.contains_func(target); });
+    return some(array, function(t) { return t.contains_func(target); });
 };
 
 /**
  * RenderT nodes can contain function references only in a few specific
  * forms, which we test for here.
  */
-ast.RenderT.TEX_ONLY.prototype.tex_contains_func = function(target) {
+ast.RenderT.prototype.tex_contains_func = function(target) {
     var t = this.tex_part(), m;
     // may have trailing '(', '[', '\\{' or " "
     t = t.replace(/(\(|\[|\\{| )$/, '');
     // special case #1: \\operatorname {someword}
-    m = /^\\operatorname \{(.*)\}$/.exec(t);
+    m = /^\\operatorname \{([^\\]*)\}$/.exec(t);
     if (m) {
         return match(target, '\\operatorname');
     }
@@ -42,6 +56,11 @@ ast.RenderT.TEX_ONLY.prototype.tex_contains_func = function(target) {
     if (m) {
         return match(target, m[1]);
     }
+    // special case #4: \\mathbb, \\mathrm
+    m = /^(\\math..) \{[^\\]*\}$/.exec(t);
+    if (m) {
+        return match(target, m[1]);
+    }
     // protect against using random strings as keys in target
     return t.charAt(0) === '\\' && match(target, t);
 };
@@ -153,8 +172,8 @@ ast.Tex.defineVisitor("contains_func", {
         // t is the environment name.
         // m is a doubly-nested array
         var expr_has = function(e) { return arr_contains_func(e, target); };
-        var line_has = function(l) { return l.some(expr_has); };
-        var matrix_has = function(m) { return m.some(line_has); };
+        var line_has = function(l) { return some(l, expr_has); };
+        var matrix_has = function(m) { return some(m, line_has); };
         return match(target, '\\begin{'+t+'}') ||
             match(target, '\\end{'+t+'}') ||
             matrix_has(m);
@@ -171,7 +190,7 @@ ast.Tex.defineVisitor("contains_func", {
 // usually be an array of `ast.Tex`), or a low-level `ast.Tex` node.
 module.exports.contains_func = function(t, target) {
     if (typeof(t) === 'string') {
-        t = require('parser').parse(t).result;
+        t = require('parser').parse(t);
     }
     if (Array.isArray(t)) {
         return arr_contains_func(t, target);

lib/index.js

@@ -9,12 +9,14 @@ module.exports = {
 
 var Parser = require('./parser');
 var render = module.exports.render = require('./render');
+var tu = require('./texutil');
 
 module.exports.ast = require('./ast');
 module.exports.parse = Parser.parse.bind(Parser);
 module.exports.SyntaxError = Parser.SyntaxError;
 
-module.exports.contains_func = require('./astutil').contains_func;
+var astutil = require('./astutil');
+var contains_func = module.exports.contains_func = astutil.contains_func;
 
 var check = module.exports.check = function(input, options) {
     /* status is one character:
@@ -29,10 +31,15 @@ var check = module.exports.check = function(input, options) {
     try {
         // allow user to pass a parsed AST as input, as well as a string
         if (typeof(input)==='string') {
-            input = Parser.parse(input).result;
+            input = Parser.parse(input);
         }
         var output = render(input);
-        return { status: '+', output: output };
+        var result = { status: '+', output: output };
+        ['ams', 'cancel', 'color', 'euro', 'teubner'].forEach(function(pkg) {
+            pkg = pkg + '_required';
+            result[pkg] = astutil.contains_func(input, tu[pkg]);
+        });
+        return result;
     } catch (e) {
         if (options && options.debug) {
             throw e;

lib/parser.js

@@ -36,10 +36,7 @@ module.exports = (function() {
         peg$startRuleFunction  = peg$parsestart,
 
         peg$c0 = peg$FAILED,
-        peg$c1 = function(t) { console.assert(t instanceof ast.LList);
-              context.result = t.toArray();
-              return context;
-            },
+        peg$c1 = function(t) { console.assert(t instanceof ast.LList); return t.toArray(); },
         peg$c2 = [],
         peg$c3 = /^[ \t\n\r]/,
         peg$c4 = { type: "class", value: "[ \\t\\n\\r]", description: "[ \\t\\n\\r]" },
@@ -6345,8 +6342,6 @@ module.exports = (function() {
         return arr;
       };
 
-      var context = {};
-
 
     peg$result = peg$startRuleFunction();
 

lib/parser.pegjs

@@ -13,16 +13,11 @@
     }
     return arr;
   };
-
-  var context = {};
 }
 // first rule is the start production.
 start
   = _ t:tex_expr
-    { console.assert(t instanceof ast.LList);
-      context.result = t.toArray();
-      return context;
-    }
+    { console.assert(t instanceof ast.LList); return t.toArray(); }
 
 // the PEG grammar doesn't automatically ignore whitespace when tokenizing.
 // so we add `_` productions in appropriate places to eat whitespace.