diff --git a/README.md b/README.md index a035374..3b806b1 100644 --- a/README.md +++ b/README.md @@ -55,16 +55,35 @@ public static dW\Lit\Highlight::toElement(string $data, string $scopeName, ?\DOM ***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. +***encoding*** - The encoding of the input data string; only used if a document wasn't provided in the previous parameter, otherwise it uses the encoding of the existing `DOMDocument` #### Return Values #### Returns a `pre` `DOMElement`. +### dW\\Lit\\Highlight::toString ### + +Highlights incoming string data and outputs a string containing serialized HTML. + +```php +public static dW\Lit\Highlight::toString(string $data, string $scopeName, string $encoding = 'windows-1252'): string +``` + +#### 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 +***encoding*** - The encoding of the input data string + +#### Return Values #### + +Returns a string. + + ## Examples ## -Here's an example of simply highlighting PHP code: +Here's an example of highlighting PHP code: ```php $code = <<setAttribute('class', 'highlighted'); + +// Use PHP DOM's DOMDocument::saveHTML method to print the highlighted markup +// when finished with manipulating it. echo $element->ownerDocument->saveHTML($element); ``` @@ -86,15 +108,10 @@ This will produce: ?> ``` -An existing `DOMDocument` may be used as the owner document of the returned `pre` element: +An already existing `DOMDocument` may be used as the owner document of the returned `pre` element: ```php -$code = << -CODE; - +... $document = new DOMDocument(); // $element will be owned by $document. $element = dW\Lit\Highlight::toElement($code, 'text.html.php', $document); @@ -103,15 +120,17 @@ $element = dW\Lit\Highlight::toElement($code, 'text.html.php', $document); Other DOM libraries which inherit from PHP's DOM such as [`MensBeam\HTML`][d] may also be used: ```php -$code = << -CODE; - +... $document = new MensBeam\HTML\Document(); // $element will be owned by $document. $element = dW\Lit\Highlight::toElement($code, 'text.html.php', $document); // MensBeam\HTML\Element can simply be cast to a string to serialize. $string = (string)$element; ``` + +Of course Lit can simply output a string, too: + +```php +... +$string = dW\Lit\Highlight::toString($code, 'text.html.php'); +``` diff --git a/lib/GrammarRegistry.php b/lib/GrammarRegistry.php index 25f46e0..5e9c08e 100644 --- a/lib/GrammarRegistry.php +++ b/lib/GrammarRegistry.php @@ -11,6 +11,12 @@ namespace dW\Lit; class GrammarRegistry { protected static array $storage = []; + + /** + * Clears all grammars from the registry + * + * @return bool + */ public static function clear(): bool { self::$storage = []; return true; @@ -30,6 +36,7 @@ class GrammarRegistry { if (file_exists($filename)) { $grammar = new Grammar(); $grammar->loadJSON($filename); + self::$storage[$scopeName] = $grammar; return $grammar; } } @@ -45,12 +52,7 @@ class GrammarRegistry { * @return bool */ public static function set(string $scopeName, Grammar $grammar): bool { - try { - self::$storage[$scopeName] = $grammar; - } catch (\Exception $e) { - return false; - } - + self::$storage[$scopeName] = $grammar; return true; } } \ No newline at end of file diff --git a/lib/Highlight.php b/lib/Highlight.php index 6fd3c76..b864e50 100644 --- a/lib/Highlight.php +++ b/lib/Highlight.php @@ -15,7 +15,7 @@ class Highlight { * @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 ?\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. + * @param string $encoding = 'windows-1252' - The encoding of the input data string; only used if a document wasn't provided in the previous parameter, otherwise it uses the encoding of the existing DOMDocument * @return \DOMElement */ public static function toElement(string $data, string $scopeName, ?\DOMDocument $document = null, string $encoding = 'windows-1252'): \DOMElement { @@ -73,6 +73,19 @@ class Highlight { return $pre; } + /** + * Highlights incoming string data and outputs a string containing serialized HTML. + * + * @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' - The encoding of the input data string + * @return string + */ + public static function toString(string $data, string $scopeName, string $encoding = 'windows-1252'): string { + $pre = self::toElement($data, $scopeName, null, $encoding); + return $pre->ownerDocument->saveHTML($pre); + } + protected static function scopeNameToCSSClassList(string $scopeName): string { return implode(' ', array_unique(explode('.', $scopeName)));