0
# Pretty String Generation
1

2
The @ToPrettyString annotation generates human-readable string representations with structured formatting, making complex objects easy to read and debug.
3

4
## Basic Pretty String
5

6
```java { .api }
7
@AutoValue
8
public abstract class Person {
9
  public abstract String name();
10
  public abstract int age();
11
  public abstract List<String> hobbies();
12
  
13
  @ToPrettyString
14
  public abstract String toPrettyString();
15
  
16
  public static Person create(String name, int age, List<String> hobbies) {
17
    return new AutoValue_Person(name, age, hobbies);
18
  }
19
}
20
```
21

22
## Usage Example
23

24
```java
25
Person person = Person.create("Alice", 30, Arrays.asList("reading", "coding", "hiking"));
26

27
System.out.println(person.toPrettyString());
28
// Output:
29
// Person{
30
//   name = Alice,
31
//   age = 30,
32
//   hobbies = [
33
//     reading,
34
//     coding,
35
//     hiking,
36
//   ]
37
// }
38
```
39

40
## Pretty String vs Regular toString()
41

42
Compare pretty string output with regular toString():
43

44
```java
45
Person person = Person.create("Alice", 30, Arrays.asList("reading", "coding"));
46

47
System.out.println(person.toString());
48
// Person{name=Alice, age=30, hobbies=[reading, coding]}
49

50
System.out.println(person.toPrettyString());
51
// Person{
52
//   name = Alice,
53
//   age = 30,
54
//   hobbies = [
55
//     reading,
56
//     coding,
57
//   ]
58
// }
59
```
60

61
## Complex Object Pretty Strings
62

63
Pretty strings handle nested objects and collections beautifully:
64

65
```java { .api }
66
@AutoValue
67
public abstract class Address {
68
  public abstract String street();
69
  public abstract String city();
70
  public abstract String zipCode();
71
  
72
  @ToPrettyString
73
  public abstract String toPrettyString();
74
  
75
  public static Address create(String street, String city, String zipCode) {
76
    return new AutoValue_Address(street, city, zipCode);
77
  }
78
}
79

80
@AutoValue
81
public abstract class Company {
82
  public abstract String name();
83
  public abstract Address headquarters();
84
  public abstract List<Address> offices();
85
  public abstract Map<String, String> contacts();
86
  
87
  @ToPrettyString  
88
  public abstract String toPrettyString();
89
  
90
  public static Company create(
91
      String name,
92
      Address headquarters, 
93
      List<Address> offices,
94
      Map<String, String> contacts) {
95
    return new AutoValue_Company(name, headquarters, offices, contacts);
96
  }
97
}
98
```
99

100
Usage:
101

102
```java
103
Address hq = Address.create("123 Main St", "Springfield", "12345");
104
Address office = Address.create("456 Oak Ave", "Springfield", "12346");
105

106
Company company = Company.create(
107
    "Tech Corp",
108
    hq,
109
    Arrays.asList(office),
110
    Map.of("sales", "sales@techcorp.com", "support", "help@techcorp.com"));
111

112
System.out.println(company.toPrettyString());
113
// Output:
114
// Company{
115
//   name = Tech Corp,
116
//   headquarters = Address{
117
//     street = 123 Main St,
118
//     city = Springfield,
119
//     zipCode = 12345,
120
//   },
121
//   offices = [
122
//     Address{
123
//       street = 456 Oak Ave,
124
//       city = Springfield,
125
//       zipCode = 12346,
126
//     },
127
//   ],
128
//   contacts = {
129
//     sales = sales@techcorp.com,
130
//     support = help@techcorp.com,
131
//   }
132
// }
133
```
134

135
## Collection Formatting
136

137
Pretty strings provide special formatting for different collection types:
138

139
```java { .api }
140
@AutoValue
141
public abstract class DataContainer {
142
  public abstract List<String> items();
143
  public abstract Set<Integer> numbers();
144
  public abstract Map<String, Object> properties();
145
  public abstract Optional<String> description();
146
  
147
  @ToPrettyString
148
  public abstract String toPrettyString();
149
  
150
  public static DataContainer create(
151
      List<String> items,
152
      Set<Integer> numbers,
153
      Map<String, Object> properties,
154
      Optional<String> description) {
155
    return new AutoValue_DataContainer(items, numbers, properties, description);
156
  }
157
}
158
```
159

