qb-answer-checker 1.0.0

package/README.md

@@ -0,0 +1,47 @@
+This document specifies the kind of (quizbowl) answerlines that the program is designed to parse.
+
+**Answerlines** should be formatted as follows:
+
+```
+<main answerline> [<sub-answerline>]
+```
+
+where the **sub-answerline** is a string of clauses separated by semicolons of the form:
+
+```
+(<special directives>;)? <clause> (; <clause>; ...)?
+```
+
+where each **clause** is a string of answers separated by the word "or" of the form:
+
+```
+<directive>? (on)? <answer>((or|,) <answer>(or|,) <answer> ...)? (by asking|with <directed prompt>)?
+```
+
+**Deprecated:** answers can also be separated by commas instead of "or", but this is deprecated and serves mostly to support old answerlines.
+
+Each **directive** should be one of:
+
+- "accept"
+- "prompt"
+- "reject"
+- "anti-prompt"
+  - some sets use "antiprompt" (no hyphen)
+
+and "on" and "by asking/with" are optional and indicate that there should be a directed prompt.
+
+## Special Directives
+
+**Special directives** should be one of the following and affect the main answerline only:
+
+- "accept either" or "accept any": accept any individual word of the main answer
+  - For example, if the entire answerline is `<b><u>Grover Underwood</u></b> [accept either]`, then "Grover", "Underwood", and "Grover Underwood" would be accepted.
+- "prompt on partial": prompt on any individual word of the main answer
+  - For example: `<b><u>John</u></b> [prompt on partial]` would prompt on "John" and "John Smith", but not "John Smithson".
+
+**Note:** special directives should be the first phrase in the sub-answerline, but this program will recognize them anywhere in the sub-answerline.
+
+## Additional Info
+
+For more information about how answerlines should be formatted, see <https://minkowski.space/quizbowl/manuals/style/answerlines.html>.
+Note that the linked guide is more useful for explaining how answerlines should be formatted from a sylistic/quizbowl sense, while this specification only describes how they should be formatted in a way that computers can understand.

package/lib/check-answer.js

