path: root/Validator/src/legacy/ParserHook.php

<?php

use ParamProcessor\ParamDefinition;
use ParamProcessor\ProcessingError;
use ParamProcessor\Processor;

/**
 * Class for out of the box parser hook functionality integrated with the validation
 * provided by Validator.
 *
 * @since 0.4
 * @deprecated since 1.0 in favour of the ParserHooks library
 *
 * @licence GNU GPL v2+
 * @author Jeroen De Dauw < jeroendedauw@gmail.com >
 * @author Daniel Werner
 */
abstract class ParserHook {

	const TYPE_TAG = 0;
	const TYPE_FUNCTION = 1;

	/**
	 * @since 0.4.3
	 *
	 * @var array
	 */
	protected static $registeredHooks = array();

	/**
	 * Returns an array of registered parser hooks (keys) and their handling
	 * ParserHook deriving class names (values).
	 *
	 * @since 0.4.3
	 *
	 * @return array
	 */
	public static function getRegisteredParserHooks() {
		return self::$registeredHooks;
	}

	/**
	 * Returns the name of the ParserHook deriving class that defines a certain parser hook,
	 * or false if there is none.
	 *
	 * @since 0.4.3
	 *
	 * @param string $hookName
	 *
	 * @return mixed string or false
	 */
	public static function getHookClassName( $hookName ) {
		return array_key_exists( $hookName, self::$registeredHooks ) ? self::$registeredHooks[$hookName] : false;
	}

	/**
	 * @since 0.4
	 *
	 * @var Processor
	 */
	protected $validator;

	/**
	 * @since 0.4
	 *
	 * @var Parser
	 */
	protected $parser;

	/**
	 * @since 0.4.4
	 *
	 * @var PPFrame
	 */
	protected $frame;

	/**
	 * @since 0.4.4
	 *
	 * @var ParserHook::TYPE_ enum item
	 */
	protected $currentType;

	/**
	 * @since 0.4
	 *
	 * @var boolean
	 */
	public $forTagExtensions;

	/**
	 * @since 0.4
	 *
	 * @var boolean
	 */
	public $forParserFunctions;

	/**
	 * Bitfifeld of Options influencing the characteristics of the registered
	 * tag/parser function.
	 * 
	 * @since 0.4.13
	 * 
	 * @var int 
	 */
	protected $parserHookOptions;
	
	/**
	 * Gets the name of the parser hook.
	 *
	 * @since 0.4
	 *
	 * @return string or array of string
	 */
	protected abstract function getName();

	/**
	 * Renders and returns the output.
	 *
	 * @since 0.4
	 *
	 * @param array $parameters
	 *
	 * @return string
	 */
	protected abstract function render( array $parameters );

	/**
	 * Flag for constructor, whether the function hook should be one callable without
	 * leading hash, i.e. {{plural:...}} instead of {{#if:...}}
	 * 
	 * @since 0.4.13
	 */
	const FH_NO_HASH = 1;
	
	/* *
	 * @ToDo: implementation of this functionality
	 * 
	 * Flag for constructor, whether the tag hook should be handled as function tag hook
	 * and not as a normal tag hook. See Parser::setFunctionTagHook() for details.
	 */
	#const TH_AS_FUNCTION_TAG = 2;
	
	/**
	 * Constructor.
	 *
	 * @since 0.4
	 *
	 * @param boolean $forTagExtensions
	 * @param boolean $forParserFunctions
	 * @param integer $flag combination of option flags to manipulare the parser hooks
	 *        characteristics. The following are available:
	 *        - ParserHook::FH_NO_HASH makes the function callable without leading hash.
	 */
	public function __construct( $forTagExtensions = true, $forParserFunctions = true, $flags = 0 ) {
		$this->forTagExtensions = $forTagExtensions;
		$this->forParserFunctions = $forParserFunctions;
		// store flags:
		$this->parserHookOptions = $flags;
	}

