temml 0.9.1

package/src/units.js

@@ -0,0 +1,109 @@
+/**
+ * This file does conversion between units.  In particular, it provides
+ * calculateSize to convert other units into CSS units.
+ */
+
+import ParseError from "./ParseError"
+import utils from "./utils"
+
+const ptPerUnit = {
+  // Convert to CSS (Postscipt) points, not TeX points
+  // https://en.wikibooks.org/wiki/LaTeX/Lengths and
+  // https://tex.stackexchange.com/a/8263
+  pt: 800 / 803, // convert TeX point to CSS (Postscript) point
+  pc: (12 * 800) / 803, // pica
+  dd: ((1238 / 1157) * 800) / 803, // didot
+  cc: ((14856 / 1157) * 800) / 803, // cicero (12 didot)
+  nd: ((685 / 642) * 800) / 803, // new didot
+  nc: ((1370 / 107) * 800) / 803, // new cicero (12 new didot)
+  sp: ((1 / 65536) * 800) / 803, // scaled point (TeX's internal smallest unit)
+  mm: (25.4 / 72),
+  cm: (2.54 / 72),
+  in: (1 / 72),
+  px: (96 / 72)
+}
+
+/**
+ * Determine whether the specified unit (either a string defining the unit
+ * or a "size" parse node containing a unit field) is valid.
+ */
+const validUnits = [
+  "em",
+  "ex",
+  "mu",
+  "pt",
+  "mm",
+  "cm",
+  "in",
+  "px",
+  "bp",
+  "pc",
+  "dd",
+  "cc",
+  "nd",
+  "nc",
+  "sp"
+]
+
+export const validUnit = function(unit) {
+  if (typeof unit !== "string") {
+    unit = unit.unit
+  }
+  return validUnits.indexOf(unit) > -1
+}
+
+export const emScale = styleLevel => {
+  const scriptLevel = Math.max(styleLevel - 1, 0)
+  return [1, 0.7, 0.5][scriptLevel]
+};
+
+/*
+ * Convert a "size" parse node (with numeric "number" and string "unit" fields,
+ * as parsed by functions.js argType "size") into a CSS value.
+ */
+export const calculateSize = function(sizeValue, style) {
+  let number = sizeValue.number
+  if (style.maxSize[0] < 0 && number > 0) {
+    return { number: 0, unit: "em" }
+  }
+  const unit = sizeValue.unit
+  switch (unit) {
+    case "mm":
+    case "cm":
+    case "in":
+    case "px": {
+      const numInCssPts = number * ptPerUnit[unit];
+      if (numInCssPts > style.maxSize[1]) {
+        return { number: style.maxSize[1], unit: "pt" }
+      }
+      return { number, unit }; // absolute CSS units.
+    }
+    case "em":
+    case "ex": {
+      // In TeX, em and ex do not change size in \scriptstyle.
+      if (unit === "ex") { number *= 0.431 }
+      number = Math.min(number / emScale(style.level), style.maxSize[0])
+      return { number: utils.round(number), unit: "em" };
+    }
+    case "bp": {
+      if (number > style.maxSize[1]) { number = style.maxSize[1] }
+      return { number, unit: "pt" }; // TeX bp is a CSS pt. (1/72 inch).
+    }
+    case "pt":
+    case "pc":
+    case "dd":
+    case "cc":
+    case "nd":
+    case "nc":
+    case "sp": {
+      number = Math.min(number * ptPerUnit[unit], style.maxSize[1])
+      return { number: utils.round(number), unit: "pt" }
+    }
+    case "mu": {
+      number = Math.min(number / 18, style.maxSize[0])
+      return { number: utils.round(number), unit: "em" }
+    }
+    default:
+      throw new ParseError("Invalid unit: '" + unit + "'")
+  }
+}

package/src/utils.js

