<?php

namespace Wikimedia\Purtle;

use Closure;
use InvalidArgumentException;
use LogicException;

/**
 * Base class for RdfWriter implementations.
 *
 * Subclasses have to implement at least the writeXXX() methods to generate the desired output
 * for the respective RDF constructs. Subclasses may override the startXXX() and finishXXX()
 * methods to generate structural output, and override expandXXX() to transform identifiers.
 *
 * @license GPL-2.0-or-later
 * @author Daniel Kinzler
 */
abstract class RdfWriterBase implements RdfWriter {

	/**
	 * @var array An array of strings, RdfWriters, or closures.
	 */
	private $buffer = [];

	/**
	 * @var RdfWriter[] sub-writers.
	 */
	private $subs = [];

	const STATE_START = 0;
	const STATE_DOCUMENT = 5;
	const STATE_SUBJECT = 10;
	const STATE_PREDICATE = 11;
	const STATE_OBJECT = 12;
	const STATE_FINISH = 666;

	/**
	 * @var string the current state
	 */
	private $state = self::STATE_START;

	/**
	 * Shorthands that can be used in place of IRIs, e.g. ("a" to mean rdf:type).
	 *
	 * @var string[] a map of shorthand names to [ $base, $local ] pairs.
	 * @todo Handle "a" as a special case directly. Use for custom "variables" like %currentValue
	 *  instead.
	 */
	private $shorthands = [];

	/**
	 * @var string[] a map of prefixes to base IRIs
	 */
	protected $prefixes = [];

	/**
	 * @var array pair to store the current subject.
	 * Holds the $base and $local parameters passed to about().
	 */
	protected $currentSubject = [ null, null ];

	/**
	 * @var array pair to store the current predicate.
	 * Holds the $base and $local parameters passed to say().
	 */
	protected $currentPredicate = [ null, null ];

	/**
	 * @var BNodeLabeler
	 */
	private $labeler;

	/**
	 * Role ID for writers that will generate a full RDF document.
	 */
	const DOCUMENT_ROLE = 'document';
	const SUBDOCUMENT_ROLE = 'sub';

	/**
	 * Role ID for writers that will generate a single inline blank node.
	 */
	const BNODE_ROLE = 'bnode';

	/**
	 * Role ID for writers that will generate a single inline RDR statement.
	 */
	const STATEMENT_ROLE = 'statement';

	/**
	 * @var string The writer's role, see the XXX_ROLE constants.
	 */
	protected $role;

	/**
	 * Are prefixed locked against modification?
	 * @var bool
	 */
	private $prefixesLocked = false;

	/**
	 * @param string $role The writer's role, use the XXX_ROLE constants.
	 * @param BNodeLabeler|null $labeler
	 *
	 * @throws InvalidArgumentException
	 */
	public function __construct( $role, BNodeLabeler $labeler = null ) {
		if ( !is_string( $role ) ) {
			throw new InvalidArgumentException( '$role must be a string' );
		}

		$this->role = $role;
		$this->labeler = $labeler ?: new BNodeLabeler();

		$this->registerShorthand( 'a', 'rdf', 'type' );

		$this->prefix( 'rdf', 'http://www.w3.org/1999/02/22-rdf-syntax-ns#' );
		$this->prefix( 'xsd', 'http://www.w3.org/2001/XMLSchema#' );
	}

	/**
	 * @param string $role
	 * @param BNodeLabeler $labeler
	 *
	 * @return RdfWriterBase
	 */
	abstract protected function newSubWriter( $role, BNodeLabeler $labeler );

	/**
	 * Registers a shorthand that can be used instead of a qname,
	 * like 'a' can be used instead of 'rdf:type'.
	 *
	 * @param string $shorthand
	 * @param string $prefix
	 * @param string $local
	 */
	protected function registerShorthand( $shorthand, $prefix, $local ) {
		$this->shorthands[$shorthand] = [ $prefix, $local ];
	}

	/**
	 * Registers a prefix
	 *
	 * @param string $prefix
	 * @param string $iri The base IRI
	 *
	 * @throws LogicException
	 */
	public function prefix( $prefix, $iri ) {
		if ( $this->prefixesLocked ) {
			throw new LogicException( 'Prefixes can not be added after start()' );
		}

		$this->prefixes[$prefix] = $iri;
	}

	/**
	 * Determines whether $shorthand can be used as a shorthand.
	 *
	 * @param string $shorthand
	 *
	 * @return bool
	 */
	protected function isShorthand( $shorthand ) {
		return isset( $this->shorthands[$shorthand] );
	}

