Rename parser stages bind -> define, preprocess -> init and finish ->…

… resolve.

README.md

@@ -20,6 +20,14 @@ The static `mayContain` member function of syntax element types (classes derived
 
 Syntax elements may also have attributes. They should be initialized to `null` in the class definition (the TypeScript compiler will automatically generate a constructor to initialize them). The parser will construct an instance of each class it finds, and examine its automatically constructed dynamic members. During parsing, they will then be automatically initialized to attributes found in the schema being parsed. Unknown attributes will be ignored.
 
+The XSD parser proceeds in stages (the parser and all syntax element classes have correspondingly named methods):
+
+- `init` which calls `define` to bind named elements, attributes, types etc. to their scope and handles `import` and `include` declarations. The imports form a directed, possibly cyclic graph and can modify root scopes of arbitrary namespaces, so it's impossible to generally resolve references to other named things visible in scope before all imports have been processed.
+- `resolve` which resolves references by name. Because possible attributes and child elements can be defined through deeply nested references that can point to other namespaces, it's generally impossible to know them all before all references in all namespaces have been resolved.
+- TODO: `transform` which renames things to avoid naming conflicts between child elements and attributes (which will be merged into members of a single JSON object) and possibly deals with scope issues for TypeScript definition output.
+
+TODO: after parsing, the resulting data structure should be exportable as JSON or a TypeScript definition file with ambient declarations of the XML namespaces.
+
 License
 =======
 

src/xsd/Loader.ts

@@ -39,7 +39,7 @@ export class Loader {
 				source.updateUrl(cached.url);
 				namespace.updateUrl(urlRemote, cached.url);
 
-				return(this.parser.preprocess(cached, source, this));
+				return(this.parser.init(cached, source, this));
 			}).then((dependencyList: Source[]) => {
 				// TODO: The source could be parsed already if all dependencies
 				// (and recursively their dependencies) have been preprocessed.
@@ -55,7 +55,7 @@ export class Loader {
 	}
 
 	finish() {
-		this.parser.finish();
+		this.parser.resolve();
 		this.resolve(this.targetNamespace);
 	}
 

src/xsd/Parser.ts

@@ -92,7 +92,7 @@ export class Parser {
 		return(state);
 	}
 
-	preprocess(cached: CacheResult, source: Source, loader: Loader) {
+	init(cached: CacheResult, source: Source, loader: Loader) {
 		var state = new State(null, this.rootRule, source);
 		var importList: {namespace: Namespace, url: string}[] = [];
 
@@ -132,7 +132,7 @@ export class Parser {
 		});
 
 		xml.on('endElement', function(name: string) {
-			if(state.xsdElement && state.xsdElement.finish) {
+			if(state.xsdElement && state.xsdElement.resolve) {
 				// Schedule finish hook to run after parsing is done.
 				// It might depend on definitions in scope but appearing later,
 				// and selectively postponing only hooks that cannot run yet
@@ -171,9 +171,9 @@ export class Parser {
 		return(promise);
 	}
 
-	finish() {
+	resolve() {
 		try {
-			this.pendingList.forEach((state: State) => state.xsdElement.finish(state));
+			this.pendingList.forEach((state: State) => state.xsdElement.resolve(state));
 			this.pendingList = [];
 		} catch(err) {
 			console.error(err);

src/xsd/types/Attribute.ts

@@ -11,11 +11,11 @@ export type XmlAttribute = string | number;
 
 export class Attribute extends types.Base {
 	init(state: State) {
-		this.bind(state, 'attribute');
+		this.define(state, 'attribute');
 		this.surrogateKey = Attribute.nextKey++;
 	}
 
-	finish(state: State) {
+	resolve(state: State) {
 		var attribute = this;
 
 		if(this.ref) {
@@ -24,7 +24,7 @@ export class Attribute extends types.Base {
 			var ref = new QName(this.ref, state.source);
 			attribute = this.scope.lookup(ref, 'attribute');
 
-			if(attribute) attribute.bind(state, 'attribute', this.scope);
+			if(attribute) attribute.define(state, 'attribute', this.scope);
 			else throw new types.MissingReferenceError(this, state, 'attribute', ref);
 		}
 	}
@@ -48,10 +48,10 @@ export class AttributeGroup extends types.Base {
 	];
 
 	init(state: State) {
-		this.bind(state, 'attributegroup');
+		this.define(state, 'attributegroup');
 	}
 
-	finish(state: State) {
+	resolve(state: State) {
 		var attributeGroup = this;
 
 		if(this.ref) {

src/xsd/types/Base.ts

@@ -27,9 +27,9 @@ export class Base {
 	}
 
 	init(state: State) {}
-	finish(state: State) {}
+	resolve(state: State) {}
 
-	bind(state: State, type: string, scope?: Scope) {
+	define(state: State, type: string, scope?: Scope) {
 		if(this.name) (scope || this.scope).addToParent(new QName(this.name, state.source), type, this);
 	}
 

src/xsd/types/ComplexType.ts

@@ -7,7 +7,7 @@ import * as types from '../types';
 
 export class TypeBase extends types.Base {
 	init(state: State) {
-		this.bind(state, 'type');
+		this.define(state, 'type');
 		this.scope.setType(this);
 		this.surrogateKey = TypeBase.nextKey++;
 	}
@@ -47,7 +47,7 @@ class ContentBase extends types.Base {
 		Restriction
 	]
 
-	finish(state: State) {
+	resolve(state: State) {
 		(state.parent.xsdElement as TypeBase).parent = this.parent;
 	}
 
@@ -68,7 +68,7 @@ export class ComplexContent extends ContentBase {
 // Derived type support
 
 export class XsdDerivationBase extends types.Base {
-	finish(state: State) {
+	resolve(state: State) {
 		var base = new QName(this.base, state.source);
 		(state.parent.xsdElement as ContentBase).parent = this.scope.lookup(base, 'type') as TypeBase || base;
 	}

src/xsd/types/Element.ts

@@ -20,11 +20,11 @@ export class Element extends ElementBase {
 	];
 
 	init(state: State) {
-		this.bind(state, 'element');
+		this.define(state, 'element');
 		this.surrogateKey = Element.nextKey++;
 	}
 
-	finish(state: State) {
+	resolve(state: State) {
 		var element = this;
 
 		if(this.ref) {
@@ -33,7 +33,7 @@ export class Element extends ElementBase {
 			var ref = new QName(this.ref, state.source);
 			element = this.scope.lookup(ref, 'element');
 
-			if(element) element.bind(state, 'element', this.scope);
+			if(element) element.define(state, 'element', this.scope);
 			else throw new types.MissingReferenceError(this, state, 'element', ref);
 		}
 

src/xsd/types/Group.ts

@@ -16,7 +16,7 @@ class GenericChildList extends GroupBase {
 		Choice
 	];
 
-	finish(state: State) {
+	resolve(state: State) {
 		this.scope.addAllToParent('element');
 	}
 }
@@ -40,10 +40,10 @@ export class Group extends GroupBase {
 	];
 
 	init(state: State) {
-		this.bind(state, 'group');
+		this.define(state, 'group');
 	}
 
-	finish(state: State) {
+	resolve(state: State) {
 		var group = this;
 
 		if(this.ref) {