<?php
/**
 * @file
 * @license https://opensource.org/licenses/Apache-2.0 Apache-2.0
 */

namespace Wikimedia\CSS\Grammar;

use Iterator;
use Wikimedia\CSS\Objects\ComponentValueList;
use Wikimedia\CSS\Objects\CSSFunction;
use Wikimedia\CSS\Objects\SimpleBlock;
use Wikimedia\CSS\Objects\Token;

/**
 * Base class for grammar matchers.
 *
 * The [CSS Syntax Level 3][SYN3] and [Values Level 3][VAL3] specifications use
 * a mostly context-free grammar to define what things like selectors and
 * property values look like. The Matcher classes allow for constructing an
 * object that will determine whether a ComponentValueList actually matches
 * this grammar.
 *
 * [SYN3]: https://www.w3.org/TR/2019/CR-css-syntax-3-20190716/
 * [VAL3]: https://www.w3.org/TR/2019/CR-css-values-3-20190606/
 */
abstract class Matcher {

	/** @var string|null Name to set on GrammarMatch objects */
	protected $captureName = null;

	/**
	 * @var array Default options for self::matchAgainst()
	 *  - skip-whitespace: (bool) Allow whitespace in between any two tokens
	 *  - nonterminal: (bool) Don't require the whole of $values is matched
	 *  - mark-significance: (bool) On a successful match, replace T_WHITESPACE
	 *    tokens as necessary to indicate significant whitespace.
	 */
	protected $defaultOptions = [
		'skip-whitespace' => true,
		'nonterminal' => false,
		'mark-significance' => false,
	];

	/**
	 * Create an instance.
	 * @param mixed ...$args See static::__construct()
	 * @return static
	 */
	public static function create( ...$args ) {
		// @phan-suppress-next-line PhanParamTooManyUnpack,PhanTypeInstantiateAbstractStatic
		return new static( ...$args );
	}

	/**
	 * Return a copy of this matcher that will capture its matches
	 *
	 * A "capturing" Matcher will produce GrammarMatches that return a value from
	 * the GrammarMatch::getName() method. The GrammarMatch::getCapturedMatches()
	 * method may be used to retrieve them from the top-level GrammarMatch.
	 *
	 * The concept is similar to capturing groups in PCRE and other regex
	 * languages.
	 *
	 * @param string|null $captureName Name to apply to captured GrammarMatch objects
	 * @return static
	 */
	public function capture( $captureName ) {
		$ret = clone $this;
		$ret->captureName = $captureName;
		return $ret;
	}

	/**
	 * Match against a list of ComponentValues
	 * @param ComponentValueList $values
	 * @param array $options Matching options, see self::$defaultOptions
	 * @return GrammarMatch|null
	 */
	public function matchAgainst( ComponentValueList $values, array $options = [] ) {
		$options += $this->getDefaultOptions();
		$start = $this->next( $values, -1, $options );
		$l = count( $values );
		foreach ( $this->generateMatches( $values, $start, $options ) as $match ) {
			if ( $options['nonterminal'] || $match->getNext() === $l ) {
				if ( $options['mark-significance'] ) {
					$significantWS = self::collectSignificantWhitespace( $match );
					self::markSignificantWhitespace( $values, $match, $significantWS, $match->getNext() );
				}
				return $match;
			}
		}
		return null;
	}

	/**
	 * Collect any 'significantWhitespace' matches
	 * @param GrammarMatch $match
	 * @param Token[] &$ret
	 * @return Token[]
	 */
	private static function collectSignificantWhitespace( GrammarMatch $match, &$ret = [] ) {
		if ( $match->getName() === 'significantWhitespace' ) {
			$ret = array_merge( $ret, $match->getValues() );
		}
		foreach ( $match->getCapturedMatches() as $m ) {
			self::collectSignificantWhitespace( $m, $ret );
		}
		return $ret;
	}

	/**
	 * Mark whitespace as significant or not
	 * @param ComponentValueList $list
	 * @param GrammarMatch $match
	 * @param Token[] $significantWS
	 * @param int $end
	 */
	private static function markSignificantWhitespace( $list, $match, $significantWS, $end ) {
		for ( $i = 0; $i < $end; $i++ ) {
			$cv = $list[$i];
			if ( $cv instanceof Token && $cv->type() === Token::T_WHITESPACE ) {
				$significant = in_array( $cv, $significantWS, true );
				if ( $significant !== $cv->significant() ) {
					$newCv = $cv->copyWithSignificance( $significant );
					$match->fixWhitespace( $cv, $newCv );
					$list[$i] = $newCv;
				}
			} elseif ( $cv instanceof CSSFunction || $cv instanceof SimpleBlock ) {
				self::markSignificantWhitespace(
					$cv->getValue(), $match, $significantWS, count( $cv->getValue() )
				);
			}
		}
	}