@@ -0,0 +1,109 @@
+//
+/**
+ * This file contains a list of utility functions which are useful in other
+ * files.
+ */
+
+/**
+ * Provide a default value if a setting is undefined
+ */
+const deflt = function(setting, defaultIfUndefined) {
+  return setting === undefined ? defaultIfUndefined : setting;
+};
+
+// hyphenate and escape adapted from Facebook's React under Apache 2 license
+
+const uppercase = /([A-Z])/g;
+const hyphenate = function(str) {
+  return str.replace(uppercase, "-$1").toLowerCase();
+};
+
+const ESCAPE_LOOKUP = {
+  "&": "&",
+  ">": ">",
+  "<": "&lt;",
+  '"': "&quot;",
+  "'": "&#x27;"
+};
+
+const ESCAPE_REGEX = /[&><"']/g;
+
+/**
+ * Escapes text to prevent scripting attacks.
+ */
+function escape(text) {
+  return String(text).replace(ESCAPE_REGEX, (match) => ESCAPE_LOOKUP[match]);
+}
+
+/**
+ * Sometimes we want to pull out the innermost element of a group. In most
+ * cases, this will just be the group itself, but when ordgroups and colors have
+ * a single element, we want to pull that out.
+ */
+const getBaseElem = function(group) {
+  if (group.type === "ordgroup") {
+    if (group.body.length === 1) {
+      return getBaseElem(group.body[0]);
+    } else {
+      return group;
+    }
+  } else if (group.type === "color") {
+    if (group.body.length === 1) {
+      return getBaseElem(group.body[0]);
+    } else {
+      return group;
+    }
+  } else if (group.type === "font") {
+    return getBaseElem(group.body);
+  } else {
+    return group;
+  }
+};
+
+/**
+ * TeXbook algorithms often reference "character boxes", which are simply groups
+ * with a single character in them. To decide if something is a character box,
+ * we find its innermost group, and see if it is a single character.
+ */
+const isCharacterBox = function(group) {
+  const baseElem = getBaseElem(group);
+
+  // These are all the types of groups which hold single characters
+  return baseElem.type === "mathord" || baseElem.type === "textord" || baseElem.type === "atom"
+};
+
+export const assert = function(value) {
+  if (!value) {
+    throw new Error("Expected non-null, but got " + String(value));
+  }
+  return value;
+};
+
+/**
+ * Return the protocol of a URL, or "_relative" if the URL does not specify a
+ * protocol (and thus is relative).
+ */
+export const protocolFromUrl = function(url) {
+  const protocol = /^\s*([^\\/#]*?)(?::|&#0*58|&#x0*3a)/i.exec(url);
+  return protocol != null ? protocol[1] : "_relative";
+};
+
+/**
+ * Round `n` to 4 decimal places, or to the nearest 1/10,000th em. The TeXbook
+ * gives an acceptable rounding error of 100sp (which would be the nearest
+ * 1/6551.6em with our ptPerEm = 10):
+ * http://www.ctex.org/documents/shredder/src/texbook.pdf#page=69
+ */
+const round = function(n) {
+  return +n.toFixed(4);
+};
+
+export default {
+  deflt,
+  escape,
+  hyphenate,
+  getBaseElem,
+  isCharacterBox,
+  protocolFromUrl,
+  round
+};

package/src/variant.js

@@ -0,0 +1,103 @@
+import symbols from "./symbols";
+
+/**
+ * Maps TeX font commands to "mathvariant" attribute in buildMathML.js
+ */
+const fontMap = {
+  // styles
+  mathbf: "bold",
+  mathrm: "normal",
+  textit: "italic",
+  mathit: "italic",
+  mathnormal: "italic",
+
+  // families
+  mathbb: "double-struck",
+  mathcal: "script",
+  mathfrak: "fraktur",
+  mathscr: "script",
+  mathsf: "sans-serif",
+  mathtt: "monospace",
+  oldstylenums: "oldstylenums"
+}
+
+/**
+ * Returns the math variant as a string or null if none is required.
+ */
+export const getVariant = function(group, style) {
+  // Handle font specifiers as best we can.
+  // Chromium does not support the MathML mathvariant attribute.
+  // So we'll use Unicode replacement characters instead.
+  // But first, determine the math variant.
+
+  // Deal with the \textit, \textbf, etc., functions.
+  if (style.fontFamily === "texttt") {
+    return "monospace"
+  } else if (style.fontFamily === "textsc") {
+    return "normal"; // handled via character substitution in symbolsOrd.js.
+  } else if (style.fontFamily === "textsf") {
+    if (style.fontShape === "textit" && style.fontWeight === "textbf") {
+      return "sans-serif-bold-italic"
+    } else if (style.fontShape === "textit") {
+      return "sans-serif-italic"
+    } else if (style.fontWeight === "textbf") {
+      return "sans-serif-bold"
+    } else {
+      return "sans-serif"
+    }
+  } else if (style.fontShape === "textit" && style.fontWeight === "textbf") {
+    return "bold-italic"
+  } else if (style.fontShape === "textit") {
+    return "italic"
+  } else if (style.fontWeight === "textbf") {
+    return "bold"
+  }
+
+  // Deal with the \mathit, mathbf, etc, functions.
+  const font = style.font
+  if (!font || font === "mathnormal") {
+    return null
+  }
+
+  const mode = group.mode;
+  switch (font) {
+    case "mathit":
+      return "italic"
+    case "mathrm": {
+      const codePoint = group.text.codePointAt(0)
+      // LaTeX \mathrm returns italic for Greek characters.
+      return  (0x03ab < codePoint && codePoint < 0x03cf) ? "italic" : "normal"
+    }
+    case "greekItalic":
+      return "italic"
+    case "up@greek":
+      return "normal"
+    case "boldsymbol":
+    case "mathboldsymbol":
+      return "bold-italic"
+    case "mathbf":
+      return "bold"
+    case "mathbb":
+      return "double-struck"
+    case "mathfrak":
+      return "fraktur"
+    case "mathscr":
+    case "mathcal":
+      return "script"
+    case "mathsf":
+      return "sans-serif"
+    case "mathtt":
+      return "monospace"
+    case "oldstylenums":
+      return "oldstylenums"
+    default:
+      break
+  }
+
+  let text = group.text;
+  if (symbols[mode][text] && symbols[mode][text].replace) {
+    text = symbols[mode][text].replace
+  }
+
+  return Object.prototype.hasOwnProperty.call(fontMap, font) ? fontMap[font] : null
+};

package/temml.js

@@ -0,0 +1,181 @@
+/* eslint no-console:0 */
+/**
+ * This is the main entry point for Temml. Here, we expose functions for
+ * rendering expressions either to DOM nodes or to markup strings.
+ *
+ * We also expose the ParseError class to check if errors thrown from Temml are
+ * errors in the expression, or errors in javascript handling.
+ */
+
+import ParseError from "./src/ParseError";
+import Settings from "./src/Settings";
+
+import Parser from "./src/Parser";
+import parseTree from "./src/parseTree";
+import buildMathML from "./src/buildMathML";
+import { StyleLevel } from "./src/constants";
+import Style from "./src/Style";
+import { Span, TextNode } from "./src/domTree";
+import { defineSymbol } from "./src/symbols";
+import defineMacro from "./src/defineMacro";
+import { postProcess, version } from "./src/postProcess";
+
+/**
+ * Parse and build an expression, and place that expression in the DOM node
+ * given.
+ */
+let render = function(expression, baseNode, options) {
+  baseNode.textContent = "";
+  const alreadyInMathElement = baseNode.tagName === "MATH"
+  if (alreadyInMathElement) { options.wrap = "none" }
+  const math = renderToMathMLTree(expression, options)
+  if (alreadyInMathElement) {
+    // The <math> element already exists. Populate it.
+    baseNode.textContent = ""
+    math.children.forEach(e => { baseNode.appendChild(e.toNode()) })
+  } else if (math.children.length > 1) {
+    baseNode.textContent = ""
+    math.children.forEach(e => { baseNode.appendChild(e.toNode()) })
+  } else {
+    baseNode.appendChild(math.toNode())
+  }
+};
+
+// Temml's styles don't work properly in quirks mode. Print out an error, and
+// disable rendering.
+if (typeof document !== "undefined") {
+  if (document.compatMode !== "CSS1Compat") {
+    typeof console !== "undefined" &&
+      console.warn(
+        "Warning: Temml doesn't work in quirks mode. Make sure your " +
+          "website has a suitable doctype."
+      );
+
+    render = function() {
+      throw new ParseError("Temml doesn't work in quirks mode.");
+    };
+  }
+}
+
+/**
+ * Parse and build an expression, and return the markup for that.
+ */
+const renderToString = function(expression, options) {
+  const markup = renderToMathMLTree(expression, options).toMarkup();
+  return markup;
+};
+
+/**
+ * Parse an expression and return the parse tree.
+ */
+const generateParseTree = function(expression, options) {
+  const settings = new Settings(options);
+  return parseTree(expression, settings);
+};
+
+/**
+ * Take an expression which contains a preamble.
+ * Parse it and return the macros.
+ */
+const definePreamble = function(expression, options) {
+  const settings = new Settings(options);
+  settings.macros = {};
+  if (!(typeof expression === "string" || expression instanceof String)) {
+    throw new TypeError("Temml can only parse string typed expression")
+  }
+  const parser = new Parser(expression, settings, true)
+  // Blank out any \df@tag to avoid spurious "Duplicate \tag" errors
+  delete parser.gullet.macros.current["\\df@tag"]
+  const macros = parser.parse()
+  return macros
+};
+
+/**
+ * If the given error is a Temml ParseError,
+ * renders the invalid LaTeX as a span with hover title giving the Temml
+ * error message.  Otherwise, simply throws the error.
+ */
+const renderError = function(error, expression, options) {
+  if (options.throwOnError || !(error instanceof ParseError)) {
+    throw error;
+  }
+  const node = new Span(["temml-error"], [new TextNode(expression + "\n" + error.toString())]);
+  node.style.color = options.errorColor
+  node.style.whiteSpace = "pre-line"
+  return node;
+};
+
+/**
+ * Generates and returns the Temml build tree. This is used for advanced
+ * use cases (like rendering to custom output).
+ */
+const renderToMathMLTree = function(expression, options) {
+  const settings = new Settings(options);
+  try {
+    const tree = parseTree(expression, settings);
+    const style = new Style({
+      level: settings.displayMode ? StyleLevel.DISPLAY : StyleLevel.TEXT,
+      maxSize: settings.maxSize
+    });
+    return buildMathML(tree, expression, style, settings);
+  } catch (error) {
+    return renderError(error, expression, settings);
+  }
+};
+
+export default {
+  /**
+   * Current Temml version
+   */
+  version: version,
+  /**
+   * Renders the given LaTeX into MathML, and adds
+   * it as a child to the specified DOM node.
+   */
+  render,
+  /**
+   * Renders the given LaTeX into MathML string,
+   * for sending to the client.
+   */
+  renderToString,
+  /**
+   * Post-process an entire HTML block.
+   * Writes AMS auto-numbers and implements \ref{}.
+   * Typcally called once, after a loop has rendered many individual spans.
+   */
+  postProcess,
+  /**
+   * Temml error, usually during parsing.
+   */
+  ParseError,
+  /**
+   * Creates a set of macros with document-wide scope.
+   */
+  definePreamble,
+  /**
+   * Parses the given LaTeX into Temml's internal parse tree structure,
+   * without rendering to HTML or MathML.
+   *
+   * NOTE: This method is not currently recommended for public use.
+   * The internal tree representation is unstable and is very likely
+   * to change. Use at your own risk.
+   */
+  __parse: generateParseTree,
+  /**
+   * Renders the given LaTeX into a MathML internal DOM tree
+   * representation, without flattening that representation to a string.
+   *
+   * NOTE: This method is not currently recommended for public use.
+   * The internal tree representation is unstable and is very likely
+   * to change. Use at your own risk.
+   */
+  __renderToMathMLTree: renderToMathMLTree,
+  /**
+   * adds a new symbol to builtin symbols table
+   */
+  __defineSymbol: defineSymbol,
+  /**
+   * adds a new macro to builtin macro list
+   */
+  __defineMacro: defineMacro
+}