namespace BitFrame\Renderer;

use \Closure;
use \League\Plates\Engine;
use \League\Plates\Template\Name;
use \League\Plates\Extension\URI;
use \BitFrame\Renderer\TemplatePath;

// implements:
use \BitFrame\Renderer\TemplateInterface;

// exceptions:
use \InvalidArgumentException;
use \BitFrame\Exception\FileNotReadableException;

/**
 * League Plates template renderer add-on.
 */
class PlatesRenderer implements TemplateInterface 
{
    /** @var Engine */
    private $template;
    
    /**
     * @param string|null $templateDir
     * @param string $templateExt (optional, default: 'tpl')
     * @param array $data (optional, default: [])
     *
     * @see Engine::__construct()
     */
    public function __construct( 
        // default template directory
        ?string $templateDir, 
        
        // templates extension
        string $templateExt = 'tpl', 
        
        // add default data (specific key/value pairs can 
        // be overwritten by using the `render()` method)
        array $data = []
     );
    
    /**
     * Render template.
     *
     * @param string $templateName
     * @param array $data (optional, default: [])
     *
     * @return string
     *
     * @throws FileNotReadableException
     *
     * @see: TemplateInterface::render()
     */
    public function render( 
        // name of the template to render
        string $templateName, 
        
        // data to pass along to the template
        array $data = []
     ): string;
    
    /**
     * Proxies to the Plate Engine's `addData()` method. 
     *
     * Add a default parameter to use with a template.
     *
     * Use this method to provide a default parameter to use 
     * when a template is rendered. The parameter may be overridden 
     * by providing it when calling `render()`, or by calling this 
     * method again with a null value.
     *
     * The parameter will be specific to the template name provided. 
     * To make the parameter available to any template, pass the 
     * TEMPLATE_ALL constant for the template name.
     *
     * If the default parameter existed previously, subsequent
     * invocations with the same template name and parameter name 
     * will overwrite.
     *
     * @param string $templateName 
     * @param array $params
     *
     * @throws InvalidArgumentException
     *
     * @see: TemplateInterface::addDefaultParam()
     */
    public function addDefaultParam( 
        // name of template to which the param applies;
        // use TEMPLATE_ALL to apply to all templates
        string $templateName, 
        
        // key/value data pair
        $params
     );
    
    /**
     * Add a template path to the engine. 
     *
     * Adds a template path, with optional namespace the
     * templates in that path provide.
     *
     * @param string $path
     * @param string|null $namespace (optional, default: null)
     *
     * @return void
     *
     * @see: TemplateInterface::addPath()
     */
    public function addPath( 
        // path to add
        string $path,
        
        // namespace for the $path
        ?string $namespace = null
     ): void;
    
    /**
     * Retrieve configured paths from the engine.
     *
     * @return TemplatePath[]
     *
     * @see: TemplateInterface::getPaths()
     */
    public function getPaths(): array;
    
    /**
     * Get Template Engine class.
     *
     * @return Engine
     */
    public function getEngine(): Engine;
    
    /**
     * Create and return a TemplatePath representing 
	 * the default Plates directory.
     *
     * @return TemplatePath
     */
    private function getDefaultPath(): TemplatePath;

    /**
     * Return the internal array of plates folders.
     *
     * @return \League\Plates\Template\Folder[]
     */
    private function getPlatesFolders(): array;
}