ZMarkupParser

https://github.com/zhgchgli/zmarkupparser
Admin
ZMarkupParser is a pure-Swift library that converts HTML strings into NSAttributedString with...
Tokens:9,328
Snippets:42
Trust Score:9
License:MIT
Update:11 months ago
Show doc for...
Tokens:
Raw
### Building a Parser with Default Configuration

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Initializes a ZMarkupParser with all predefined HTML tags and default styling. This is a starting point for parsing HTML content.

```APIDOC
## Building a Parser with Default Configuration

### Description
Initializes a parser with all pre-defined HTML tags and default styling.

### Method
Initialization

### Endpoint
N/A

### Parameters
None

### Request Example
```swift
import ZMarkupParser

// Create parser with default settings
let parser = ZHTMLParserBuilder.initWithDefault()
    .set(rootStyle: MarkupStyle(font: MarkupStyleFont(size: 13)))
    .build()

// Use the parser to render HTML
let htmlString = "<p>Hello <b>World</b>!</p>"
let attributedString = parser.render(htmlString)

// Apply to UILabel
let label = UILabel()
label.setHtmlString(htmlString, with: parser)
```

### Response
#### Success Response (Initialization)
- **parser** (ZHTMLParser) - An initialized parser instance.

#### Response Example
```swift
// parser object is created and ready to use
```
```

--------------------------------

### UILabel and UITextView HTML Extensions (Swift)

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Provides examples of using convenient extension methods on UILabel and UITextView to set HTML content. It covers both synchronous and asynchronous rendering with completion callbacks.

```swift
import ZMarkupParser
import UIKit

let parser = ZHTMLParserBuilder.initWithDefault()
    .set(rootStyle: MarkupStyle(font: MarkupStyleFont(size: 14)))
    .build()

// UILabel with synchronous rendering
let label = UILabel()
label.numberOfLines = 0
let labelHtml = "<p>Hello <b>World</b>!</p>"
label.setHtmlString(labelHtml, with: parser)

// UILabel with asynchronous rendering
label.setHtmlString(labelHtml, with: parser) { attributedString in
    print("UILabel rendering completed: \(attributedString.length) chars")
}

// UITextView with synchronous rendering
let textView = UITextView()
let textViewHtml = """
<h1>Title</h1>
<p>This is a <a href=\"https://example.com\">clickable link</a></p>
<ul>
    <li>Item 1</li>
    <li>Item 2</li>
</ul>
"""
textView.setHtmlString(textViewHtml, with: parser)

// UITextView with asynchronous rendering and callback
textView.setHtmlString(textViewHtml, with: parser) { attributedString in
    print("UITextView rendering completed with link support")
}
```

--------------------------------

### Swift Package Manager Installation for ZMarkupParser

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

This snippet shows how to add the ZMarkupParser library to your Swift project using the Swift Package Manager. It outlines the steps within Xcode and provides the necessary dependency configuration for your project's `Package.swift` file.

```swift
dependencies: [
  .package(url: "https://github.com/ZhgChgLi/ZMarkupParser.git", from: "1.12.0"),
]
...
.target(
    ...
    dependencies: [
        "ZMarkupParser",
    ],
    ...
)
```

--------------------------------

### Swift MarkupStyle Properties for NSAttributedString Attributes

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

Illustrates the properties available within the `MarkupStyle` wrapper in ZMarkupParser, used for defining various attributes of an `NSAttributedString`. Includes examples of initializing `MarkupStyle`.

```swift
var font:MarkupStyleFont
var paragraphStyle:MarkupStyleParagraphStyle
var foregroundColor:MarkupStyleColor? = nil
var backgroundColor:MarkupStyleColor? = nil
var ligature:NSNumber? = nil
var kern:NSNumber? = nil
var tracking:NSNumber? = nil
var strikethroughStyle:NSUnderlineStyle? = nil
var underlineStyle:NSUnderlineStyle? = nil
var strokeColor:MarkupStyleColor? = nil
var strokeWidth:NSNumber? = nil
var shadow:NSShadow? = nil
var textEffect:String? = nil
var attachment:NSTextAttachment? = nil
var link:URL? = nil
var baselineOffset:NSNumber? = nil
var underlineColor:MarkupStyleColor? = nil
var strikethroughColor:MarkupStyleColor? = nil
var obliqueness:NSNumber? = nil
var expansion:NSNumber? = nil
var writingDirection:NSNumber? = nil
var verticalGlyphForm:NSNumber? = nil
... 

// Example:
MarkupStyle(font: MarkupStyleFont(size: 13), backgroundColor: MarkupStyleColor(name: .aquamarine))
```

--------------------------------

