0
# XML Entities
1

2
Groovy XML provides predefined XML and HTML entity constants through the Entity class, making it easy to include special characters in XML documents without manual escaping.
3

4
## Entity Class
5

6
Core class providing predefined XML and HTML entity constants that implement the Buildable interface for use in builders.
7

8
```groovy { .api }
9
class Entity implements Buildable {
10
    // Constructors
11
    Entity(String name)
12
    Entity(int name)
13
    
14
    // Core method
15
    void build(GroovyObject builder)
16
}
17
```
18

19
## Predefined Entities
20

21
### XML Core Entities
22

23
Essential XML entities for special characters:
24

25
```groovy { .api }
26
// Core XML entities
27
public static final Entity lt      // less-than sign (<), U+003C
28
public static final Entity gt      // greater-than sign (>), U+003E  
29
public static final Entity amp     // ampersand (&), U+0026
30
public static final Entity apos    // apostrophe ('), U+0027
31
public static final Entity quot    // quotation mark ("), U+0022
32
```
33

34
### ISO Latin 1 Character Entities
35

36
Complete set of ISO Latin 1 entities for extended characters:
37

38
```groovy { .api }
39
// Common punctuation and symbols
40
public static final Entity nbsp    // no-break space, U+00A0
41
public static final Entity iexcl   // inverted exclamation mark (¡), U+00A1
42
public static final Entity cent    // cent sign (¢), U+00A2
43
public static final Entity pound   // pound sign (£), U+00A3
44
public static final Entity curren  // currency sign (¤), U+00A4
45
public static final Entity yen     // yen sign (¥), U+00A5
46
public static final Entity copy    // copyright sign (©), U+00A9
47
public static final Entity reg     // registered sign (®), U+00AE
48

49
// Mathematical symbols
50
public static final Entity deg     // degree sign (°), U+00B0
51
public static final Entity plusmn  // plus-minus sign (±), U+00B1
52
public static final Entity sup2    // superscript two (²), U+00B2
53
public static final Entity sup3    // superscript three (³), U+00B3
54
public static final Entity frac14  // vulgar fraction one quarter (¼), U+00BC
55
public static final Entity frac12  // vulgar fraction one half (½), U+00BD
56
public static final Entity frac34  // vulgar fraction three quarters (¾), U+00BE
57
public static final Entity times   // multiplication sign (×), U+00D7
58
public static final Entity divide  // division sign (÷), U+00F7
59

60
// Accented characters (uppercase)
61
public static final Entity Agrave // latin capital A with grave (À), U+00C0
62
public static final Entity Aacute // latin capital A with acute (Á), U+00C1
63
public static final Entity Acirc  // latin capital A with circumflex (Â), U+00C2
64
public static final Entity Atilde // latin capital A with tilde (Ã), U+00C3
65
public static final Entity Auml   // latin capital A with diaeresis (Ä), U+00C4
66
public static final Entity Aring  // latin capital A with ring above (Å), U+00C5
67
// ... (all uppercase accented characters)
68

69
// Accented characters (lowercase)  
70
public static final Entity agrave // latin small a with grave (à), U+00E0
71
public static final Entity aacute // latin small a with acute (á), U+00E1
72
public static final Entity acirc  // latin small a with circumflex (â), U+00E2
73
public static final Entity atilde // latin small a with tilde (ã), U+00E3
74
public static final Entity auml   // latin small a with diaeresis (ä), U+00E4
75
public static final Entity aring  // latin small a with ring above (å), U+00E5
76
// ... (all lowercase accented characters)
77
```
78

79
### Special Character Entities
80

81
Extended character set for typography and special symbols:
82

