Skip to content

Commit 2a3873f

Browse files
koukou
committed
Add API reference of xmlua.HTML.parse
1 parent 22bf3e7 commit 2a3873f

File tree

1 file changed

+92
-0
lines changed

1 file changed

+92
-0
lines changed

‎README.md

+92
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,100 @@ The user-friendly API is implemented top of low-level libxml2 API.
3030

3131
## API
3232

33+
### Internal modules
34+
35+
The following modules aren't exported into public API but you can use
36+
them via public classes such as `xmlua.HTML` and `xmlua.XML`:
37+
38+
* `xmlua.Document`
39+
40+
* `xmlua.Savable`
41+
42+
* `xmlua.Searchable`
43+
44+
#### `xmlua.Document`
45+
46+
It provides common features for HTML document and XML document.
47+
48+
##### `root() -> xmlua.Element`
49+
50+
It returns the root element.
51+
52+
#### `xmlua.Savable`
53+
3354
...
3455

56+
#### `xmlua.Searchable`
57+
58+
..
59+
60+
### public Classes
61+
62+
#### `xmlua.HTML`
63+
64+
It has methods of the following modules:
65+
66+
* `xmlua.Document`
67+
68+
* `xmlua.Savable`
69+
70+
* `xmlua.Searchable`
71+
72+
It means that you can use methods in the modules. For example:
73+
74+
```lua
75+
-- Call `xmlua.Document.root` method
76+
html:root() -- -> Root element
77+
```
78+
79+
##### `xmlua.HTML.parse(html) -> xmlua.HTML`
80+
81+
`html`: HTML string to be parsed.
82+
83+
It parses the given HTML and returns `xmlua.HTML` object.
84+
85+
The encoding of HTML is guessed.
86+
87+
If HTML parsing is failed, it raises an error. The error has the
88+
following structure:
89+
90+
```lua
91+
{
92+
message = "Error details",
93+
}
94+
```
95+
96+
Here is an example to parse HTML:
97+
98+
```lua
99+
local xmlua = require("xmlua")
100+
101+
-- HTML to be parsed.
102+
-- You may want to use HTML in a file. If you want to use HTML in a file,
103+
-- you need to read HTML content from a file by yourself.
104+
local html = [[
105+
<html>
106+
<body>
107+
<p>Hello</p>
108+
</body>
109+
</html>
110+
]]
111+
112+
-- Parses HTML
113+
local success, document = pcall(xmlua.HTML.parse, html)
114+
if not success then
115+
local err = document
116+
print("Failed to parse HTML: " .. err.message)
117+
os.exit(1)
118+
end
119+
120+
-- Gets the root element
121+
local root = document:root() -- --> <html> element as xmlua.Element
122+
123+
-- Prints root element name
124+
print(root:name()) -- -> html
125+
```
126+
35127
## Authors
36128

37129
* Horimoto Yasuhiro \<[email protected]\>

0 commit comments

Comments
 (0)