### Asynchronous HTML Parsing and Rendering (Swift)

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

Provides examples of using ZMarkupParser asynchronously for rendering, stripping, and selecting from HTML strings. This is recommended for handling large HTML documents to avoid blocking the main thread. Dependencies: ZMarkupParser. Input: HTML string and a completion handler. Output: Processed attributed string or data via callback.

```swift
parser.render(String) { _ in }
parser.stripper(String) { _ in }
parser.selector(String) { _ in }
```

--------------------------------

### CocoaPods Installation for ZMarkupParser

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

This code block demonstrates how to integrate the ZMarkupParser library into an iOS project using CocoaPods. It specifies the source repository, platform version, and the dependency declaration for the ZMarkupParser pod.

```ruby
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '12.0'
use_frameworks!

target 'MyApp' do
  pod 'ZMarkupParser', '~> 1.12.0'
end
```

--------------------------------

### Extend HTML Tag Name and Style in Swift

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

This example illustrates how to extend HTML tag names and apply custom styles using `ExtendTagName` and the `ZHTMLParserBuilder`. It defines a new tag `<zhgchgli>` and associates it with a specific `MarkupStyle`, in this case, a light aquamarine background color.

```swift
let parser = ZHTMLParserBuilder.initWithDefault().add(ExtendTagName("zhgchgli"), withCustomStyle: MarkupStyle(backgroundColor: MarkupStyleColor(name: .aquamarine))).build()
```

--------------------------------

### Initialize Parser with Default Configuration

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Initializes a ZMarkupParser with all predefined HTML tags and default styling. It then demonstrates how to use the parser to render an HTML string and apply it to a UILabel.

```swift
import ZMarkupParser

// Create parser with default settings
let parser = ZHTMLParserBuilder.initWithDefault()
    .set(rootStyle: MarkupStyle(font: MarkupStyleFont(size: 13)))
    .build()

// Use the parser to render HTML
let htmlString = "<p>Hello <b>World</b>!</p>"
let attributedString = parser.render(htmlString)

// Apply to UILabel
let label = UILabel()
label.setHtmlString(htmlString, with: parser)
```

--------------------------------

### Pseudocode for ZMarkupParser HTML to AST Conversion

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

This pseudocode outlines the steps ZMarkupParser takes to convert an HTML string into an abstract syntax tree. It involves regex-based tokenization, array traversal for tag correction, AST generation, and mapping to markup styles.

```pseudocode
1. Input html string: `<a>Link<b>LinkBold</a>Bold</b>`
2. Convert string to array of tag element through Regex:
```
[
  {tagStart: "a"},
  {string: "Link"},
  {tagStart: "b"},
  {string: "LinkBold"},
  {tagClose: "a"},
  {string: "Bold"},
  {tagClose: "b"}
]
```
3. Traverse tag element array to autocorrect mixed tags and find isolated tags:
```
[
  {tagStart: "a"},
  {string: "Link"},
  {tagStart: "b"},
  {string: "LinkBold"},
  {tagClose: "b"},
  {tagClose: "a"},
  {tagStart: "b"},
  {string: "Bold"},
  {tagClose: "b"}
]
```
4. Convert tag element array to abstract syntax tree:
```
RootMarkup
|--A
|  |--String("Link")
|  |--B
|     |--String("LinkBold")
|
|--B
   |--String("Bold")
```
5. Map tag to abstract Markup/MarkupStyle:
```
RootMarkup
|--A(underline=true)
|  |--String("Link")(color=blue, font=13pt)
|  |--B
|     |--String("LinkBold")(color=blue, font=18pt, bold=true)
|
|--B(font=18pt, bold=true)
```
6. Use Visitor Pattern to visit every tree leaf Markup/MarkupStyle and combine it to NSAttributedString through recursion.
```

--------------------------------

### Initialize Default ZHTMLParserBuilder in Swift

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

This code shows how to initialize a ZHTMLParserBuilder with default settings. The `initWithDefault()` method includes all predefined HTML tag names and style attributes, setting a default root style for rendering. The builder pattern is used for configuration before building the final parser.

```swift
import ZMarkupParser

let parser = ZHTMLParserBuilder.initWithDefault().set(rootStyle: MarkupStyle(font: MarkupStyleFont(size: 13))).build()
```

--------------------------------

### Working with Colors in ZMarkupParser (Swift)

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Illustrates how to use predefined color names and custom UIColor/NSColor instances for styling HTML elements with ZMarkupParser. This includes styling text color and background color.

