schema-markdown 1.1.6 → 1.2.2

package/README.md

@@ -3,91 +3,105 @@
 [![npm](https://img.shields.io/npm/v/schema-markdown)](https://www.npmjs.com/package/schema-markdown)
 [![GitHub](https://img.shields.io/github/license/craigahobbs/schema-markdown-js)](https://github.com/craigahobbs/schema-markdown-js/blob/main/LICENSE)
 
-**Schema Markdown** is a human-friendly schema definition language and schema validator. Here are
-its features at a glance:
-
-- Schema-validate JSON objects
-- Human-friendly schema definition
-- Validates member value and length contraints
-- Validation *type-massages* string member values
-- Pure JavaScript
+**schema-markdown** is a schema definition and validation library.
 
 
 ## Links
 
-- [Schema Markdown Language Reference](https://craigahobbs.github.io/schema-markdown/schema-markdown.html)
-- [Documentation on GitHub Pages](https://craigahobbs.github.io/schema-markdown-js/)
-- [Package on npm](https://www.npmjs.com/package/schema-markdown)
-- [Source code on GitHub](https://github.com/craigahobbs/schema-markdown-js)
+- [The Schema Markdown Language](https://craigahobbs.github.io/schema-markdown-js/language/)
+- [API Documentation](https://craigahobbs.github.io/schema-markdown-js/)
+- [Source code](https://github.com/craigahobbs/schema-markdown-js)
 
 
-## Usage
+## Define a Schema
 
-To schema-validate an object, first parse its *Schema Markdown* using the
-[SchemaMarkdownParser](https://craigahobbs.github.io/schema-markdown-js/module-lib_parser.SchemaMarkdownParser.html)
-class:
+Schemas are defined using the
+[Schema Markdown language](https://craigahobbs.github.io/schema-markdown-js/language/),
+which is parsed by the
+[parseSchemaMarkdown](https://craigahobbs.github.io/schema-markdown-js/module-lib_parser.html#.parseSchemaMarkdown)
+function. For example:
 
 ``` javascript
-import {SchemaMarkdownParser} from 'schema-markdown/parser.js';
-import {validateType} from 'schema-markdown/schema.js';
-
-const parser = new SchemaMarkdownParser(`\
-# An aggregation function
-enum Aggregation
-    Average
-    Sum
+import {parseSchemaMarkdown} from 'schema-markdown/parser.js';
 
+export const modelTypes = parseSchemaMarkdown(`\
 # An aggregate numerical operation
-struct Operation
+struct Aggregation
+
     # The aggregation function - default is "Sum"
-    optional Aggregation aggregation
+    optional AggregationFunction aggregation
 
-    # The numbers to operate on
+    # The numbers to aggregate on
     int[len > 0] numbers
+
+# An aggregation function
+enum AggregationFunction
+    Average
+    Sum
 `);
 ```
 
-Then, validate an object using the
+
+## Validate using a Schema
+
+To validate an object using the schema, use the
 [validateType](https://craigahobbs.github.io/schema-markdown-js/module-lib_schema.html#.validateType)
-function:
+function. For example:
 
 ``` javascript
-const obj = validateType(parser.types, 'Operation', {
-    'numbers': [1, 2, '3', 4]
-});
+import {validateType} from 'schema-markdown/schema.js';
+
+const obj = validateType(modelTypes, 'Aggregation', {'numbers': [1, 2, '3', 4]});
 console.assert(obj.numbers[2] === 3);
 ```
 
 Notice that the numerical input '3' above is *type-massaged* to the integer 3 by validation.
+
 Validation fails if the object does not match the schema:
 
 ``` javascript
 try {
-    validateType(parser.types, 'Operation', {
-        'numbers': [1, 2, 'asdf', 4]
-    });
+    validateType(modelTypes, 'Aggregation', {'numbers': [1, 2, 'asdf', 4]});
 } catch ({message}) {
     console.assert(message === "Invalid value \"asdf\" (type 'string') for member 'numbers.2', expected type 'int'", message);
 }
 ```
 
-Validation also fails if a member contraint is violated:
+Validation also fails if a member constraint is violated:
 
 ``` javascript
 try {
-    validateType(parser.types, 'Operation', {
-        'numbers': []
-    });
+    validateType(modelTypes, 'Aggregation', {'numbers': []});
 } catch ({message}) {
     console.assert(message === "Invalid value [] (type 'object') for member 'numbers', expected type 'array' [len > 0]", message);
 }
 ```
 
 
+## Document a Schema
+
+To document the schema, download the
+[documentation application](https://github.com/craigahobbs/schema-markdown-doc#the-schema-markdown-documentation-viewer)
+stub and save the type model as JSON:
+
+~~~
+curl -O https://craigahobbs.github.io/schema-markdown-doc/extra/index.html
+node --input-type=module \
+    -e 'import {modelTypes} from "model.js"; console.log(JSON.stringify(modelTypes))' \
+    > model.json
+~~~
+
+To host locally, start a local static web server:
+
+```
+python3 -m http.server
+```
+
+
 ## Development
 
-schema-markdown is developed using [javascript-build](https://github.com/craigahobbs/javascript-build#readme)
-and it was started using [javascript-template](https://github.com/craigahobbs/javascript-template#readme):
+This package is developed using [javascript-build](https://github.com/craigahobbs/javascript-build#readme).
+It was started using [javascript-template](https://github.com/craigahobbs/javascript-template#readme) as follows:
 
 ```
 template-specialize javascript-template/template/ schema-markdown-js/ -k package schema-markdown -k name 'Craig A. Hobbs' -k email 'craigahobbs@gmail.com' -k github 'craigahobbs' -k noapp 1

package/lib/parser.js

@@ -5,106 +5,457 @@
 
 import {validateTypeModelErrors} from './schemaUtil.js';
 
-/* eslint-disable prefer-template */
+
+// Built-in types
+const builtinTypes = new Set(['bool', 'date', 'datetime', 'float', 'int', 'object', 'string', 'uuid']);
 
 
 // Schema Markdown regex
-const RE_PART_ID = '(?:[A-Za-z]\\w*)';
-const RE_PART_ATTR_GROUP =
+const rPartId = '(?:[A-Za-z]\\w*)';
+const rPartAttrGroup =
       '(?:(?<nullable>nullable)' +
       '|(?<op><=|<|>|>=|==)\\s*(?<opnum>-?\\d+(?:\\.\\d+)?)' +
       '|(?<ltype>len)\\s*(?<lop><=|<|>|>=|==)\\s*(?<lopnum>\\d+))';
-const RE_PART_ATTR = RE_PART_ATTR_GROUP.replace(/\(\?<[^>]+>/g, '(?:');
-const RE_PART_ATTRS = '(?:' + RE_PART_ATTR + '(?:\\s*,\\s*' + RE_PART_ATTR + ')*)';
-const RE_ATTR_GROUP = new RegExp(RE_PART_ATTR_GROUP);
-const RE_FIND_ATTRS = new RegExp(RE_PART_ATTR + '(?:\\s*,\\s*|\\s*$)', 'g');
-const RE_LINE_CONT = /\\\s*$/;
-const RE_COMMENT = /^\s*(?:#-.*|#(?<doc>.*))?$/;
-const RE_GROUP = /^group(?:\s+"(?<group>.+?)")?\s*$/;
-const RE_ACTION = new RegExp('^action\\s+(?<id>' + RE_PART_ID + ')');
-const RE_PART_BASE_IDS = '(?:\\s*\\(\\s*(?<base_ids>' + RE_PART_ID + '(?:\\s*,\\s*' + RE_PART_ID + ')*)\\s*\\)\\s*)';
-const RE_BASE_IDS_SPLIT = /\s*,\s*/;
-const RE_DEFINITION = new RegExp('^(?<type>struct|union|enum)\\s+(?<id>' + RE_PART_ID + ')' + RE_PART_BASE_IDS + '?\\s*$');
-const RE_SECTION = new RegExp('^\\s+(?<type>path|query|input|output|errors)' + RE_PART_BASE_IDS + '?\\s*$');
-const RE_SECTION_PLAIN = /^\s+(?<type>urls)\s*$/;
-const RE_PART_TYPEDEF =
-      '(?<type>' + RE_PART_ID + ')' +
-      '(?:\\s*\\(\\s*(?<attrs>' + RE_PART_ATTRS + ')\\s*\\))?' +
+const rPartAttr = rPartAttrGroup.replace(/\(\?<[^>]+>/g, '(?:');
+const rPartAttrs = `(?:${rPartAttr}(?:\\s*,\\s*${rPartAttr})*)`;
+const rAttrGroup = new RegExp(rPartAttrGroup);
+const rFindAttrs = new RegExp(`${rPartAttr}(?:\\s*,\\s*|\\s*$)`, 'g');
+const rLineCont = /\\\s*$/;
+const rComment = /^\s*(?:#-.*|#(?<doc>.*))?$/;
+const rGroup = /^group(?:\s+"(?<group>.+?)")?\s*$/;
+const rAction = new RegExp(`^action\\s+(?<id>${rPartId})`);
+const rPartBaseIds = `(?:\\s*\\(\\s*(?<baseIds>${rPartId}(?:\\s*,\\s*${rPartId})*)\\s*\\)\\s*)`;
+const rBaseIdsSplit = /\s*,\s*/;
+const rDefinition = new RegExp(`^(?<type>struct|union|enum)\\s+(?<id>${rPartId})${rPartBaseIds}?\\s*$`);
+const rSection = new RegExp(`^\\s+(?<type>path|query|input|output|errors)${rPartBaseIds}?\\s*$`);
+const rSectionPlain = /^\s+(?<type>urls)\s*$/;
+const rPartTypedef =
+      `(?<type>${rPartId})` +
+      `(?:\\s*\\(\\s*(?<attrs>${rPartAttrs})\\s*\\))?` +
       '(?:' +
-      '(?:\\s*\\[\\s*(?<array>' + RE_PART_ATTRS + '?)\\s*\\])?' +
+      `(?:\\s*\\[\\s*(?<array>${rPartAttrs}?)\\s*\\])?` +
       '|' +
       '(?:' +
-      '\\s*:\\s*(?<dictValueType>' + RE_PART_ID + ')' +
-      '(?:\\s*\\(\\s*(?<dictValueAttrs>' + RE_PART_ATTRS + ')\\s*\\))?' +
+      `\\s*:\\s*(?<dictValueType>${rPartId})` +
+      `(?:\\s*\\(\\s*(?<dictValueAttrs>${rPartAttrs})\\s*\\))?` +
       ')?' +
-      '(?:\\s*\\{\\s*(?<dict>' + RE_PART_ATTRS + '?)\\s*\\})?' +
+      `(?:\\s*\\{\\s*(?<dict>${rPartAttrs}?)\\s*\\})?` +
       ')' +
-      '\\s+(?<id>' + RE_PART_ID + ')';
-const RE_TYPEDEF = new RegExp('^typedef\\s+' + RE_PART_TYPEDEF + '\\s*$');
-const RE_MEMBER = new RegExp('^\\s+(?<optional>optional\\s+)?' + RE_PART_TYPEDEF + '\\s*$');
-const RE_VALUE = new RegExp('^\\s+(?<id>' + RE_PART_ID + ')\\s*$');
-const RE_VALUE_QUOTED = /^\s+"(?<id>.*?)"\s*$/;
-const RE_URL = /^\s+(?<method>[A-Za-z]+|\*)(?:\s+(?<path>\/[^\s]*))?/;
+      `\\s+(?<id>${rPartId})`;
+const rTypedef = new RegExp(`^typedef\\s+${rPartTypedef}\\s*$`);
+const rMember = new RegExp(`^\\s+(?<optional>optional\\s+)?${rPartTypedef}\\s*$`);
+const rValue = new RegExp(`^\\s+(?<id>${rPartId})\\s*$`);
+const rValueQuoted = /^\s+"(?<id>.*?)"\s*$/;
+const rURL = /^\s+(?<method>[A-Za-z]+|\*)(?:\s+(?<path>\/[^\s]*))?/;
+const rLineSplit = /\r?\n/;
 
 
-// Built-in types
-const BUILTIN_TYPES = new Set(['bool', 'date', 'datetime', 'float', 'int', 'object', 'string', 'uuid']);
+/**
+ * Parse Schema Markdown from a string or an iterator of strings
+ *
+ * @param {string|string[]} text - The Schema Markdown text
+ * @param {Object} [options.types=''] - The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
+ * @param {string} [options.filename=''] - The name of file being parsed (for error messages)
+ * @param {boolean} [options.validate=true] - If true, validate after parsing
+ * @returns {Object} The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
+ * @throws [SchemaMarkdownParserError]{@link module:lib/parser.SchemaMarkdownParserError}
+ */
+export function parseSchemaMarkdown(text, {types = {}, filename = '', validate = true} = {}) {
+    // Current parser state
+    const errorMap = {};
+    const filepos = {};
+    let action = null;
+    let urls = null;
+    let userType = null;
+    let doc = [];
+    let docGroup = null;
+    let linenum = 0;
+
+    // Helper function to add an error message
+    const addError = (msg, errorFilename, errorLinenum) => {
+        const errorMsg = `${errorFilename}:${errorLinenum}: error: ${msg}`;
+        errorMap[errorMsg] = [errorFilename, errorLinenum, errorMsg];
+    };
+
+    // Helper function to get documentation strings
+    const getDoc = () => {
+        let result = null;
+        if (doc.length) {
+            result = doc;
+            doc = [];
+        }
+        return result;
+    };
+
+    // Line-split all script text
+    const lines = [];
+    if (typeof text === 'string') {
+        lines.push(...text.split(rLineSplit));
+    } else {
+        for (const textPart of text) {
+            lines.push(...textPart.split(rLineSplit));
+        }
+    }
+    lines.push('');
 
+    // Process each line
+    const lineContinuation = [];
+    for (const linePart of lines) {
+        linenum += 1;
 
-// Helper function to parse an attributes string - returns an attributes model
-function parseAttr(attrsString) {
-    let attrs = null;
-    if (typeof attrsString !== 'undefined') {
-        for (const [attrString] of attrsString.matchAll(RE_FIND_ATTRS)) {
-            if (attrs === null) {
-                attrs = {};
+        // Line continuation?
+        const linePartNoContinuation = linePart.replace(rLineCont, '');
+        if (lineContinuation.length || linePartNoContinuation !== linePart) {
+            lineContinuation.push(linePartNoContinuation);
+        }
+        if (linePartNoContinuation !== linePart) {
+            continue;
+        }
+        let line;
+        if (lineContinuation.length) {
+            line = lineContinuation.join('');
+            lineContinuation.length = 0;
+        } else {
+            line = linePart;
+        }
+
+        // Match syntax
+        let matchName = 'comment';
+        let match = line.match(rComment);
+        if (match === null) {
+            matchName = 'group';
+            match = line.match(rGroup);
+        }
+        if (match === null) {
+            matchName = 'action';
+            match = line.match(rAction);
+        }
+        if (match === null) {
+            matchName = 'definition';
+            match = line.match(rDefinition);
+        }
+        if (match === null && action !== null) {
+            matchName = 'section';
+            match = line.match(rSection);
+        }
+        if (match === null && action !== null) {
+            matchName = 'sectionPlain';
+            match = line.match(rSectionPlain);
+        }
+        if (match === null && userType !== null && 'enum' in userType) {
+            matchName = 'value';
+            match = line.match(rValue);
+            if (match === null) {
+                match = line.match(rValueQuoted);
             }
-            const matchAttr = attrString.match(RE_ATTR_GROUP);
-            const attrOp = matchAttr.groups.op;
-            const attrLengthOp = matchAttr.groups.lop;
+        }
+        if (match === null && userType !== null && 'struct' in userType) {
+            matchName = 'member';
+            match = line.match(rMember);
+        }
+        if (match === null && urls !== null) {
+            matchName = 'urls';
+            match = line.match(rURL);
+        }
+        if (match === null) {
+            matchName = 'typedef';
+            match = line.match(rTypedef);
+        }
+        if (match === null) {
+            matchName = null;
+        }
 
-            if (typeof matchAttr.groups.nullable !== 'undefined') {
-                attrs.nullable = true;
-            } else if (typeof attrOp !== 'undefined') {
-                const attrValue = parseFloat(matchAttr.groups.opnum);
-                if (attrOp === '<') {
-                    attrs.lt = attrValue;
-                } else if (attrOp === '<=') {
-                    attrs.lte = attrValue;
-                } else if (attrOp === '>') {
-                    attrs.gt = attrValue;
-                } else if (attrOp === '>=') {
-                    attrs.gte = attrValue;
-                } else {
-                    attrs.eq = attrValue;
+        // Comment?
+        if (matchName === 'comment') {
+            const docString = match.groups.doc;
+            if (typeof docString !== 'undefined') {
+                doc.push(!docString.startsWith(' ') ? docString : docString.slice(1));
+            }
+
+        // Documentation group?
+        } else if (matchName === 'group') {
+            docGroup = match.groups.group;
+            if (typeof docGroup !== 'undefined') {
+                docGroup = docGroup.trim();
+            } else {
+                docGroup = null;
+            }
+
+        // Action?
+        } else if (matchName === 'action') {
+            const actionId = match.groups.id;
+
+            // Action already defined?
+            if (actionId in types) {
+                addError(`Redefinition of action '${actionId}'`, filename, linenum);
+            }
+
+            // Clear parser state
+            urls = null;
+            userType = null;
+            const actionDoc = getDoc();
+
+            // Create the new action
+            action = {'name': actionId};
+            types[actionId] = {'action': action};
+            if (actionDoc !== null) {
+                action.doc = actionDoc;
+            }
+            if (docGroup !== null) {
+                action.docGroup = docGroup;
+            }
+
+        // Definition?
+        } else if (matchName === 'definition') {
+            const definitionString = match.groups.type;
+            const definitionId = match.groups.id;
+            const definitionBaseIds = match.groups.baseIds;
+
+            // Type already defined?
+            if (builtinTypes.has(definitionId) || definitionId in types) {
+                addError(`Redefinition of type '${definitionId}'`, filename, linenum);
+            }
+
+            // Clear parser state
+            action = null;
+            urls = null;
+            const definitionDoc = getDoc();
+
+            // Struct definition
+            if (definitionString === 'struct' || definitionString === 'union') {
+                // Create the new struct type
+                const struct = {'name': definitionId};
+                userType = {'struct': struct};
+                types[definitionId] = userType;
+                if (definitionDoc !== null) {
+                    struct.doc = definitionDoc;
+                }
+                if (docGroup !== null) {
+                    struct.docGroup = docGroup;
+                }
+                if (definitionString === 'union') {
+                    struct.union = true;
+                }
+                if (typeof definitionBaseIds !== 'undefined') {
+                    struct.bases = definitionBaseIds.split(rBaseIdsSplit);
                 }
+
+            // Enum definition
             } else {
-                // typeof attrLengthOp !== 'undefined'
-                const attrValue = parseInt(matchAttr.groups.lopnum, 10);
-                if (attrLengthOp === '<') {
-                    attrs.lenLT = attrValue;
-                } else if (attrLengthOp === '<=') {
-                    attrs.lenLTE = attrValue;
-                } else if (attrLengthOp === '>') {
-                    attrs.lenGT = attrValue;
-                } else if (attrLengthOp === '>=') {
-                    attrs.lenGTE = attrValue;
-                } else {
-                    attrs.lenEq = attrValue;
+                // definitionString == 'enum':
+                // Create the new enum type
+                const enum_ = {'name': definitionId};
+                userType = {'enum': enum_};
+                types[definitionId] = userType;
+                if (definitionDoc !== null) {
+                    enum_.doc = definitionDoc;
+                }
+                if (docGroup !== null) {
+                    enum_.docGroup = docGroup;
+                }
+                if (typeof definitionBaseIds !== 'undefined') {
+                    enum_.bases = definitionBaseIds.split(rBaseIdsSplit);
+                }
+            }
+
+            // Record the definition's line number
+            filepos[definitionId] = linenum;
+
+        // Action section?
+        } else if (matchName === 'section') {
+            const sectionString = match.groups.type;
+            const sectionBaseIds = match.groups.baseIds;
+
+            // Action section redefinition?
+            if (sectionString in action) {
+                addError(`Redefinition of action ${sectionString}`, filename, linenum);
+            }
+
+            // Clear parser state
+            urls = null;
+
+            // Set the action section type
+            const sectionTypeName = `${action.name}_${sectionString}`;
+            action[sectionString] = sectionTypeName;
+            if (sectionString === 'errors') {
+                const enum_ = {'name': sectionTypeName};
+                userType = {'enum': enum_};
+                types[sectionTypeName] = userType;
+                if (typeof sectionBaseIds !== 'undefined') {
+                    enum_.bases = sectionBaseIds.split(rBaseIdsSplit);
+                }
+            } else {
+                const struct = {'name': sectionTypeName};
+                userType = {'struct': struct};
+                types[sectionTypeName] = userType;
+                if (typeof sectionBaseIds !== 'undefined') {
+                    struct.bases = sectionBaseIds.split(rBaseIdsSplit);
                 }
             }
+
+            // Record the definition's line number
+            filepos[sectionTypeName] = linenum;
+
+        // Plain action section?
+        } else if (matchName === 'sectionPlain') {
+            const sectionString = match.groups.type;
+
+            // Action section redefinition?
+            if (sectionString in action) {
+                addError(`Redefinition of action ${sectionString}`, filename, linenum);
+            }
+
+            // Clear parser state
+            userType = null;
+
+            // Update the parser state
+            urls = [];
+
+        // Enum value?
+        } else if (matchName === 'value') {
+            const valueString = match.groups.id;
+
+            // Add the enum value
+            const enum_ = userType.enum;
+            if (!('values' in enum_)) {
+                enum_.values = [];
+            }
+            const enumValue = {'name': valueString};
+            enum_.values.push(enumValue);
+            const enumValueDoc = getDoc();
+            if (enumValueDoc !== null) {
+                enumValue.doc = enumValueDoc;
+            }
+
+            // Record the definition's line number
+            filepos[`${enum_.name}.${valueString}`] = linenum;
+
+        // Struct member?
+        } else if (matchName === 'member') {
+            const optional = typeof match.groups.optional !== 'undefined';
+            const memberName = match.groups.id;
+
+            // Add the member
+            const {struct} = userType;
+            if (!('members' in struct)) {
+                struct.members = [];
+            }
+            const [memberType, memberAttr] = parseTypedef(match);
+            const memberDoc = getDoc();
+            const member = {
+                'name': memberName,
+                'type': memberType
+            };
+            struct.members.push(member);
+            if (memberAttr !== null) {
+                member.attr = memberAttr;
+            }
+            if (memberDoc !== null) {
+                member.doc = memberDoc;
+            }
+            if (optional) {
+                member.optional = true;
+            }
+
+            // Record the definition's line number
+            filepos[`${struct.name}.${memberName}`] = linenum;
+
+        // URL?
+        } else if (matchName === 'urls') {
+            const {method, path} = match.groups;
+
+            // Create the action URL object
+            const actionUrl = {};
+            if (method !== '*') {
+                actionUrl.method = method;
+            }
+            if (typeof path !== 'undefined') {
+                actionUrl.path = path;
+            }
+
+            // Duplicate URL?
+            if (urls.some((url) => url.method === actionUrl.method && url.path === actionUrl.path)) {
+                addError(`Duplicate URL: ${method} ${'path' in actionUrl ? actionUrl.path : ''}`, filename, linenum);
+            }
+
+            // Add the URL
+            if (!('urls' in action)) {
+                action.urls = urls;
+            }
+            urls.push(actionUrl);
+
+        // Typedef?
+        } else if (matchName === 'typedef') {
+            const definitionId = match.groups.id;
+
+            // Type already defined?
+            if (builtinTypes.has(definitionId) || definitionId in types) {
+                addError(`Redefinition of type '${definitionId}'`, filename, linenum);
+            }
+
+            // Clear parser state
+            action = null;
+            urls = null;
+            userType = null;
+            const typedefDoc = getDoc();
+
+            // Create the typedef
+            const [typedefType, typedefAttr] = parseTypedef(match);
+            const typedef = {
+                'name': definitionId,
+                'type': typedefType
+            };
+            types[definitionId] = {'typedef': typedef};
+            if (typedefAttr !== null) {
+                typedef.attr = typedefAttr;
+            }
+            if (typedefDoc !== null) {
+                typedef.doc = typedefDoc;
+            }
+            if (docGroup !== null) {
+                typedef.docGroup = docGroup;
+            }
+
+            // Record the definition's line number
+            filepos[definitionId] = linenum;
+
+        // Unrecognized line syntax
+        } else {
+            addError('Syntax error', filename, linenum);
         }
     }
-    return attrs;
-}
 
+    // Validate the type model, if requested
+    if (validate) {
+        for (const [typeName, memberName, errorMsg] of validateTypeModelErrors(types)) {
+            let errorFilename = filename;
+            let errorLinenum = null;
+            if (memberName !== null) {
+                errorLinenum = filepos[`${typeName}.${memberName}`] ?? null;
+            }
+            if (errorLinenum === null) {
+                errorLinenum = filepos[typeName] ?? null;
+            }
+            if (errorLinenum === null) {
+                errorFilename = '';
+                errorLinenum = 1;
+            }
+            addError(errorMsg, errorFilename, errorLinenum);
+        }
+    }
 
-// Helper function to create a type model
-function createType(typeName) {
-    if (BUILTIN_TYPES.has(typeName)) {
-        return {'builtin': typeName};
+    // Raise a parser exception if there are any errors
+    const errors = Array.from(Object.values(errorMap)).sort(compareTuple).map(([,, msg]) => msg);
+    if (errors.length) {
+        throw new SchemaMarkdownParserError(errors);
     }
-    return {'user': typeName};
+
+    return types;
+}
+
+
+function compareTuple(v1, v2) {
+    return v1.reduce((tot, val, idx) => (tot !== 0 ? tot : (val < v2[idx] ? -1 : (val > v2[idx] ? 1 : 0))), 0);
 }
 
 
@@ -159,9 +510,61 @@ function parseTypedef(matchTypedef) {
 }
 
 
-// Helper function to compare tuples/lists
-const compareTuple =
-      (v1, v2) => (v1.reduce((tot, val, idx) => (tot !== 0 ? tot : (val < v2[idx] ? -1 : (val > v2[idx] ? 1 : 0))), 0));
+// Helper function to create a type model
+function createType(typeName) {
+    if (builtinTypes.has(typeName)) {
+        return {'builtin': typeName};
+    }
+    return {'user': typeName};
+}
+
+
+// Helper function to parse an attributes string - returns an attributes model
+function parseAttr(attrsString) {
+    let attrs = null;
+    if (typeof attrsString !== 'undefined') {
+        for (const [attrString] of attrsString.matchAll(rFindAttrs)) {
+            if (attrs === null) {
+                attrs = {};
+            }
+            const matchAttr = attrString.match(rAttrGroup);
+            const attrOp = matchAttr.groups.op;
+            const attrLengthOp = matchAttr.groups.lop;
+
+            if (typeof matchAttr.groups.nullable !== 'undefined') {
+                attrs.nullable = true;
+            } else if (typeof attrOp !== 'undefined') {
+                const attrValue = parseFloat(matchAttr.groups.opnum);
+                if (attrOp === '<') {
+                    attrs.lt = attrValue;
+                } else if (attrOp === '<=') {
+                    attrs.lte = attrValue;
+                } else if (attrOp === '>') {
+                    attrs.gt = attrValue;
+                } else if (attrOp === '>=') {
+                    attrs.gte = attrValue;
+                } else {
+                    attrs.eq = attrValue;
+                }
+            } else {
+                // typeof attrLengthOp !== 'undefined'
+                const attrValue = parseInt(matchAttr.groups.lopnum, 10);
+                if (attrLengthOp === '<') {
+                    attrs.lenLT = attrValue;
+                } else if (attrLengthOp === '<=') {
+                    attrs.lenLTE = attrValue;
+                } else if (attrLengthOp === '>') {
+                    attrs.lenGT = attrValue;
+                } else if (attrLengthOp === '>=') {
+                    attrs.lenGTE = attrValue;
+                } else {
+                    attrs.lenEq = attrValue;
+                }
+            }
+        }
+    }
+    return attrs;
+}
 
 
 /**
@@ -180,456 +583,3 @@ export class SchemaMarkdownParserError extends Error {
         this.errors = errors;
     }
 }
-
-
-/**
- * The parser class for Schema Markdown. Parsing can occur at initialization time or by calling the
- * "parseString" method, which can be called repeatedly.
- *
- * @property {Object} types - The map of user type name to user type model
- * @property {Object} errorMap - Set of filename, linenum, and error-message tuples
- * @property {Object} filepos - Map of definition-name to filename/linenum-tuples
- */
-export class SchemaMarkdownParser {
-    /**
-     * Create a Schema Markdown parser instance
-     *
-     * @param {string} [text=null]: An optional Schema Markdown string to parse
-     * @param {Object} [types=null]: An optional map of user type name to user type model
-     * @throws {SchemaMarkdownParserError}
-     */
-    constructor(text = null, types = null) {
-        this.types = types !== null ? types : {};
-        this.errorMap = {};
-        this.filepos = {};
-
-        // Parse the Schema Markdown string, if any
-        if (text !== null) {
-            this.parseString(text);
-        }
-    }
-
-    addError(msg, filename, linenum) {
-        const errorMsg = `${filename}:${linenum}: error: ${msg}`;
-        this.errorMap[errorMsg] = [filename, linenum, errorMsg];
-    }
-
-    getFilepos(typeName, typeKey) {
-        let filepos = null;
-        if (typeKey !== null) {
-            const key = `${typeName}.${typeKey}`;
-            filepos = key in this.filepos ? this.filepos[key] : null;
-        }
-        if (filepos === null) {
-            filepos = typeName in this.filepos ? this.filepos[typeName] : null;
-        }
-        if (filepos === null) {
-            filepos = ['', 1];
-        }
-        return filepos;
-    }
-
-    /**
-     * The list of parser error strings
-     */
-    get errors() {
-        return Array.from(Object.values(this.errorMap)).sort(compareTuple).map(([,, msg]) => msg);
-    }
-
-    /**
-     * Finalize a parsing operation. You only need to call this method if you set the "parse"
-     * method's "finalize" argument to false.
-     *
-     * @throws {SchemaMarkdownParserError}
-     */
-    finalize() {
-        // Do the finalization
-        for (const [typeName, memberName, errorMsg] of validateTypeModelErrors(this.types)) {
-            this.addError(errorMsg, ...this.getFilepos(typeName, memberName));
-        }
-
-        // Raise a parser exception if there are any errors
-        const {errors} = this;
-        if (errors.length) {
-            throw new SchemaMarkdownParserError(errors);
-        }
-    }
-
-    /**
-     * Parse a Schema Markdown string. This method can be called repeatedly.
-     *
-     * @param {string} text - The Schema Markdown string
-     * @param {string} [filename=''] - The name of file being parsed (for error messages)
-     * @param {boolean} [finalize=true] - If true, resolve names after parsing. Be sure to call the
-     *     "finalize" method when finished.
-     * @throws {SchemaMarkdownParserError}
-     */
-    parseString(text, filename = '', finalize = true) {
-        this.parse(text.split(/\r?\n/), filename, finalize);
-    }
-
-    /**
-     * Parse Schema Markdown from an iterator of line strings (e.g an input stream). This method can
-     * be called repeatedly.
-     *
-     * @param {string[]} lines - An array of Schema Markdown line strings
-     * @param {string} [filename=''] - The name of file being parsed (for error messages)
-     * @param {boolean} [finalize=true] - If true, resolve names after parsing. Be sure to call the
-     *     "finalize" method when finished.
-     * @throws {SchemaMarkdownParserError}
-     */
-    parse(lines, filename = '', finalize = true) {
-        // Current parser state
-        let action = null;
-        let urls = null;
-        let userType = null;
-        let doc = [];
-        let docGroup = null;
-        let linenum = 0;
-
-        // Helper function to get documentation strings
-        const getDoc = () => {
-            let result = null;
-            if (doc.length) {
-                result = doc;
-                doc = [];
-            }
-            return result;
-        };
-
-        // Process each line
-        const lineContinuation = [];
-        const lineGroups = [lines, ['']];
-        for (const lineGroup of lineGroups) {
-            for (const linePart of lineGroup) {
-                linenum += 1;
-
-                // Line continuation?
-                const linePartNoContinuation = linePart.replace(RE_LINE_CONT, '');
-                if (lineContinuation.length || linePartNoContinuation !== linePart) {
-                    lineContinuation.push(linePartNoContinuation);
-                }
-                if (linePartNoContinuation !== linePart) {
-                    continue;
-                }
-                let line;
-                if (lineContinuation.length) {
-                    line = lineContinuation.join('');
-                    lineContinuation.length = 0;
-                } else {
-                    line = linePart;
-                }
-
-                // Match syntax
-                let matchName = 'comment';
-                let match = line.match(RE_COMMENT);
-                if (match === null) {
-                    matchName = 'group';
-                    match = line.match(RE_GROUP);
-                }
-                if (match === null) {
-                    matchName = 'action';
-                    match = line.match(RE_ACTION);
-                }
-                if (match === null) {
-                    matchName = 'definition';
-                    match = line.match(RE_DEFINITION);
-                }
-                if (match === null && action !== null) {
-                    matchName = 'section';
-                    match = line.match(RE_SECTION);
-                }
-                if (match === null && action !== null) {
-                    matchName = 'section_plain';
-                    match = line.match(RE_SECTION_PLAIN);
-                }
-                if (match === null && userType !== null && 'enum' in userType) {
-                    matchName = 'value';
-                    match = line.match(RE_VALUE);
-                    if (match === null) {
-                        match = line.match(RE_VALUE_QUOTED);
-                    }
-                }
-                if (match === null && userType !== null && 'struct' in userType) {
-                    matchName = 'member';
-                    match = line.match(RE_MEMBER);
-                }
-                if (match === null && urls !== null) {
-                    matchName = 'urls';
-                    match = line.match(RE_URL);
-                }
-                if (match === null) {
-                    matchName = 'typedef';
-                    match = line.match(RE_TYPEDEF);
-                }
-                if (match === null) {
-                    matchName = null;
-                }
-
-                // Comment?
-                if (matchName === 'comment') {
-                    const docString = match.groups.doc;
-                    if (typeof docString !== 'undefined') {
-                        doc.push(!docString.startsWith(' ') ? docString : docString.slice(1));
-                    }
-
-                // Documentation group?
-                } else if (matchName === 'group') {
-                    docGroup = match.groups.group;
-                    if (typeof docGroup !== 'undefined') {
-                        docGroup = docGroup.trim();
-                    } else {
-                        docGroup = null;
-                    }
-
-                // Action?
-                } else if (matchName === 'action') {
-                    const actionId = match.groups.id;
-
-                    // Action already defined?
-                    if (actionId in this.types) {
-                        this.addError(`Redefinition of action '${actionId}'`, filename, linenum);
-                    }
-
-                    // Clear parser state
-                    urls = null;
-                    userType = null;
-                    const actionDoc = getDoc();
-
-                    // Create the new action
-                    action = {'name': actionId};
-                    this.types[actionId] = {'action': action};
-                    if (actionDoc !== null) {
-                        action.doc = actionDoc;
-                    }
-                    if (docGroup !== null) {
-                        action.docGroup = docGroup;
-                    }
-
-                // Definition?
-                } else if (matchName === 'definition') {
-                    const definitionString = match.groups.type;
-                    const definitionId = match.groups.id;
-                    const definitionBaseIds = match.groups.base_ids;
-
-                    // Type already defined?
-                    if (BUILTIN_TYPES.has(definitionId) || definitionId in this.types) {
-                        this.addError(`Redefinition of type '${definitionId}'`, filename, linenum);
-                    }
-
-                    // Clear parser state
-                    action = null;
-                    urls = null;
-                    const definitionDoc = getDoc();
-
-                    // Struct definition
-                    if (definitionString === 'struct' || definitionString === 'union') {
-                        // Create the new struct type
-                        const struct = {'name': definitionId};
-                        userType = {'struct': struct};
-                        this.types[definitionId] = userType;
-                        if (definitionDoc !== null) {
-                            struct.doc = definitionDoc;
-                        }
-                        if (docGroup !== null) {
-                            struct.docGroup = docGroup;
-                        }
-                        if (definitionString === 'union') {
-                            struct.union = true;
-                        }
-                        if (typeof definitionBaseIds !== 'undefined') {
-                            struct.bases = definitionBaseIds.split(RE_BASE_IDS_SPLIT);
-                        }
-
-                    // Enum definition
-                    } else {
-                        // definition_string == 'enum':
-                        // Create the new enum type
-                        const enum_ = {'name': definitionId};
-                        userType = {'enum': enum_};
-                        this.types[definitionId] = userType;
-                        if (definitionDoc !== null) {
-                            enum_.doc = definitionDoc;
-                        }
-                        if (docGroup !== null) {
-                            enum_.docGroup = docGroup;
-                        }
-                        if (typeof definitionBaseIds !== 'undefined') {
-                            enum_.bases = definitionBaseIds.split(RE_BASE_IDS_SPLIT);
-                        }
-                    }
-
-                    // Record finalization information
-                    this.filepos[definitionId] = [filename, linenum];
-
-                // Action section?
-                } else if (matchName === 'section') {
-                    const sectionString = match.groups.type;
-                    const sectionBaseIds = match.groups.base_ids;
-
-                    // Action section redefinition?
-                    if (sectionString in action) {
-                        this.addError(`Redefinition of action ${sectionString}`, filename, linenum);
-                    }
-
-                    // Clear parser state
-                    urls = null;
-
-                    // Set the action section type
-                    const sectionTypeName = `${action.name}_${sectionString}`;
-                    action[sectionString] = sectionTypeName;
-                    if (sectionString === 'errors') {
-                        const enum_ = {'name': sectionTypeName};
-                        userType = {'enum': enum_};
-                        this.types[sectionTypeName] = userType;
-                        if (typeof sectionBaseIds !== 'undefined') {
-                            enum_.bases = sectionBaseIds.split(RE_BASE_IDS_SPLIT);
-                        }
-                    } else {
-                        const struct = {'name': sectionTypeName};
-                        userType = {'struct': struct};
-                        this.types[sectionTypeName] = userType;
-                        if (typeof sectionBaseIds !== 'undefined') {
-                            struct.bases = sectionBaseIds.split(RE_BASE_IDS_SPLIT);
-                        }
-                    }
-
-                    // Record finalization information
-                    this.filepos[sectionTypeName] = [filename, linenum];
-
-                // Plain action section?
-                } else if (matchName === 'section_plain') {
-                    const sectionString = match.groups.type;
-
-                    // Action section redefinition?
-                    if (sectionString in action) {
-                        this.addError(`Redefinition of action ${sectionString}`, filename, linenum);
-                    }
-
-                    // Clear parser state
-                    userType = null;
-
-                    // Update the parser state
-                    urls = [];
-
-                // Enum value?
-                } else if (matchName === 'value') {
-                    const valueString = match.groups.id;
-
-                    // Add the enum value
-                    const enum_ = userType.enum;
-                    if (!('values' in enum_)) {
-                        enum_.values = [];
-                    }
-                    const enumValue = {'name': valueString};
-                    enum_.values.push(enumValue);
-                    const enumValueDoc = getDoc();
-                    if (enumValueDoc !== null) {
-                        enumValue.doc = enumValueDoc;
-                    }
-
-                    // Record finalization information
-                    this.filepos[`${enum_.name}.${valueString}`] = [filename, linenum];
-
-                // Struct member?
-                } else if (matchName === 'member') {
-                    const optional = typeof match.groups.optional !== 'undefined';
-                    const memberName = match.groups.id;
-
-                    // Add the member
-                    const {struct} = userType;
-                    if (!('members' in struct)) {
-                        struct.members = [];
-                    }
-                    const [memberType, memberAttr] = parseTypedef(match);
-                    const memberDoc = getDoc();
-                    const member = {
-                        'name': memberName,
-                        'type': memberType
-                    };
-                    struct.members.push(member);
-                    if (memberAttr !== null) {
-                        member.attr = memberAttr;
-                    }
-                    if (memberDoc !== null) {
-                        member.doc = memberDoc;
-                    }
-                    if (optional) {
-                        member.optional = true;
-                    }
-
-                    // Record finalization information
-                    this.filepos[`${struct.name}.${memberName}`] = [filename, linenum];
-
-                // URL?
-                } else if (matchName === 'urls') {
-                    const {method, path} = match.groups;
-
-                    // Create the action URL object
-                    const actionUrl = {};
-                    if (method !== '*') {
-                        actionUrl.method = method;
-                    }
-                    if (typeof path !== 'undefined') {
-                        actionUrl.path = path;
-                    }
-
-                    // Duplicate URL?
-                    if (urls.some((url) => url.method === actionUrl.method && url.path === actionUrl.path)) {
-                        this.addError(`Duplicate URL: ${method} ${'path' in actionUrl ? actionUrl.path : ''}`, filename, linenum);
-                    }
-
-                    // Add the URL
-                    if (!('urls' in action)) {
-                        action.urls = urls;
-                    }
-                    urls.push(actionUrl);
-
-                // Typedef?
-                } else if (matchName === 'typedef') {
-                    const definitionId = match.groups.id;
-
-                    // Type already defined?
-                    if (BUILTIN_TYPES.has(definitionId) || definitionId in this.types) {
-                        this.addError(`Redefinition of type '${definitionId}'`, filename, linenum);
-                    }
-
-                    // Clear parser state
-                    action = null;
-                    urls = null;
-                    userType = null;
-                    const typedefDoc = getDoc();
-
-                    // Create the typedef
-                    const [typedefType, typedefAttr] = parseTypedef(match);
-                    const typedef = {
-                        'name': definitionId,
-                        'type': typedefType
-                    };
-                    this.types[definitionId] = {'typedef': typedef};
-                    if (typedefAttr !== null) {
-                        typedef.attr = typedefAttr;
-                    }
-                    if (typedefDoc !== null) {
-                        typedef.doc = typedefDoc;
-                    }
-                    if (docGroup !== null) {
-                        typedef.docGroup = docGroup;
-                    }
-
-                    // Record finalization information
-                    this.filepos[definitionId] = [filename, linenum];
-
-                // Unrecognized line syntax
-                } else {
-                    this.addError('Syntax error', filename, linenum);
-                }
-            }
-        }
-
-        // Finalize, if requested
-        if (finalize) {
-            this.finalize();
-        }
-    }
-}

package/lib/schema.js

@@ -10,10 +10,10 @@ import {validateTypeModelErrors} from './schemaUtil.js';
 /**
  * Get a user type's referenced type model
  *
- * @param {Object} types - The map of user type name to user type model
+ * @param {Object} types - The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
  * @param {string} typeName - The type name
  * @param {Object} [referencedTypes=null] - Optional map of referenced user type name to user type model
- * @returns {Object}
+ * @returns {Object} The referenced [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
  */
 export function getReferencedTypes(types, typeName, referencedTypes = {}) {
     return getReferencedTypesHelper(types, {'user': typeName}, referencedTypes);
@@ -104,7 +104,7 @@ export class ValidationError extends Error {
     /**
      * Schema Markdown type model validation error constructor
      *
-     * @param {string} [memberFqn=null] - Optional fully-qualified member name
+     * @param {string} [memberFqn=null] - The fully-qualified member name
      */
     constructor(message, memberFqn = null) {
         super(message);
@@ -117,12 +117,12 @@ export class ValidationError extends Error {
  * Type-validate a value using a user type model. Container values are duplicated since some member types are
  * transformed during validation.
  *
- * @param {Object} types - The map of user type name to user type model
+ * @param {Object} types - The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
  * @param {string} typeName - The type name
  * @param {Object} value - The value object to validate
- * @param {string} [memberFqn=null] - Optional fully-qualified member name
+ * @param {?string} [memberFqn=null] - The fully-qualified member name
  * @returns {Object} The validated, transformed value object
- * @throws {ValidationError} A validation error occurred
+ * @throws [ValidationError]{@link module:lib/schema.ValidationError}
  */
 export function validateType(types, typeName, value, memberFqn = null) {
     if (!(typeName in types)) {
@@ -448,9 +448,10 @@ function validateAttr(type, attr, value, memberFqn) {
 /**
  * Get the struct's members (inherited members first)
  *
- * @param {Object} types - The map of user type name to user type model
- * @param {Object} struct - The struct model
- * @returns {Array<Object>} The array of struct member models
+ * @param {Object} types - The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
+ * @param {Object} struct - The [struct model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Struct'}
+ * @returns {Array<Object>} The array of
+ *     [struct member models]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='StructMember'}
  */
 export function getStructMembers(types, struct) {
     // No base structs?
@@ -480,9 +481,10 @@ export function getStructMembers(types, struct) {
 /**
  * Get the enum's values (inherited values first)
  *
- * @param {Object} types - The map of user type name to user type model
- * @param {Object} enum_ - The enum model
- * @returns {Array<Object>} The array of enum value models
+ * @param {Object} types - The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
+ * @param {Object} enum_ - The [enum model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Enum'}
+ * @returns {Array<Object>} The array of
+ *     [enum value models]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='EnumValue'}
  */
 export function getEnumValues(types, enum_) {
     // No base enums?
@@ -512,9 +514,9 @@ export function getEnumValues(types, enum_) {
 /**
  * Validate a type model's types object
  *
- * @param {Object} types - The map of user type name to user type model
- * @returns {Object} The validated, transformed types object
- * @throws {ValidationError} A validation error occurred
+ * @param {Object} types - The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
+ * @returns {Object} The validated [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
+ * @throws [ValidationError]{@link module:lib/schema.ValidationError}
  */
 export function validateTypeModel(types) {
     // Validate with the type model

package/lib/typeModel.js

@@ -3,11 +3,13 @@
 
 /** @module lib/typeModel */
 
-import {SchemaMarkdownParser} from './parser.js';
+import {parseSchemaMarkdown} from './parser.js';
 
 
-// The Schema Markdown type model defined as Schema Markdown
-const typeModelSmd = `\
+/**
+ * The Schema Markdown type model
+ */
+export const typeModel = parseSchemaMarkdown(`\
 # Map of user type name to user type model
 typedef UserType{len > 0} Types
 
@@ -240,10 +242,4 @@ struct ActionURL
 
     # The URL path. If not provided, uses the default URL path of "/<actionName>".
     optional string path
-`;
-
-
-/**
- * The Schema Markdown type model
- */
-export const typeModel = (new SchemaMarkdownParser(typeModelSmd)).types;
+`);

package/package.json

@@ -1,8 +1,8 @@
 {
     "type": "module",
     "name": "schema-markdown",
-    "version": "1.1.6",
-    "description": "Human-friendly schema definition language and schema validator",
+    "version": "1.2.2",
+    "description": "A schema definition and validation library",
     "keywords": [
         "schema",
         "definition",
@@ -24,10 +24,10 @@
         "test": "ava -v test/"
     },
     "devDependencies": {
-        "ava": "~4.2",
-        "c8": "~7.11",
-        "eslint": "~8.14",
+        "ava": "~4.3",
+        "c8": "~7.12",
+        "eslint": "~8.21",
         "jsdoc": "~3.6",
-        "jsdom": "~19.0"
+        "jsdom": "~20.0"
     }
 }