@@ -0,0 +1,348 @@
+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.
+ * @param {string} answerline
+ */
+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;
+}
+
+
+const 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
+ */
+function tokenListsMatch(given, reference, acceptSubstring, strictness, useStemmer) {
+    let j = 0;
+    for (let i = 0; i < given.length; i++) {
+        let matches = false;
+
+        while (j < reference.length && matches === false) {
+            let errors;
+
+            if (useStemmer) {
+                errors = distance(stemmer(given[i]), stemmer(reference[j]));
+            } else {
+                errors = distance(given[i], reference[j]);
+            }
+
+            if (strictness * errors <= reference[j].length) {
+                matches = true;
+            }
+
+            if (acceptSubstring && reference[j].includes(given[i])) {
+                matches = true;
+            }
+
+            j++;
+        }
+
+        if (!matches) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Returns true if and only if every token in `string` is present in `reference`.
+ * @param {String} string
+ * @param {String} reference
+ * @param {Number} strictness - the number of characters per error allowed for two tokens to match.
+ * @param {Boolean} acceptSubstring - whether or not to accept substrings.
+ * @param {Boolean} useStemmer - whether or not to use a stemmer.
+ * @param {Boolean} respectOrder - 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 = 5, acceptSubstring = false, useStemmer = true, respectOrder = false }) {
+    if (string === null || string === undefined || reference === null || reference === undefined)
+        return false;
+
+    if (string.length === 0)
+        return false;
+
+    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));
+    }
+
+    if (/-/.test(reference)) {
+        referenceTokenLists.push(generateTokens(reference.replace(/-/g, ' ')));
+        referenceTokenLists.push(generateTokens(reference.replace(/-/g, '')));
+    } else {
+        referenceTokenLists.push(generateTokens(reference));
+    }
+
+    if (!respectOrder) {
+        stringTokenLists = stringTokenLists.map(tokenList => tokenList.sort());
+        referenceTokenLists = referenceTokenLists.map(tokenList => tokenList.sort());
+    }
+
+    // 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;
+            }
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Check if the given answer matches the answerline.
+ * @param {String} answerline
+ * @param {String} givenAnswer
+ * @returns {{
+    * directive: 'accept' | 'prompt' | 'reject',
+    * directedPrompt: String | null
+ * }}
+ */
+function checkAnswer(answerline, givenAnswer) {
+    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 });
+        } else {
+            return stringMatchesReference({ string: givenAnswer, reference: answerline, acceptSubstring: true });
+        }
+    };
+
+    const parsedAnswerline = parseAnswerline(answerline);
+
+    if (!answerlineIsFormatted && 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: 11, useStemmer }))
+            continue;
+
+        if (!stringMatchesReference({ string: givenAnswer, reference: answer, strictness: 11, useStemmer }))
+            continue;
+
+        return { directive: 'reject', directedPrompt: null };
+    }
+
+    for (const answer of parsedAnswerline.accept) {
+        if (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/equivalent-answers.js

@@ -0,0 +1,62 @@
+import { removeHTMLTags } from './utils.js';
+
+/**
+ * Given an answer, return an array of equivalent answers (i.e. answers that should always match).
+ * @param {string} answer
+ * @returns {string[]} An array of equivalent answers.
+ */
+function getEquivalentAnswers(answer) {
+    answer = answer.toLowerCase();
+    answer = removeHTMLTags(answer);
+    switch (answer) {
+    case 'atomic bombs':
+    case 'nuclear weapons':
+    case 'nukes':
+        return ['atomic bombs', 'atomic weapons', 'nuclear bombs', 'nuclear weapons', 'nukes', 'fission bombs', 'A-bombs'];
+    case 'house':
+        return ['home'];
+    case 'mouse':
+        return ['mice'];
+    case 'rail':
+    case 'railroad':
+        return ['rail', 'railroad'];
+    case 'nineteen eighty-four':
+    case 'nineteen eighty four':
+        return ['1984'];
+    case 'oxidation number':
+    case 'oxidation state':
+        return ['oxidation number', 'oxidation state'];
+    case 'ralph vaughan-williams':
+        return ['rvw'];
+    case 'spacewalk':
+        return ['space walk'];
+    case 'sugar cane':
+    case 'sugarcane':
+        return ['sugar cane', 'sugarcane'];
+    case 'wavefunction':
+    case 'wave function':
+        return ['wave function', 'wavefunction'];
+    case 'world war 1':
+    case 'world war i':
+    case 'world war one':
+        return [
+            'first world war',
+            'great war',
+        ];
+    case 'world war ii':
+    case 'world war two':
+    case 'world war 2':
+        return [
+            'ww2',
+            'wwii',
+            'world war ii',
+            'world war 2',
+            'world war two',
+            'second world war',
+        ];
+    }
+
+    return [];
+}
+
+export default getEquivalentAnswers;

package/lib/standardize-tokens.js

@@ -0,0 +1,52 @@
+/**
+ * Given a token, convert it to a standard form when it can be represented in multiple ways.
+ * @param {string} token
+ * @returns {string}
+ */
+function standardizeTokens(token) {
+    switch (token) {
+    case 'dr':
+    case 'dr.':
+        return 'doctor';
+
+    case 'st':
+    case 'st.':
+        return 'saint';
+
+        // ordinals
+    case '1st':
+        return 'first';
+    case '2nd':
+        return 'second';
+    case '3rd':
+        return 'third';
+    case '4th':
+        return 'fourth';
+    case '5th':
+        return 'fifth';
+    case '6th':
+        return 'sixth';
+    case '7th':
+        return 'seventh';
+    case '8th':
+        return 'eighth';
+    case '9th':
+        return 'ninth';
+    case '10th':
+        return 'tenth';
+
+        // units
+    case 'cm':
+        return 'centimeter';
+    case 'mm':
+        return 'millimeter';
+
+        // typoes
+    case 'contentinal':
+        return 'continental';
+    }
+
+    return token;
+}
+
+export default standardizeTokens;

package/lib/utils.js

@@ -0,0 +1,131 @@
+/**
+ * Get all words which are partially or wholly underlined.
+ * @param {string} string
+ * @returns {string}
+ */
+function extractKeyWords(string) {
+    const requiredWords = extractUnderlining(string).split(' ');
+
+    string = string
+        .split(' ')
+        .filter(token => token.length > 0)
+        .filter(token => token.match(/<\/?u>/) || requiredWords.includes(token))
+        .reduce((prev, curr) => prev + curr + ' ', '')
+        .trim();
+
+    return removeHTMLTags(string);
+}
+
+
+/**
+ * Extracts the text in quotes from a given string.
+ * @param {string} string - The input string.
+ * @returns {string} - The extracted quotes or the string without HTML tags.
+ */
+function extractQuotes(string) {
+    const matches = string.match(/(?<=["])[^"]*(?=["])/g);
+
+    if (matches) {
+        return matches.reduce((prev, curr) => prev + ' ' + curr, '').trim();
+    } else {
+        return string;
+    }
+}
+
+
+/**
+ * Extracts the underlined text from a string.
+ * If no underlined text is found, it removes HTML tags from the string.
+ * @param {string} string - The input string.
+ * @returns {string} - The extracted underlined text or the string without HTML tags.
+ */
+function extractUnderlining(string) {
+    const matches = string.match(/(?<=<u>)[^<]*(?=<\/u>)/g);
+
+    if (matches) {
+        return removeHTMLTags(matches.reduce((prev, curr) => prev + curr + ' ', '').trim());
+    } else {
+        return removeHTMLTags(string);
+    }
+}
+
+
+/**
+ * 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 => removeHTMLTags(token).charAt(0))
+        .reduce((a, b) => a + b, '')
+        .trim();
+}
+
+
+/**
+ * Removes HTML tags from a string.
+ * @param {string} string
+ * @returns {string}
+ */
+function removeHTMLTags(string) {
+    return string.replace(/<[^>]*>/g, '');
+}
+
+
+/**
+ *
+ * @param {string} string
+ * @returns {string}
+ */
+function removeItalics(string) {
+    return string.replace(/<\/?i>/g, '');
+}
+
+
+/**
+ * Removes parentheses and square brackets from a string.
+ * @param {string} string - The input string.
+ * @returns {string} The string with parentheses and square brackets removed.
+ */
+function removeParentheses(string) {
+    return string
+        .replace(/\([^)]*\)/g, '')
+        .replace(/\[[^\]]*\]/g, '');
+}
+
+
+function removePunctuation(string) {
+    return string.replace(/[.,!;:'"\\/?@#$%^&*_~’]/g, '');
+}
+
+
+function replaceSpecialCharacters(string) {
+    return string
+        .normalize('NFD').replace(/[\u0300-\u036f]/g, '')
+        .replace(/["“‟❝”❞]/g, '"');
+}
+
+
+function replaceSpecialSubstrings(string) {
+    return string
+        .replace(/\(s\)/g, 's')
+        .replace(/\p{Pd}/gu, '-'); // replace all dashes with the same dash
+}
+
+
+export {
+    extractKeyWords,
+    extractQuotes,
+    extractUnderlining,
+    getAbbreviation,
+    removeHTMLTags,
+    removeItalics,
+    removeParentheses,
+    removePunctuation,
+    replaceSpecialCharacters,
+    replaceSpecialSubstrings,
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "qb-answer-checker",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "A package to automatically check/judge answers against quizbowl answerlines.",
+  "main": "lib/check-answer.js",
+  "scripts": {
+    "test": "mocha test/script.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qbreader/qb-answer-checker.git"
+  },
+  "keywords": [
+    "quizbowl",
+    "qb"
+  ],
+  "author": "Geoffrey Wu",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/qbreader/qb-answer-checker/issues"
+  },
+  "homepage": "https://github.com/qbreader/qb-answer-checker#readme",
+  "devDependencies": {
+    "chai": "^4.3.10",
+    "mocha": "^10.2.0"
+  },
+  "dependencies": {
+    "damerau-levenshtein-js": "^1.1.8",
+    "number-to-words": "^1.2.4",
+    "roman-numerals": "^0.3.2",
+    "stemmer": "^2.0.1"
+  }
+}

package/test/bcolors.js

@@ -0,0 +1,26 @@
+// A class that contains bash escape sequences for common colors.
+// Shamelessly copied from https://svn.blender.org/svnroot/bf-blender/trunk/blender/build_files/scons/tools/bcolors.py
+
+
+
+const HEADER = '\x1b[95m';
+const OKBLUE = '\x1b[94m';
+const OKCYAN = '\x1b[96m';
+const OKGREEN = '\x1b[92m';
+const WARNING = '\x1b[93m';
+const FAIL = '\x1b[91m';
+const ENDC = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const UNDERLINE = '\x1b[4m';
+
+export {
+    HEADER,
+    OKBLUE,
+    OKCYAN,
+    OKGREEN,
+    WARNING,
+    FAIL,
+    ENDC,
+    BOLD,
+    UNDERLINE,
+};