TextUtils (NetPhantom® 8.0 Java API Specification)

java.lang.Object
- co.mindus.utils.TextUtils

public class TextUtils
extends Object

Text utilities providing Markdown-to-HTML conversion via dynamically loaded commonmark-java libraries.

This class has zero compile-time dependencies on commonmark. At first use, it detects the Java runtime version, locates the appropriate uber JAR (Java 8 or Java 11+), creates an isolated URLClassLoader, and sets up the parser and renderer entirely via reflection. Everything is cached for subsequent calls.

The uber JARs are located using the following strategies (in order):

Classpath resource embedded inside the server JAR at /co/mindus/utils/md/np-md-java8.jar or /co/mindus/utils/md/np-md-java17.jar.
Filesystem: C:\NP6\Java\Base\ directory (NetPhantom standard layout).

Themes

Full-document output supports a two-layer theme system:

Document themes (TextUtils.Theme) — control the overall page appearance (fonts, headings, tables, blockquotes, background). Six built-in themes are provided as three light/dark pairs:

Document themes
Light	Dark	Style
`BASIC`	`BASIC_DARK`	System fonts, minimal borders
`MODERN`	`MODERN_DARK`	Inter font, soft shadows, gradient HRs
`GITHUB`	`GITHUB_DARK`	GitHub-inspired, rounded code blocks

Use TextUtils.Theme.NONE for bare unstyled HTML.

Syntax highlight themes (SyntaxHighlighter.HighlightTheme) — control the colors of syntax-highlighted code blocks. 77 themes are available (16 curated + 61 extended), covering popular styles like GitHub, Monokai, Nord, Dracula, Solarized, Atom One, VS Code, and many more. See SyntaxHighlighter.HighlightTheme for the full catalog.

When using the TextUtils.DocumentBuilder, the highlight theme is auto-selected to match the document theme's brightness (light document → GITHUB, dark document → GITHUB_DARK). Override with TextUtils.DocumentBuilder.highlightTheme(SyntaxHighlighter.HighlightTheme).

For full-document output with CSS theming, use parseMarkdownToDocument(String) or the TextUtils.DocumentBuilder obtained via documentBuilder().

All public methods are thread-safe.

Author:: Christopher Mindus
See Also:: SyntaxHighlighter

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`TextUtils.DocumentBuilder` Builder for full HTML documents with configurable theme, title, language, and CSS handling.
`static class`	`TextUtils.Theme` Available CSS themes for Markdown document rendering.

Field Summary

Fields
Modifier and Type Field and Description

static TextUtils.Theme DEFAULT_THEME
Default theme used by parseMarkdownToDocument(String).

Fields
Modifier and Type	Field and Description
`static TextUtils.Theme`	`DEFAULT_THEME` Default theme used by `parseMarkdownToDocument(String)`.

Constructor Summary

Constructors
Constructor and Description

TextUtils()

Constructors
Constructor and Description
`TextUtils()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`dispose()` Closes the internal class loader and releases resources.
`static TextUtils.DocumentBuilder`	`documentBuilder()` Creates a new `TextUtils.DocumentBuilder` for configuring full-document output.
`static String`	`escapeNonAscii(String html)` Replaces all non-ASCII characters (codepoints above U+007E) in an HTML string with numeric character references (`&#xNNNN;`).
`static TextUtils.Theme[]`	`getAvailableThemes()` Returns all available themes (excluding `TextUtils.Theme.NONE`).
`static String[]`	`getLoadedExtensions()` Returns the list of successfully loaded extension class names, or `null` if not yet initialized.
`static String`	`getLoadedVersion()` Returns the version descriptor of the loaded commonmark library, or `null` if not yet initialized.
`static boolean`	`isInitialized()` Returns `true` if the Markdown engine is initialized and ready.
`static String`	`loadCssFromFile(File cssFile)` Loads a CSS file from the filesystem and returns its content.
`static String`	`loadThemeCss(TextUtils.Theme theme)` Loads the CSS text for a given theme.
`static void`	`main(String[] args)` Test entry point — demonstrates both fragment and full-document rendering.
`static String`	`parseMarkdownToDocument(String markdown)` Parses Markdown and wraps the resulting HTML in a complete HTML document using the `default theme` with inline CSS.
`static String`	`parseMarkdownToHtml(String markdown)` Parses a Markdown string and renders it to HTML.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_THEME
```
public static final TextUtils.Theme DEFAULT_THEME
```
    Default theme used by parseMarkdownToDocument(String).
- Constructor Detail
  - TextUtils
