[2.x] Further API changes

README.md

@@ -53,7 +53,7 @@ All you need to do is register the extension through a CommonMark `Environment`
 use League\CommonMark\Environment\Environment;
 use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
 use League\CommonMark\MarkdownConverter;
-use Phiki\CommonMark\PhikiExtension;
+use Phiki\Adapters\CommonMark\PhikiExtension;
 
 $environment = new Environment;
 $environment
@@ -73,7 +73,7 @@ $output = $converter->convert(<<<'MD'
 If you're using Laravel's `Str::markdown()` or `str()->markdown()` methods, you can use the same CommonMark extension by passing it through to the method.
 
 ```php
-use Phiki\CommonMark\PhikiExtension;
+use Phiki\Adapters\CommonMark\PhikiExtension;
 
 Str::markdown('...', extensions: [
     new PhikiExtension('github-dark'),
@@ -87,20 +87,11 @@ To use a language or theme that Phiki doesn't support, you need to register it w
 This can be done by building a custom `Environment` object and telling Phiki to use this instead of the default one.
 
 ```php
-use Phiki\Environment\Environment;
-
-$environment = Environment::default();
-
-// Register a custom language.
-$environment
-    ->getGrammarRepository()
-    ->register('my-language', __DIR__ . '/../path/to/grammar.json');
-
-$environment
-    ->getThemeRepository()
-    ->register('my-theme', __DIR__ . '/../path/to/theme.json');
+use Phiki\Phiki;
 
-$phiki = new Phiki($environment);
+$phiki = (new Phiki)
+    ->grammar('my-language', __DIR__ . '/../path/to/grammar.json')
+    ->theme('my-theme', __DIR__ . '/../path/to/theme.json');
 
 $phiki->codeToHtml('...', 'my-language', 'my-theme');
 ```

src/CommonMark/CodeBlockRenderer.php → src/Adapters/CommonMark/CodeBlockRenderer.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Phiki\CommonMark;
+namespace Phiki\Adapters\CommonMark;
 
 use InvalidArgumentException;
 use League\CommonMark\Extension\CommonMark\Node\Block\FencedCode;

src/CommonMark/PhikiExtension.php → src/Adapters/CommonMark/PhikiExtension.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Phiki\CommonMark;
+namespace Phiki\Adapters\CommonMark;
 
 use League\CommonMark\Environment\EnvironmentBuilderInterface;
 use League\CommonMark\Extension\CommonMark\Node\Block\FencedCode;

src/Adapters/Laravel/Facades/Phiki.php

@@ -5,14 +5,13 @@
 use Illuminate\Support\Facades\Facade;
 
 /**
- * @method static \Phiki\Environment\Environment environment()
  * @method static array<int, array<int, \Phiki\Token\Token>> codeToTokens(string $code, string|\Phiki\Grammar\Grammar|\Phiki\Grammar\ParsedGrammar $grammar)
  * @method static array<int, array<int, \Phiki\Token\HighlightedToken>> tokensToHighlightedTokens(array<int, array<int, \Phiki\Token\Token>> $tokens, string|array|\Phiki\Theme\Theme $theme)
  * @method static array<int, array<int, \Phiki\Token\HighlightedToken>> codeToHighlightedTokens(string $code, string|\Phiki\Grammar\Grammar $grammar, string|array|\Phiki\Theme\Theme $theme)
  * @method static \Phiki\Output\Html\PendingHtmlOutput codeToHtml(string $code, string|\Phiki\Grammar\Grammar $grammar, string|array|\Phiki\Theme\Theme $theme)
- * @method static \Phiki\Phiki addExtension(\Phiki\Contracts\ExtensionInterface $extension)
- * @method static \Phiki\Phiki registerGrammar(string $name, string|\Phiki\Grammar\ParsedGrammar $pathOrGrammar)
- * @method static \Phiki\Phiki registerTheme(string $name, string|\Phiki\Theme\ParsedTheme $pathOrTheme)
+ * @method static \Phiki\Phiki extend(\Phiki\Contracts\ExtensionInterface $extension)
+ * @method static \Phiki\Phiki grammar(string $name, string|\Phiki\Grammar\ParsedGrammar $pathOrGrammar)
+ * @method static \Phiki\Phiki theme(string $name, string|\Phiki\Theme\ParsedTheme $pathOrTheme)
  * 
  * @see \Phiki\Phiki
  */

src/Contracts/ExtensionInterface.php

@@ -2,7 +2,7 @@
 
 namespace Phiki\Contracts;
 
-use Phiki\Environment\Environment;
+use Phiki\Environment;
 
 interface ExtensionInterface
 {

src/Contracts/GrammarRepositoryInterface.php

@@ -2,42 +2,37 @@
 
 namespace Phiki\Contracts;
 
+use Phiki\Grammar\Grammar;
 use Phiki\Grammar\ParsedGrammar;
 
 interface GrammarRepositoryInterface
 {
     /**
      * Get a grammar from the repository.
      *
-     * If the grammar is not already loaded, it will be loaded and cached.
-     *
-     * @param  string  $name  The name of the grammar.
-     *
      * @throws \Phiki\Exceptions\UnrecognisedGrammarException If the grammar is not registered.
      */
     public function get(string $name): ParsedGrammar;
 
     /**
      * Get a grammar from the repository by scope name.
      *
-     * @param  string  $scope  The name of the scope.
-     *
      * @throws \Phiki\Exceptions\UnrecognisedGrammarException If the grammar is not registered.
      */
     public function getFromScope(string $scope): ParsedGrammar;
 
     /**
      * Check whether a grammar exists in the repository.
-     *
-     * @param  string  $name  The name of the grammar.
      */
     public function has(string $name): bool;
 
     /**
-     * Register a new Grammar to use when highlighting.
-     *
-     * @param  string  $name  The name of the grammar.
-     * @param  string|ParsedGrammar  $pathOrGrammar  The path to the grammar file or the grammar itself.
+     * Register a new grammar to use when highlighting.
      */
     public function register(string $name, string|ParsedGrammar $pathOrGrammar): void;
+
+    /**
+     * Resolve the given grammar from the repository.
+     */
+    public function resolve(string|Grammar|ParsedGrammar $theme): ParsedGrammar;
 }

src/Contracts/ThemeRepositoryInterface.php

@@ -3,6 +3,7 @@
 namespace Phiki\Contracts;
 
 use Phiki\Theme\ParsedTheme;
+use Phiki\Theme\Theme;
 
 interface ThemeRepositoryInterface
 {
@@ -11,24 +12,22 @@ interface ThemeRepositoryInterface
      *
      * If the theme is not already loaded, it will be loaded and cached.
      *
-     * @param  string  $name  The name of the theme.
-     *
      * @throws \Phiki\Exceptions\UnrecognisedThemeException If the theme is not registered.
      */
     public function get(string $name): ParsedTheme;
 
     /**
      * Check whether a theme exists in the repository.
-     *
-     * @param  string  $name  The name of the theme.
      */
     public function has(string $name): bool;
 
     /**
      * Register a new theme to use when highlighting.
-     *
-     * @param  string  $name  The name of the theme.
-     * @param  string|ParsedTheme  $pathOrTheme  The path to the theme file or the theme itself.
      */
     public function register(string $name, string|ParsedTheme $pathOrTheme): void;
+
+    /**
+     * Resolve the given theme from the repository.
+     */
+    public function resolve(string|Theme|ParsedTheme $theme): ParsedTheme;
 }

src/Environment.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Phiki;
+
+use Phiki\Contracts\ExtensionInterface;
+use Phiki\Grammar\Grammar;
+use Phiki\Grammar\GrammarRepository;
+use Phiki\Grammar\ParsedGrammar;
+use Phiki\Theme\ParsedTheme;
+use Phiki\Theme\Theme;
+use Phiki\Theme\ThemeRepository;
+
+class Environment
+{
+    public readonly GrammarRepository $grammars;
+
+    public readonly ThemeRepository $themes;
+
+    public function __construct()
+    {
+        $this->grammars = new GrammarRepository;
+        $this->themes = new ThemeRepository;
+    }
+
+    public function extend(ExtensionInterface $extension): static
+    {
+        $extension->register($this);
+
+        return $this;
+    }
+}

src/Grammar/GrammarRepository.php

@@ -66,4 +66,16 @@ public function register(string $name, string|ParsedGrammar $pathOrGrammar): voi
     {
         $this->grammars[$name] = $pathOrGrammar;
     }
+
+    public function resolve(string|Grammar|ParsedGrammar $grammar): ParsedGrammar
+    {
+        if ($grammar instanceof ParsedGrammar) {
+            return $grammar;
+        }
+
+        return match (true) {
+            is_string($grammar) => $this->get($grammar),
+            $grammar instanceof Grammar => $grammar->toParsedGrammar($this),
+        };
+    }
 }