	/**
	 * Fetch the default options for this Matcher
	 * @return array See self::$defaultOptions
	 */
	public function getDefaultOptions() {
		return $this->defaultOptions;
	}

	/**
	 * Set the default options for this Matcher
	 * @param array $options See self::$defaultOptions
	 * @return static $this
	 */
	public function setDefaultOptions( array $options ) {
		$this->defaultOptions = $options + $this->defaultOptions;
		return $this;
	}

	/**
	 * Find the next ComponentValue in the input, possibly skipping whitespace
	 * @param ComponentValueList $values Input values
	 * @param int $start Current position in the input. May be -1, in which
	 *  case the first position in the input should be returned.
	 * @param array $options See self::$defaultOptions
	 * @return int Next token index
	 */
	protected function next( ComponentValueList $values, $start, array $options ) {
		$skipWS = $options['skip-whitespace'];

		$i = $start;
		$l = count( $values );
		do {
			$i++;
		} while ( $skipWS && $i < $l &&
			// @phan-suppress-next-line PhanNonClassMethodCall False positive
			$values[$i] instanceof Token && $values[$i]->type() === Token::T_WHITESPACE
		);
		return $i;
	}

	/**
	 * Create a GrammarMatch
	 * @param ComponentValueList $list
	 * @param int $start
	 * @param int $end First position after the match
	 * @param GrammarMatch|null $submatch Sub-match, for capturing. If $submatch
	 *  itself named it will be kept as a capture in the returned GrammarMatch,
	 *  otherwise its captured matches (if any) as returned by getCapturedMatches()
	 *  will be kept as captures in the returned GrammarMatch.
	 * @param array $stack Stack from which to fetch more submatches for
	 *  capturing (see $submatch). The stack is expected to be an array of
	 *  arrays, with the first element of each subarray being a GrammarMatch.
	 * @return GrammarMatch
	 */
	protected function makeMatch(
		ComponentValueList $list, $start, $end, ?GrammarMatch $submatch = null, array $stack = []
	) {
		$matches = array_column( $stack, 0 );
		$matches[] = $submatch;

		$keptMatches = [];
		while ( $matches ) {
			$m = array_shift( $matches );
			if ( !$m instanceof GrammarMatch ) {
				// skip it, probably null
			} elseif ( $m->getName() !== null ) {
				$keptMatches[] = $m;
			} elseif ( $m->getCapturedMatches() ) {
				$matches = array_merge( $m->getCapturedMatches(), $matches );
			}
		}

		return new GrammarMatch( $list, $start, $end - $start, $this->captureName, $keptMatches );
	}

	/**
	 * Match against a list of ComponentValues
	 *
	 * The job of a Matcher is to determine all the ways its particular grammar
	 * fragment can consume ComponentValues starting at a particular location
	 * in the ComponentValueList, represented by returning GrammarMatch objects.
	 * For example, a matcher implementing `IDENT*` at a starting position where
	 * there are three IDENT tokens in a row would be able to match 0, 1, 2, or
	 * all 3 of those IDENT tokens, and therefore should return an iterator
	 * over that set of GrammarMatch objects.
	 *
	 * Some matchers take other matchers as input, for example `IDENT*` is
	 * probably going to be implemented as a matcher for `*` that repeatedly
	 * applies a matcher for `IDENT`. The `*` matcher would call the `IDENT`
	 * matcher's generateMatches() method directly.
	 *
	 * Most Matchers implement this method as a generator to not build up
	 * the full set of results when it's reasonably likely the caller is going
	 * to terminate early.
	 *
	 * @param ComponentValueList $values
	 * @param int $start Starting position in $values
	 * @param array $options See self::$defaultOptions.
	 *  Always use the options passed in, don't use $this->defaultOptions yourself.
	 * @return Iterator<GrammarMatch> Iterates over the set of GrammarMatch
	 *  objects defining all the ways this matcher can match.
	 */
	abstract protected function generateMatches( ComponentValueList $values, $start, array $options );
}