	/**
	 * Function to hook up the coordinate rendering functions to the parser.
	 *
	 * @since 0.4
	 *
	 * @param Parser $parser
	 *
	 * @return true
	 */
	public function init( Parser &$parser ) {
		$className = get_class( $this );
		$first = true;

		foreach ( $this->getNames() as $name ) {
			if ( $first ) {
				self::$registeredHooks[$name] = $className;
				$first = false;
			}
			
			// Parser Tag hooking:
			if ( $this->forTagExtensions ) {
				$parser->setHook(
					$name,
					array( new ParserHookCaller( $className, 'renderTag' ), 'runTagHook' )
				);
			}

			// Parser Function hooking:
			if ( $this->forParserFunctions ) {
				$flags = 0;
				$function = 'renderFunction';
				$callerFunction = 'runFunctionHook';
				
				// use object arguments if available:
				if ( defined( 'SFH_OBJECT_ARGS' ) ) {
					$flags = $flags | SFH_OBJECT_ARGS;
					$function .= 'Obj';
					$callerFunction .= 'Obj';
				}
				// no leading Hash required?
				if ( $this->parserHookOptions & self::FH_NO_HASH ) {
					$flags = $flags | SFH_NO_HASH;
				}
				
				$parser->setFunctionHook(
					$name,
					array( new ParserHookCaller( $className, $function ), $callerFunction ),
					$flags
				);
			}
		}

		return true;
	}

	/**
	 * Returns an array with the names for the parser hook.
	 *
	 * @since 0.4
	 *
	 * @return array
	 */
	protected function getNames() {
		$names = $this->getName();

		if ( !is_array( $names ) ) {
			$names = array( $names );
		}

		return $names;
	}

	/**
	 * Function to add the magic word in pre MW 1.16.
	 *
	 * @since 0.4
	 *
	 * @param array $magicWords
	 * @param string $langCode
	 *
	 * @return boolean
	 */
	public function magic( array &$magicWords, $langCode ) {
		foreach ( $this->getNames() as $name ) {
			$magicWords[$name] = array( 0, $name );
		}

		return true;
	}

	/**
	 * Handler for rendering the tag hook registered by Parser::setHook()
	 *
	 * @since 0.4
	 *
	 * @param mixed $input string or null
	 * @param array $args
	 * @param Parser $parser
	 * @param PPFrame $frame Available from 1.16
	 *
	 * @return string
	 */
	public function renderTag( $input, array $args, Parser $parser, PPFrame $frame = null  ) {
		$this->parser = $parser;
		$this->frame = $frame;

		$defaultParameters = $this->getDefaultParameters( self::TYPE_TAG );
		$defaultParam = array_shift( $defaultParameters );

		// If there is a first default parameter, set the tag contents as its value.
		if ( !is_null( $defaultParam ) && !is_null( $input ) ) {
			$args[$defaultParam] = $input;
		}

		return $this->validateAndRender( $args, self::TYPE_TAG );
	}

	/**
	 * Handler for rendering the function hook registered by Parser::setFunctionHook()
	 *
	 * @since 0.4
	 *
	 * @param Parser &$parser
	 * ... further arguments ...
	 *
	 * @return array
	 */
	public function renderFunction( Parser &$parser /*, n args */ ) {
		$args = func_get_args();
		
		$this->parser = array_shift( $args );
								
		$output = $this->validateAndRender( $args, self::TYPE_FUNCTION );
		$options = $this->getFunctionOptions();

		if ( array_key_exists( 'isHTML', $options ) && $options['isHTML'] ) {
			/** @ToDo: FIXME: Is this really necessary? The same thing is propably going to
			 *                happen in Parser::braceSubstitution() if 'isHTML' is set!
			 *  @ToDo: other options besides 'isHTML' like 'noparse' are ignored here!
			 */
			return $this->parser->insertStripItem( $output, $this->parser->mStripState );
		}

		return array_merge(
			array( $output ),
			$options
		);
	}
	