```swift
import ZMarkupParser

// Using named colors
let parser = ZHTMLParserBuilder.initWithDefault()
    .add(SPAN_HTMLTagName(), withCustomStyle: MarkupStyle(
        foregroundColor: MarkupStyleColor(name: .aquamarine),
        backgroundColor: MarkupStyleColor(name: .azure)
    ))
    .build()

// HTML with color styles
let html = """
<p style=\"color: red\">Red text</p>
<p style=\"background-color: yellow; color: black\">Yellow background</p>
<span>Aquamarine text on azure background</span>
"""

let result = parser.render(html)

// Using custom UIColor/NSColor
let customParser = ZHTMLParserBuilder.initWithDefault()
    .add(P_HTMLTagName(), withCustomStyle: MarkupStyle(
        foregroundColor: MarkupStyleColor(color: .systemPurple)
    ))
    .build()

let customColorHtml = "<p>Purple paragraph text</p>"
let customResult = customParser.render(customColorHtml)
```

--------------------------------

### Extend Parser with Custom Tags

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Illustrates how to define and use custom HTML tags like 'highlight' and 'callout' by extending the parser with new tag names and their associated styles.

```swift
import ZMarkupParser

// Create parser with extended custom tag
let parser = ZHTMLParserBuilder.initWithDefault()
    .add(ExtendTagName("highlight"), withCustomStyle: MarkupStyle(
        backgroundColor: MarkupStyleColor(name: .yellow),
        foregroundColor: MarkupStyleColor(name: .black)
    ))
    .add(ExtendTagName("callout"), withCustomStyle: MarkupStyle(
        font: MarkupStyleFont(size: 16, weight: .style(.bold)),
        backgroundColor: MarkupStyleColor(name: .aquamarine)
    ))
    .build()

// Use custom tags in HTML
let html = """
<p>Normal text <highlight>highlighted section</highlight> more text</p>
<callout>This is a custom callout box!</callout>
"""
let attributedString = parser.render(html)
print("Rendered: \(attributedString.string)")
```

--------------------------------

### Render HTML with Custom Tag Styles

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Demonstrates how to build a parser with custom styling for specific HTML tags like 'b' and 'a'. It also shows asynchronous rendering for UITextView.

```swift
import ZMarkupParser

// Build parser with customized bold tag style
let parser = ZHTMLParserBuilder.initWithDefault()
    .add(B_HTMLTagName(), withCustomStyle: MarkupStyle(
        font: MarkupStyleFont(size: 18, weight: .style(.semibold)),
        foregroundColor: MarkupStyleColor(name: .red)
    ))
    .add(A_HTMLTagName(), withCustomStyle: MarkupStyle(
        foregroundColor: MarkupStyleColor(name: .blue),
        underlineStyle: .single
    ))
    .set(rootStyle: MarkupStyle(font: MarkupStyleFont(size: 14)))
    .build()

// Render HTML with custom styles
let html = "<p>Regular text with <b>bold red text</b> and <a>blue underlined link</a></p>"
let result = parser.render(html)

// Apply to UITextView with async rendering
let textView = UITextView()
textView.setHtmlString(html, with: parser) { attributedString in
    print("Rendering completed with \(attributedString.length) characters")
}
```

--------------------------------

### Handle Complex Nested HTML with ZMarkupParser in Swift

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Illustrates rendering complex HTML structures, including nested elements like articles, headers, paragraphs, lists, links, and blockquotes, using ZMarkupParser. It shows how to set root styles and customize styles for specific tags (h1, h2). Asynchronous rendering for UI components is also demonstrated.

```swift
import ZMarkupParser

let parser = ZHTMLParserBuilder.initWithDefault()
    .set(rootStyle: MarkupStyle(font: MarkupStyleFont(size: 14)))
    .add(H1_HTMLTagName(), withCustomStyle: MarkupStyle(
        font: MarkupStyleFont(size: 24, weight: .style(.bold))
    ))
    .add(H2_HTMLTagName(), withCustomStyle: MarkupStyle(
        font: MarkupStyleFont(size: 20, weight: .style(.semibold))
    ))
    .build()

let complexHtml = """
<article>
    <h1>Article Title</h1>
    <p>Published on <i>January 1, 2024</i></p>
    <hr/>
    <h2>Introduction</h2>
    <p>This article covers <b>important topics</b> including:</p>
    <ul>
        <li>First topic with <a href="#">link</a></li>
        <li>Second topic</li>
        <li>Third topic with <code>code snippet</code></li>
    </ul>
    <blockquote>
        <p>This is a quoted section with <strong>emphasis</strong>.</p>
    </blockquote>
    <h2>Conclusion</h2>
    <p>Thank you for reading. Visit <a href="https://example.com">our website</a>.</p>
</article>
"""

let rendered = parser.render(complexHtml)
print("Rendered \(rendered.length) characters")

// Apply to UI asynchronously
let textView = UITextView()
textView.setHtmlString(complexHtml, with: parser) { attributedString in
    print("Complex HTML rendering completed successfully")
}
```