```
public TextUtils()
```
- Method Detail
  - parseMarkdownToHtml
```
public static String parseMarkdownToHtml(String markdown)
```
    Parses a Markdown string and renders it to HTML.
    This is the primary entry point. The first call triggers lazy initialization of the Markdown engine (detecting Java version, loading the appropriate library).
    
    Parameters:
    
    markdown - The Markdown text to convert.
    
    Returns:
    
    The resulting HTML string.
    
    Throws:
    
    IllegalStateException - if the Markdown engine could not be initialized.
    
    RuntimeException - wrapping any reflection/invocation errors.
  - getLoadedVersion
```
public static String getLoadedVersion()
```
    Returns the version descriptor of the loaded commonmark library, or null if not yet initialized.
  - getLoadedExtensions
```
public static String[] getLoadedExtensions()
```
    Returns the list of successfully loaded extension class names, or null if not yet initialized.
  - isInitialized
```
public static boolean isInitialized()
```
    Returns true if the Markdown engine is initialized and ready.
  - dispose
```
public static void dispose()
```
    Closes the internal class loader and releases resources. After this call, the Markdown engine is no longer usable. Intended for server shutdown.
  - parseMarkdownToDocument
```
public static String parseMarkdownToDocument(String markdown)
```
    Parses Markdown and wraps the resulting HTML in a complete HTML document using the default theme with inline CSS.
    Equivalent to documentBuilder().markdown(markdown).build().
    
    Parameters:
    
    markdown - The Markdown text to convert.
    
    Returns:
    
    A complete HTML document string.
  - documentBuilder
```
public static TextUtils.DocumentBuilder documentBuilder()
```
    Creates a new TextUtils.DocumentBuilder for configuring full-document output.
    Usage example:
```
 String html = TextUtils.documentBuilder()
     .markdown(text)
     .title("My Report")
     .theme(TextUtils.Theme.GITHUB)
     .inlineCss(true)
     .build();
 
```
    Returns:
    
    A new builder instance.
  - loadThemeCss
```
public static String loadThemeCss(TextUtils.Theme theme)
```
    Loads the CSS text for a given theme. The result is cached after first load.
    
    Parameters:
    
    theme - The theme to load.
    
    Returns:
    
    The CSS text, or null if the theme is TextUtils.Theme.NONE or the resource could not be read.
  - loadCssFromFile
```
public static String loadCssFromFile(File cssFile)
```
    Loads a CSS file from the filesystem and returns its content.
    
    Parameters:
    
    cssFile - The CSS file to read.
    
    Returns:
    
    The CSS text, or null if the file does not exist or cannot be read.
  - getAvailableThemes
```
public static TextUtils.Theme[] getAvailableThemes()
```
    Returns all available themes (excluding TextUtils.Theme.NONE).
  - escapeNonAscii
```
public static String escapeNonAscii(String html)
```
    Replaces all non-ASCII characters (codepoints above U+007E) in an HTML string with numeric character references (&#xNNNN;).
    This makes the output safe for any HTTP transport regardless of the Content-Type charset sent by the web server. Without this, browsers that receive HTML without an explicit charset=UTF-8 header may fall back to ISO-8859-1 or Windows-1252, producing mojibake for multi-byte UTF-8 sequences.
    
    Characters typically affected
    - U+21A9 (↩) — footnote backlink arrow injected by the CommonMark footnotes extension
    - U+2014 (—) — em-dash from Markdown content
    - Any other non-ASCII character present in Markdown source text or injected by CommonMark extensions at render time
    The method includes a fast-path: if the input contains no characters above U+007E, it is returned as-is with zero allocation.
    
    Usage example:
```
 String html = TextUtils.parseMarkdownToHtml(markdown);
 html = TextUtils.escapeNonAscii(html);  // safe for any Content-Type
 
```
    Parameters:
    
    html - The HTML string to process. May be a fragment or a complete document.
    
    Returns:
    
    The same HTML with all characters above U+007E replaced by &#xNNNN; entities, or the original string unchanged if it is already pure ASCII.
  - main
```
public static void main(String[] args)
```
    Test entry point — demonstrates both fragment and full-document rendering.

Class TextUtils

Themes

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_THEME

Constructor Detail

TextUtils

Method Detail

parseMarkdownToHtml

getLoadedVersion

getLoadedExtensions

isInitialized

dispose

parseMarkdownToDocument

documentBuilder

loadThemeCss

loadCssFromFile

getAvailableThemes

escapeNonAscii

Characters typically affected

main