Started documenting the library in the readme

README.md

@@ -4,4 +4,44 @@
 
 # Lit #
 
-Lit is a multilanguage syntax highlighter written in PHP. It takes code as input and returns HTML with classes based upon tokens in the code. It is loosely based upon [Atom][a]'s [Highlights][b] which is used in the Atom text editor to syntax highlight code. Atom's Highlights is in turn based upon [TextMate][c]'s syntax highlighting using its concepts of scope selectors and common keywords for components of programming languages.
+Lit is a multilanguage syntax highlighter written in PHP. It takes code as input and returns an HTML pre element containing the code highlighted using span elements with classes based upon tokens in the code. It is loosely based upon [Atom][a]'s [Highlights][b] which is used in the Atom text editor to syntax highlight code. Atom's Highlights is in turn based upon [TextMate][c]'s syntax highlighting using its concepts of scope selectors and common keywords for components of programming languages. Lit is not a port of Atom's Highlights but instead an independent implementation of what I can understand of TextMate's grammar syntax, parsing, and tokenization by analyzing other implementations. It aims to at least have feature parity or better with Atom's highlights.
+
+## Documentation ##
+
+### dW\\Lit\\Highlight::toElement ###
+
+Highlights incoming string data and outputs a PHP `\DOMElement`.
+
+```php
+public static dW\Lit\Highlight::toElement(string $data, string $scopeName, ?\DOMDocument $document = null, string $encoding = 'windows-1252'): \DOMElement
+```
+
+#### Parameters ####
+
+data - The input data string.
+scopeName - The scope name (eg: text.html.php) of the grammar that's needed to highlight the input data.
+document - An existing `\DOMDocument` to use as the owner document of the returned `\DOMElement`; if omitted one will be created instead.
+encoding - If a document isn't provided an encoding may be provided for the new document; the HTML standard default windows-1252 is used if no encoding is provided.
+
+#### Return Values ####
+
+Returns a `pre` `\DOMElement`.
+
+## Usage ##
+
+Here's an example of highlighting PHP code:
+
+```php
+$code = <<<CODE
+<?php
+echo "OOK!";
+?>
+CODE;
+
+$element = dW\Lit\Highlight::toElement($code, 'text.html.php');
+// Use PHP DOM's DOMDocument::saveHTML method to print the highlighted markup.
+$string = $element->ownerDocument->saveHTML($element);
+```
+
+
+

lib/Highlight.php

@@ -6,40 +6,19 @@
 declare(strict_types=1);
 namespace dW\Lit;
 use dW\Lit\Grammar\Exception;
-use MensBeam\HTML\{
-        Document,
-        Element
-};
 
 
 class Highlight {
     /**
-     * Highlights incoming string data and outputs an HTML DOM Mensbeam\HTML\Element.
+     * Highlights incoming string data and outputs a PHP DOMElement.
      *
      * @param string $data - The input data string.
      * @param string $scopeName - The scope name (eg: text.html.php) of the grammar that's needed to highlight the input data.
-     * @param ?Mensbeam\HTML\Document [$document = null] - An existing MensBeam\HTML\Document to use as the owner document of the returned MensBeam\HTML\Element; if omitted one will be created instead.
-     * @param string [$encoding = 'windows-1252'] - If a document isn't provided an encoding may be provided for the new document; the HTML standard default windows-1252 is used if no encoding is provided.
-     * @return Mensbeam\HTML\Element
+     * @param ?\DOMDocument $document = null - An existing DOMDocument to use as the owner document of the returned DOMElement; if omitted one will be created instead.
+     * @param string $encoding = 'windows-1252' - If a document isn't provided an encoding may be provided for the new document; the HTML standard default windows-1252 is used if no encoding is provided.
+     * @return \DOMElement
      */
-    public static function toElement(string $data, string $scopeName, ?Document $document = null, string $encoding = 'windows-1252'): Element {
-        return self::highlight($data, $scopeName, $document, $encoding);
-    }
-
-    /**
-     * Highlights incoming string data and outputs an HTML string.
-     *
-     * @param string $data - The input data string.
-     * @param string $scopeName - The scope name (eg: text.html.php) of the grammar that's needed to highlight the input data.
-     * @param string [$encoding = 'windows-1252'] - Encoding for the input string data; the HTML standard default windows-1252 is used if no encoding is provided.
-     * @return string
-     */
-    public static function toString(string $data, string $scopeName, string $encoding = 'windows-1252'): string {
-        return (string)self::highlight($data, $scopeName, null, $encoding);
-    }
-
-
-    protected static function highlight(string $data, string $scopeName, ?Document $document = null, string $encoding = 'windows-1252'): Element {
+    public static function toElement(string $data, string $scopeName, ?\DOMDocument $document = null, string $encoding = 'windows-1252'): \DOMElement {
         $grammar = GrammarRegistry::get($scopeName);
         if ($grammar === false) {
             throw new Exception(Exception::GRAMMAR_MISSING, $scopeName);
@@ -49,13 +28,13 @@ class Highlight {
         $tokenList = $tokenizer->tokenize();
 
         if ($document === null) {
-            $document = new Document();
+            $document = new \DOMDocument();
             $document->encoding = $encoding;
         }
 
         $pre = $document->createElement('pre');
         $code = $document->createElement('code');
-        $code->setAttribute('class', implode(' ', array_unique(explode('.', $scopeName))));
+        $code->setAttribute('class', self::scopeNameToCSSClassList($scopeName));
         $pre->appendChild($code);
 
         $elementStack = [ $code ];
@@ -73,7 +52,7 @@ class Highlight {
                         }
 
                         $span = $document->createElement('span');
-                        $span->setAttribute('class', implode(' ', array_unique(explode('.', $scope))));
+                        $span->setAttribute('class', self::scopeNameToCSSClassList($scope));
                         end($elementStack)->appendChild($span);
                         $scopeStack[] = $scope;
                         $elementStack[] = $span;
@@ -93,4 +72,9 @@ class Highlight {
 
         return $pre;
     }
+
+
+    protected static function scopeNameToCSSClassList(string $scopeName): string {
+        return implode(' ', array_unique(explode('.', $scopeName)));
+    }
 }