--------------------------------

### Asynchronous HTML Rendering and Selection with Swift

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Renders large HTML strings or processes selectors asynchronously to prevent blocking the main thread. ZMarkupParser provides methods for async rendering which return the result in a completion handler, and async selector processing for handling complex HTML structures without UI lag. Requires importing ZMarkupParser and Foundation for UUID.

```swift
import ZMarkupParser
import Foundation

let parser = ZHTMLParserBuilder.initWithDefault()
    .set(rootStyle: MarkupStyle(font: MarkupStyleFont(size: 14)))
    .build()

// Async rendering for large HTML content
let largeHtml = """
<div>
    \(String(repeating: "<p>Paragraph \(UUID().uuidString)</p>", count: 1000))
</div>
"""

// Render asynchronously
parser.render(largeHtml) { attributedString in
    print("Async rendering completed: \(attributedString.length) characters")
    // Update UI on main thread (already handled by parser)
    DispatchQueue.main.async {
        let label = UILabel()
        label.attributedText = attributedString
    }
}

// Async selector processing
parser.selector(largeHtml) { selector in
    let paragraphs = selector.filter("p")
    print("Found \(paragraphs.count) paragraphs asynchronously")
}
```

--------------------------------

### Swift HTML Tag Name Definitions in ZMarkupParser

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

Demonstrates the predefined HTML tag names provided by ZMarkupParser, which map to abstract markup classes. It also shows how to extend this functionality with custom tag names.

```swift
A_HTMLTagName(), // <a></a>
B_HTMLTagName(), // <b></b>
BR_HTMLTagName(), // <br></br> and also <br/>
DIV_HTMLTagName(), // <div></div>
HR_HTMLTagName(), // <hr></hr>
I_HTMLTagName(), // <i></i>
LI_HTMLTagName(), // <li></li>
OL_HTMLTagName(), // <ol></ol>
P_HTMLTagName(), // <p></p>
SPAN_HTMLTagName(), // <span></span>
STRONG_HTMLTagName(), // <strong></strong>
U_HTMLTagName(), // <u></u>
UL_HTMLTagName(), // <ul></ul>
DEL_HTMLTagName(), // <del></del>
IMG_HTMLTagName(handler: ZNSTextAttachmentHandler), // <img> and image downloader
TR_HTMLTagName(), // <tr>
TD_HTMLTagName(), // <td>
TH_HTMLTagName() // <th>
...and more
```

--------------------------------

### Rendering HTML with Custom Tag Styles

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Customizes the visual appearance of specific HTML tags by providing custom MarkupStyle configurations. This allows for tailored styling of elements like bold text and links.

```APIDOC
## Rendering HTML with Custom Tag Styles

### Description
Customize the visual appearance of specific HTML tags by providing custom MarkupStyle configurations.

### Method
Configuration and Rendering

### Endpoint
N/A

### Parameters
- **B_HTMLTagName()** (Tag Name) - Customizes the style for the `<b>` tag.
- **A_HTMLTagName()** (Tag Name) - Customizes the style for the `<a>` tag.
- **rootStyle** (MarkupStyle) - Sets the default style for the root element.

### Request Example
```swift
import ZMarkupParser

// Build parser with customized bold tag style
let parser = ZHTMLParserBuilder.initWithDefault()
    .add(B_HTMLTagName(), withCustomStyle: MarkupStyle(
        font: MarkupStyleFont(size: 18, weight: .style(.semibold)),
        foregroundColor: MarkupStyleColor(name: .red)
    ))
    .add(A_HTMLTagName(), withCustomStyle: MarkupStyle(
        foregroundColor: MarkupStyleColor(name: .blue),
        underlineStyle: .single
    ))
    .set(rootStyle: MarkupStyle(font: MarkupStyleFont(size: 14)))
    .build()

// Render HTML with custom styles
let html = "<p>Regular text with <b>bold red text</b> and <a>blue underlined link</a></p>"
let result = parser.render(html)

// Apply to UITextView with async rendering
let textView = UITextView()
textView.setHtmlString(html, with: parser) { attributedString in
    print("Rendering completed with \(attributedString.length) characters")
}
```

### Response
#### Success Response (Rendering)
- **result** (NSAttributedString) - The attributed string generated from the HTML.
- **attributedString** (NSAttributedString) - In the async completion handler, the final attributed string.

#### Response Example
```swift
// NSAttributedString object with styled text
// Completion handler prints rendering status
```
```

--------------------------------

### Customize HTML Tag Style in Swift

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

