mediawiki-extensions-VisualEditor/modules/ve/dm/ve.dm.ModelRegistry.js

/*!
 * VisualEditor ModelRegistry class.
 *
 * @copyright 2011-2012 VisualEditor Team and others; see AUTHORS.txt
 * @license The MIT License (MIT); see LICENSE.txt
 */
( function ( ve ) {

/**
 * Registry for models. A model is a node or an annotation.
 *
 * To register a new node type or annotation type, call ve.dm.modelRegistry.register()
 *
 * @extends ve.Registry
 * @constructor
 */
ve.dm.ModelRegistry = function VeDmModelRegistry() {
	// Parent constructor
	ve.Registry.call( this );
	// [ { tagName: [modelNamesWithoutFunc] }, { tagName: [modelNamesWithFunc] } ]
	this.modelsByTag = [ {}, {} ];
	// { matchFunctionPresence: { rdfaType: { tagName: [modelNames] } } }
	// [ { rdfaType: { tagName: [modelNamesWithoutFunc] } }, { rdfaType: { tagName: [modelNamesWithFunc] } ]
	this.modelsByTypeAndTag = [];
	// { nameA: 0, nameB: 1, ... }
	this.registrationOrder = {};
	this.nextNumber = 0;
};

/* Inheritance */

ve.inheritClass( ve.dm.ModelRegistry, ve.Registry );

/* Private helper functions */

/**
 * Helper function for register(). Adds a value to the front of an array in a nested object.
 * Objects and arrays are created if needed. You can specify either two or three keys and a value.
 *
 * Specifically:
 * addType( obj, keyA, keyB, keyC, value ) does obj[keyA][keyB][keyC].unshift( value );
 * addType( obj, keyA, keyB, value ) does obj[keyA][keyB].unshift( value );
 *
 * @param {Object} obj Object to add to
 * @param {string} keyA Key into obj
 * @param {string} keyB Key into obj[keyA]
 * @param {string|Mixed} keyC Key into obj[keyA][keyB], or value to add to array if value not set
 * @param {Mixed} [value] Value to add to the array
 */
function addType( obj, keyA, keyB, keyC, value ) {
	if ( obj[keyA] === undefined ) {
		obj[keyA] = {};
	}
	if ( obj[keyA][keyB] === undefined ) {
		obj[keyA][keyB] = value === undefined ? [] : {};
	}
	if ( value !== undefined && obj[keyA][keyB][keyC] === undefined ) {
		obj[keyA][keyB][keyC] = [];
	}
	if ( value === undefined ) {
		obj[keyA][keyB].unshift( keyC );
	} else {
		obj[keyA][keyB][keyC].unshift( value );
	}
}

/* Public methods */

/**
 * Register a model type.
 * @param {string} name Symbolic name for the model
 * @param {ve.dm.Annotation|ve.dm.Node} constructor Subclass of ve.dm.Annotation or ve.dm.Node
 */
ve.dm.ModelRegistry.prototype.register = function ( name, constructor ) {
	if ( typeof name !== 'string' || name === '' ) {
		throw new Error( 'Model names must be strings and must not be empty' );
	}

	// Register the model with the right factory
	if ( constructor.prototype instanceof ve.dm.Annotation ) {
		ve.dm.annotationFactory.register( name, constructor );
	} else if ( constructor.prototype instanceof ve.dm.Node ) {
		ve.dm.nodeFactory.register( name, constructor );
		// TODO handle things properly so we don't need this
		// HACK don't actually register nodes here, the converter isn't ready for that yet
		return;
	} else {
		throw new Error( 'Models must be subclasses of ve.dm.Annotation or ve.dm.Node' );
	}
	// Call parent implementation
	ve.Registry.prototype.register.call( this, name, constructor );

	name = constructor.static.name;

	var i, j,
		tags = constructor.static.matchTagNames === null ?
			[ '' ] :
			constructor.static.matchTagNames,
		types = constructor.static.matchRdfaTypes === null ?
			[ '' ] :
			constructor.static.matchRdfaTypes;

	for ( i = 0; i < tags.length; i++ ) {
		// +!!foo is a shorter equivalent of Number( Boolean( foo ) ) or foo ? 1 : 0
		addType( this.modelsByTag, +!!constructor.static.matchFunction,
			tags[i], name
		);
	}
	for ( i = 0; i < types.length; i++ ) {
		for ( j = 0; j < tags.length; j++ ) {
			addType( this.modelsByTypeAndTag,
				+!!constructor.static.matchFunction, types[i], tags[j], name
			);
		}
	}

	this.registrationOrder[name] = this.nextNumber++;
};

/**
 * Determine which model best matches the given element
 *
 * Model matching works as follows:
 * Get all models whose tag and rdfaType rules match
 * Rank them in order of specificity:
 * * tag, rdfaType and func specified
 * * rdfaType and func specified
 * * tag and func specified
 * * func specified
 * * tag and rdfaType specified
 * * rdfaType specified
 * * tag specified
 * * nothing specified
 * If there are multiple candidates with the same specificity, they are ranked in reverse order of
 * registration (i.e. if A was registered before B, B will rank above A).
 * The highest-ranking model whose test function does not return false, wins.
 *
 * @param {HTMLElement} element Element to match
 * @returns {string|null} Model type, or null if none found
 */
ve.dm.ModelRegistry.prototype.matchElement = function ( element ) {
	var i, name, model, matches, winner, types,
		tag = element.nodeName.toLowerCase(),
		typeAttr = element.getAttribute( 'typeof' ) || element.getAttribute( 'rel' ),
		reg = this;

	function byRegistrationOrderDesc( a, b ) {
		return reg.registrationOrder[b] - reg.registrationOrder[a];
	}

	function matchWithFunc( types, tag ) {
		var i, j, matches, queue = [];
		for ( i = 0; i < types.length; i++ ) {
			matches = ve.getProp( reg.modelsByTypeAndTag, 1, types[i], tag ) || [];
			for ( j = 0; j < matches.length; j++ ) {
				queue.push( matches[j] );
			}
		}
		queue.sort( byRegistrationOrderDesc );
		for ( i = 0; i < queue.length; i++ ) {
			if ( reg.registry[queue[i]].static.matchFunction( element ) ) {
				return queue[i];
			}
		}
		return null;
	}

	function matchWithoutFunc( types, tag ) {
		var i, j, matches, winningName = null;
		for ( i = 0; i < types.length; i++ ) {
			matches = ve.getProp( reg.modelsByTypeAndTag, 0, types[i], tag ) || [];
			for ( j = 0; j < matches.length; j++ ) {
				if (
					winningName === null ||
					reg.registrationOrder[winningName] < reg.registrationOrder[matches[j]]
				) {
					winningName = matches[j];
				}
			}
		}
		return winningName;
	}

	types = typeAttr ? typeAttr.split( ' ' ) : [];
	if ( types.length ) {
		// func+tag+type match
		winner = matchWithFunc( types, tag );
		if ( winner !== null ) {
			return winner;
		}

		// func+type match
		// Only look at rules with no tag specified; if a rule does specify a tag, we've
		// either already processed it above, or the tag doesn't match
		winner = matchWithFunc( types, '' );
		if ( winner !== null ) {
			return winner;
		}
	}

	// func+tag match
	matches = ve.getProp( this.modelsByTag, 1, tag ) || [];
	// No need to sort because individual arrays in modelsByTag are already sorted
	// correctly
	for ( i = 0; i < matches.length; i++ ) {
		name = matches[i];
		model = this.registry[name];
		// Only process this one if it doesn't specify types
		// If it does specify types, then we've either already processed it in the
		// func+tag+type step above, or its type rule doesn't match
		if ( model.static.matchRdfaTypes === null && model.static.matchFunction( element ) ) {
			return matches[i];
		}
	}

	// func only
	// We only need to get the [''][''] array because the other arrays were either
	// already processed during the steps above, or have a type or tag rule that doesn't
	// match this element.
	// No need to sort because individual arrays in modelsByTypeAndTag are already sorted
	// correctly
	matches = ve.getProp( this.modelsByTypeAndTag, 1, '', '' ) || [];
	for ( i = 0; i < matches.length; i++ ) {
		if ( this.registry[matches[i]].static.matchFunction( element ) ) {
			return matches[i];
		}
	}

	// tag+type
	winner = matchWithoutFunc( types, tag );
	if ( winner !== null ) {
		return winner;
	}

	// type only
	// Only look at rules with no tag specified; if a rule does specify a tag, we've
	// either already processed it above, or the tag doesn't match
	winner = matchWithoutFunc( types, '' );
	if ( winner !== null ) {
		return winner;
	}

	// tag only
	matches = ve.getProp( this.modelsByTag, 0, tag ) || [];
	// No need to track winningName because the individual arrays in nodelsByTag are
	// already sorted correctly
	for ( i = 0; i < matches.length; i++ ) {
		name = matches[i];
		model = this.registry[name];
		// Only process this one if it doesn't specify types
		// If it does specify types, then we've either already processed it in the
		// tag+type step above, or its type rule doesn't match
		if ( model.static.matchRdfaTypes === null ) {
			return matches[i];
		}
	}

	// Rules with no type or tag specified
	// These are the only rules that can still qualify at this point, the others we've either
	// already processed or have a type or tag rule that disqualifies them
	matches = ve.getProp( this.modelsByTypeAndTag, 0, '', '' ) || [];
	if ( matches.length > 0 ) {
		return matches[0];
	}

	// We didn't find anything, give up
	return null;
};

/* Initialization */

ve.dm.modelRegistry = new ve.dm.ModelRegistry();

} )( ve );