qb-answer-checker 1.0.6 → 1.1.0

package/README.md

@@ -10,10 +10,10 @@ This section specifies the kind of (quizbowl) answerlines that the program is de
 **Answerlines** should be formatted as follows:
 
 ```
-<main answerline> [<sub-answerline>]
+<main section> [<sub-section>] [<sub-section>]? ...
 ```
 
-where the **sub-answerline** is a string of clauses separated by semicolons of the form:
+where each **section** is a string of **clauses** separated by semicolons of the form:
 
 ```
 (<special directives>;)? <clause> (; <clause>; ...)?

package/lib/check-answer.js

@@ -1,367 +1,77 @@
+import referenceContainsTokens from './contains-tokens.js';
+import generateUnformattedAnswers from './generate-unformatted-answers.js';
+import getSpecialDirectives from './get-special-directives.js';
+import splitIntoSections from './split-into-sections.js';
+import splitSectionIntoParsedClauses from './split-section-into-clauses.js';
+import tokenize from './tokenize.js';
 import * as utils from './utils.js';
-import getEquivalentAnswers from './equivalent-answers.js';
-import standardizeTokens from './standardize-tokens.js';
-
-import { distance } from 'damerau-levenshtein-js';
-import numberToWords from 'number-to-words';
-import { toArabic } from 'roman-numerals';
-import { stemmer } from 'stemmer';
-
-const { toWords } = numberToWords;
-
-/**
- * Splits a string into the main answer and the sub-answer (everything in brackets or parentheses),
- * while intelligently detecting whether to keep the part in parentheses, if present.
- * @param {string} string
- * @returns {{ mainAnswer: string, subAnswer: string }}
- */
-const splitMainAnswer = (string) => {
-    const bracketsSubAnswer = (string.match(/(?<=\[)[^\]]*(?=\])/g) ?? ['']).pop();
-    const parenthesesSubAnswer = (string.match(/(?<=\()[^)]*(?=\))/g) ?? ['']).pop();
-
-    const mainAnswer = utils.removeParentheses(string);
-
-    if (bracketsSubAnswer.length !== 0)
-        return { mainAnswer, subAnswer: bracketsSubAnswer };
-
-    for (const directive of ['or', 'prompt', 'antiprompt', 'anti-prompt', 'accept', 'reject', 'do not accept']) {
-        if (parenthesesSubAnswer.startsWith(directive))
-            return { mainAnswer, subAnswer: parenthesesSubAnswer };
-    }
-
-    return { mainAnswer, subAnswer: '' };
-};
-
-/**
- * Split either the main- or sub-answerline into clauses.
- * @param {string} string
- * @returns {string[]} the clauses in the string
- */
-const splitAnswerlineIntoClauses = (string) => {
-    return string.split(';').map(token => token.trim());
-};
 
 /**
- *
- * @param {string} clause
- * @returns {{directive: "accept" | "reject" | "prompt", answers: string[], directedPrompt: string?}} the answers in the clause
- */
-const splitClauseIntoAnswers = (clause) => {
-    let directive = 'accept'; // by default, this clause accepts answers that match to it
-    if (clause.startsWith('prompt')) {
-        directive = 'prompt';
-    } else if (clause.startsWith('antiprompt') || clause.startsWith('anti-prompt')) {
-        directive = 'accept';
-    } else if (clause.startsWith('reject') || clause.startsWith('do not accept')) {
-        directive = 'reject';
-    }
-
-    let directedPrompt = null;
-    if (directive === 'prompt') {
-        for (const key of ['by asking', 'with']) {
-            const index = clause.indexOf(key);
-
-            if (index < 0) {
-                continue;
-            }
-
-            directedPrompt = utils.extractQuotes(clause.slice(index + key.length));
-            clause = clause.slice(0, index);
-            break;
-        }
-    }
-
-    clause = clause.replace(/^(or|prompt|prompt on|antiprompt|antiprompt on|anti-prompt|anti-prompt on|accept|reject|do not accept or prompt on|do not accept)/, '').trim();
-
-    const answers = clause.split(/,? or |, /).map(token => token.trim()).filter(token => token.length > 0);
-
-    return { directive, answers, directedPrompt };
-};
-
-
-/**
- * Parses the answerline, returning the acceptable, promptable, and rejectable answers.
+ * Check if the given answer matches the answerline.
  * @param {string} answerline
+ * @param {string} givenAnswer
+ * @param {number} [strictness]
+ * @param {boolean} [verbose] - whether to print debug information
+ * @returns {{directive: "accept" | "prompt" | "reject", directedPrompt: string | undefined}}
  */
-function parseAnswerline(answerline) {
-    answerline = utils.removeItalics(answerline);
-    answerline = utils.replaceSpecialCharacters(answerline);
-    answerline = utils.replaceSpecialSubstrings(answerline);
-
-    const { mainAnswer, subAnswer } = splitMainAnswer(answerline);
-    const mainAnswers = mainAnswer.split(' or ').map(token => token.trim()).filter(token => token.length > 0);
-
-    /**
-     * @type {{ "accept": String[], "prompt": String[][2], "reject": String[] }}
-     */
-    const parsedAnswerline = {
-        accept: [],
-        prompt: [],
-        reject: [],
-    };
-
-    for (const answer of mainAnswers) {
-        parsedAnswerline.accept.push(utils.extractUnderlining(answer), utils.extractKeyWords(answer), utils.extractQuotes(answer));
-    }
-
-    if (utils.getAbbreviation(mainAnswer).length > 1) {
-        parsedAnswerline.accept.push(utils.getAbbreviation(mainAnswer));
-    }
-
-    if (utils.getAbbreviation(utils.extractUnderlining(mainAnswer)).length > 1) {
-        parsedAnswerline.accept.push(utils.getAbbreviation(utils.extractUnderlining(mainAnswer)));
-    }
-
-    if (/[[(]accept either/i.test(answerline) || /[[(]accept any/i.test(answerline)) {
-        for (const answer of parsedAnswerline.accept[0].split(' ')) {
-            parsedAnswerline.accept.push(answer);
-        }
-    }
-
-    if (/prompt on (a )?partial/.test(answerline)) {
-        for (const answer of parsedAnswerline.accept[0].split(' ')) {
-            parsedAnswerline.prompt.push([answer, null]);
-        }
-    }
-
-    for (const answer of parsedAnswerline.accept) {
-        const equivalentAnswers = getEquivalentAnswers(answer);
-        parsedAnswerline.accept = parsedAnswerline.accept.concat(equivalentAnswers);
-    }
-
-    const clauses = splitAnswerlineIntoClauses(subAnswer);
-    clauses.forEach(clause => {
-        if (clause.length === 0)
-            return;
-
-        const { directive, answers, directedPrompt } = splitClauseIntoAnswers(clause);
-
-        for (const answer of answers) {
-            switch (directive) {
-                case 'accept':
-                    parsedAnswerline[directive].push(utils.extractUnderlining(answer), utils.extractKeyWords(answer), utils.extractQuotes(answer));
-                    break;
-                case 'prompt': {
-                    parsedAnswerline[directive].push([utils.extractUnderlining(answer), directedPrompt]);
-                    parsedAnswerline[directive].push([utils.extractKeyWords(answer), directedPrompt]);
-                    parsedAnswerline[directive].push([utils.extractQuotes(answer), directedPrompt]);
-                    break;
-                }
-                case 'reject':
-                    parsedAnswerline[directive].push(utils.extractQuotes(answer));
-                    break;
-            }
-        }
-    });
-
-    return parsedAnswerline;
-}
-
-
-/**
- * Generates standardized tokens from a string.
- * @param {string} string
- * @returns {string[]} the tokens generated from the string
- */
-function generateTokens(string) {
-    const tokens = string.split(' ')
-        .filter(token => token.length > 0)
-        .map(string => standardizeTokens(string));
-
-    for (let i = tokens.length - 1; i >= 0; i--) {
-        if (tokens[i].endsWith('s')) {
-            tokens[i] = tokens[i].slice(0, -1);
-        }
-
-        try {
-            tokens[i] = toArabic(tokens[i]);
-        } catch (e) {
-            if (e.message !== 'toArabic expects a valid roman number' && !(e instanceof TypeError)) {
-                throw e;
-            }
-        }
-
-        if (isFinite(tokens[i])) {
-            tokens[i] = parseInt(tokens[i]);
-        } else {
-            continue;
-        }
-
-        if (tokens[i] <= 100) {
-            tokens[i] = toWords(tokens[i]);
-        } else {
-            tokens[i] = tokens[i].toString();
-        }
-    }
-
-    return tokens;
-};
-
-
-/**
- * Helper method to check if every token in `given` is present in `reference`.
- * @param {string[]} given
- * @param {string[]} reference
- * @param {boolean} acceptSubstring
- * @param {number} strictness
- * @param {boolean} useStemmer
- * @returns {boolean}
- */
-function tokenListsMatch(given, reference, acceptSubstring, strictness, useStemmer) {
-    let j = 0;
-    for (const element of given) {
-        let matches = false;
+function checkAnswer (answerline, givenAnswer, strictness = 7, verbose = false) {
+  if (typeof answerline !== 'string' || typeof givenAnswer !== 'string') {
+    return { directive: 'reject', directedPrompt: undefined };
+  }
 
-        while (j < reference.length && matches === false) {
-            let errors;
+  const isFormattedAnswerline = /<u>/.test(answerline);
 
-            if (useStemmer) {
-                errors = distance(stemmer(element), stemmer(reference[j]));
-            } else {
-                errors = distance(element, reference[j]);
-            }
+  answerline = utils.replaceSpecialCharacters(answerline);
+  answerline = answerline.toLowerCase();
+  answerline = utils.replaceSpecialSubstrings(answerline);
+  answerline = utils.removeItalics(answerline);
 
-            if (strictness > 0 && strictness * errors <= reference[j].length) {
-                matches = true;
-            }
+  givenAnswer = utils.replaceSpecialCharacters(givenAnswer);
+  givenAnswer = givenAnswer.toLowerCase();
+  givenAnswer = utils.replaceSpecialSubstrings(givenAnswer);
+  givenAnswer = utils.removeItalics(givenAnswer);
+  givenAnswer = utils.removePunctuation(givenAnswer);
+  const givenAnswerTokens = tokenize(givenAnswer, true);
 
-            if (acceptSubstring && reference[j].includes(element)) {
-                matches = true;
-            }
+  const sections = splitIntoSections(answerline);
+  const parsedClauses = sections.flatMap((section, index) => splitSectionIntoParsedClauses(section, index === 0));
+  const mainAnswer = parsedClauses[0].formattedAnswers[0];
 
-            if (errors === 0) {
-                matches = true;
-            }
+  if (!isFormattedAnswerline && mainAnswer?.length > 1 && givenAnswer.length === 1 && isNaN(givenAnswer)) {
+    return { directive: 'reject' };
+  }
 
-            j++;
-        }
-
-        if (!matches) {
-            return false;
-        }
-    }
-
-    return true;
-}
-
-/**
- * Returns true if and only if every token in `string` is present in `reference`.
- * @param {object} options
- * @param {string} options.string
- * @param {string} options.reference
- * @param {number} [options.strictness=7] - the number of characters per error allowed for two tokens to match. If set to a negative number or 0, then no errors are allowed.
- * @param {boolean} [options.acceptSubstring=false] - whether or not to accept substrings.
- * @param {boolean} [options.useStemmer=true] - whether or not to use a stemmer.
- * @param {boolean} [options.respectOrder=false] - whether or not to respect the order of the tokens (i.e. "a b" is not the same as "b a").
- * @returns {boolean}
- */
-function stringMatchesReference({ string, reference, strictness = 7, acceptSubstring = false, useStemmer = true, respectOrder = false }) {
-    if (string === null || string === undefined || reference === null || reference === undefined) {
-        return false;
+  for (const specialDirective of getSpecialDirectives(answerline)) {
+    if (specialDirective === 'accept either') {
+      parsedClauses.push({ directive: 'accept', formattedAnswers: mainAnswer.split(' ') });
     }
 
-    if (string.length === 0) {
-        return false;
+    if (specialDirective === 'prompt on partial') {
+      parsedClauses.push({ directive: 'prompt', formattedAnswers: mainAnswer.split(' ') });
     }
+  }
 
-    string = utils.removePunctuation(string).trim();
-    reference = utils.removePunctuation(reference).trim();
-
-    let stringTokenLists = [];
-    let referenceTokenLists = [];
-
-    if (/-/.test(string)) {
-        stringTokenLists.push(generateTokens(string.replace(/-/g, ' ')));
-        stringTokenLists.push(generateTokens(string.replace(/-/g, '')));
-    } else {
-        stringTokenLists.push(generateTokens(string));
-    }
+  parsedClauses.sort((a, b) => (a.directive === 'reject' ? -1 : 1) - (b.directive === 'reject' ? -1 : 1));
 
-    if (/-/.test(reference)) {
-        referenceTokenLists.push(generateTokens(reference.replace(/-/g, ' ')));
-        referenceTokenLists.push(generateTokens(reference.replace(/-/g, '')));
-    } else {
-        referenceTokenLists.push(generateTokens(reference));
-    }
+  for (const { directive, formattedAnswers, directedPrompt, isMainAnswer } of parsedClauses) {
+    for (const formattedAnswer of formattedAnswers) {
+      for (const unformattedAnswer of generateUnformattedAnswers(formattedAnswer, isMainAnswer)) {
+        const tokens = tokenize(unformattedAnswer, true);
 
-    if (!respectOrder) {
-        stringTokenLists = stringTokenLists.map(tokenList => tokenList.sort());
-        referenceTokenLists = referenceTokenLists.map(tokenList => tokenList.sort());
-    }
+        const matches = referenceContainsTokens(
+          isFormattedAnswerline || directive === 'reject' ? tokens : givenAnswerTokens,
+          isFormattedAnswerline || directive === 'reject' ? givenAnswerTokens : tokens,
+          directive === 'reject' ? -1 : strictness,
+          !isFormattedAnswerline,
+          directive !== 'reject'
+        );
 
-    // check if every token in the string is in the reference
-    for (const stringTokenList of stringTokenLists) {
-        for (const referenceTokenList of referenceTokenLists) {
-            if (tokenListsMatch(stringTokenList, referenceTokenList, acceptSubstring, strictness, useStemmer)) {
-                return true;
-            }
-        }
+        if (matches) { return { directive, directedPrompt }; }
+      }
     }
+  }
 
-    return false;
+  return { directive: 'reject' };
 }
 
-/**
- * Check if the given answer matches the answerline.
- * @param {String} answerline
- * @param {String} givenAnswer
- * @param {Number} [strictness]
- * @returns {{
-    * directive: 'accept' | 'prompt' | 'reject',
-    * directedPrompt: String | null
- * }}
- */
-function checkAnswer(answerline, givenAnswer, strictness = 7) {
-    if (!answerline || !givenAnswer) {
-        return { directive: 'reject', directedPrompt: null };
-    }
-
-    if (typeof answerline !== 'string' || typeof givenAnswer !== 'string') {
-        return { directive: 'reject', directedPrompt: null };
-    }
-
-    answerline = answerline.toLowerCase();
-    givenAnswer = utils.replaceSpecialCharacters(givenAnswer.toLowerCase());
-    const answerlineIsFormatted = answerline.includes('<u>');
-
-    const answerWorks = (answerline, givenAnswer) => {
-        if (answerlineIsFormatted) {
-            return stringMatchesReference({ string: answerline, reference: givenAnswer, strictness: strictness });
-        } else {
-            return stringMatchesReference({ string: givenAnswer, reference: answerline, strictness: strictness, acceptSubstring: true });
-        }
-    };
-
-    const parsedAnswerline = parseAnswerline(answerline);
-
-    if (!answerlineIsFormatted && parsedAnswerline.accept[0] && parsedAnswerline.accept[0].length > 1 && givenAnswer.length === 1 && isNaN(givenAnswer))
-        return { directive: 'reject', directedPrompt: null };
-
-    for (const answer of parsedAnswerline.reject) {
-        const useStemmer = (stemmer(answer) !== stemmer(parsedAnswerline.accept[0]));
-
-        if (!stringMatchesReference({ string: answer, reference: givenAnswer, strictness: -1, useStemmer }))
-            continue;
-
-        if (!stringMatchesReference({ string: givenAnswer, reference: answer, strictness: -1, useStemmer }))
-            continue;
-
-        return { directive: 'reject', directedPrompt: null };
-    }
-
-    if (parsedAnswerline.accept.some(answer => answerWorks(answer, givenAnswer))) {
-        return { directive: 'accept', directedPrompt: null };
-    }
-
-    for (const answer of parsedAnswerline.prompt) {
-        const directedPrompt = answer[1];
-        if (answerWorks(answer[0], givenAnswer)) {
-            return { directive: 'prompt', directedPrompt: directedPrompt };
-        }
-    }
-
-    return { directive: 'reject', directedPrompt: null };
-}
-
-
 export default checkAnswer;

package/lib/constants.js

@@ -0,0 +1,11 @@
+export const DIRECTIVES = {
+  accept: ['accept', 'or', 'antiprompt on', 'anti-prompt on', 'antiprompt', 'anti-prompt'],
+  prompt: ['prompt on', 'prompt'],
+  reject: ['reject', 'do not accept or prompt on', 'do not accept']
+};
+export const DIRECTIVES_FLATTENED = Object.values(DIRECTIVES).flat();
+
+export const SPECIAL_DIRECTIVES = {
+  'accept either': ['accept either', 'accept any'],
+  'prompt on partial': ['prompt on partial', 'prompt on a partial']
+};

package/lib/contains-tokens.js

@@ -0,0 +1,41 @@
+import { distance } from 'damerau-levenshtein-js';
+import { stemmer } from 'stemmer';
+
+/**
+ * Check if all elements of `tokens` are present in `reference`.
+ * @param {string[]} tokens
+ * @param {string[]} references
+ * @param {number} strictness
+ * @param {boolean} acceptSubstring
+ * @param {boolean} useStemmer
+ */
+export default function referenceContainsTokens (tokens, references, strictness, acceptSubstring, useStemmer) {
+  let index = 0;
+  for (const token of tokens) {
+    let containsToken = false;
+    while (index < references.length) {
+      const reference = references[index];
+      index++;
+      const errors = useStemmer ? distance(stemmer(token), stemmer(reference)) : distance(token, reference);
+
+      if (strictness > 0 && strictness * errors <= reference.length) {
+        containsToken = true;
+        break;
+      }
+
+      if (acceptSubstring && reference.includes(token)) {
+        containsToken = true;
+        break;
+      }
+
+      if (errors === 0) {
+        containsToken = true;
+        break;
+      }
+    }
+
+    if (!containsToken) { return false; }
+  }
+
+  return true;
+}

package/lib/equivalent-answers.csv

@@ -0,0 +1,144 @@
+atomic bombs,atomic weapons,nuclear bombs,nuclear weapons,nukes,fission bombs,A-bombs
+nuclear weapons,atomic bombs,atomic weapons,nuclear bombs,nukes,fission bombs,A-bombs
+nukes,atomic bombs,atomic weapons,nuclear bombs,nuclear weapons,fission bombs,A-bombs
+fairytales,fairy tales
+fairy tales,fairytales
+house,home,dwelling,residence
+mouse,mice
+rail,railroad
+railroad,rail
+nineteen eighty-four,1984,nineteen eighty four
+nineteen eighty four,1984,nineteen eighty-four
+oxidation number,oxidation state
+oxidation state,oxidation number
+ralph vaughan-williams,rvw
+spacewalk,space walk
+spacewalks,space walk
+sugar cane,sugarcane
+sugarcane,sugar cane
+wavefunction,wave function
+wave function,wavefunction
+world war 1,first world war,great war,world war i,world war one
+world war i,first world war,great war,world war 1,world war one
+world war one,first world war,great war,world war 1,world war i
+world war ii,ww2,wwii,world war 2,world war two,second world war
+world war two,ww2,wwii,world war ii,world war 2,second world war
+world war 2,ww2,wwii,world war ii,world war two,second world war
+hydrogen,h
+helium,he
+lithium,li
+beryllium,be
+boron,b
+carbon,c
+nitrogen,n
+oxygen,o
+fluorine,f
+neon,ne
+sodium,na
+magnesium,mg
+aluminum,al
+silicon,si
+phosphorus,p
+sulfur,s
+chlorine,cl
+argon,ar
+potassium,k
+calcium,ca
+scandium,sc
+titanium,ti
+vanadium,v
+chromium,cr
+manganese,mn
+iron,fe
+cobalt,co
+nickel,ni
+copper,cu
+zinc,zn
+gallium,ga
+germanium,ge
+arsenic,as
+selenium,se
+bromine,br
+krypton,kr
+rubidium,rb
+strontium,sr
+yttrium,y
+zirconium,zr
+niobium,nb
+molybdenum,mo
+technetium,tc
+ruthenium,ru
+rhodium,rh
+palladium,pd
+silver,ag
+cadmium,cd
+indium,in
+tin,sn
+antimony,sb
+tellurium,te
+iodine,i
+xenon,xe
+cesium,cs
+barium,ba
+lanthanum,la
+cerium,ce
+praseodymium,pr
+neodymium,nd
+promethium,pm
+samarium,sm
+europium,eu
+gadolinium,gd
+terbium,tb
+dysprosium,dy
+holmium,ho
+erbium,er
+thulium,tm
+ytterbium,yb
+lutetium,lu
+hafnium,hf
+tantalum,ta
+tungsten,w
+rhenium,re
+osmium,os
+iridium,ir
+platinum,pt
+gold,au
+mercury,hg
+thallium,tl
+lead,pb
+bismuth,bi
+polonium,po
+astatine,at
+radon,rn
+francium,fr
+radium,ra
+actinium,ac
+thorium,th
+protactinium,pa
+uranium,u
+neptunium,np
+plutonium,pu
+americium,am
+curium,cm
+berkelium,bk
+californium,cf
+einsteinium,es
+fermium,fm
+mendelevium,md
+nobelium,no
+lawrencium,lr
+rutherfordium,rf
+dubnium,db
+seaborgium,sg
+bohrium,bh
+hassium,hs
+meitnerium,mt
+darmstadtium,ds
+roentgenium,rg
+copernicium,cn
+nihonium,nh
+flerovium,fl
+moscovium,mc
+livermorium,lv
+tennessine,ts
+oganesson,og

package/lib/generate-unformatted-answers.js

@@ -0,0 +1,50 @@
+import loadCSVAsDict from './load-csv-as-dict.js';
+import * as utils from './utils.js';
+
+const equivalentAnswers = loadCSVAsDict('equivalent-answers.csv');
+
+/**
+ * Get the abbreviation of a string by taking the first letter of each word.
+ * For example, "World Health Organization" becomes "WHO".
+ * @param {string} string
+ * @returns {string}
+ */
+function getAbbreviation (string) {
+  return string
+    .split(' ')
+    .filter(token => token.length > 0)
+    .map(token => utils.removeHTMLTags(token).charAt(0))
+    .reduce((a, b) => a + b, '')
+    .trim();
+}
+
+/**
+ * @param {string} formattedAnswer
+ * @param {boolean} isMainAnswer
+ * @returns {string[]}
+ */
+export default function generateUnformattedAnswers (formattedAnswer, isMainAnswer) {
+  if (/-/.test(formattedAnswer)) {
+    const object1 = generateUnformattedAnswers(formattedAnswer.replace(/-/g, ' '), isMainAnswer);
+    const object2 = generateUnformattedAnswers(formattedAnswer.replace(/-/g, ''), isMainAnswer);
+    return [...object1, ...object2];
+  }
+
+  const answers = [
+    utils.removeHTMLTags(formattedAnswer),
+    utils.extractUnderlining(formattedAnswer),
+    utils.extractKeyWords(formattedAnswer),
+    utils.extractQuotes(formattedAnswer)
+  ];
+
+  if (isMainAnswer) {
+    answers.push(getAbbreviation(formattedAnswer));
+    answers.push(getAbbreviation(utils.extractUnderlining(formattedAnswer)));
+  }
+
+  if (answers[0] in equivalentAnswers) {
+    answers.push(...equivalentAnswers[answers[0]]);
+  }
+
+  return answers.map(answer => utils.removePunctuation(answer));
+}