83
```groovy { .api }
84
// Extended Latin
85
public static final Entity OElig   // latin capital ligature OE (Œ), U+0152
86
public static final Entity oelig   // latin small ligature oe (œ), U+0153
87
public static final Entity Scaron  // latin capital letter S with caron (Š), U+0160
88
public static final Entity scaron  // latin small letter s with caron (š), U+0161
89
public static final Entity Yuml    // latin capital letter Y with diaeresis (Ÿ), U+0178
90

91
// Spacing modifiers
92
public static final Entity circ    // modifier letter circumflex accent (ˆ), U+02C6
93
public static final Entity tilde   // small tilde (˜), U+02DC
94

95
// Punctuation and typography
96
public static final Entity ensp    // en space, U+2002
97
public static final Entity emsp    // em space, U+2003
98
public static final Entity thinsp  // thin space, U+2009
99
public static final Entity ndash   // en dash (–), U+2013
100
public static final Entity mdash   // em dash (—), U+2014
101
public static final Entity lsquo   // left single quotation mark ('), U+2018
102
public static final Entity rsquo   // right single quotation mark ('), U+2019
103
public static final Entity ldquo   // left double quotation mark ("), U+201C
104
public static final Entity rdquo   // right double quotation mark ("), U+201D
105
public static final Entity dagger  // dagger (†), U+2020
106
public static final Entity Dagger  // double dagger (‡), U+2021
107
public static final Entity permil  // per mille sign (‰), U+2030
108
public static final Entity lsaquo  // single left-pointing angle quotation mark (‹), U+2039
109
public static final Entity rsaquo  // single right-pointing angle quotation mark (›), U+203A
110
public static final Entity euro    // euro sign (€), U+20AC
111

112
// Control characters
113
public static final Entity zwnj    // zero width non-joiner, U+200C
114
public static final Entity zwj     // zero width joiner, U+200D
115
public static final Entity lrm     // left-to-right mark, U+200E
116
public static final Entity rlm     // right-to-left mark, U+200F
117
```
118

119
## Usage with Builders
120

121
### MarkupBuilder Integration
122

123
```groovy
124
import static groovy.xml.Entity.*
125

126
def writer = new StringWriter()
127
def xml = new MarkupBuilder(writer)
128

129
xml.document {
130
    title("Caf${eacute} Menu")  // Café Menu
131
    
132
    prices {
133
        item(name: "Coffee") {
134
            price("${dollar}3.50")  // Using entity in text
135
            note("Includes ${copy} trademark beans")  // ©
136
        }
137
        
138
        item(name: "Caf${eacute} au Lait") {
139
            price("${dollar}4.25")
140
            discount("10${percent} off")  // 10% off
141
        }
142
    }
143
    
144
    footer {
145
        copyright("${copy} 2023 Caf${eacute} Corp. All rights reserved.")
146
        legal("Prices subject to change ${plusmn} local taxes")
147
    }
148
}
149

150
println writer.toString()
151
```
152

153
### StreamingMarkupBuilder Integration
154

155
```groovy
156
import static groovy.xml.Entity.*
157

158
def smb = new StreamingMarkupBuilder()
159
smb.encoding = 'UTF-8'
160

161
def content = smb.bind {
162
    document {
163
        header {
164
            title("Mathematics ${amp} Science")
165
            subtitle("Formulas ${amp} Equations")
166
        }
167
        
168
        formulas {
169
            formula(type: "area") {
170
                description("Circle area: ${pi}r${sup2}")
171
                example("For r=5: A ${approx} 78.54")
172
            }
173
            
174
            formula(type: "temperature") {
175
                description("Water freezes at 32${deg}F (0${deg}C)")
176
                conversion("${deg}F = (${deg}C ${times} 9${divide}5) + 32")
177
            }
178
            
179
            formula(type: "fraction") {
180
                description("Common fractions:")
181
                examples {
182
                    mkp.yield("${frac14} = 0.25")
183
                    br()
184
                    mkp.yield("${frac12} = 0.5") 
185
                    br()
186
                    mkp.yield("${frac34} = 0.75")
187
                }
188
            }
189
        }
190
    }
191
}
192

193
content.writeTo(new FileWriter('math-formulas.xml'))
194
```
195

196
### Custom Entity Creation
197

198
```groovy
199
// Create custom entities
200
def trademark = new Entity("trade")  // ™
201
def registered = new Entity("reg")   // ®
202
def checkmark = new Entity(10003)    // ✓ using Unicode code point
203

204
def xml = new MarkupBuilder(writer)
205
xml.products {
206
    product(name: "Widget Pro") {
207
        branding {
208
            mkp.yield("Widget Pro")
209
            trademark.build(xml)  // Manually build entity
210
        }
211
        
212
        certification {
213
            mkp.yield("ISO 9001 Certified")
214
            checkmark.build(xml)
215
        }
216
        
217
        legal {
218
            mkp.yield("Widget")
219
            registered.build(xml)
220
            mkp.yield(" is a registered trademark")
221
        }
222
    }
223
}
224
```
225

226
### International Character Support
227