	/**
	 * Determines whether $shorthand can legally be used as a prefix.
	 *
	 * @param string $prefix
	 *
	 * @return bool
	 */
	protected function isPrefix( $prefix ) {
		return isset( $this->prefixes[$prefix] );
	}

	/**
	 * Returns the prefix map.
	 *
	 * @return string[] An associative array mapping prefixes to base IRIs.
	 */
	public function getPrefixes() {
		return $this->prefixes;
	}

	/**
	 * @param string|null $languageCode
	 *
	 * @return bool
	 */
	protected function isValidLanguageCode( $languageCode ) {
		// preg_match is somewhat (12%) slower than strspn but more readable
		return $languageCode !== null && preg_match( '/^[\da-z-]{2,}$/i', $languageCode );
	}

	/**
	 * @return RdfWriter
	 */
	final public function sub() {
		$writer = $this->newSubWriter( self::SUBDOCUMENT_ROLE, $this->labeler );
		$writer->state = self::STATE_DOCUMENT;

		// share registered prefixes
		$writer->prefixes =& $this->prefixes;

		$this->subs[] = $writer;
		return $writer;
	}

	/**
	 * Returns the writers role. The role determines the behavior of the writer with respect
	 * to which states and transitions are possible: a BNODE_ROLE writer would for instance
	 * not accept a call to about(), since it can only process triples about a single subject
	 * (the blank node it represents).
	 *
	 * @return string A string corresponding to one of the the XXX_ROLE constants.
	 */
	final public function getRole() {
		return $this->role;
	}

	/**
	 * Appends string to the output buffer.
	 * @param string $w
	 */
	final protected function write( $w ) {
		$this->buffer[] = $w;
	}

	/**
	 * If $base is a shorthand, $base and $local are updated to hold whatever qname
	 * the shorthand was associated with.
	 *
	 * Otherwise, $base and $local remain unchanged.
	 *
	 * @param string &$base
	 * @param string|null &$local
	 */
	protected function expandShorthand( &$base, &$local ) {
		if ( $local === null && isset( $this->shorthands[$base] ) ) {
			list( $base, $local ) = $this->shorthands[$base];
		}
	}

	/**
	 * If $base is a registered prefix, $base will be replaced by the base IRI associated with
	 * that prefix, with $local appended. $local will be set to null.
	 *
	 * Otherwise, $base and $local remain unchanged.
	 *
	 * @param string &$base
	 * @param string|null &$local
	 *
	 * @throws LogicException
	 */
	protected function expandQName( &$base, &$local ) {
		if ( $local !== null && $base !== '_' ) {
			if ( isset( $this->prefixes[$base] ) ) {
				$base = $this->prefixes[$base] . $local; // XXX: can we avoid this concat?
				$local = null;
			} else {
				throw new LogicException( 'Unknown prefix: ' . $base );
			}
		}
	}

	/**
	 * @see RdfWriter::blank()
	 *
	 * @param string|null $label node label, will be generated if not given.
	 *
	 * @return string
	 */
	final public function blank( $label = null ) {
		return $this->labeler->getLabel( $label );
	}

	/**
	 * @see RdfWriter::start()
	 */
	final public function start() {
		$this->state( self::STATE_DOCUMENT );
		$this->prefixesLocked = true;
	}

	/**
	 * @see RdfWriter::finish()
	 */
	final public function finish() {
		// close all unclosed states
		$this->state( self::STATE_DOCUMENT );

		// ...then insert output of sub-writers into the buffer,
		// so it gets placed before the footer...
		$this->drainSubs();

		// and then finalize
		$this->state( self::STATE_FINISH );

		// Detaches all subs.
		$this->subs = [];
	}

	/**
	 * @see RdfWriter::drain()
	 *
	 * @return string RDF
	 */
	final public function drain() {
		// we can drain after finish, but finish state is sticky
		if ( $this->state !== self::STATE_FINISH ) {
			$this->state( self::STATE_DOCUMENT );
		}

		$this->drainSubs();
		$this->flattenBuffer();

		$rdf = implode( '', $this->buffer );
		$this->buffer = [];

		return $rdf;
	}

