qb-answer-checker 1.0.0 → 1.0.2

package/README.md

@@ -1,4 +1,11 @@
-This document specifies the kind of (quizbowl) answerlines that the program is designed to parse.
+# QB Answer Checker
+
+A package to automatically check/judge answers against quizbowl answerlines.
+Mostly used in conjunction with [qbreader](https://www.qbreader.org/) to automatically check answers.
+
+## Answerline Specification
+
+This section specifies the kind of (quizbowl) answerlines that the program is designed to parse.
 
 **Answerlines** should be formatted as follows:
 
@@ -30,7 +37,7 @@ Each **directive** should be one of:
 
 and "on" and "by asking/with" are optional and indicate that there should be a directed prompt.
 
-## Special Directives
+### Special Directives
 
 **Special directives** should be one of the following and affect the main answerline only:
 
@@ -41,7 +48,7 @@ and "on" and "by asking/with" are optional and indicate that there should be a d
 
 **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
+### 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/check-answer.d.ts

@@ -0,0 +1,4 @@
+declare module 'qb-answer-checker' {
+    function checkAnswer(answer: string, givenAnswer: string): boolean;
+    export = checkAnswer;
+}

package/lib/check-answer.js

@@ -158,7 +158,12 @@ function parseAnswerline(answerline) {
 }
 
 
-const generateTokens = (string) => {
+/**
+ * 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));
@@ -200,7 +205,7 @@ const generateTokens = (string) => {
  * @param {boolean} acceptSubstring
  * @param {number} strictness
  * @param {boolean} useStemmer
- * @returns
+ * @returns {boolean}
  */
 function tokenListsMatch(given, reference, acceptSubstring, strictness, useStemmer) {
     let j = 0;
@@ -216,7 +221,7 @@ function tokenListsMatch(given, reference, acceptSubstring, strictness, useStemm
                 errors = distance(given[i], reference[j]);
             }
 
-            if (strictness * errors <= reference[j].length) {
+            if (strictness > 0 && strictness * errors <= reference[j].length) {
                 matches = true;
             }
 
@@ -224,6 +229,10 @@ function tokenListsMatch(given, reference, acceptSubstring, strictness, useStemm
                 matches = true;
             }
 
+            if (errors === 0) {
+                matches = true;
+            }
+
             j++;
         }
 
@@ -237,20 +246,23 @@ function tokenListsMatch(given, reference, acceptSubstring, strictness, useStemm
 
 /**
  * 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}
+ * @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 = 5, acceptSubstring = false, useStemmer = true, respectOrder = false }) {
-    if (string === null || string === undefined || reference === null || reference === undefined)
+function stringMatchesReference({ string, reference, strictness = 7, acceptSubstring = false, useStemmer = true, respectOrder = false }) {
+    if (string === null || string === undefined || reference === null || reference === undefined) {
         return false;
+    }
 
-    if (string.length === 0)
+    if (string.length === 0) {
         return false;
+    }
 
     string = utils.removePunctuation(string).trim();
     reference = utils.removePunctuation(reference).trim();
@@ -319,10 +331,10 @@ function checkAnswer(answerline, givenAnswer) {
     for (const answer of parsedAnswerline.reject) {
         const useStemmer = (stemmer(answer) !== stemmer(parsedAnswerline.accept[0]));
 
-        if (!stringMatchesReference({ string: answer, reference: givenAnswer, strictness: 11, useStemmer }))
+        if (!stringMatchesReference({ string: answer, reference: givenAnswer, strictness: -1, useStemmer }))
             continue;
 
-        if (!stringMatchesReference({ string: givenAnswer, reference: answer, strictness: 11, useStemmer }))
+        if (!stringMatchesReference({ string: givenAnswer, reference: answer, strictness: -1, useStemmer }))
             continue;
 
         return { directive: 'reject', directedPrompt: null };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qb-answer-checker",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "description": "A package to automatically check/judge answers against quizbowl answerlines.",
   "main": "lib/check-answer.js",

package/test/script.js

@@ -1,4 +1,4 @@
-import checkAnswer from 'qb-answer-checker';
+import checkAnswer from '../lib/check-answer.js';
 import * as bcolors from './bcolors.js';
 
 import { assert } from 'chai';

package/test/tests.json

@@ -1,5 +1,19 @@
 {
     "formatted": [
+        {
+            "answerline": "<b><u>realignments</u></b> [reject \"dealignments\"]",
+            "tests": [
+                { "directive": "accept", "given": "realignments" },
+                { "directive": "reject", "given": "dealignments" }
+            ]
+        },
+        {
+            "answerline": "<b><u>dihydroxylation</u></b> [prompt on <b><u>hydroxylation</u></b>]",
+            "tests": [
+                { "directive": "accept", "given": "dihydroxylation" },
+                { "directive": "prompt", "given": "hydroxylation" }
+            ]
+        },
         {
             "answerline": "<b><u>Major Major Major</u></b>",
             "tests": [