docs/sxml.md — sigil-sxml

1# SXML

2

3> SXML representation and HTML/XML serialization.

4

5```scheme

6(import (sigil sxml))

7```

8

9## SXML Format

SXML is an S-expression representation of XML/HTML documents. Elements are lists starting with a tag symbol, with optional attributes in an `(@)` form.

13| Form | Description |

14|------|-------------|

15| `(tag content ...)` | Element with content |

16| `(tag (@ (attr val) ...) content ...)` | Element with attributes |

17| `"text"` | Text content |

18| `(*raw* "html")` | Raw HTML (no escaping) |

19| `(document content ...)` | Document wrapper (stripped on output) |

21```scheme

22;; Simple element

23'(p "Hello, world!")

25;; Element with attributes

26'(div (@ (class "main") (id "content")) "Hello")

28;; Nested elements

29'(ul (li "One") (li "Two") (li "Three"))

30```

32## sxml->html

Convert an SXML tree to an HTML string. Void elements like `<br>` and `<img>` are output without a closing slash. Content inside `<style>` and `<script>` tags is not escaped.

36```scheme

37(sxml->html '(p "Hello"))

38; => "<p>Hello</p>"

40(sxml->html '(div (@ (class "main")) (p "text")))

41; => "<div class=\"main\"><p>text</p></div>"

43;; Void elements use HTML style (no closing slash)

44(sxml->html '(br))

45; => "<br>"

47(sxml->html '(img (@ (src "photo.jpg"))))

48; => "<img src=\"photo.jpg\">"

50;; Document wrapper is stripped

51(sxml->html '(document (p "From markdown")))

52; => "<p>From markdown</p>"

53```

55## sxml->xml

57Convert an SXML tree to an XML string. Void elements use self-closing syntax with ` />`.

59```scheme

60(sxml->xml '(item (@ (id "1")) "Content"))

61; => "<item id=\"1\">Content</item>"

63;; Void elements use XML style

64(sxml->xml '(img (@ (src "photo.jpg"))))

65; => "<img src=\"photo.jpg\" />"

66```

68## xml-escape

70Escape special XML characters (`&`, `<`, `>`, `"`, `'`) in text.

72```scheme

73(xml-escape "Tom & Jerry") ; => "Tom & Jerry"

74(xml-escape "<script>") ; => "<script>"

75(xml-escape "She said \"hi\"") ; => "She said "hi""

76```

78## Element Inspection

80Examine the structure of SXML elements.

82```scheme

83(sxml-element? '(div "hello")) ; => #t

84(sxml-element? "text") ; => #f

86(sxml-tag '(div (@ (class "box")) "content"))

87; => div

89(sxml-attributes '(div (@ (id "main") (class "box")) "text"))

90; => ((id "main") (class "box"))

92(sxml-attributes '(p "text"))

93; => ()

95(sxml-content '(div (@ (id "main")) "hello" " " "world"))

96; => ("hello" " " "world")

97```

99## Attribute Utilities

101Look up or modify attributes on SXML elements.

103```scheme

104;; Get attribute value

105(sxml-attr-ref '(div (@ (id "main"))) 'id) ; => "main"

106(sxml-attr-ref '(div (@ (id "main"))) 'class) ; => #f

108;; Set attribute (returns new element)

109(sxml-attr-set '(div "text") 'id "main")

110; => (div (@ (id "main")) "text")

112(sxml-attr-set '(div (@ (id "old"))) 'id "new")

113; => (div (@ (id "new")))

114```

116## Common Patterns

118### Building a Page

120```scheme

121(import (sigil sxml))

123(define (page title body)

124 `(html

125 (head (title ,title))

126 (body ,@body)))

128(sxml->html

129 (page "My Site"

130 (list

131 '(h1 "Welcome")

132 '(p "Hello, world!"))))

133```

135### Raw HTML Content

137Use `*raw*` to embed pre-rendered HTML without escaping:

139```scheme

140(sxml->html

141 `(div (@ (class "content"))

142 (*raw* "<strong>Already formatted</strong>")))

143; => "<div class=\"content\"><strong>Already formatted</strong></div>"

144```

146### Inline Styles

148```scheme

149(sxml->html

150 `(style (*raw* ,(css->string

151 (css ".container" (max-width "800px"))))))

152```