Shows how to customize the style of an existing HTML tag, such as `<b>`, using ZMarkupParser. The `add` method of `ZHTMLParserBuilder` is used with a specific `HTMLTagName` instance and a `MarkupStyle` object to define the desired rendering.

```swift
let parser = ZHTMLParserBuilder.initWithDefault().add(B_HTMLTagName(), withCustomStyle: MarkupStyle(font: MarkupStyleFont(size: 18, weight: .style(.semibold)))).build()
```

--------------------------------

### Map Class/ID Attributes to Styles in Swift

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

Demonstrates how to use `HTMLTagClassAttribute` and `HTMLTagIdAttribute` to map HTML class and ID attributes to specific `MarkupStyle` objects. This allows for targeted styling based on the attributes defined in the HTML markup.

```swift
let parser = ZHTMLParserBuilder.initWithDefault().add(HTMLTagClassAttribute(className: "text-red", render: {
    return MarkupStyle(foregroundColor: MarkupStyleColor(color: .red))
})).add(HTMLTagClassAttribute(className: "text-small", render: {
    return MarkupStyle(font: MarkupStyleFont(.systemFont(ofSize: 6)))
})).add(HTMLTagIdAttribute(idName: "header", render: {
    return MarkupStyle(font: MarkupStyleFont(.systemFont(ofSize: 36)))
})).build()
```

--------------------------------

### Extending with Custom Tags

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Allows developers to define and render custom HTML tags with personalized styling. This extends the parser's capabilities beyond standard HTML tags.

```APIDOC
## Extending with Custom Tags

### Description
Define and render custom HTML tags with personalized styling.

### Method
Extension and Rendering

### Endpoint
N/A

### Parameters
- **ExtendTagName("tag-name")** (Custom Tag) - Defines a new custom tag with the specified name.
- **withCustomStyle** (MarkupStyle) - The style to apply to the custom tag.

### Request Example
```swift
import ZMarkupParser

// Create parser with extended custom tag
let parser = ZHTMLParserBuilder.initWithDefault()
    .add(ExtendTagName("highlight"), withCustomStyle: MarkupStyle(
        backgroundColor: MarkupStyleColor(name: .yellow),
        foregroundColor: MarkupStyleColor(name: .black)
    ))
    .add(ExtendTagName("callout"), withCustomStyle: MarkupStyle(
        font: MarkupStyleFont(size: 16, weight: .style(.bold)),
        backgroundColor: MarkupStyleColor(name: .aquamarine)
    ))
    .build()

// Use custom tags in HTML
let html = """
<p>Normal text <highlight>highlighted section</highlight> more text</p>
<callout>This is a custom callout box!</callout>
"""
let attributedString = parser.render(html)
print("Rendered: \(attributedString.string)")
```

### Response
#### Success Response (Rendering)
- **attributedString** (NSAttributedString) - The attributed string with custom tags rendered.

#### Response Example
```swift
// attributedString.string contains the rendered text including custom tag styles
```
```

--------------------------------

### Parse HTML with Class and ID Attributes

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Shows how to configure the parser to map CSS class names and IDs to specific styling rules using `HTMLTagClassAttribute` and `HTMLTagIdAttribute`.

```swift
import ZMarkupParser

// Configure parser with class and ID attributes
let parser = ZHTMLParserBuilder.initWithDefault()
    .add(HTMLTagClassAttribute(className: "text-red", render: {
        return MarkupStyle(foregroundColor: MarkupStyleColor(color: .red))
    }))
    .add(HTMLTagClassAttribute(className: "text-small", render: {
        return MarkupStyle(font: MarkupStyleFont(.systemFont(ofSize: 10)))
    }))
    .add(HTMLTagIdAttribute(idName: "header", render: {
        return MarkupStyle(font: MarkupStyleFont(.systemFont(ofSize: 24)))
    }))
    .build()

// HTML with class and id attributes
let html = """
<span id="header">Title Text</span>
<p>Normal paragraph</p>
<span class="text-red">Red text</span>
<span class="text-red text-small">Small red text with multiple classes</span>
"""
let result = parser.render(html)
```

--------------------------------

### Parse HTML String to Selector (Swift)

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

Demonstrates how to use the ZMarkupParser library to parse an HTML string into a selector object. This allows for the extraction of specific elements and their attributes. Dependencies: ZMarkupParser. Input: HTML string. Output: Selector object or its properties.

```swift
let selector = parser.selector(htmlString) // HTMLSelector e.g. input: <a><b>Test</b>Link</a>
selector.first("a")?.first("b").attributedString // will return Test
selector.filter("a").get() // will return dict struct
selector.filter("a") // will return json string of dict
```

