Sinobu

Sinobu provides functionality for handling HTML and XML documents. It uses a built-in, lenient parser (often called a tag soup parser) that can handle malformed HTML, similar to how web browsers do. The core class for this is XML, which offers a jQuery-like API for traversing and manipulating the document structure.

🍜 Tag Soup Friendly

Handles malformed HTML gracefully, tolerating missing or mismatched tags commonly found in real-world web content.

public void caseInconsistencyLowerUpper() {
    XML root = parseAsHTML("<div>crazy</DIV>");

    assert root.find("div").size() == 1;
}

🎯 CSS Selector Power

Leverages CSS selectors for efficient and flexible element selection, similar to JavaScript libraries like jQuery.

public void tag() {
    XML xml = I.xml("""
            <root>
                <h1></h1>
                <article/>
                <article></article>
            </root>
            """);

    assert xml.find("h1").size() == 1;
    assert xml.find("article").size() == 2;
}

🛠️ jQuery-Like API

Provides a fluent and chainable API for easy DOM manipulation, inspired by the familiar jQuery syntax.

public void append() {
    XML root = I.xml("<m><Q><P/></Q><Q><P/></Q></m>");

    assert root.find("Q").append("<R/><R/>").find("R").size() == 4;
    assert root.find("Q > R").size() == 4;
    assert root.find("Q > R:first-child").size() == 0;
}

🌐 XML Ready

Supports not only HTML but also XML documents, providing a unified interface for structured data processing.

You can parse HTML/XML from various sources using the I class utility methods. Sinobu automatically detects whether the input is a URL, file path, or raw string. The parser is designed to be tolerant of errors and can handle common issues found in real-world HTML, such as missing tags or incorrect nesting. This makes it suitable for scraping or processing potentially messy markup.

• I#xml(String)
• I#xml(java.nio.file.Path)
• I#xml(java.io.InputStream)
• I#xml(java.io.Reader)
• I#xml(Node)

public void htmlLiteral() {
    XML root = I.xml("<html/>");

    assert root.size() == 1;
    assert root.name() == "html";
}

And can parse the invalid structure.

public void caseInconsistencyLowerUpper() {
    XML root = parseAsHTML("<div>crazy</DIV>");

    assert root.find("div").size() == 1;
}

public void slipOut() {
    XML root = parseAsHTML("<a><b>crazy</a></b>");

    assert root.find("a").text().equals("crazy");
    assert root.find("b").text().equals("crazy");
}

You can serialize the XML structure back into a string representation or write it to an Appendable (like Writer or StringBuilder). Sinobu offers both compact and formatted output options.

The XML#toString() method provides a compact string representation without extra formatting.

public void format() {
    XML root = I.xml("<root><child/><child/></root>");

    assert root.toString().equals(normalize("""
            <root>
                <child/>
                <child/>
            </root>
            """));
}

The XML#to(Appendable, String, String...) method allows for pretty-printing the XML structure with configurable indentation for improved readability. You can specify the indentation string (e.g., a tab character \t or spaces).

public void specialIndent() {
    StringBuilder out = new StringBuilder();
    I.xml("<root><child><nested/></child></root>").to(out, "*");

    assert out.toString().equals(normalize("""
            <root>
            *<child>
            **<nested/>
            *</child>
            </root>
            """));
}

You can also specify tag names that should be treated as inline elements (no line breaks around them), preserving the original formatting for elements like <span> or <a>.

public void inlineElement() {
    StringBuilder out = new StringBuilder();
    I.xml("<root><inline/></root>").to(out, "\t", "inline");

    assert out.toString().equals("<root><inline/></root>");
}

By using the special prefix `` before a tag name, you can also specify tags that should always be treated as non-empty elements (always have a closing tag like <script></script>, even if empty).

public void nonEmptyElement() {
    StringBuilder out = new StringBuilder();
    I.xml("<root/>").to(out, "\t", "&root");

    assert out.toString().equals("<root></root>");
}

By passing null as the indent character, formatting (indentation and line breaks) is disabled, similar to toString() but writing to an Appendable.

public void withoutFormat() {
    StringBuilder out = new StringBuilder();
    I.xml("<root><child/></root>").to(out, null);

    assert out.toString().equals("<root><child/></root>");
}

Sinobu leverages CSS selectors for querying elements within the document structure using the XML#find(String) method. This provides a powerful and familiar way to select nodes, similar to JavaScript's document.querySelectorAll. This library supports many standard CSS3 selectors and includes some useful extensions.

public void tag() {
    XML xml = I.xml("""
            <root>
                <h1></h1>
                <article/>
                <article></article>
            </root>
            """);

    assert xml.find("h1").size() == 1;
    assert xml.find("article").size() == 2;
}

public void attribute() {
    XML xml = I.xml("""
            <m>
                <e A='one' B='one'/>
                <e A='two' B='two'/>
            </m>
            """);

    assert xml.find("[A]").size() == 2;
    assert xml.find("[A=one]").size() == 1;
}

public void clazz() {
    XML xml = I.xml("""
            <root>
                <p class="on"/>
                <p class="on large"/>
                <p class=""/>
                <p no-class-attr="on"/>
            </root>
            """);

    assert xml.find(".on").size() == 2;
    assert xml.find(".large").size() == 1;
    assert xml.find(".on.large").size() == 1;
}

public void mix() {
    XML xml = I.xml("""
            <m>
                <ok/>
                <ok>
                    <ok id="not"/>
                    <not>
                        <ok/>
                    </not>
                </ok>
            </m>
            """);

    assert xml.find("ok").size() == 4;
    assert xml.find("not ok").size() == 1;
    assert xml.find("ok > ok").size() == 1;
}

The XML object provides a fluent API, similar to jQuery, for modifying the document structure.

Important: These manipulation methods modify the underlying DOM structure directly; the XML object itself is mutable in this regard. Explore the nested classes for specific manipulation categories.

Navigate the DOM tree relative to the currently selected elements. Most traversal methods return a new XML object containing the resulting elements, allowing for method chaining without modifying the original selection (unless intended). Explore the nested classes for specific traversal categories.