core: refine host provider contract; add exception hierarchy; update specs for whitespace and data access

SPECS.md

@@ -41,7 +41,7 @@ composer require getphred/scape
 
 ### 3. Logic & Control Flow
 - **Syntax**: Uses `{( ... )}` for logic tags.
-- **White-space Management**: Logic tags `{( ... )}` automatically consume one trailing newline immediately following the closing `)}` tag to prevent unintended vertical spacing in the rendered output.
+- **White-space Management**: Logic tags `{( ... )}` and block/inheritance tags `{[ ... ]}` automatically consume one trailing newline immediately following their closing `)}` or `]}` to prevent unintended vertical spacing in the rendered output.
 - **"Logic-Light" Constraints**:
     - No generic programming or complex expressions.
     - No `if` statements or conditional branching (by design).

src/Exceptions/FilterNotFoundException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Exceptions;
+
+/**
+ * Class FilterNotFoundException
+ *
+ * Thrown when a 'uses' or 'load_filter' target is missing.
+ *
+ * @package Scape\Exceptions
+ */
+class FilterNotFoundException extends ScapeException
+{
+}

src/Exceptions/PropertyNotFoundException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Exceptions;
+
+/**
+ * Class PropertyNotFoundException
+ *
+ * Thrown in Debug mode when accessing undefined keys/properties.
+ *
+ * @package Scape\Exceptions
+ */
+class PropertyNotFoundException extends ScapeException
+{
+}

src/Exceptions/RecursionLimitException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Exceptions;
+
+/**
+ * Class RecursionLimitException
+ *
+ * Thrown if partial nesting exceeds the limit (default 20).
+ *
+ * @package Scape\Exceptions
+ */
+class RecursionLimitException extends ScapeException
+{
+}

src/Exceptions/ScapeException.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Exceptions;
+
+use Exception;
+
+/**
+ * Class ScapeException
+ *
+ * Base exception for all Scape-related errors.
+ *
+ * @package Scape\Exceptions
+ */
+class ScapeException extends Exception
+{
+}

src/Exceptions/SyntaxException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Exceptions;
+
+/**
+ * Class SyntaxException
+ *
+ * Thrown when the parser encounters malformed tags or illegal logic.
+ *
+ * @package Scape\Exceptions
+ */
+class SyntaxException extends ScapeException
+{
+}

src/Exceptions/TemplateNotFoundException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Exceptions;
+
+/**
+ * Class TemplateNotFoundException
+ *
+ * Thrown when a main template, layout, or partial cannot be resolved.
+ *
+ * @package Scape\Exceptions
+ */
+class TemplateNotFoundException extends ScapeException
+{
+}

src/Interfaces/FilterInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Interfaces;
+
+/**
+ * Interface FilterInterface
+ *
+ * Defines the contract for all Scape filters.
+ *
+ * @package Scape\Interfaces
+ */
+interface FilterInterface
+{
+    /**
+     * Transforms the given value using the provided arguments.
+     *
+     * @param mixed $value The value to be transformed.
+     * @param array $args  An array of optional arguments for the filter.
+     *
+     * @return mixed The transformed value.
+     */
+    public function transform(mixed $value, array $args = []): mixed;
+}

src/Interfaces/HostProviderInterface.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Interfaces;
+
+/**
+ * Interface HostProviderInterface
+ *
+ * Defines the contract for registering custom providers to handle calls in the 'host' namespace.
+ *
+ * @package Scape\Interfaces
+ */
+interface HostProviderInterface
+{
+    /**
+     * Checks if the host provider can handle the given name.
+     *
+     * @param string $name The name of the property or method being queried.
+     *
+     * @return bool True if the provider can handle the call; otherwise false.
+     */
+    public function has(string $name): bool;
+
+    /**
+     * Invokes the host provider for the given name.
+     *
+     * @param string $name The name of the property or method being called.
+     * @param array  $args Optional arguments for the call.
+     *
+     * @return mixed The resolved value.
+     */
+    public function call(string $name, array $args = []): mixed;
+}