@thejaredwilcurt/csslop 0.0.49 → 0.0.51

package/src/value/math/tokenizer.js

@@ -0,0 +1,160 @@
+/**
+ * @file Splits a CSS math function into the numbers, identifiers, function names, operators, and punctuation it is written from.
+ */
+
+import {
+  PERCENTAGE,
+  UNITLESS
+} from './unit-totals.js';
+
+/**
+ * Matches a CSS number where the scanner stands: the digits it is written
+ * from, together with the fraction and the exponent it may be written with.
+ * A sign is left to the parser, which tells the sign of a number from an
+ * operator by whether whitespace stands between the two.
+ *
+ * @type {RegExp}
+ */
+const NUMBER_AT_INDEX = /(?:\d+\.\d+|\.\d+|\d+)(?:e[+-]?\d+)?/iy;
+
+/**
+ * Matches a CSS identifier where the scanner stands: a name of letters,
+ * digits, underscores, and hyphens that does not begin with a digit. A numeric
+ * constant, a function name, and a keyword argument are all written as
+ * identifiers.
+ *
+ * @type {RegExp}
+ */
+const IDENTIFIER_AT_INDEX = /[a-z_][a-z0-9_-]*/iy;
+
+/**
+ * Matches the unit written against a number where the scanner stands. Every
+ * CSS unit is named in letters alone, so a name holding anything else is a
+ * token of its own that a number cannot carry.
+ *
+ * @type {RegExp}
+ */
+const UNIT_AT_INDEX = /[a-z]+/iy;
+
+/**
+ * The characters CSS counts as whitespace, which separates the tokens of a
+ * calculation and tells an operator apart from the sign of a number.
+ *
+ * @type {Set<string>}
+ */
+const WHITESPACE_CHARACTERS = new Set([' ', '\t', '\n', '\r', '\f']);
+
+/**
+ * The characters that punctuate a calculation, and the kind of token each of
+ * them stands for.
+ *
+ * @type {Map<string, string>}
+ */
+const PUNCTUATION_TOKEN_TYPES = new Map([
+  ['(', 'open'],
+  [')', 'close'],
+  [',', 'comma']
+]);
+
+/**
+ * The arithmetic operators a calculation is written with.
+ *
+ * @type {Set<string>}
+ */
+const OPERATOR_CHARACTERS = new Set(['+', '-', '*', '/']);
+
+/**
+ * Reads the unit written directly against the number that ends at the given
+ * index, which is a percent sign or an identifier naming the unit. A number
+ * with nothing written against it carries no unit.
+ *
+ * @param  {string} text   The math function being tokenized.
+ * @param  {number} index  The index just past the number's digits.
+ * @return {object}        The unit read and the index just past it.
+ */
+function readUnitAtIndex (text, index) {
+  if (text[index] === PERCENTAGE) {
+    return { unit: PERCENTAGE, nextIndex: index + 1 };
+  }
+  UNIT_AT_INDEX.lastIndex = index;
+  const unitMatch = UNIT_AT_INDEX.exec(text);
+  if (!unitMatch) {
+    return { unit: UNITLESS, nextIndex: index };
+  }
+  return { unit: unitMatch[0], nextIndex: index + unitMatch[0].length };
+}
+
+/**
+ * Splits a math function into the tokens it is written from: its numbers with
+ * the units they carry, its identifiers, its function names, its operators,
+ * and its punctuation. Each token records whether whitespace precedes it,
+ * since that is what tells the sign of a number from an operator.
+ *
+ * @param  {string}     text  The math function as it is written.
+ * @return {Array|null}       The tokens of the math function, or null when it holds a character no calculation is written with.
+ */
+function tokenizeMathExpression (text) {
+  const tokens = [];
+  let index = 0;
+  let precededBySpace = false;
+
+  while (index < text.length) {
+    const character = text[index];
+
+    if (WHITESPACE_CHARACTERS.has(character)) {
+      precededBySpace = true;
+      index++;
+      continue;
+    }
+
+    NUMBER_AT_INDEX.lastIndex = index;
+    const numberMatch = NUMBER_AT_INDEX.exec(text);
+    if (numberMatch) {
+      const { unit, nextIndex } = readUnitAtIndex(text, index + numberMatch[0].length);
+      tokens.push({
+        type: 'number',
+        number: Number(numberMatch[0]),
+        unit,
+        precededBySpace
+      });
+      index = nextIndex;
+      precededBySpace = false;
+      continue;
+    }
+
+    if (OPERATOR_CHARACTERS.has(character) || PUNCTUATION_TOKEN_TYPES.has(character)) {
+      tokens.push({
+        type: PUNCTUATION_TOKEN_TYPES.get(character) || 'operator',
+        operator: character,
+        precededBySpace
+      });
+      index++;
+      precededBySpace = false;
+      continue;
+    }
+
+    IDENTIFIER_AT_INDEX.lastIndex = index;
+    const identifierMatch = IDENTIFIER_AT_INDEX.exec(text);
+    if (!identifierMatch) {
+      return null;
+    }
+    index = index + identifierMatch[0].length;
+    // A name written directly against an opening parenthesis calls a function
+    const callsFunction = text[index] === '(';
+    if (callsFunction) {
+      index++;
+    }
+    tokens.push({
+      type: callsFunction ? 'function' : 'identifier',
+      name: identifierMatch[0].toLowerCase(),
+      precededBySpace
+    });
+    precededBySpace = false;
+  }
+
+  return tokens;
+}
+
+export {
+  tokenizeMathExpression
+};