	/**
	 * Handler for rendering the function hook registered by Parser::setFunctionHook() together
	 * with object style arguments (SFH_OBJECT_ARGS flag).
	 *
	 * @since 0.4.13
	 * 
	 * @param Parser &$parser
	 * @param PPFrame $frame
	 * @param type $args
	 * @return array 
	 */
	public function renderFunctionObj( Parser &$parser, PPFrame $frame, $args ) {		
		$this->frame = $frame;
		
		// create non-object args for old style 'renderFunction()'
		$oldStyleArgs = array( &$parser );
		
		foreach( $args as $arg ) {
			$oldStyleArgs[] = trim( $frame->expand( $arg ) );
		}
		
		/*
		 * since we can't validate un-expandet arguments, we just go on with old-style function
		 * handling from here. Only advantage is that we have $this->frame set properly.
		 */
		return call_user_func_array( array( $this, 'renderFunction' ), $oldStyleArgs );
	}

	/**
	 * Returns the parser function otpions.
	 *
	 * @since 0.4
	 *
	 * @return array
	 */
	protected function getFunctionOptions() {
		return array();
	}

	/**
	 * Takes care of validation and rendering, and returns the output.
	 *
	 * @since 0.4
	 *
	 * @param array $arguments
	 * @param integer $type Item of the ParserHook::TYPE_ enum
	 *
	 * @return string
	 */
	public function validateAndRender( array $arguments, $type ) {
		$names = $this->getNames();
		$this->validator = Processor::newDefault();
		$this->validator->getOptions()->setName( $names[0] );

		if ( $type === self::TYPE_FUNCTION ) {
			$this->validator->setFunctionParams( $arguments, $this->getParameterInfo( $type ), $this->getDefaultParameters( $type ) );
		}
		else {
			$this->validator->setParameters( $arguments, $this->getParameterInfo( $type ) );
		}

		$this->validator->validateParameters();

		$fatalError = $this->validator->hasFatalError();

		if ( $fatalError === false ) {
			$output = $this->render( $this->validator->getParameterValues() );
		}
		else {
			$output = $this->renderFatalError( $fatalError );
		}

		return $output;
	}

	/**
	 * Returns the ProcessingError objects for the errors and warnings that should be displayed.
	 *
	 * @since 0.4
	 *
	 * @return array of array of ProcessingError
	 */
	protected function getErrorsToDisplay() {
		$errors = array();
		$warnings = array();

		foreach ( $this->validator->getErrors() as $error ) {
			// Check if the severity of the error is high enough to display it.
			if ( $error->shouldShow() ) {
				$errors[] = $error;
			}
			elseif ( $error->shouldWarn() ) {
				$warnings[] = $error;
			}
		}

		return array( 'errors' => $errors, 'warnings' => $warnings );
	}

	/**
	 * Creates and returns the output when a fatal error prevent regular rendering.
	 *
	 * @since 0.4
	 *
	 * @param ProcessingError $error
	 *
	 * @return string
	 */
	protected function renderFatalError( ProcessingError $error ) {
		return '<div><span class="errorbox">' .
			wfMessage( 'validator-fatal-error', $error->getMessage() )->parse() .
			'</span></div><br /><br />';
	}

	// TODO: replace render errors functionality

	/**
	 * Returns an array containing the parameter info.
	 * Override in deriving classes to add parameter info.
	 *
	 * @since 0.4
	 *
	 * @param integer $type Item of the ParserHook::TYPE_ enum
	 *
	 * @return array
	 */
	protected function getParameterInfo( $type ) {
		return array();
	}

	public function getParamDefinitions( $type = self::TYPE_FUNCTION ) {
		return $this->getParameterInfo( $type );
	}

	/**
	 * Returns the list of default parameters. These parameters can be used as
	 * unnamed parameters where it is not necessary to use the name and the '=' as
	 * long as there is no '=' within the value.
	 * It is possible to define that a parameter should not have a named fallback.
	 * Therefore the information has to be returnd as sub-array with the parameter
	 * name as first and Validator::PARAM_UNNAMED as second value. Parameter using
	 * this option must be set first, before any unnamed parameter in the same order
	 * as set here. All parameters defined before the last parameter making use of
	 * Validator::PARAM_UNNAMED will automatically be populated with this option.
	 * 
	 * Override in deriving classes to add default parameters.
	 *
	 * @since 0.4
	 *
	 * @param integer $type Item of the ParserHook::TYPE_ enum
	 *
	 * @return array
	 */
	protected function getDefaultParameters( $type ) {
		return array();
	}

