<?php

declare(strict_types=1);

namespace App\Cfnpp\Expression;

/**
 * Token parsed out of an expression.
 *
 * @author Adam Pippin <hello@adampippin.ca>
 */
abstract class Token
{
	/**
	 * Determine whether the passed stream contains an instance of this token.
	 *
	 * @param  string $stream
	 * @return bool
	 */
	abstract public static function isToken(string $stream): bool;

	/**
	 * Consume a token from the passed stream.
	 *
	 * This method is expected to modify the stream to remove all
	 * consumed characters
	 *
	 * @param  string $stream
	 * @return Token
	 */
	abstract public static function getToken(string &$stream): Token;

	/**
	 * Execute the token given the requested parameters.
	 *
	 * @param  ?\App\Util\GraphNode[]                $arguments
	 * @return \App\Util\GraphNode|Token|scalar|null
	 */
	abstract public function execute(?array $arguments = null);
}