--------------------------------

### Select HTML Elements using CSS Selectors in Swift

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Enables querying and filtering of HTML content using a CSS-like selector syntax. ZMarkupParser allows creating a selector from an HTML string and then filtering elements by tag name, retrieving the first match, converting the structure to a dictionary, or rendering a selected element. Requires importing ZMarkupParser.

```swift
import ZMarkupParser

let parser = ZHTMLParserBuilder.initWithDefault().build()

// Create selector from HTML
let html = """
<div>
    <a href="https://example.com"><b>Bold Link</b>Text</a>
    <p>Paragraph content</p>
    <a href="https://another.com">Another Link</a>
</div>
"""

let selector = parser.selector(html)

// Filter elements by tag name
let allLinks = selector.filter("a")
print("Found \(allLinks.count) links")

// Get first matching element
if let firstLink = selector.first("a") {
    if let boldText = firstLink.first("b") {
        print("Bold text in link: \(boldText.attributedString.string)")
    }
}

// Convert selection to dictionary structure
let structure = selector.get()
print("HTML structure: \(structure)")

// Render selected element
if let paragraph = selector.first("p") {
    let renderedParagraph = parser.render(paragraph)
    print("Rendered: \(renderedParagraph)")
}
```

--------------------------------

### Render HTML String with Selector (Swift)

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

Shows how to render a specific part of an HTML string, identified by a selector, into an attributed string using ZMarkupParser. Dependencies: ZMarkupParser. Input: HTML string and a selector. Output: Rendered attributed string.

```swift
let selector = parser.selector(htmlString) // HTMLSelector e.g. input: <a><b>Test</b>Link</a>
parser.render(selector.first("a")?.first("b"))
```

--------------------------------

### Configure Link Attributes with ZMarkupParser (Swift)

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Shows how to configure and apply custom link text attributes for UITextView using ZHTMLParser. This includes setting foreground color and underline styles for anchor tags.

```swift
import ZMarkupParser

// Build parser with custom link style
let parser = ZHTMLParserBuilder.initWithDefault()
    .add(A_HTMLTagName(), withCustomStyle: MarkupStyle(
        foregroundColor: MarkupStyleColor(color: .systemBlue),
        underlineStyle: .single,
        underlineColor: MarkupStyleColor(color: .systemBlue)
    ))
    .build()

// HTML with links
let html = """
<p>Visit our <a href=\"https://example.com\">website</a> for more information.</p>
<p>Contact us at <a href=\"mailto:info@example.com\">info@example.com</a></p>
"""

// Apply to UITextView with link attributes
let textView = UITextView()
textView.isEditable = false
textView.isSelectable = true
textView.setHtmlString(html, with: parser)

// Access link attributes
print("Link attributes: \(textView.linkTextAttributes)")

// Manual access to parser's link attributes
let linkAttributes = parser.linkTextAttributes
print("Parser link attributes: \(linkAttributes)")
```

--------------------------------

### Pre-defined HTML Tag Style Attributes in Swift

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

This snippet shows the pre-defined style attributes available in ZMarkupParser for customizing HTML tag conversions to NSAttributedString attributes. These include color, background color, font size, font weight, line height, and word spacing. These are typically used when initializing or configuring the parser.

```swift
ColorHTMLTagStyleAttribute(), // color
BackgroundColorHTMLTagStyleAttribute(), // background-color
FontSizeHTMLTagStyleAttribute(), // font-size
FontWeightHTMLTagStyleAttribute(), // font-weight
LineHeightHTMLTagStyleAttribute(), // line-height
WordSpacingHTMLTagStyleAttribute() // word-spacing
```

--------------------------------

### Parsing HTML with Class and ID Attributes

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Enables mapping of CSS class names and IDs to specific MarkupStyle configurations for targeted styling of HTML elements.

```APIDOC
## Parsing HTML with Class and ID Attributes

### Description
Map CSS class names and IDs to specific MarkupStyle configurations for targeted styling.

### Method
Configuration and Rendering

### Endpoint
N/A

### Parameters
- **HTMLTagClassAttribute(className: "class-name")** (Class Attribute) - Defines styling for elements with a specific class.
- **HTMLTagIdAttribute(idName: "id-name")** (ID Attribute) - Defines styling for elements with a specific ID.
- **render** (Closure) - A closure returning the MarkupStyle for the given attribute.

### Request Example
```swift
import ZMarkupParser

