<?php
/**
 * Speech Chunker
 *
 * Cuts a streaming answer into pieces that can be spoken one at a time.
 *
 * The first full sentence goes out while the model is still writing the rest.
 * Why: waiting for the whole answer before making audio is the slowest part
 * of a call.
 *
 * @package Aisentic\Voice
 */

declare( strict_types = 1 );

namespace Aisentic\Voice;

defined( 'ABSPATH' ) || exit;

/**
 * Holds streamed text until there is a whole sentence worth speaking.
 */
class Speech_Chunker {

	/**
	 * Text received so far and not yet given out.
	 *
	 * @var string
	 */
	private $buffer = '';

	/**
	 * Shortest piece worth its own audio call, in characters.
	 *
	 * Why: "Sure." alone becomes a clip, then a pause, then the answer.
	 * Waiting for a few more words sounds better.
	 *
	 * @var int
	 */
	private $min;

	/**
	 * Longest piece before it is cut at a space anyway, in characters.
	 *
	 * Why: a long sentence with no full stop must not hold back the answer.
	 *
	 * @var int
	 */
	private $max;

	/**
	 * Constructor.
	 *
	 * @param int $min Shortest piece, in characters.
	 * @param int $max Longest piece, in characters.
	 */
	public function __construct( int $min = 25, int $max = 200 ) {
		$this->min = $min;
		$this->max = $max;
	}

	/**
	 * Add streamed text and take out whatever is ready to speak.
	 *
	 * @param string $text Newly streamed text.
	 * @return string[] Zero or more pieces, in order.
	 */
	public function add( string $text ): array {
		$this->buffer .= $text;

		$pieces = [];

		while ( true ) {
			$piece = $this->take();

			if ( null === $piece ) {
				break;
			}

			$pieces[] = $piece;
		}

		return $pieces;
	}

	/**
	 * Look at what is waiting, without taking it.
	 *
	 * Used when the model stops to call a tool. The caller decides if the
	 * text so far is long enough to speak.
	 *
	 * @return string
	 */
	public function peek(): string {
		return trim( $this->buffer );
	}

	/**
	 * Take everything that is left, finished or not.
	 *
	 * Called once the model has stopped writing.
	 *
	 * @return string May be empty.
	 */
	public function rest(): string {
		$rest         = trim( $this->buffer );
		$this->buffer = '';

		return $rest;
	}

	/**
	 * Throw away everything waiting, without speaking it.
	 *
	 * Used when an answer was a guess and is thrown away.
	 * Why: the last sentence stays in the buffer until rest(). Without this,
	 * the end of the deleted guess ("Want me to narrow that down?") was
	 * spoken later in the turn.
	 * rest() also empties the buffer, but this name says what we mean.
	 *
	 * @return void
	 */
	public function forget(): void {
		$this->buffer = '';
	}

	/**
	 * Pull one finished piece off the front of the buffer.
	 *
	 * @return string|null Null while there is nothing ready.
	 */
	private function take(): ?string {
		$limit = $this->settled();

		if ( $limit < $this->min ) {
			return null;
		}

		$region = mb_substr( $this->buffer, 0, $limit );

		// A full stop, ?, ! or Bangla danda (।), followed by a space.
		// The space keeps "9.30" and "wp-admin.php" in one piece. It also
		// shows the sentence really ended, and the stream did not just pause
		// inside a number. A sentence end at the very end of the buffer waits.
		$pattern = '/^.{' . $this->min . ',}?[.!?\x{0964}](?=\s)/us';

		if ( preg_match( $pattern, $region, $m ) ) {
			return $this->cut( mb_strlen( $m[0] ) );
		}

		// No sentence end in sight. Cut at the last space instead.
		if ( $limit >= $this->max ) {
			$head  = mb_substr( $this->buffer, 0, $this->max );
			$space = mb_strrpos( $head, ' ' );

			if ( false !== $space && $space >= $this->min ) {
				return $this->cut( $space );
			}
		}

		return null;
	}

	/**
	 * Remove the first $length characters from the buffer and return them.
	 *
	 * @param int $length Characters to take.
	 * @return string
	 */
	private function cut( int $length ): string {
		$piece        = mb_substr( $this->buffer, 0, $length );
		$this->buffer = ltrim( mb_substr( $this->buffer, $length ) );

		return trim( $piece );
	}

	/**
	 * How much of the buffer is safe to cut, in characters.
	 *
	 * Stops before any HTML tag or link that is not finished yet.
	 * Why: a link like `<a href="...">Open page</a>` comes in several chunks.
	 * A cut inside it would make "Open page" be read out as a sentence.
	 *
	 * @return int
	 */
	private function settled(): int {
		$limit = mb_strlen( $this->buffer );

		// An opening tag with no ">" yet.
		$angle = mb_strrpos( $this->buffer, '<' );

		if ( false !== $angle && false === mb_strpos( mb_substr( $this->buffer, $angle ), '>' ) ) {
			$limit = min( $limit, $angle );
		}

		// A link that has not been closed yet.
		$link = mb_strrpos( $this->buffer, '<a' );

		if ( false !== $link && false === mb_strpos( mb_substr( $this->buffer, $link ), '</a>' ) ) {
			$limit = min( $limit, $link );
		}

		return $limit;
	}
}