wip

README.md

@@ -76,4 +76,32 @@ Keep in mind that you need to manually install `league/commonmark`:
 
 ```php
 composer require league/commonmark;
-```
+```
+
+## Language support
+
+This package makes it easy for developers to add new languages or extend existing languages. Right now, these languages are supported: `php`, `html`, `css`. More will be added.
+
+In order to build your own highlighter functionality, you need to understand two concepts of how code is highlighted.
+
+**1. Tokens**
+
+A `token` represents part of your code that should be highlighted. A `token` can be a single keyword like `return` or `class`, or it could be any part of your code, like for example a comment: `/* this is a comment */` or an attribute: `#[Get(uri: '/')]`.
+
+A `token` is represented by a simple class that provides a regex pattern, and a `TokenType`. The regex pattern will find the relevant content, while the `TokenType` is an enum that will determine how that specific token is colored.
+
+
+
+**2. Injections**
+
+### Extending existing languages
+
+Instead of starting from scratch, the best approach to adding new languages is by extending existing ones. For example, let's add support for `blade`:
+
+```php
+class BladeLanguage extends HtmlLanguage
+{
+}
+```
+
+### Adding your own languages

src/Highlighter.php

@@ -16,9 +16,17 @@ final class Highlighter
 
     public function __construct()
     {
-        $this->languages['php'] = new PhpLanguage();
-        $this->languages['html'] = new HtmlLanguage();
-        $this->languages['css'] = new CssLanguage();
+        $this
+            ->setLanguage('php', new PhpLanguage())
+            ->setLanguage('html', new HtmlLanguage())
+            ->setLanguage('css', new CssLanguage());
+    }
+
+    public function setLanguage(string $name, Language $language): self
+    {
+        $this->languages[$name] = $language;
+
+        return $this;
     }
 
     public function parse(string $content, string $language): string

src/Tokens/ParseTokens.php

@@ -10,7 +10,7 @@
 final readonly class ParseTokens
 {
     /**
-     * @return \App\Tokens\Token[]
+     * @return \Tempest\Highlight\Tokens\Token[]
      */
     public function __invoke(string $content, Language $language): array
     {

src/Tokens/RenderTokens.php

@@ -8,7 +8,7 @@ final class RenderTokens
 {
     /**
      * @param string $content
-     * @param \App\Tokens\Token[] $tokens
+     * @param \Tempest\Highlight\Tokens\Token[] $tokens
      * @param int $parsedOffset
      * @return string
      */

src/Tokens/Token.php

@@ -11,7 +11,7 @@ final class Token
     public int $length;
     public int $start;
     public int $end;
-    /** @var \App\Highlight\Token[] */
+    /** @var \Tempest\Highlight\Tokens\Token[] */
     public array $children = [];
     public ?Token $parent = null;