package/src/value/math/unit-totals.js

@@ -0,0 +1,194 @@
+/**
+ * @file Represents the value of a CSS calculation as totals keyed by unit, and works out the sums, products, and quotients of such values.
+ */
+
+import { convertAbsoluteLengthToPx } from '../shared.js';
+
+/**
+ * The unit a plain number is totalled under. A number carries no unit, and the
+ * empty string is the unit it does not carry.
+ *
+ * @type {string}
+ */
+const UNITLESS = '';
+
+/**
+ * The unit a percentage is totalled under. A percentage is only resolved
+ * against its basis once the element is laid out, so it is totalled as a unit
+ * of its own rather than as the number it is written from.
+ *
+ * @type {string}
+ */
+const PERCENTAGE = '%';
+
+/**
+ * Creates the totals of a value that states a single quantity, holding the
+ * number it is written from under the unit it is written with. An absolute
+ * length is held as the pixels it measures, since every length stating the
+ * same measurement then totals under the same unit.
+ *
+ * @param  {number}  number                   The number the quantity is written from.
+ * @param  {string}  unit                     The unit the quantity is written with, or the empty string when it is a plain number.
+ * @param  {boolean} preserveWrittenQuantity  Whether to retain the original spelling for a standalone quantity.
+ * @return {Map}                              The unit totals the quantity states.
+ */
+function createUnitTotals (number, unit, preserveWrittenQuantity = false) {
+  const lowercasedUnit = unit.toLowerCase();
+  const pixels = convertAbsoluteLengthToPx(number, lowercasedUnit);
+  let totals;
+  if (pixels === null) {
+    totals = new Map([[lowercasedUnit, number]]);
+  } else {
+    totals = new Map([['px', pixels]]);
+  }
+  if (preserveWrittenQuantity) {
+    totals.writtenQuantity = {
+      number,
+      unit: lowercasedUnit,
+      canonicalUnit: pixels === null ? lowercasedUnit : 'px',
+      canonicalNumber: pixels === null ? number : pixels
+    };
+  }
+  return totals;
+}
+
+/**
+ * Reports whether a value states a plain number, which is what an operand has
+ * to be to scale or divide the quantity it is written against.
+ *
+ * @param  {Map}     value  The unit totals the value holds.
+ * @return {boolean}        Whether the value states a plain number.
+ */
+function isPlainNumber (value) {
+  return value.size === 1 && value.has(UNITLESS);
+}
+
+/**
+ * Reads a value as the single quantity it states, which is what a function
+ * comparing its arguments needs each of them to be. A value totalling more
+ * than one unit is only resolved once its units are resolved against the
+ * element, so it states no single number to read.
+ *
+ * @param  {Map}         value  The unit totals the value holds.
+ * @return {object|null}        The number and the unit the value states, or null when it states more than one quantity.
+ */
+function readSingleQuantity (value) {
+  if (value.size !== 1) {
+    return null;
+  }
+  const [[unit, number]] = [...value];
+  return { number, unit };
+}
+
+/**
+ * Scales every quantity a value states by a plain number, which is how a
+ * multiplication and a division are worked out.
+ *
+ * @param  {Map}    value   The unit totals the value holds.
+ * @param  {number} factor  The number every total is scaled by.
+ * @return {Map}            The scaled unit totals.
+ */
+function scaleUnitTotals (value, factor) {
+  const scaled = new Map();
+  for (const [unit, coefficient] of value) {
+    scaled.set(unit, coefficient * factor);
+  }
+  return scaled;
+}
+
+/**
+ * Adds one value to another, totalling the quantities they state under the
+ * units they are written with. A sum of a plain number and a quantity carrying
+ * a unit states nothing a stylesheet can hold, so such a sum has no total to
+ * give.
+ *
+ * @param  {Map}      left   The unit totals the value on the left holds.
+ * @param  {Map}      right  The unit totals the value on the right holds.
+ * @param  {number}   sign   The direction the right value is added in: 1 to add it, -1 to subtract it.
+ * @return {Map|null}        The totals of the sum, or null when the two cannot be added.
+ */
+function addUnitTotals (left, right, sign) {
+  const totals = new Map(left);
+  for (const [unit, coefficient] of right) {
+    totals.set(unit, (totals.get(unit) || 0) + (coefficient * sign));
+  }
+  const addsNumberToQuantity = totals.has(UNITLESS) && totals.size > 1;
+  if (addsNumberToQuantity) {
+    return null;
+  }
+  return totals;
+}
+
+/**
+ * Multiplies two values, which CSS only allows when one of them is a plain
+ * number: the product of two quantities carrying units measures an area or a
+ * rate, and no CSS property takes one.
+ *
+ * @param  {Map}      left   The unit totals the value on the left holds.
+ * @param  {Map}      right  The unit totals the value on the right holds.
+ * @return {Map|null}        The totals of the product, or null when neither side is a plain number.
+ */
+function multiplyUnitTotals (left, right) {
+  if (isPlainNumber(right)) {
+    return scaleUnitTotals(left, right.get(UNITLESS));
+  }
+  if (isPlainNumber(left)) {
+    return scaleUnitTotals(right, left.get(UNITLESS));
+  }
+  const leftQuantity = readSingleQuantity(left);
+  const rightQuantity = readSingleQuantity(right);
+  if (leftQuantity && rightQuantity) {
+    if (leftQuantity.unit.startsWith('reciprocal:') && leftQuantity.unit.slice('reciprocal:'.length) === rightQuantity.unit) {
+      return createUnitTotals(leftQuantity.number * rightQuantity.number, UNITLESS);
+    }
+    if (rightQuantity.unit.startsWith('reciprocal:') && rightQuantity.unit.slice('reciprocal:'.length) === leftQuantity.unit) {
+      return createUnitTotals(leftQuantity.number * rightQuantity.number, UNITLESS);
+    }
+  }
+  return null;
+}
+
+/**
+ * Divides a value by another, which CSS only allows when the divisor is a
+ * plain number. A division by zero resolves to an infinity that no property
+ * takes, so it is left for the stylesheet to state as written.
+ *
+ * @param  {Map}      left   The unit totals of the value being divided.
+ * @param  {Map}      right  The unit totals of the value dividing it.
+ * @return {Map|null}        The totals of the quotient, or null when the division cannot be worked out.
+ */
+function divideUnitTotals (left, right) {
+  if (isPlainNumber(right)) {
+    const divisor = right.get(UNITLESS);
+    if (divisor === 0) {
+      return null;
+    }
+    return scaleUnitTotals(left, 1 / divisor);
+  }
+  const dividendQuantity = readSingleQuantity(left);
+  const divisorQuantity = readSingleQuantity(right);
+  if (!dividendQuantity || !divisorQuantity || divisorQuantity.number === 0) {
+    return null;
+  }
+  if (dividendQuantity.unit === divisorQuantity.unit) {
+    return createUnitTotals(dividendQuantity.number / divisorQuantity.number, UNITLESS);
+  }
+  if (dividendQuantity.unit === UNITLESS) {
+    return createUnitTotals(
+      dividendQuantity.number / divisorQuantity.number,
+      'reciprocal:' + divisorQuantity.unit
+    );
+  }
+  return null;
+}
+
+export {
+  addUnitTotals,
+  createUnitTotals,
+  divideUnitTotals,
+  multiplyUnitTotals,
+  PERCENTAGE,
+  readSingleQuantity,
+  scaleUnitTotals,
+  UNITLESS
+};