Skip to content

Commit 3711b00

Browse files
RandgaltRandgalt
committed
Documentation for options
Closes #162
1 parent d228666 commit 3711b00

File tree

3 files changed

+100
-2
lines changed

3 files changed

+100
-2
lines changed

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ _Details:_
2222
- [Generation Via Includes](#generation-via-includes)
2323
- [Usage](#usage)
2424
- [Customizing](customizing.md) (e.g. add immutable collections, etc.)
25+
- [Options](options.md)
2526

2627
## RecordBuilder Example
2728

‎customizing.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ enable optional features.
99
# Customizing RecordBuilder
1010

1111
RecordBuilder can be customized in a number of ways. The types of customizations will change over time. See
12-
[@RecordBuilder.Options](record-builder-core/src/main/java/io/soabase/recordbuilder/core/RecordBuilder.java)
12+
[RecordBuilder Options](options.md)
1313
for the current set of customizations and their default values. For example, the `useImmutableCollections` option
1414
adds special handling for record components of type `java.util.List`, `java.util.Set`, `java.util.Map` and `java.util.Collection`. When the record is built, any components of these types are passed through an added shim method that uses the corresponding immutable collection (e.g. `List.copyOf(o)`) or an empty immutable collection if the component is `null`.
1515

@@ -59,7 +59,7 @@ compilerArgs.addAll(['-AprefixEnclosingClassNames=false', '-AfileComment="someth
5959

6060
## Customize a single record
6161

62-
To customize a single record, add `@RecordBuilder.Options` in addition to
62+
To customize a single record, add `@RecordBuilder.Options` ([options details](options.md)) in addition to
6363
`@RecordBuilder`.
6464

6565
E.g.

‎options.md

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
[◀︎ RecordBuilder](README.md) • RecordBuilder Options
2+
3+
# RecordBuilder Options
4+
5+
RecordBuilder supports many options that change the behavior of generated builders. These options are added to over
6+
time and the project is open to suggestions/submissions from users.
7+
8+
Options are specified by adding `@RecordBuilder.Options` annotations on source records. The project's test
9+
files have many examples.
10+
11+
## Naming
12+
13+
The names used for generated methods, classes, etc. can be changed via the following options:
14+
15+
| option | details |
16+
|-------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
17+
| `@RecordBuilder.Options(suffix = "foo")` | The builder class name will be the name of the record (prefixed with any enclosing class) plus this suffix. |
18+
| `@RecordBuilder.Options(interfaceSuffix = "Foo")` | Used by {@code RecordInterface}. The generated record will have the same name as the annotated interface plus this suffix. |
19+
| `@RecordBuilder.Options(copyMethodName = "foo")` | The name to use for the copy builder. |
20+
| `@RecordBuilder.Options(builderMethodName = "foo")` | The name to use for the builder. |
21+
| `@RecordBuilder.Options(buildMethodName = "foo")` | The name to use for the build method. |
22+
| `@RecordBuilder.Options(fromMethodName = "foo")` | The name to use for the from-to-wither method. |
23+
| `@RecordBuilder.Options(componentsMethodName = "foo")` | The name to use for the method that returns the record components as a stream. |
24+
| `@RecordBuilder.Options(withClassName = "Foo")` | The name to use for the nested With class. |
25+
| `@RecordBuilder.Options(withClassMethodPrefix = "foo")` | The prefix to use for the methods in the With class. |
26+
| `@RecordBuilder.Options(singleItemBuilderPrefix = "foo")` | The prefix for adder methods when `addSingleItemCollectionBuilders()` is enabled. |
27+
| `@RecordBuilder.Options(fromWithClassName = "Foo")` | The `fromMethodName` method instantiates an internal private class. This is the name of that class. |
28+
| `@RecordBuilder.Options(mutableListClassName = "Foo")` | If `addSingleItemCollectionBuilders()` and `useImmutableCollections()` are enabled the builder uses an internal class to track changes to lists. This is the name of that class. |
29+
| `@RecordBuilder.Options(mutableSetClassName = "Foo")` | If `addSingleItemCollectionBuilders()` and `useImmutableCollections()` are enabled the builder uses an internal class to track changes to sets. This is the name of that class. |
30+
| `@RecordBuilder.Options(mutableMapClassName = "Foo")` | If `addSingleItemCollectionBuilders()` and `useImmutableCollections()` are enabled the builder uses an internal class to track changes to maps. This is the name of that class. |
31+
| `@RecordBuilder.Options(stagedBuilderMethodName = "foo")` | The name to use for the staged builder if present. |
32+
| `@RecordBuilder.Options(stagedBuilderMethodSuffix = "Foo")` | The suffix to use for the staged builder interfaces if present. |
33+
| `@RecordBuilder.Options(getterPrefix = "foo")` | If set, all builder getter methods will be prefixed with this string. |
34+
| `@RecordBuilder.Options(booleanPrefix = "foo")` | If set, all boolean builder getter methods will be prefixed with this string. |
35+
36+
## Withers
37+
38+
| option | details |
39+
|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
40+
| `@RecordBuilder.Options(enableWither = true/false)` | The builder class name will be the name of the record (prefixed with any enclosing class) plus this suffix. The default is `true`. |
41+
| `@RecordBuilder.Options(withClassName = "Foo")` | The name to use for the nested With class. |
42+
| `@RecordBuilder.Options(withClassMethodPrefix = "foo")` | The prefix to use for the methods in the With class. |
43+
| `@RecordBuilder.Options(addFunctionalMethodsToWith = true/false)` | When enabled, adds functional methods to the nested "With" class. The default is `false`. |
44+
| `@RecordBuilder.Options(fromWithClassName = "Foo")` | The `fromMethodName` method instantiates an internal private class. This is the name of that class. |
45+
46+
## File/Class Generation
47+
48+
| option | details |
49+
|------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
50+
| `@RecordBuilder.Options(fileComment = "foo")` | Return the comment to place at the top of generated files. Return null or an empty string for no comment. |
51+
| `@RecordBuilder.Options(fileIndent = " ")` | Return the file indent to use. |
52+
| `@RecordBuilder.Options(prefixEnclosingClassNames = true/false)` | If the record is declared inside another class, the outer class's name will be prefixed to the builder name if this returns true. The default is `true`. |
53+
54+
## Miscellaneous
55+
56+
| option | details |
57+
|----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
58+
| `@RecordBuilder.Options(inheritComponentAnnotations = true/false)` | If true, any annotations (if applicable) on record components are copied to the builder methods. The default is `true`. |
59+
| `@RecordBuilder.Options(publicBuilderConstructors = true/false)` | Makes the generated builder's constructors public. The default is `false`. |
60+
| `@RecordBuilder.Options(builderClassModifiers = {}})` | Any additional `javax.lang.model.element.Modifier` you wish to apply to the builder. |
61+
| `@RecordBuilder.Options(beanClassName = "Foo")` | If set, the Builder will contain an internal interface with this name. |
62+
| `@RecordBuilder.Options(addClassRetainedGenerated = true/false)` | If true, generated classes are annotated with `RecordBuilderGenerated`. The default is `false`. |
63+
| `@RecordBuilder.Options(addStaticBuilder = true/false)` | If true, a functional-style builder is added so that record instances can be instantiated without `new()`. The default is `true`. |
64+
| `@RecordBuilder.Options(inheritComponentAnnotations = true/false)` | If true, any annotations (if applicable) on record components are copied to the builder methods. The default is `true`. |
65+
| `@RecordBuilder.Options(addConcreteSettersForOptional = true/false)` | Add non-optional setter methods for optional record components. The default is `false`. |
66+
| `@RecordBuilder.Options(useValidationApi = true/false)` | Pass built records through the Java Validation API if it's available in the classpath. The default is `false`. |
67+
68+
## Default Values / Initializers
69+
70+
| option | details |
71+
|--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
72+
| `@RecordBuilder.Options(emptyDefaultForOptional = true/false)` | Set the default value of `Optional` record components to `Optional.empty()`. The default is `true`. |
73+
74+
### `@RecordBuilder.Initializer`
75+
76+
You can annotate record components with `@RecordBuilder.Initializer(...)` to specify initializers for the corresponding
77+
field in the generated builder. See [Initialized.java](record-builder-test/src/main/java/io/soabase/recordbuilder/test/Initialized.java)
78+
for an example.
79+
80+
## Null Handling
81+
82+
| option | details |
83+
|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
84+
| `@RecordBuilder.Options(interpretNotNulls = true/false)` | Add not-null checks for record components annotated with any null-pattern annotation. The default is `false`. |
85+
| `@RecordBuilder.Options(interpretNotNullsPattern = "regex")` | The regex pattern used to determine if an annotation name means non-null. |
86+
| `@RecordBuilder.Options(allowNullableCollections = true/false)` | Adds special null handling for record collectioncomponents. The default is `false`. |
87+
88+
## Collections
89+
90+
Special handling for collections. See the project test classes for usage.
91+
92+
| option | details |
93+
|------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
94+
| `@RecordBuilder.Options(useImmutableCollections = true/false)` | Adds special handling for collection record components. The default is `false`. |
95+
| `@RecordBuilder.Options(useUnmodifiableCollections = true/false)` | Adds special handling for collection record components. The default is `false`. |
96+
| `@RecordBuilder.Options(allowNullableCollections = true/false)` | Adds special null handling for record collectioncomponents. The default is `false`. |
97+
| `@RecordBuilder.Options(addSingleItemCollectionBuilders = true/false)` | Adds special handling for record collectioncomponents. The default is `false`. |

0 commit comments

Comments
 (0)