	/**
	 * Calls drain() an any RdfWriter instances in $this->buffer, and replaces them
	 * in $this->buffer with the string returned by the drain() call. Any closures
	 * present in the $this->buffer will be called, and replaced by their return value.
	 */
	private function flattenBuffer() {
		foreach ( $this->buffer as &$b ) {
			if ( $b instanceof Closure ) {
				$b = $b();
			}
			if ( $b instanceof RdfWriter ) {
				$b = $b->drain();
			}
		}
	}

	/**
	 * Drains all subwriters, and appends their output to this writer's buffer.
	 * Subwriters remain usable.
	 */
	private function drainSubs() {
		foreach ( $this->subs as $sub ) {
			$rdf = $sub->drain();
			$this->write( $rdf );
		}
	}

	/**
	 * @see RdfWriter::about()
	 *
	 * @param string $base A QName prefix if $local is given, or an IRI if $local is null.
	 * @param string|null $local A QName suffix, or null if $base is an IRI.
	 *
	 * @return RdfWriter $this
	 */
	final public function about( $base, $local = null ) {
		$this->expandSubject( $base, $local );

		if ( $this->state === self::STATE_OBJECT
			&& $base === $this->currentSubject[0]
			&& $local === $this->currentSubject[1]
		) {
			return $this; // redundant about() call
		}

		$this->state( self::STATE_SUBJECT );

		$this->currentSubject[0] = $base;
		$this->currentSubject[1] = $local;
		$this->currentPredicate[0] = null;
		$this->currentPredicate[1] = null;

		$this->writeSubject( $base, $local );
		return $this;
	}

	/**
	 * @see RdfWriter::a()
	 * Shorthand for say( 'a' )->is( $type ).
	 *
	 * @param string $typeBase The data type's QName prefix if $typeLocal is given,
	 *        or an IRI or shorthand if $typeLocal is null.
	 * @param string|null $typeLocal The data type's  QName suffix,
	 *        or null if $typeBase is an IRI or shorthand.
	 *
	 * @return RdfWriter $this
	 */
	final public function a( $typeBase, $typeLocal = null ) {
		return $this->say( 'a' )->is( $typeBase, $typeLocal );
	}

	/**
	 * @see RdfWriter::say()
	 *
	 * @param string $base A QName prefix.
	 * @param string|null $local A QName suffix.
	 *
	 * @return RdfWriter $this
	 */
	final public function say( $base, $local = null ) {
		$this->expandPredicate( $base, $local );

		if ( $this->state === self::STATE_OBJECT
			&& $base === $this->currentPredicate[0]
			&& $local === $this->currentPredicate[1]
		) {
			return $this; // redundant about() call
		}

		$this->state( self::STATE_PREDICATE );

		$this->currentPredicate[0] = $base;
		$this->currentPredicate[1] = $local;

		$this->writePredicate( $base, $local );
		return $this;
	}

	/**
	 * @see RdfWriter::is()
	 *
	 * @param string $base A QName prefix if $local is given, or an IRI if $local is null.
	 * @param string|null $local A QName suffix, or null if $base is an IRI.
	 *
	 * @return RdfWriter $this
	 */
	final public function is( $base, $local = null ) {
		$this->state( self::STATE_OBJECT );

		$this->expandResource( $base, $local );
		$this->writeResource( $base, $local );
		return $this;
	}

	/**
	 * @see RdfWriter::text()
	 *
	 * @param string $text the text to be placed in the output
	 * @param string|null $language the language the text is in
	 *
	 * @return $this
	 */
	final public function text( $text, $language = null ) {
		$this->state( self::STATE_OBJECT );

		$this->writeText( $text, $language );
		return $this;
	}

	/**
	 * @see RdfWriter::value()
	 *
	 * @param string $value the value encoded as a string
	 * @param string|null $typeBase The data type's QName prefix if $typeLocal is given,
	 *        or an IRI or shorthand if $typeLocal is null.
	 * @param string|null $typeLocal The data type's  QName suffix,
	 *        or null if $typeBase is an IRI or shorthand.
	 *
	 * @return $this
	 */
	final public function value( $value, $typeBase = null, $typeLocal = null ) {
		$this->state( self::STATE_OBJECT );

		if ( $typeBase === null && !is_string( $value ) ) {
			$vtype = gettype( $value );
			switch ( $vtype ) {
				case 'integer':
					$typeBase = 'xsd';
					$typeLocal = 'integer';
					$value = "$value";
					break;

				case 'double':
					$typeBase = 'xsd';
					$typeLocal = 'double';
					$value = "$value";
					break;

				case 'boolean':
					$typeBase = 'xsd';
					$typeLocal = 'boolean';
					$value = $value ? 'true' : 'false';
					break;
			}
		}

		$this->expandType( $typeBase, $typeLocal );

		$this->writeValue( $value, $typeBase, $typeLocal );
		return $this;
	}

