xlsform2lstsv 0.2.1 → 0.2.3

package/README.md

@@ -35,7 +35,7 @@ Convert XLSForm surveys to LimeSurvey TSV format.
   - its a complex task to ensure the transpiler covers everything and we currently cannot guarantee error free/complete transpiling 
 
 - constraint_message ❌
-- XLSForms Calculation ❌
+- XLSForms Calculation ✅ (`calculate` type → LimeSurvey Equation question `*`; `${var}` references in labels/hints converted to EM `{var}` syntax)
 - XLSForms Trigger ❌
 - Repeats ❌
 - LimeSurvey Assessments ❌

package/dist/converters/xpathTranspiler.js

@@ -7,6 +7,12 @@
  * The transpiler uses js-xpath library to parse XPath expressions into AST,
  * then recursively transforms the AST nodes to LimeSurvey-compatible syntax.
  */
+function isVariableRef(node) {
+    return !!(node.steps && node.steps.length > 0 && node.steps[0].name);
+}
+function isStringLiteral(node) {
+    return typeof node.value === 'string';
+}
 /**
  * Sanitize field names by removing underscores and hyphens to match LimeSurvey's naming conventions
  */
@@ -32,7 +38,7 @@ function sanitizeName(name) {
  * @returns The transpiled LimeSurvey expression string
  * @throws Error if an unsupported node structure is encountered
  */
-function transpile(node) {
+function transpile(node, ctx) {
     if (!node)
         return '';
     // https://getodk.github.io/xforms-spec/#xpath-functions
@@ -40,92 +46,97 @@ function transpile(node) {
     if (node.id) {
         switch (node.id) {
             case 'count':
-                return `count(${node.args?.map(arg => transpile(arg)).join(', ') || ''})`;
+                return `count(${node.args?.map(arg => transpile(arg, ctx)).join(', ') || ''})`;
             case 'concat':
-                return node.args?.map(arg => transpile(arg)).join(' + ') || '';
+                return node.args?.map(arg => transpile(arg, ctx)).join(' + ') || '';
             case 'regex':
-                return `regexMatch(${node.args?.map(arg => transpile(arg)).join(', ') || ''})`;
+                return `regexMatch(${node.args?.map(arg => transpile(arg, ctx)).join(', ') || ''})`;
             case 'contains':
                 // Custom handling for contains
                 if (node.args?.length === 2) {
-                    return `contains(${transpile(node.args[0])}, ${transpile(node.args[1])})`;
+                    return `contains(${transpile(node.args[0], ctx)}, ${transpile(node.args[1], ctx)})`;
                 }
                 break;
             case 'selected':
-                // Handle selected(${field}, 'value') -> (field=="value")
+                // Handle selected(${field}, 'value')
                 if (node.args?.length === 2) {
                     const fieldArg = node.args[0];
                     const valueArg = node.args[1];
-                    const fieldName = transpile(fieldArg);
-                    let value = transpile(valueArg);
-                    // Remove any existing quotes and use double quotes
+                    const fieldName = transpile(fieldArg, ctx);
+                    let value = transpile(valueArg, ctx);
+                    // Remove any existing quotes
                     value = value.replace(/^['"]|['"]$/g, "");
-                    return `(${sanitizeName(fieldName)}=="${value}")`;
+                    const sanitizedField = sanitizeName(fieldName);
+                    // Use buildSelectedExpr if available (handles select_one vs select_multiple)
+                    if (ctx?.buildSelectedExpr) {
+                        return ctx.buildSelectedExpr(sanitizedField, value);
+                    }
+                    return `(${sanitizedField}=="${value}")`;
                 }
                 break;
             case 'string':
                 // string() function - just return the argument
                 if (node.args?.length === 1) {
-                    return transpile(node.args[0]);
+                    return transpile(node.args[0], ctx);
                 }
                 break;
             case 'number':
                 // number() function - just return the argument
                 if (node.args?.length === 1) {
-                    return transpile(node.args[0]);
+                    return transpile(node.args[0], ctx);
                 }
                 break;
             case 'floor':
                 if (node.args?.length === 1) {
-                    return `floor(${transpile(node.args[0])})`;
+                    return `floor(${transpile(node.args[0], ctx)})`;
                 }
                 break;
             case 'ceiling':
                 if (node.args?.length === 1) {
-                    return `ceil(${transpile(node.args[0])})`;
+                    return `ceil(${transpile(node.args[0], ctx)})`;
                 }
                 break;
             case 'round':
                 if (node.args?.length === 1) {
-                    return `round(${transpile(node.args[0])})`;
+                    return `round(${transpile(node.args[0], ctx)})`;
                 }
                 break;
             case 'sum':
                 if (node.args?.length === 1) {
-                    return `sum(${transpile(node.args[0])})`;
+                    return `sum(${transpile(node.args[0], ctx)})`;
                 }
                 break;
             case 'substring':
                 if (node.args && node.args.length >= 2) {
-                    const stringArg = transpile(node.args[0]);
-                    const startArg = transpile(node.args[1]);
-                    const lengthArg = node.args.length > 2 ? transpile(node.args[2]) : '';
+                    const stringArg = transpile(node.args[0], ctx);
+                    const startArg = transpile(node.args[1], ctx);
+                    const lengthArg = node.args.length > 2 ? transpile(node.args[2], ctx) : '';
                     return `substr(${stringArg}, ${startArg}${lengthArg ? ', ' + lengthArg : ''})`;
                 }
                 break;
             case 'string-length':
                 if (node.args?.length === 1) {
-                    return `strlen(${transpile(node.args[0])})`;
+                    return `strlen(${transpile(node.args[0], ctx)})`;
                 }
                 break;
             case 'starts-with':
                 if (node.args?.length === 2) {
-                    return `startsWith(${transpile(node.args[0])}, ${transpile(node.args[1])})`;
+                    return `startsWith(${transpile(node.args[0], ctx)}, ${transpile(node.args[1], ctx)})`;
                 }
                 break;
             case 'ends-with':
                 if (node.args?.length === 2) {
-                    return `endsWith(${transpile(node.args[0])}, ${transpile(node.args[1])})`;
+                    return `endsWith(${transpile(node.args[0], ctx)}, ${transpile(node.args[1], ctx)})`;
                 }
                 break;
             case 'not':
                 if (node.args?.length === 1) {
-                    return `!(${transpile(node.args[0])})`;
+                    return `!(${transpile(node.args[0], ctx)})`;
                 }
                 break;
             case 'if':
                 if (node.args?.length === 3) {
-                    return `(${transpile(node.args[0])} ? ${transpile(node.args[1])} : ${transpile(node.args[2])})`;
+                    return `(${transpile(node.args[0], ctx)} ? ${transpile(node.args[1], ctx)} : ${transpile(node.args[2], ctx)})`;
                 }
                 break;
             case 'today':
@@ -136,40 +147,63 @@ function transpile(node) {
                 throw new Error(`Unsupported function: ${node.id}`);
         }
     }
-    // https://getodk.github.io/xforms-spec/#xpath-operators 
+    // https://getodk.github.io/xforms-spec/#xpath-operators
     // to https://www.limesurvey.org/manual/ExpressionScript_-_Presentation (see syntax)
     if (node.type) {
+        const lookupAnswerCode = ctx?.lookupAnswerCode;
         switch (node.type) {
             // Comparison operators
             case '<=':
-                return `${transpile(node.left)} <= ${transpile(node.right)}`;
+                return `${transpile(node.left, ctx)} <= ${transpile(node.right, ctx)}`;
             case '>=':
-                return `${transpile(node.left)} >= ${transpile(node.right)}`;
+                return `${transpile(node.left, ctx)} >= ${transpile(node.right, ctx)}`;
             case '=':
-            case '==':
-                return `${transpile(node.left)} == ${transpile(node.right)}`;
-            case '!=':
-                return `${transpile(node.left)} != ${transpile(node.right)}`;
+            case '==': {
+                const leftNode = node.left;
+                const rightNode = node.right;
+                if (lookupAnswerCode && isVariableRef(leftNode) && isStringLiteral(rightNode)) {
+                    const fieldName = sanitizeName(leftNode.steps[0].name);
+                    const rawValue = rightNode.value;
+                    const rewritten = lookupAnswerCode(fieldName, rawValue);
+                    if (rewritten !== rawValue) {
+                        return `${fieldName} == "${rewritten}"`;
+                    }
+                }
+                return `${transpile(leftNode, ctx)} == ${transpile(rightNode, ctx)}`;
+            }
+            case '!=': {
+                const leftNode = node.left;
+                const rightNode = node.right;
+                if (lookupAnswerCode && isVariableRef(leftNode) && isStringLiteral(rightNode)) {
+                    const fieldName = sanitizeName(leftNode.steps[0].name);
+                    const rawValue = rightNode.value;
+                    const rewritten = lookupAnswerCode(fieldName, rawValue);
+                    if (rewritten !== rawValue) {
+                        return `${fieldName} != "${rewritten}"`;
+                    }
+                }
+                return `${transpile(leftNode, ctx)} != ${transpile(rightNode, ctx)}`;
+            }
             case '<':
-                return `${transpile(node.left)} < ${transpile(node.right)}`;
+                return `${transpile(node.left, ctx)} < ${transpile(node.right, ctx)}`;
             case '>':
-                return `${transpile(node.left)} > ${transpile(node.right)}`;
+                return `${transpile(node.left, ctx)} > ${transpile(node.right, ctx)}`;
             // Arithmetic operators
             case '+':
-                return `${transpile(node.left)} + ${transpile(node.right)}`;
+                return `${transpile(node.left, ctx)} + ${transpile(node.right, ctx)}`;
             case '-':
-                return `${transpile(node.left)} - ${transpile(node.right)}`;
+                return `${transpile(node.left, ctx)} - ${transpile(node.right, ctx)}`;
             case '*':
-                return `${transpile(node.left)} * ${transpile(node.right)}`;
+                return `${transpile(node.left, ctx)} * ${transpile(node.right, ctx)}`;
             case 'div':
-                return `${transpile(node.left)} / ${transpile(node.right)}`;
+                return `${transpile(node.left, ctx)} / ${transpile(node.right, ctx)}`;
             case 'mod':
-                return `${transpile(node.left)} % ${transpile(node.right)}`;
+                return `${transpile(node.left, ctx)} % ${transpile(node.right, ctx)}`;
             // Logical operators
             case 'and':
-                return `${transpile(node.left)} and ${transpile(node.right)}`;
+                return `${transpile(node.left, ctx)} and ${transpile(node.right, ctx)}`;
             case 'or':
-                return `${transpile(node.left)} or ${transpile(node.right)}`;
+                return `${transpile(node.left, ctx)} or ${transpile(node.right, ctx)}`;
             // Unsupported operators
             case '|':
             case '/':
@@ -219,7 +253,7 @@ function transpile(node) {
  * @param xpathExpr - The XPath expression to convert
  * @returns LimeSurvey Expression Manager syntax, or null if conversion fails
  */
-export async function xpathToLimeSurvey(xpathExpr) {
+export async function xpathToLimeSurvey(xpathExpr, ctx) {
     if (!xpathExpr || xpathExpr.trim() === '') {
         return '1'; // Default relevance expression
     }
@@ -241,7 +275,7 @@ export async function xpathToLimeSurvey(xpathExpr) {
             throw new Error('js-xpath module does not export parse function');
         }
         const parsed = jxpath.parse(processedExpr);
-        return transpile(parsed);
+        return transpile(parsed, ctx);
     }
     catch (error) {
         console.error(`Transpilation error: ${error.message}`);
@@ -385,14 +419,14 @@ function parseRegexMatchArguments(argsString) {
  * @param xpath - The XPath relevance expression
  * @returns LimeSurvey Expression Manager syntax
  */
-export async function convertRelevance(xpathExpr) {
+export async function convertRelevance(xpathExpr, ctx) {
     if (!xpathExpr)
         return '1';
     // Preprocess: normalize operators to lowercase for jsxpath compatibility
     let normalizedXPath = xpathExpr
         .replace(/\bAND\b/gi, 'and')
         .replace(/\bOR\b/gi, 'or');
-    const result = await xpathToLimeSurvey(normalizedXPath);
+    const result = await xpathToLimeSurvey(normalizedXPath, ctx);
     // Handle edge case: selected() with just {field} (without $)
     if (result && result.includes('selected(')) {
         return result.replace(/selected\s*\(\s*\{(\w+)\}\s*,\s*["']([^'"]+)["']\s*\)/g, (_match, fieldName, value) => {

package/dist/processors/TypeMapper.js

@@ -20,6 +20,7 @@ export const TYPE_MAPPINGS = {
     select_multiple: { limeSurveyType: 'M', supportsOther: true, answerClass: 'SQ' },
     // Other types
     note: { limeSurveyType: 'X' },
+    calculate: { limeSurveyType: '*' },
     rank: { limeSurveyType: 'R', answerClass: 'A', supportsOther: true },
 };
 export class TypeMapper {

package/dist/xlsformConverter.js

@@ -1,5 +1,5 @@
 import { ConfigManager } from './config/ConfigManager.js';
-import { convertRelevance, convertConstraint } from './converters/xpathTranspiler.js';
+import { convertRelevance, convertConstraint, xpathToLimeSurvey } from './converters/xpathTranspiler.js';
 import { FieldSanitizer } from './processors/FieldSanitizer.js';
 import { TSVGenerator } from './processors/TSVGenerator.js';
 import { TypeMapper } from './processors/TypeMapper.js';
@@ -7,7 +7,7 @@ import { getBaseLanguage } from './utils/languageUtils.js';
 // Metadata types that should be silently skipped (no visual representation)
 const SKIP_TYPES = [
     'start', 'end', 'today', 'deviceid', 'username',
-    'calculate', 'hidden', 'audit'
+    'hidden', 'audit'
 ];
 // Unimplemented XLSForm types that should raise an error
 const UNIMPLEMENTED_TYPES = [
@@ -49,6 +49,9 @@ export class XLSFormToTSVConverter {
         this.inMatrix = false;
         this.matrixListName = null;
         this.groupContentBuffer = [];
+        this.answerCodeMap = new Map();
+        this.questionToListMap = new Map();
+        this.questionBaseTypeMap = new Map();
     }
     /**
      * Get the current configuration
@@ -84,6 +87,9 @@ export class XLSFormToTSVConverter {
         this.detectAvailableLanguages(surveyData, choicesData, settingsData);
         // Build choices map
         this.buildChoicesMap(choicesData);
+        // Build answer code and question-to-list maps for relevance rewriting
+        this.buildAnswerCodeMap();
+        this.buildQuestionToListMap(surveyData);
         // Add survey row (class S)
         this.addSurveyRow(settingsData[0] || {});
         // Check if we need a default group (if no groups are defined)
@@ -161,6 +167,51 @@ export class XLSFormToTSVConverter {
             this.choicesMap.get(listName).push(choice);
         }
     }
+    buildAnswerCodeMap() {
+        this.answerCodeMap = new Map();
+        for (const [listName, choices] of this.choicesMap) {
+            const codeMap = new Map();
+            const sanitized = [];
+            for (const choice of choices) {
+                const raw = choice.name?.trim() || '';
+                sanitized.push(raw ? this.sanitizeAnswerCode(raw) : '');
+            }
+            const used = new Set();
+            for (let i = 0; i < sanitized.length; i++) {
+                if (!sanitized[i])
+                    continue;
+                let name = sanitized[i];
+                if (used.has(name)) {
+                    let counter = 1;
+                    let candidate;
+                    do {
+                        const suffix = String(counter);
+                        candidate = name.substring(0, 5 - suffix.length) + suffix;
+                        counter++;
+                    } while (used.has(candidate));
+                    sanitized[i] = candidate;
+                }
+                used.add(sanitized[i]);
+                const originalName = choices[i].name?.trim() || '';
+                if (originalName) {
+                    codeMap.set(originalName, sanitized[i]);
+                }
+            }
+            this.answerCodeMap.set(listName, codeMap);
+        }
+    }
+    buildQuestionToListMap(surveyData) {
+        this.questionToListMap = new Map();
+        this.questionBaseTypeMap = new Map();
+        for (const row of surveyData) {
+            const typeInfo = this.parseType(row.type || '');
+            if (typeInfo.listName && row.name) {
+                const sanitizedName = this.sanitizeName(row.name.trim());
+                this.questionToListMap.set(sanitizedName, typeInfo.listName);
+                this.questionBaseTypeMap.set(sanitizedName, typeInfo.base);
+            }
+        }
+    }
     addDefaultGroup() {
         // Add a default group for surveys without explicit groups
         const defaults = this.configManager.getDefaults();
@@ -489,6 +540,21 @@ export class XLSFormToTSVConverter {
     sanitizeAnswerCode(code) {
         return this.fieldSanitizer.sanitizeAnswerCode(code);
     }
+    /**
+     * Convert ${varname} references in text to LimeSurvey EM syntax {sanitizedname}.
+     */
+    convertVariableReferences(text) {
+        return text.replace(/\$\{([^}]+)\}/g, (_, name) => {
+            const sanitized = name.replace(/[_-]/g, '');
+            return `{${sanitized}}`;
+        });
+    }
+    /**
+     * Transpile an XLSForm calculation expression to a LimeSurvey EM expression.
+     */
+    async convertCalculation(calculation) {
+        return await xpathToLimeSurvey(calculation);
+    }
     async addGroup(row) {
         // Auto-generate name if missing (matches LimeSurvey behavior)
         const groupName = row.name && row.name.trim() !== ''
@@ -561,21 +627,38 @@ export class XLSFormToTSVConverter {
         }
         // Notes have special handling
         const isNote = xfTypeInfo.base === 'note';
+        const isCalculate = xfTypeInfo.base === 'calculate';
+        // For calculate type, transpile the calculation expression to EM syntax
+        let calculationExpr = '';
+        if (isCalculate && row.calculation) {
+            calculationExpr = await this.convertCalculation(row.calculation);
+        }
         // Add main question for each language
         for (const lang of this.availableLanguages) {
+            let text;
+            if (isCalculate) {
+                // Equation question: the EM expression wrapped in {} IS the question text
+                text = `{${calculationExpr}}`;
+            }
+            else {
+                text = this.getLanguageSpecificValue(row.label, lang) || questionName;
+            }
+            // Convert ${var} references to EM {var} syntax in text and help
+            text = this.convertVariableReferences(text);
+            const help = this.convertVariableReferences(this.getLanguageSpecificValue(row.hint, lang) || '');
             this.bufferRow({
                 class: 'Q',
                 'type/scale': isNote ? 'X' : lsType.type,
                 name: questionName,
                 relevance: await this.convertRelevance(row.relevant),
-                text: this.getLanguageSpecificValue(row.label, lang) || questionName,
-                help: this.getLanguageSpecificValue(row.hint, lang) || '',
+                text,
+                help,
                 language: lang,
                 validation: "",
-                em_validation_q: isNote ? "" : await convertConstraint(row.constraint || ""),
-                mandatory: isNote ? '' : (row.required === 'yes' || row.required === 'true' ? 'Y' : ''),
-                other: isNote ? '' : (lsType.other ? 'Y' : ''),
-                default: isNote ? '' : (row.default || ''),
+                em_validation_q: (isNote || isCalculate) ? "" : await convertConstraint(row.constraint || ""),
+                mandatory: (isNote || isCalculate) ? '' : (row.required === 'yes' || row.required === 'true' ? 'Y' : ''),
+                other: (isNote || isCalculate) ? '' : (lsType.other ? 'Y' : ''),
+                default: (isNote || isCalculate) ? '' : (row.default || ''),
                 same_default: ''
             });
         }
@@ -736,9 +819,35 @@ export class XLSFormToTSVConverter {
             }
         }
     }
+    lookupAnswerCode(fieldName, choiceValue) {
+        // Truncate to 20 chars to match converter's field sanitization
+        // (the transpiler only removes _/- but doesn't truncate)
+        const truncated = fieldName.length > 20 ? fieldName.substring(0, 20) : fieldName;
+        const listName = this.questionToListMap.get(truncated);
+        if (!listName)
+            return { code: choiceValue, listName: undefined };
+        const codeMap = this.answerCodeMap.get(listName);
+        if (!codeMap)
+            return { code: choiceValue, listName };
+        return { code: codeMap.get(choiceValue) ?? choiceValue, listName };
+    }
     async convertRelevance(relevant) {
         if (!relevant)
             return '1';
-        return await convertRelevance(relevant);
+        const ctx = {
+            lookupAnswerCode: (fieldName, choiceValue) => {
+                return this.lookupAnswerCode(fieldName, choiceValue).code;
+            },
+            buildSelectedExpr: (fieldName, choiceValue) => {
+                const truncated = fieldName.length > 20 ? fieldName.substring(0, 20) : fieldName;
+                const { code } = this.lookupAnswerCode(fieldName, choiceValue);
+                const baseType = this.questionBaseTypeMap.get(truncated);
+                if (baseType === 'select_multiple') {
+                    return `(${truncated}_${code}.NAOK == "Y")`;
+                }
+                return `(${truncated}.NAOK=="${code}")`;
+            },
+        };
+        return await convertRelevance(relevant, ctx);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xlsform2lstsv",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Convert XLSForm surveys to LimeSurvey TSV format",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",