[With] renaming lombok.experimental.Wither to lombok.experimental.With

88 files changed, 912 insertions, 807 deletions

diff --git a/src/core/lombok/ConfigurationKeys.java b/src/core/lombok/ConfigurationKeys.java
index d46889d6..0baf1f3b 100644
--- a/src/core/lombok/ConfigurationKeys.java
+++ b/src/core/lombok/ConfigurationKeys.java
@@ -593,14 +593,14 @@ public class ConfigurationKeys {
 	 */
 	public static final ConfigurationKey<Boolean> FIELD_NAME_CONSTANTS_UPPERCASE = new ConfigurationKey<Boolean>("lombok.fieldNameConstants.uppercase", "The default name of the constants inside the inner type generated by @FieldNameConstants follow the variable name precisely. If this config key is true, lombok will uppercase them as best it can. (default: false).") {};
 	
-	// ----- Wither -----
+	// ----- With -----
 	
 	/**
-	 * lombok configuration: {@code lombok.wither.flagUsage} = {@code WARNING} | {@code ERROR}.
+	 * lombok configuration: {@code lombok.with.flagUsage} = {@code WARNING} | {@code ERROR}.
 	 * 
-	 * If set, <em>any</em> usage of {@code @Wither} results in a warning / error.
+	 * If set, <em>any</em> usage of {@code @With} results in a warning / error.
 	 */
-	public static final ConfigurationKey<FlagUsageType> WITHER_FLAG_USAGE = new ConfigurationKey<FlagUsageType>("lombok.wither.flagUsage", "Emit a warning or error if @Wither is used.") {};
+	public static final ConfigurationKey<FlagUsageType> WITH_FLAG_USAGE = new ConfigurationKey<FlagUsageType>("lombok.with.flagUsage", "Emit a warning or error if @With is used.") {};
 	
 	// ----- SuperBuilder -----
 	
@@ -625,9 +625,9 @@ public class ConfigurationKeys {
 	/**
 	 * lombok configuration: {@code lombok.copyableAnnotations} += &lt;TypeName: fully-qualified annotation class name&gt;.
 	 *
-	 * Copy these annotations to getters, setters, withers, builder-setters, etc.
+	 * Copy these annotations to getters, setters, with methods, builder-setters, etc.
 	 */
-	public static final ConfigurationKey<List<TypeName>> COPYABLE_ANNOTATIONS = new ConfigurationKey<List<TypeName>>("lombok.copyableAnnotations", "Copy these annotations to getters, setters, withers, builder-setters, etc.") {};
+	public static final ConfigurationKey<List<TypeName>> COPYABLE_ANNOTATIONS = new ConfigurationKey<List<TypeName>>("lombok.copyableAnnotations", "Copy these annotations to getters, setters, with methods, builder-setters, etc.") {};
 	
 	/**
 	 * lombok configuration: {@code checkerframework} = {@code true} | {@code false} | &lt;String: MajorVer.MinorVer&gt; (Default: false).
diff --git a/src/core/lombok/With.java b/src/core/lombok/With.java
new file mode 100644
index 00000000..141d1fa6
--- /dev/null
+++ b/src/core/lombok/With.java
@@ -0,0 +1,94 @@
+/*
+ * Copyright (C) 2012-2019 The Project Lombok Authors.
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package lombok;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import lombok.AccessLevel;
+
+/**
+ * Put on any field to make lombok build a 'with' - a withX method which produces a clone of this object (except for 1 field which gets a new value).
+ * <p>
+ * Complete documentation is found at <a href="https://projectlombok.org/features/With">the project lombok features page for &#64;With</a>.
+ * <p>
+ * Example:
+ * <pre>
+ *     private &#64;With final int foo;
+ * </pre>
+ * 
+ * will generate:
+ * 
+ * <pre>
+ *     public SELF_TYPE withFoo(int foo) {
+ *         return this.foo == foo ? this : new SELF_TYPE(otherField1, otherField2, foo);
+ *     }
+ * </pre>
+ * <p>
+ * This annotation can also be applied to a class, in which case it'll be as if all non-static fields that don't already have
+ * a {@code With} annotation have the annotation.
+ */
+@Target({ElementType.FIELD, ElementType.TYPE})
+@Retention(RetentionPolicy.SOURCE)
+public @interface With {
+	/**
+	 * If you want your with method to be non-public, you can specify an alternate access level here.
+	 * 
+	 * @return The method will be generated with this access modifier.
+	 */
+	AccessLevel value() default AccessLevel.PUBLIC;
+	
+	/**
+	 * Any annotations listed here are put on the generated method.
+	 * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br>
+	 * up to JDK7:<br>
+	 *  {@code @With(onMethod=@__({@AnnotationsGoHere}))}<br>
+	 * from JDK8:<br>
+	 *  {@code @With(onMethod_={@AnnotationsGohere})} // note the underscore after {@code onMethod}.
+	 * 
+	 * @return List of annotations to apply to the generated method.
+	 */
+	AnyAnnotation[] onMethod() default {};
+	
+	/**
+	 * Any annotations listed here are put on the generated method's parameter.
+	 * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br>
+	 * up to JDK7:<br>
+	 *  {@code @With(onParam=@__({@AnnotationsGoHere}))}<br>
+	 * from JDK8:<br>
+	 *  {@code @With(onParam_={@AnnotationsGohere})} // note the underscore after {@code onParam}.
+	 * 
+	 * @return List of annotations to apply to the generated parameter in the method.
+	 */
+	AnyAnnotation[] onParam() default {};
+	
+	/**
+	  * Placeholder annotation to enable the placement of annotations on the generated code.
+	  * @deprecated Don't use this annotation, ever - Read the documentation.
+	  */
+	@Deprecated
+	@Retention(RetentionPolicy.SOURCE)
+	@Target({})
+	@interface AnyAnnotation {}
+}
diff --git a/src/core/lombok/core/LombokInternalAliasing.java b/src/core/lombok/core/LombokInternalAliasing.java
index c1089580..0b92d3b9 100644
--- a/src/core/lombok/core/LombokInternalAliasing.java
+++ b/src/core/lombok/core/LombokInternalAliasing.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2013-2018 The Project Lombok Authors.
+ * Copyright (C) 2013-2019 The Project Lombok Authors.
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -51,6 +51,7 @@ public class LombokInternalAliasing {
 		m2.put("lombok.experimental.Builder", "lombok.Builder");
 		m2.put("lombok.experimental.var", "lombok.var");
 		m2.put("lombok.Delegate", "lombok.experimental.Delegate");
+		m2.put("lombok.experimental.Wither", "lombok.With");
 		ALIASES = Collections.unmodifiableMap(m2);
 	}
 }
diff --git a/src/core/lombok/core/handlers/HandlerUtil.java b/src/core/lombok/core/handlers/HandlerUtil.java
index 21a3a216..be32e101 100644
--- a/src/core/lombok/core/handlers/HandlerUtil.java
+++ b/src/core/lombok/core/handlers/HandlerUtil.java
@@ -38,6 +38,7 @@ import lombok.RequiredArgsConstructor;
 import lombok.Setter;
 import lombok.ToString;
 import lombok.Value;
+import lombok.With;
 import lombok.core.AST;
 import lombok.core.AnnotationValues;
 import lombok.core.JavaIdentifiers;
@@ -47,7 +48,6 @@ import lombok.core.configuration.ConfigurationKey;
 import lombok.core.configuration.FlagUsageType;
 import lombok.experimental.Accessors;
 import lombok.experimental.FieldDefaults;
-import lombok.experimental.Wither;
 
 /**
  * Container for static utility methods useful for some of the standard lombok handlers, regardless of
@@ -406,7 +406,7 @@ public class HandlerUtil {
 	@SuppressWarnings({"all", "unchecked", "deprecation"})
 	public static final List<String> INVALID_ON_BUILDERS = Collections.unmodifiableList(
 			Arrays.<String>asList(
-			Getter.class.getName(), Setter.class.getName(), Wither.class.getName(),
+			Getter.class.getName(), Setter.class.getName(), With.class.getName(), "lombok.experimental.Wither",
 			ToString.class.getName(), EqualsAndHashCode.class.getName(), 
 			RequiredArgsConstructor.class.getName(), AllArgsConstructor.class.getName(), NoArgsConstructor.class.getName(), 
 			Data.class.getName(), Value.class.getName(), "lombok.experimental.Value", FieldDefaults.class.getName()));
@@ -502,7 +502,7 @@ public class HandlerUtil {
 	}
 	
 	/**
-	 * Generates a wither name from a given field name.
+	 * Generates a with name from a given field name.
 	 * 
 	 * Strategy:
 	 * <ul>
@@ -518,9 +518,9 @@ public class HandlerUtil {
 	 * @param accessors Accessors configuration.
 	 * @param fieldName the name of the field.
 	 * @param isBoolean if the field is of type 'boolean'. For fields of type {@code java.lang.Boolean}, you should provide {@code false}.
-	 * @return The wither name for this field, or {@code null} if this field does not fit expected patterns and therefore cannot be turned into a getter name.
+	 * @return The with name for this field, or {@code null} if this field does not fit expected patterns and therefore cannot be turned into a getter name.
 	 */
-	public static String toWitherName(AST<?, ?, ?> ast, AnnotationValues<Accessors> accessors, CharSequence fieldName, boolean isBoolean) {
+	public static String toWithName(AST<?, ?, ?> ast, AnnotationValues<Accessors> accessors, CharSequence fieldName, boolean isBoolean) {
 		return toAccessorName(ast, accessors, fieldName, isBoolean, "with", "with", false);
 	}
 	
@@ -582,7 +582,7 @@ public class HandlerUtil {
 	}
 	
 	/**
-	 * Returns all names of methods that would represent the wither for a field with the provided name.
+	 * Returns all names of methods that would represent the with for a field with the provided name.
 	 * 
 	 * For example if {@code isBoolean} is true, then a field named {@code isRunning} would produce:<br />
 	 * {@code [withRunning, withIsRunning]}
@@ -591,7 +591,7 @@ public class HandlerUtil {
 	 * @param fieldName the name of the field.
 	 * @param isBoole