	/**
	 * State transition table
	 * First state is "from", second is "to"
	 * @var array
	 */
	protected $transitionTable = [
			self::STATE_START => [
					self::STATE_DOCUMENT => true,
			],
			self::STATE_DOCUMENT => [
					self::STATE_DOCUMENT => true,
					self::STATE_SUBJECT => true,
					self::STATE_FINISH => true,
			],
			self::STATE_SUBJECT => [
					self::STATE_PREDICATE => true,
			],
			self::STATE_PREDICATE => [
					self::STATE_OBJECT => true,
			],
			self::STATE_OBJECT => [
					self::STATE_DOCUMENT => true,
					self::STATE_SUBJECT => true,
					self::STATE_PREDICATE => true,
					self::STATE_OBJECT => true,
			],
	];

	/**
	 * Perform a state transition. Writer states roughly correspond to states in a naive
	 * regular parser for the respective syntax. State transitions may generate output,
	 * particularly of structural elements which correspond to terminals in a respective
	 * parser.
	 *
	 * @param int $newState one of the self::STATE_... constants
	 *
	 * @throws LogicException
	 */
	final protected function state( $newState ) {
		if ( !isset( $this->transitionTable[$this->state][$newState] ) ) {
			throw new LogicException( 'Bad transition: ' . $this->state . ' -> ' . $newState );
		}

		$action = $this->transitionTable[$this->state][$newState];
		if ( $action !== true ) {
			if ( is_string( $action ) ) {
				$this->write( $action );
			} else {
				$action();
			}
		}

		$this->state = $newState;
	}

	/**
	 * Must be implemented to generate output that starts a statement (or set of statements)
	 * about a subject. Depending on the requirements of the output format, the implementation
	 * may be empty.
	 *
	 * @note: $base and $local are given as passed to about() and processed by expandSubject().
	 *
	 * @param string $base
	 * @param string|null $local
	 */
	abstract protected function writeSubject( $base, $local = null );

	/**
	 * Must be implemented to generate output that represents the association of a predicate
	 * with a subject that was previously defined by a call to writeSubject().
	 *
	 * @note: $base and $local are given as passed to say() and processed by expandPredicate().
	 *
	 * @param string $base
	 * @param string|null $local
	 */
	abstract protected function writePredicate( $base, $local = null );

	/**
	 * Must be implemented to generate output that represents a resource used as the object
	 * of a statement.
	 *
	 * @note: $base and $local are given as passed to is() and processed by expandObject().
	 *
	 * @param string $base
	 * @param string|null $local
	 */
	abstract protected function writeResource( $base, $local = null );

	/**
	 * Must be implemented to generate output that represents a text used as the object
	 * of a statement.
	 *
	 * @param string $text the text to be placed in the output
	 * @param string|null $language the language the text is in
	 */
	abstract protected function writeText( $text, $language );

	/**
	 * Must be implemented to generate output that represents a (typed) literal used as the object
	 * of a statement.
	 *
	 * @note: $typeBase and $typeLocal are given as passed to value() and processed by expandType().
	 *
	 * @param string $value the value encoded as a string
	 * @param string|null $typeBase
	 * @param string|null $typeLocal
	 */
	abstract protected function writeValue( $value, $typeBase, $typeLocal = null );

	/**
	 * Perform any expansion (shorthand to qname, qname to IRI) desired
	 * for subject identifiers.
	 *
	 * @param string &$base
	 * @param string|null &$local
	 */
	protected function expandSubject( &$base, &$local ) {
	}

	/**
	 * Perform any expansion (shorthand to qname, qname to IRI) desired
	 * for predicate identifiers.
	 *
	 * @param string &$base
	 * @param string|null &$local
	 */
	protected function expandPredicate( &$base, &$local ) {
	}

	/**
	 * Perform any expansion (shorthand to qname, qname to IRI) desired
	 * for resource identifiers.
	 *
	 * @param string &$base
	 * @param string|null &$local
	 */
	protected function expandResource( &$base, &$local ) {
	}

	/**
	 * Perform any expansion (shorthand to qname, qname to IRI) desired
	 * for type identifiers.
	 *
	 * @param string|null &$base
	 * @param string|null &$local
	 */
	protected function expandType( &$base, &$local ) {
	}

}