// Configure parser with class and ID attributes
let parser = ZHTMLParserBuilder.initWithDefault()
    .add(HTMLTagClassAttribute(className: "text-red", render: {
        return MarkupStyle(foregroundColor: MarkupStyleColor(color: .red))
    }))
    .add(HTMLTagClassAttribute(className: "text-small", render: {
        return MarkupStyle(font: MarkupStyleFont(.systemFont(ofSize: 10)))
    }))
    .add(HTMLTagIdAttribute(idName: "header", render: {
        return MarkupStyle(font: MarkupStyleFont(.systemFont(ofSize: 24)))
    }))
    .build()

// HTML with class and id attributes
let html = """
<span id="header">Title Text</span>
<p>Normal paragraph</p>
<span class="text-red">Red text</span>
<span class="text-red text-small">Small red text with multiple classes</span>
"""
let result = parser.render(html)
```

### Response
#### Success Response (Rendering)
- **result** (NSAttributedString) - The attributed string with styles applied based on class and ID attributes.

#### Response Example
```swift
// NSAttributedString object with text styled according to specified classes and IDs
```
```

--------------------------------

### Customize List Styles with Swift

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Configures the appearance of ordered and unordered lists in ZMarkupParser by setting custom markers and indentation. This involves using ZHTMLParserBuilder to add custom styles for UL and OL tags, specifying text list style types and indentation. Requires importing ZMarkupParser.

```swift
import ZMarkupParser

// Customize list rendering
let parser = ZHTMLParserBuilder.initWithDefault()
    .add(UL_HTMLTagName(), withCustomStyle: MarkupStyle(
        paragraphStyle: MarkupStyleParagraphStyle(
            textListStyleType: .disc,
            textListHeadIndent: 8,
            textListIndent: 16
        )
    ))
    .add(OL_HTMLTagName(), withCustomStyle: MarkupStyle(
        paragraphStyle: MarkupStyleParagraphStyle(
            textListStyleType: .decimal,
            textListHeadIndent: 8,
            textListIndent: 16
        )
    ))
    .build()

// Render lists with custom styles
let html = """
<ul>
    <li>First unordered item</li>
    <li>Second unordered item</li>
</ul>
<ol>
    <li>First ordered item</li>
    <li>Second ordered item</li>
</ol>
"""
let result = parser.render(html)
```

--------------------------------

### Extend HTML Tag Style Attribute in Swift

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

Demonstrates how to define custom HTML style attributes using ExtendHTMLTagStyleAttribute when a pre-defined one is not available. It takes a style name and a closure to define how the new style attribute should be rendered based on an existing style and the new value.

```swift
ExtendHTMLTagStyleAttribute(styleName: "text-decoration", render: { fromStyle, value in
  var newStyle = fromStyle
  if value == "underline" {
    newStyle.underline = NSUnderlineStyle.single
  } else {
    // ...  
  }
  return newStyle
})
```

--------------------------------

### Decode HTML Entities with ZMarkupParser (Swift)

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Demonstrates how to decode HTML entities in strings using ZHTMLParser. It covers default automatic decoding, disabling it, and manual decoding for both regular strings and NSAttributedString.

```swift
import ZMarkupParser

let parser = ZHTMLParserBuilder.initWithDefault().build()

// HTML with entities - decoded by default
let html = "<p>Copyright &copy; 2024 &amp; Company&trade;</p>"
let decoded = parser.render(html) // Automatically decodes entities
print(decoded.string) // Output: "Copyright © 2024 & Company™"

// Disable automatic entity decoding
let rawHtml = parser.render(html, forceDecodeHTMLEntities: false)
print(rawHtml.string) // Output: "Copyright &copy; 2024 &amp; Company&trade;"

// Manually decode entities
let entityString = "Hello &lt;World&gt; &quot;Test&quot;"
let decodedString = parser.decodeHTMLEntities(entityString)
print(decodedString) // Output: "Hello <World> "Test""

// Decode entities in attributed string
let attributedWithEntities = NSAttributedString(string: "Test &amp; Data")
let decodedAttributed = parser.decodeHTMLEntities(attributedWithEntities)
print(decodedAttributed.string) // Output: "Test & Data"
```

--------------------------------

### Render HTML String to NSAttributedString in Swift

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

Shows how to use the `render` method of a configured ZMarkupParser instance to convert an HTML string into an NSAttributedString. It also explains how to optionally disable HTML entity decoding using the `forceDecodeHTMLEntities` parameter.

```swift
// Render with default HTML entity decoding
parser.render(htmlString) // NSAttributedString

// Render without HTML entity decoding
parser.render(htmlString, forceDecodeHTMLEntities: false)

// Or using a convenience method for UITextView/UILabel
textView.setHtmlString(htmlString)
label.setHtmlString(htmlString)
```

--------------------------------

