<?php

namespace NPS\DependencyInjection;

use NPS\Model\TraversableXMLElement as XML;
use NPS\Etc\IMessage;


/**
 * Default interface to plug-in any expert system
 * @author Lukas Korinek
 */
interface IExpertSystemBridge extends IMessage
{
    /**
     * Starts a consultation
     * @param string $path Knowledge base path
     * @return bool True on success
     */
    function startConsultation($path);

    /**
     * Loads a consultation from stored state
     * @param array $data 
     * @return bool True on success
     */
    function loadConsultationState(array $data);

    /**
     * Saves the consultation and returns consultation data
     * @return array with keys "base", "started", "language", "internal"
     */
    function saveConsultationState();

    /**
     * Sets the language of the consultation
     * @param string $language One of the languages
     * @return bool|null Null for an unsupported language. False for command fail
     */
    function setLanguage($language);

    /**
     * Gets the language which is currently set for the consultation
     * @return string null on failure
     */
    function getLanguage();

    /**
     * Gets all the supported languages of this base
     * @return array
     */
    function getSupportedLanguages();

    /**
     * Gets next question
     * @return XML|null Element with question details, null on failure
     */
    function getQuestion();

    /**
     * Sets answer to the current question
     * @param mixed $answer 
     * @return bool
     */
    function setAnswer($answer);

    /**
     * Rewinds the consultation back by one question
     * @return bool
     */
    function back();

    /**
     * Shifts the consultation to go forward by one question (answered)
     * @return bool
     */
    function forward();

    /**
     * Gets hypothesis for the consultation and their rank
     * @return array|null Array of hypothesis content elements, null on failure
     */
    function getHypothesis();

    /**
     * Ends the current consultation
     * @return bool
     */
    function endConsultation();

    /**
     * Determines if the consultation has ended
     * @return bool|null Null on failure
     */
    function isEnded();
}

