Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ZhgChgLi/ZMarkupParser
ZMarkupParser is a pure-Swift library that helps you convert HTML strings into NSAttributedString with customized styles and tags.
https://github.com/ZhgChgLi/ZMarkupParser
cocoapods html html-converter html-parser html-renderer ios nsattributedstring swift swift-package textfield uikit uilabel uitextview
Last synced: 3 months ago
JSON representation
ZMarkupParser is a pure-Swift library that helps you convert HTML strings into NSAttributedString with customized styles and tags.
- Host: GitHub
- URL: https://github.com/ZhgChgLi/ZMarkupParser
- Owner: ZhgChgLi
- License: mit
- Created: 2023-02-17T08:41:37.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-29T01:13:19.000Z (5 months ago)
- Last Synced: 2024-05-29T02:46:04.774Z (5 months ago)
- Topics: cocoapods, html, html-converter, html-parser, html-renderer, ios, nsattributedstring, swift, swift-package, textfield, uikit, uilabel, uitextview
- Language: Swift
- Homepage: https://zhgchg.li
- Size: 35.1 MB
- Stars: 274
- Watchers: 8
- Forks: 22
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-ios - ZMarkupParser - Convert HTML strings into NSAttributedString with customized styles and tags. (Parsing / XML & HTML)
- awesome-ios-star - ZMarkupParser - Convert HTML strings into NSAttributedString with customized styles and tags. (Parsing / XML & HTML)
README
ZMarkupParser is a pure-Swift library that helps you convert HTML strings into NSAttributedString with customized styles and tags.
## Technical Details:
- \[Chinese\] [Development Notes](https://medium.com/zrealm-ios-dev/zmarkupparser-html-string-%E8%BD%89%E6%8F%9B-nsattributedstring-%E5%B7%A5%E5%85%B7-a5643de271e4)
- \[English\] [Development Notes (translated using ChatGPT)](https://en.zhgchg.li/posts/2724f02f6e7/)
- \[English\] [Brief Introduction to Operation](https://github.com/ZhgChgLi/ZMarkupParser/blob/main/technicalDetail.md)
## Features
- [x] Parse HTML strings using pure-Swift and regular expressions.
- [x] Automatically correct invalid HTML strings, including mixed or isolated tags (e.g., `LinkLinkBoldBold
` -> `LinkLinkBoldBold
`).
- [x] More compatible with HTML tags than a parser that is based on XMLParser.
- [x] Customizable HTML tag parser with painless extended tag support and the ability to customize tag styles.
- [x] Support for HTML rendering, stripping, and selecting.
- [x] Support for `
- ` list views, `` table view, `
-
OL_HTMLTagName(), //
P_HTMLTagName(), //
SPAN_HTMLTagName(), //
STRONG_HTMLTagName(), //
U_HTMLTagName(), //
UL_HTMLTagName(), //
DEL_HTMLTagName(), //
IMG_HTMLTagName(handler: ZNSTextAttachmentHandler), //and image downloader
TR_HTMLTagName(), //
TD_HTMLTagName(), //
TH_HTMLTagName(), //
...and more
```### MarkupStyle/MarkupStyleColor/MarkupStyleParagraphStyle
The MarkupStyle wrapper contains various properties that are used to define the attributes of an NSAttributedString. These properties includes:
```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
...
```For example, you can initialize or define a MarkupStyle object with the properties you want, such as setting the font size to 13 and the background color to aquamarine:
```swift
MarkupStyle(font: MarkupStyleFont(size: 13), backgroundColor: MarkupStyleColor(name: .aquamarine))
```### HTMLTagStyleAttribute
These are pre-defined style attributes that can be used in the conversion of HTML tags to NSAttributedString attributes. Each style attribute has a corresponding class that defines its behavior and how it should be applied to the NSAttributedString.
```swift
ColorHTMLTagStyleAttribute(), // color
BackgroundColorHTMLTagStyleAttribute(), // background-color
FontSizeHTMLTagStyleAttribute(), // font-size
FontWeightHTMLTagStyleAttribute(), // font-weight
LineHeightHTMLTagStyleAttribute(), // line-height
WordSpacingHTMLTagStyleAttribute(), // word-spacing
```If there is a style attribute that is not defined, the ExtendHTMLTagStyleAttribute class can be used to define it. This class takes in a style name and a closure that takes in an existing style and the value of the new style attribute and returns a new style with the new attribute applied.
For exmaple: `style="text-decoration"`
```swift
ExtendHTMLTagStyleAttribute(styleName: "text-decoration", render: { fromStyle, value in
var newStyle = fromStyle
if value == "underline" {
newStyle.underline = NSUnderlineStyle.single
} else {
// ...
}
return newStyle
})
```## Usage
```swift
import ZMarkupParser
```### Builder Pattern to Build Parser
```swift
let parser = ZHTMLParserBuilder.initWithDefault().set(rootStyle: MarkupStyle(font: MarkupStyleFont(size: 13)).build()
```The code initializes a new ZHTMLParserBuilder object with default settings using the `initWithDefault()` method. This method adds all pre-defined HTML tag names and style attributes, and sets the tag's default MarkupStyle to render.
Then, the `set(rootStyle: MarkupStyle)` method is called to specify the default root style to render. This root style will be applied to the entire attributed string that is generated by the parser.
Finally, the `build()` method is called at the end to generate the parser object.
#### Customized List Item Tag (`ul/ol`)
```
let parser = ZHTMLParserBuilder.initWithDefault().add(OL_HTMLTagName(), withCustomStyle: MarkupStyle(paragraphStyle: MarkupStyleParagraphStyle(textListStyleType: .circle, textListHeadIndent: 4, textListIndent: 8))).build()
```
#### Customized Tag Style/Extend Tag Name
These code snippets demonstrate how to customize the style of a tag or extend the tag name:
To customize the style of a tag, you can use the add method of the ZHTMLParserBuilder class and provide an instance of HTMLTagName and a MarkupStyle object as parameters. For example, the following code snippet will use a custom markup style to render the tag:
```swift
let parser = ZHTMLParserBuilder.initWithDefault().add(B_HTMLTagName(), withCustomStyle: MarkupStyle(font: MarkupStyleFont(size: 18, weight: .style(.semibold)))).build()
```To extend the tag name and customize its style, you can use the ExtendTagName class and the add method of the ZHTMLParserBuilder class. For example, the following code snippet will extend the tag name to and use a custom markup style to render it:
```swift
let parser = ZHTMLParserBuilder.initWithDefault().add(ExtendTagName("zhgchgli"), withCustomStyle: MarkupStyle(backgroundColor: MarkupStyleColor(name: .aquamarine))).build()
```#### Support for Class/ID Style Mapping and Parsing
The class HTML attribute can use the HTMLTagClassAttribute to define classNames with pre-defined styles.
HTML allows specifying multiple `class` attributes separated by spaces, but the `id` attribute can only be assigned a single value per HTML tag.
e.g.:
```
heyhey Teste de texto text small heyheyheyhey
``````
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()
```### Render HTML String
```swift
parser.render(htmlString) // NSAttributedStringBy default, ZMarkupParser will decode HTML entities using the [HTMLString](https://github.com/alexisakers/HTMLString) library.
If you wish to keep the raw data clean, you can disable this feature by using the following syntax: `parser.render(htmlString, forceDecodeHTMLEntities: false)` or `setHtmlString(attributedString, with: parser, forceDecodeHTMLEntities: false)`.
// work with UITextView
textView.setHtmlString(htmlString)// work with UILabel
label.setHtmlString(htmlString)
```### Stripper HTML String
```swift
parser.stripper(htmlString) // NSAttributedString
```### Selector HTML String
```swift
let selector = parser.selector(htmlString) // HTMLSelector e.g. input: TestLink
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```
### Selector+Render HTML String
```swift
let selector = parser.selector(htmlString) // HTMLSelector e.g. input: TestLink
parser.render(selector.first("a")?.first("b"))
```### With Async
```swift
parser.render(String) { _ in }...
parser.stripper(String) { _ in }...
parser.selector(String) { _ in }...
```
If you want to render huge html string, please use async instead.## Things to know
- To change the style of links in UITextView, you need to set the linkTextAttributes property to an NSAttributedString.Key value that includes the desired style properties.
- If you're using a UILabel to render attributed strings, note that you can't change the color of .link text using the NSAttributedString.Key.foregroundColor attribute.
- The ZHTMLParser library is intended for rendering partial HTML content, and may not be suitable for rendering very large or complex HTML documents. For these use cases, it's better to use a web view to render the HTML content.## Sponsor
- If this project has been helpful to you, I would greatly appreciate your support.
- If you're willing, you can consider buying me a cup of coffee as a token of encouragement.
- Your brand will be displayed here, and the colors will be implemented in [MarkupStyleSponsorColor](https://github.com/ZhgChgLi/ZMarkupParser/blob/main/Sources/ZMarkupParser/Core/MarkupStyle/MarkupStyleSponsorColor.swift).
- You can initialize the color directly using `MarkupStyleColor(sponsor: .pinkoi(.navy))`.## Who is using
[](https://en.pinkoi.com)[Pinkoi.com](https://en.pinkoi.com) is Asia's leading online marketplace for original design goods, digital creations, and workshop experiences.
---
- If your project/product is using ZMarkupParser, feel free to create a PR (Pull Request) here (the "Who is using" section in the Readme file). :)
- Please also add your brand and brand colors to [MarkupStyleVendorColor.swift](https://github.com/ZhgChgLi/ZMarkupParser/blob/main/Sources/ZMarkupParser/Core/MarkupStyle/MarkupStyleVendorColor.swift).
- You can initialize the color directly using `MarkupStyleVendorColor(vendor: .pinkoi(.navy))`.## About
- [ZhgChg.Li](https://zhgchg.li/)
- [ZhgChgLi's Medium](https://blog.zhgchg.li/)## Other works
### Swift Libraries
- [ZMarkupParser](https://github.com/ZhgChgLi/ZMarkupParser) is a pure-Swift library that helps you to convert HTML strings to NSAttributedString with customized style and tags.
- [ZPlayerCacher](https://github.com/ZhgChgLi/ZPlayerCacher) is a lightweight implementation of the AVAssetResourceLoaderDelegate protocol that enables AVPlayerItem to support caching streaming files.
- [ZNSTextAttachment](https://github.com/ZhgChgLi/ZNSTextAttachment) enables NSTextAttachment to download images from remote URLs, support both UITextView and UILabel.### Integration Tools
- [ZReviewTender](https://github.com/ZhgChgLi/ZReviewTender) is a tool for fetching app reviews from the App Store and Google Play Console and integrating them into your workflow.
- [ZMediumToMarkdown](https://github.com/ZhgChgLi/ZMediumToMarkdown) is a powerful tool that allows you to effortlessly download and convert your Medium posts to Markdown format.# Donate
[](https://www.buymeacoffee.com/zhgchgli)
If you find this library helpful, please consider starring the repo or recommending it to your friends.
Feel free to open an issue or submit a fix/contribution via pull request. :)
` horizontal lines, and more.
- [x] Support for parsing and setting styles from HTML tag attributes such as style="color:red".
- [x] Support for parsing HTML color names into UIColor/NSColor.
- [x] Better performance compared to `NSAttributedString.DocumentType.html`.
- [x] Fully test cases and test coverage.
## Try it!
To run the ZMarkupParser demo, download the repository and open ZMarkupParser.xcworkspace. Then, select the ZMarkupParser-Demo target and run it to start exploring the library. Enjoy!
### Performance Benchmark
[](https://quickchart.io/chart-maker/view/zm-73887470-e667-4ca3-8df0-fe3563832b0b)
(2022/M2/24GB Memory/macOS 13.2/XCode 14.1)
Note that rendering an NSAttributedString with the DocumentType.html option can cause a crash when the length of the HTML string exceeds 54,600+ characters. To avoid this issue, consider using ZMarkupParser instead.
The chart above shows the elapsed time (in seconds) to render different HTML string lengths (x). As you can see, ZMarkupParser performs better than NSAttributedString.DocumentType.html, especially for larger HTML strings.
## Installation
### Swift Package Manager
- File > Swift Packages > Add Package Dependency
- Add `https://github.com/ZhgChgLi/ZMarkupParser.git`
- Select "Up to Next Major" with "1.10.0"
or
```swift
...
dependencies: [
.package(url: "https://github.com/ZhgChgLi/ZMarkupParser.git", from: "1.10.0"),
]
...
.target(
...
dependencies: [
"ZMarkupParser",
],
...
)
```
### CocoaPods
```ruby
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '12.0'
use_frameworks!
target 'MyApp' do
pod 'ZMarkupParser', '~> 1.10.0'
end
```
## How it works? (explain with Pseudocode)
1. Input html string: `LinkLinkBoldBold`
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.
Result:
```
Link{
NSColor = "UIExtendedSRGBColorSpace 0 0.478431 1 1";
NSFont = " font-family: \".SFUI-Regular\"; font-weight: normal; font-style: normal; font-size: 13.00pt";
NSUnderline = 1;
}LinkBold{
NSColor = "UIExtendedSRGBColorSpace 0 0.478431 1 1";
NSFont = " font-family: \".SFUI-Semibold\"; font-weight: bold; font-style: normal; font-size: 18.00pt";
NSUnderline = 1;
}Bold{
NSFont = " font-family: \".SFUI-Semibold\"; font-weight: bold; font-style: normal; font-size: 18.00pt";
}
```
### Example
## Introduction
### HTMLTagName
ZMarkupParser provides a set of pre-defined tag names that map to abstract markup classes, such as A_HTMLTagName() for , B_HTMLTagName() for , and so on. This mapping is used to create instances of the corresponding markup classes during the parsing process.
In addition, if there is a tag that is not defined or you want to customize your own tag, you can use the `ExtendTagName(tagName: String)` method to create a custom tag name and map it to an abstract markup class of your own design.
```swift
A_HTMLTagName(), //
B_HTMLTagName(), //
BR_HTMLTagName(), //
and also
DIV_HTMLTagName(), //
HR_HTMLTagName(), //
I_HTMLTagName(), //
LI_HTMLTagName(), //