### Control HTML Style with Policies in Swift

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Demonstrates two policies for ZMarkupParser: '.respectMarkupStyleFromHTMLStyleAttribute' where HTML inline styles override custom styles, and '.ignoreMarkupStyleFromHTMLStyleAttribute' where custom styles always take precedence. This allows fine-grained control over style application.

```swift
import ZMarkupParser

// Respect HTML style attributes (default behavior)
let respectParser = ZHTMLParserBuilder.initWithDefault()
    .set(policy: .respectMarkupStyleFromHTMLStyleAttribute)
    .add(P_HTMLTagName(), withCustomStyle: MarkupStyle(
        foregroundColor: MarkupStyleColor(color: .blue)
    ))
    .build()

// HTML inline styles override custom tag styles
let html = """
<p>Blue paragraph (custom style)</p>
<p style=\"color: red\">Red paragraph (inline style takes precedence)</p>
"""
let respectedResult = respectParser.render(html)

// Ignore HTML style attributes policy
let ignoreParser = ZHTMLParserBuilder.initWithDefault()
    .set(policy: .ignoreMarkupStyleFromHTMLStyleAttribute)
    .add(P_HTMLTagName(), withCustomStyle: MarkupStyle(
        foregroundColor: MarkupStyleColor(color: .blue)
    ))
    .build()

// Custom tag styles always apply, inline styles ignored
let ignoredResult = ignoreParser.render(html)
// Both paragraphs will be blue
```

--------------------------------

### Add Custom HTML Style Attributes with Swift

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Extends ZMarkupParser to handle custom inline style attributes in HTML. This allows for defining specific rendering logic for attributes like 'text-decoration' and 'font-style' beyond the default set. It requires importing ZMarkupParser and using ZHTMLParserBuilder.

```swift
import ZMarkupParser

// Add custom style attribute handler
let parser = ZHTMLParserBuilder.initWithDefault()
    .add(ExtendHTMLTagStyleAttribute(styleName: "text-decoration", render: { fromStyle, value in
        var newStyle = fromStyle
        if value == "underline" {
            newStyle.underlineStyle = .single
        } else if value == "line-through" {
            newStyle.strikethroughStyle = .single
        }
        return newStyle
    }))
    .add(ExtendHTMLTagStyleAttribute(styleName: "font-style", render: { fromStyle, value in
        var newStyle = fromStyle
        if value == "italic" {
            newStyle.obliqueness = 0.2
        }
        return newStyle
    }))
    .build()

// HTML with custom style attributes
let html = """
<p style="text-decoration: underline">Underlined paragraph</p>
<span style="font-style: italic; color: blue">Italic blue text</span>
<p style="text-decoration: line-through">Strikethrough text</p>
"""
let attributedString = parser.render(html)
```

--------------------------------

### Customize List Item Tag (ul/ol) in Swift

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

This snippet demonstrates how to customize list item tags like `<ul>` and `<ol>` within ZMarkupParser. It uses the `add` method with `OL_HTMLTagName()` and a custom `MarkupStyle` to define list appearance, specifically setting text list style type and indents.

```swift
let parser = ZHTMLParserBuilder.initWithDefault().add(OL_HTMLTagName(), withCustomStyle: MarkupStyle(paragraphStyle: MarkupStyleParagraphStyle(textListStyleType: .circle, textListHeadIndent: 4, textListIndent: 8))).build()
```

--------------------------------

### Strip HTML Tags to Plain Text with Swift

Source: https://context7.com/zhgchgli/zmarkupparser/llms.txt

Removes all HTML markup from a given string, returning only the plain text content. ZMarkupParser provides both synchronous and asynchronous methods for stripping tags, as well as a method to strip NSAttributedString input. Requires importing ZMarkupParser.

```swift
import ZMarkupParser

let parser = ZHTMLParserBuilder.initWithDefault().build()

// Strip HTML tags synchronously
let html = "<p>Hello <b>World</b>! <a href='#'>Click here</a></p>"
let plainText = parser.stripper(html)
print(plainText) // Output: "Hello World! Click here"

// Strip HTML tags asynchronously
parser.stripper(html) { plainText in
    print("Stripped text: \(plainText)")
}

// Strip to NSAttributedString (preserves structure without HTML)
let strippedAttributed = parser.stripper(NSAttributedString(string: html))
print(strippedAttributed.string)
```

--------------------------------

### Strip HTML Tags from String in Swift

Source: https://github.com/zhgchgli/zmarkupparser/blob/main/README.md

This snippet demonstrates how to use the `stripper` method of a ZMarkupParser instance. This method removes all HTML tags from a given string, returning the plain text content as an NSAttributedString, without applying any styling.

```swift
parser.stripper(htmlString) // NSAttributedString
```
Tokens:
Raw