228
```groovy
229
import static groovy.xml.Entity.*
230

231
def createInternationalMenu = {
232
    def xml = new MarkupBuilder(writer)
233
    
234
    xml.menu {
235
        section(cuisine: "French") {
236
            item("Caf${eacute} au lait")      // Café au lait
237
            item("Cr${egrave}me br${ucirc}l${eacute}e")  // Crème brûlée  
238
            item("Ratatouille ni${ccedil}oise")  // Ratatouille niçoise
239
        }
240
        
241
        section(cuisine: "German") {
242
            item("Sch${auml}ferhund")         // Schäferhund
243
            item("M${uuml}nchener Wei${szlig}bier")  // Münchener Weißbier
244
            item("${Auml}pfel mit Sahne")     // Äpfel mit Sahne
245
        }
246
        
247
        section(cuisine: "Spanish") {
248
            item("Ni${ntilde}o especial")     // Niño especial
249
            item("Jalape${ntilde}o")          // Jalapeño
250
            item("A${ntilde}ejo tequila")     // Añejo tequila
251
        }
252
        
253
        section(cuisine: "Scandinavian") {
254
            item("K${oslash}benhavn")         // København
255
            item("Sm${oslash}rrebr${oslash}d")  // Smørrebrød
256
        }
257
    }
258
}
259
```
260

261
### Typography and Publishing
262

263
```groovy
264
import static groovy.xml.Entity.*
265

266
def createTypographicDocument = {
267
    def xml = new MarkupBuilder(writer)
268
    
269
    xml.article {
270
        title("Typography ${amp} Design")
271
        
272
        paragraph {
273
            mkp.yield("The ${ldquo}quick brown fox${rdquo} jumps over the lazy dog.")
274
            mkp.yield("This sentence contains ${mdash} em dash, ${ndash} en dash, and ${hellip} ellipsis.")
275
        }
276
        
277
        quote {
278
            mkp.yield("${ldquo}Design is not just what it looks like ${mdash} ")
279
            mkp.yield("design is how it works.${rdquo}")
280
            attribution("${mdash} Steve Jobs")
281
        }
282
        
283
        technical {
284
            formula("E = mc${sup2}")
285
            temperature("Water boils at 100${deg}C (212${deg}F)")
286
            fraction("${frac12} + ${frac14} = ${frac34}")
287
            percentage("Sales increased by 15${permil}")
288
        }
289
        
290
        legal {
291
            copyright("${copy} 2023 Design Corp.")
292
            trademark("DesignTool${trade}")
293
            registered("StyleGuide${reg}")
294
        }
295
    }
296
}
297
```
298

299
### Entity Reference Table
300

301
For quick reference, here are the most commonly used entities:
302

303
| Entity | Symbol | Description | Unicode |
304
|--------|--------|-------------|---------|
305
| `lt` | < | Less than | U+003C |
306
| `gt` | > | Greater than | U+003E |
307
| `amp` | & | Ampersand | U+0026 |
308
| `quot` | " | Quotation mark | U+0022 |
309
| `apos` | ' | Apostrophe | U+0027 |
310
| `nbsp` |   | Non-breaking space | U+00A0 |
311
| `copy` | © | Copyright | U+00A9 |
312
| `reg` | ® | Registered | U+00AE |
313
| `trade` | ™ | Trademark | U+2122 |
314
| `deg` | ° | Degree | U+00B0 |
315
| `plusmn` | ± | Plus-minus | U+00B1 |
316
| `times` | × | Multiplication | U+00D7 |
317
| `divide` | ÷ | Division | U+00F7 |
318
| `frac12` | ½ | One half | U+00BD |
319
| `euro` | € | Euro | U+20AC |
320
| `mdash` | — | Em dash | U+2014 |
321
| `ndash` | – | En dash | U+2013 |
322
| `ldquo` | " | Left double quote | U+201C |
323
| `rdquo` | " | Right double quote | U+201D |
324
325
### Performance Notes
326

327
```groovy
328
// Entities are static final constants - very efficient
329
import static groovy.xml.Entity.*
330

331
// Good: Direct entity usage
332
xml.text("Price: ${pound}10.99")
333

334
// Avoid: Creating new entities repeatedly  
335
xml.text("Price: ${new Entity('pound')}10.99")  // Less efficient
336

337
// For high-performance scenarios, consider pre-building entity strings
338
def currencySymbols = [
339
    USD: dollar.toString(),
340
    GBP: pound.toString(), 
341
    EUR: euro.toString(),
342
    YEN: yen.toString()
343
]
344

345
xml.prices {
346
    currencySymbols.each { code, symbol ->
347
        currency(code: code, symbol: symbol)
348
    }
349
}
350
```