160
Usage:
161

162
```java
163
DataContainer container = DataContainer.create(
164
    Arrays.asList("apple", "banana", "cherry"),
165
    Set.of(1, 2, 3, 5, 8),
166
    Map.of("color", "red", "size", "large", "count", 42),
167
    Optional.of("A sample data container"));
168

169
System.out.println(container.toPrettyString());
170
// Output:
171
// DataContainer{
172
//   items = [
173
//     apple,
174
//     banana,
175
//     cherry,
176
//   ],
177
//   numbers = [
178
//     1,
179
//     2,
180
//     3,
181
//     5,
182
//     8,
183
//   ],
184
//   properties = {
185
//     color = red,
186
//     size = large,
187
//     count = 42,
188
//   },
189
//   description = A sample data container
190
// }
191
```
192

193
## String Formatting with Special Characters
194

195
Pretty strings handle special characters and newlines gracefully:
196

197
```java { .api }
198
@AutoValue
199
public abstract class TextData {
200
  public abstract String title();
201
  public abstract String content();
202
  public abstract List<String> lines();
203
  
204
  @ToPrettyString
205
  public abstract String toPrettyString();
206
  
207
  public static TextData create(String title, String content, List<String> lines) {
208
    return new AutoValue_TextData(title, content, lines);
209
  }
210
}
211
```
212

213
Usage:
214

215
```java
216
TextData data = TextData.create(
217
    "Sample Document",
218
    "This is a document\nwith multiple lines\nand\ttabs",
219
    Arrays.asList("Line 1", "Line with\nnewline", "Line\twith\ttabs"));
220

221
System.out.println(data.toPrettyString());
222
// Output:
223
// TextData{
224
//   title = Sample Document,
225
//   content = This is a document
226
//   with multiple lines
227
//   and	tabs,
228
//   lines = [
229
//     Line 1,
230
//     Line with
231
//     newline,
232
//     Line	with	tabs,
233
//   ]
234
// }
235
```
236

237
## Custom Pretty String Methods
238

239
Non-AutoValue classes can provide pretty string methods:
240

241
```java { .api }
242
public class CustomClass {
243
  private final String name;
244
  private final int value;
245
  
246
  public CustomClass(String name, int value) {
247
    this.name = name;
248
    this.value = value;
249
  }
250
  
251
  @ToPrettyString
252
  public String toPrettyString() {
253
    return "CustomClass{name=" + name + ", value=" + value + "}";
254
  }
255
  
256
  // Regular getters...
257
}
258

259
@AutoValue
260
public abstract class Container {
261
  public abstract CustomClass custom();
262
  public abstract List<CustomClass> items();
263
  
264
  @ToPrettyString
265
  public abstract String toPrettyString();
266
  
267
  public static Container create(CustomClass custom, List<CustomClass> items) {
268
    return new AutoValue_Container(custom, items);
269
  }
270
}
271
```
272

273
The pretty string generator will use the custom `toPrettyString()` method:
274

275
```java
276
CustomClass custom1 = new CustomClass("first", 1);
277
CustomClass custom2 = new CustomClass("second", 2);
278
Container container = Container.create(custom1, Arrays.asList(custom1, custom2));
279

280
System.out.println(container.toPrettyString());
281
// Output:
282
// Container{
283
//   custom = CustomClass{name=first, value=1},
284
//   items = [
285
//     CustomClass{name=first, value=1},
286
//     CustomClass{name=second, value=2},
287
//   ]
288
// }
289
```
290

291
## Pretty String with Inheritance
292

293
Pretty string works with AutoValue class hierarchies:
294

