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)));