	/**
	 * Returns the data needed to describe the parser hook.
	 * This is mainly needed because some of the individual get methods
	 * that return the needed data are protected, and cannot be made
	 * public without breaking b/c in a rather bad way.
	 *
	 * @since 0.4.3
	 *
	 * @param integer $type Item of the ParserHook::TYPE_ enum
	 *
	 * @return array
	 */
	public function getDescriptionData( $type ) {
		return array(
			'names' => $this->getNames(),
			'description' => $this->getDescription(),
			'message' => $this->getMessage(),
			'parameters' => ParamDefinition::getCleanDefinitions( $this->getParameterInfo( $type ) ),
			'defaults' => $this->getDefaultParameters( $type ),
		);
	}

	/**
	 * Returns a description for the parser hook, or false when there is none.
	 * Override in deriving classes to add a message.
	 *
	 * @since 0.4.3
	 * @deprecated since 1.0
	 *
	 * @return mixed string or false
	 */
	public function getDescription() {
		$msg = $this->getMessage();
		return $msg === false ? false : wfMessage( $msg )->plain();
	}
	
	/**
	 * Returns a description message for the parser hook, or false when there is none.
	 * Override in deriving classes to add a message.
	 * 
	 * @since 0.4.10
	 * 
	 * @return mixed string or false
	 */
	public function getMessage() {
		return false;
	}

	/**
	 * Returns if the current render request is coming from a tag extension.
	 *
	 * @since 0.4.4
	 *
	 * @return boolean
	 */
	protected function isTag() {
		return $this->currentType == self::TYPE_TAG;
	}

	/**
	 * Returns if the current render request is coming from a parser function.
	 *
	 * @since 0.4.4
	 *
	 * @return boolean
	 */
	protected function isFunction() {
		return $this->currentType == self::TYPE_FUNCTION;
	}

	/**
	 * Utility function to parse wikitext without having to care
	 * about handling a tag extension or parser function.
	 *
	 * @since 0.4.4
	 *
	 * @param string $text The wikitext to be parsed
	 *
	 * @return string the parsed output
	 */
	protected function parseWikitext( $text ) {
		// Parse the wikitext to HTML.
		if ( $this->isFunction() ) {
			return $this->parser->parse(
				$text,
				$this->parser->mTitle,
				$this->parser->mOptions,
				true,
				false
			)->getText();
		}
		else {
			return $this->parser->recursiveTagParse(
				$text,
				$this->frame
			);
		}
	}

}

/**
 * Completely evil class to create a new instance of the handling ParserHook when the actual hook gets called.
 *
 * @evillness >9000 - to be replaced when a better solution (LSB?) is possible.
 *
 * @since 0.4
 *
 * @author Jeroen De Dauw
 * @author Daniel Werner
 */
class ParserHookCaller {
	
	protected $class;
	protected $method;
	
	function __construct( $class, $method ) {
		$this->class = $class;
		$this->method = $method;
	}
	
	/*
	 * See Parser::braceSubstitution() and Parser::extensionSubstitution() for details about
	 * how the Parser object and other parameters are being passed. Therefore for function
	 * hooks &$parser fullfills the same purpos as $parser for the tag hook.
	 * functionTagHook (!) calls (if implemented at a later time) are more like function hooks,
	 * meaning, they would require &$parser as well.
	 */
	
	public function runTagHook( $input, array $args, Parser $parser, PPFrame $frame = null  ) {
		$obj = new $this->class();		
		return $obj->{$this->method}( $input, $args, $parser, $frame );
	}
	
	public function runFunctionHook( Parser &$parser /*, n args */ ) {
		$args = func_get_args();
		$args[0] = &$parser; // with '&' becaus call_user_func_array is being used
		return call_user_func_array( array( new $this->class(), $this->method ), $args );
	}
	
	public function runFunctionHookObj( Parser &$parser, PPFrame $frame, array $args ) {
		$obj = new $this->class();		
		return $obj->{$this->method}( $parser, $frame, $args );
	}

}