295
```java { .api }
296
@AutoValue
297
public abstract class Animal {
298
  public abstract String name();
299
  public abstract int age();
300
  
301
  @ToPrettyString
302
  public abstract String toPrettyString();
303
}
304

305
@AutoValue
306
public abstract class Dog extends Animal {
307
  public abstract String breed();
308
  public abstract boolean trained();
309
  
310
  @ToPrettyString
311
  @Override
312
  public abstract String toPrettyString();
313
  
314
  public static Dog create(String name, int age, String breed, boolean trained) {
315
    return new AutoValue_Dog(name, age, breed, trained);
316
  }
317
}
318
```
319

320
Usage:
321

322
```java
323
Dog dog = Dog.create("Buddy", 3, "Golden Retriever", true);
324

325
System.out.println(dog.toPrettyString());
326
// Output:
327
// Dog{
328
//   name = Buddy,
329
//   age = 3,
330
//   breed = Golden Retriever,
331
//   trained = true,
332
// }
333
```
334

335
## Pretty String for toString() Override
336

337
You can use @ToPrettyString to override the default toString():
338

339
```java { .api }
340
@AutoValue
341
public abstract class Product {
342
  public abstract String name();
343
  public abstract double price();
344
  public abstract List<String> categories();
345
  public abstract Map<String, String> attributes();
346
  
347
  @ToPrettyString
348
  @Override
349
  public abstract String toString();
350
  
351
  public static Product create(
352
      String name,
353
      double price,
354
      List<String> categories, 
355
      Map<String, String> attributes) {
356
    return new AutoValue_Product(name, price, categories, attributes);
357
  }
358
}
359
```
360

361
Now `toString()` will return the pretty formatted string:
362

363
```java
364
Product product = Product.create(
365
    "Laptop",
366
    999.99,
367
    Arrays.asList("Electronics", "Computers"),
368
    Map.of("brand", "TechCorp", "warranty", "1 year"));
369

370
System.out.println(product); // Calls toString() which uses pretty formatting
371
// Output:
372
// Product{
373
//   name = Laptop,
374
//   price = 999.99,
375
//   categories = [
376
//     Electronics,
377
//     Computers,
378
//   ],
379
//   attributes = {
380
//     brand = TechCorp,
381
//     warranty = 1 year,
382
//   }
383
// }
384
```
385

386
## Integration with Other Extensions
387

388
Pretty strings work with other AutoValue extensions:
389

390
```java { .api }
391
@SerializableAutoValue
392
@AutoValue
393
public abstract class CachedData implements Serializable {
394
  public abstract String data();
395
  public abstract Optional<List<String>> tags();
396
  
397
  @Memoized
398
  public String processedData() {
399
    return data().toUpperCase().trim();
400
  }
401
  
402
  @ToPrettyString
403
  public abstract String toPrettyString();
404
  
405
  public static CachedData create(String data, Optional<List<String>> tags) {
406
    return new AutoValue_CachedData(data, tags);
407
  }
408
}
409
```
410

411
## Empty Collections and Null Handling
412

413
Pretty strings handle empty collections and null values gracefully:
414

415
```java
416
@AutoValue
417
public abstract class Example {
418
  @Nullable
419
  public abstract String nullableField();
420
  public abstract List<String> emptyList();
421
  public abstract Optional<String> emptyOptional();
422
  
423
  @ToPrettyString
424
  public abstract String toPrettyString();
425
  
426
  public static Example create(
427
      @Nullable String nullableField,
428
      List<String> emptyList,
429
      Optional<String> emptyOptional) {
430
    return new AutoValue_Example(nullableField, emptyList, emptyOptional);
431
  }
432
}
433

434
Example example = Example.create(null, Collections.emptyList(), Optional.empty());
435
System.out.println(example.toPrettyString());
436
// Output:
437
// Example{
438
//   nullableField = null,
439
//   emptyList = [],
440
//   emptyOptional = <absent>,
441
// }
442
```
443

444
## Performance Considerations
445

446
- Pretty string generation builds strings efficiently using StringBuilder
447
- Nested object pretty strings are called recursively
448
- Large collections may produce very long output
449
- Consider using regular toString() for performance-critical logging
450
- Pretty strings are best used for debugging and development