Merge branch 'builderClone'

Conflicts:
	doc/changelog.markdown

6 files changed, 513 insertions, 103 deletions

diff --git a/src/core/lombok/Builder.java b/src/core/lombok/Builder.java
index 4556bef0..0639c4cb 100644
--- a/src/core/lombok/Builder.java
+++ b/src/core/lombok/Builder.java
@@ -113,9 +113,40 @@ public @interface Builder {
 	/** Name of the instance method in the builder class that creates an instance of your {@code @Builder}-annotated class. */
 	String buildMethodName() default "build";
 	
-	/** Name of the builder class.
+	/**
+	 * Name of the builder class.
+	 * 
 	 * Default for {@code @Builder} on types and constructors: {@code (TypeName)Builder}.
+	 * <p>
 	 * Default for {@code @Builder} on static methods: {@code (ReturnTypeName)Builder}.
 	 */
 	String builderClassName() default "";
+	
+	/**
+	 * If true, generate an instance method to obtain a builder that is initialized with the values of this instance.
+	 * Legal only if {@code @Builder} is used on a constructor, on the type itself, or on a static method that returns
+	 * an instance of the declaring type.
+	 */
+	boolean toBuilder() default false;
+	
+	/**
+	 * Put on a field (in case of {@code @Builder} on a type) or a parameter (for {@code @Builder} on a constructor or static method) to
+	 * indicate how lombok should obtain a value for this field or parameter given an instance; this is only relevant if {@code toBuilder} is {@code true}.
+	 * 
+	 * You do not need to supply an {@code @ObtainVia} annotation unless you wish to change the default behaviour: Use a field with the same name.
+	 * <p>
+	 * Note that one of {@code field} or {@code method} should be set, or an error is generated.
+	 * <p>
+	 * The default behaviour is to obtain a value by referencing the name of the parameter as a field on 'this'.
+	 */
+	public @interface ObtainVia {
+		/** Tells lombok to obtain a value with the expression {@code this.value}. */
+		String field() default "";
+		
+		/** Tells lombok to obtain a value with the expression {@code this.method()}. */
+		String method() default "";
+		
+		/** Tells lombok to obtain a value with the expression {@code SelfType.method(this)}; requires {@code method} to be set. */
+		boolean isStatic() default false;
+	}
 }
diff --git a/src/core/lombok/core/TypeLibrary.java b/src/core/lombok/core/TypeLibrary.java
index dc557c47..cdaf7a70 100644
--- a/src/core/lombok/core/TypeLibrary.java
+++ b/src/core/lombok/core/TypeLibrary.java
@@ -50,13 +50,20 @@ public class TypeLibrary {
 	}
 	
 	private TypeLibrary(String fqnSingleton) {
-		unqualifiedToQualifiedMap = null;
-		qualified = fqnSingleton;
-		int idx = fqnSingleton.lastIndexOf('.');
-		if (idx == -1) {
-			unqualified = fqnSingleton;
+		if (fqnSingleton.indexOf("$") != -1) {
+			unqualifiedToQualifiedMap = new HashMap<String, String>();
+			unqualified = null;
+			qualified = null;
+			addType(fqnSingleton);
 		} else {
-			unqualified = fqnSingleton.substring(idx + 1);
+			unqualifiedToQualifiedMap = null;
+			qualified = fqnSingleton;
+			int idx = fqnSingleton.lastIndexOf('.');
+			if (idx == -1) {
+				unqualified = fqnSingleton;
+			} else {
+				unqualified = fqnSingleton.substring(idx + 1);
+			}
 		}
 		locked = true;
 	}
@@ -71,18 +78,29 @@ public class TypeLibrary {
 	 * @param fullyQualifiedTypeName the FQN type name, such as 'java.lang.String'.
 	 */
 	public void addType(String fullyQualifiedTypeName) {
+		String dotBased = fullyQualifiedTypeName.replace("$", ".");
+		
 		if (locked) throw new IllegalStateException("locked");
-		fullyQualifiedTypeName = fullyQualifiedTypeName.replace("$", ".");
 		int idx = fullyQualifiedTypeName.lastIndexOf('.');
 		if (idx == -1) throw new IllegalArgumentException(
 				"Only fully qualified types are allowed (and stuff in the default package is not palatable to us either!)");
 		String unqualified = fullyQualifiedTypeName.substring(idx + 1);
 		if (unqualifiedToQualifiedMap == null) throw new IllegalStateException("SingleType library");
 		
-		unqualifiedToQualifiedMap.put(unqualified, fullyQualifiedTypeName);
-		unqualifiedToQualifiedMap.put(fullyQualifiedTypeName, fullyQualifiedTypeName);
+		unqualifiedToQualifiedMap.put(unqualified.replace("$", "."), dotBased);
+		unqualifiedToQualifiedMap.put(unqualified, dotBased);
+		unqualifiedToQualifiedMap.put(fullyQualifiedTypeName, dotBased);
+		unqualifiedToQualifiedMap.put(dotBased, dotBased);
 		for (Map.Entry<String, String> e : LombokInternalAliasing.ALIASES.entrySet()) {
-			if (fullyQualifiedTypeName.equals(e.getValue())) unqualifiedToQualifiedMap.put(e.getKey(), fullyQualifiedTypeName);
+			if (fullyQualifiedTypeName.equals(e.getValue())) unqualifiedToQualifiedMap.put(e.getKey(), dotBased);
+		}
+		
+		int idx2 = fullyQualifiedTypeName.indexOf('$', idx + 1);
+		while (idx2 != -1) {
+			String unq = fullyQualifiedTypeName.substring(idx2 + 1);
+			unqualifiedToQualifiedMap.put(unq.replace("$", "."), dotBased);
+			unqualifiedToQualifiedMap.put(unq, dotBased);
+			idx2 = fullyQualifiedTypeName.indexOf('$', idx2 + 1);
 		}
 	}
 	
diff --git a/src/core/lombok/core/TypeResolver.java b/src/core/lombok/core/TypeResolver.java
index 287a085f..60ac6b6a 100644
--- a/src/core/lombok/core/TypeResolver.java
+++ b/src/core/lombok/core/TypeResolver.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2009-2013 The Project Lombok Authors.
+ * Copyright (C) 2009-2015 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
@@ -53,10 +53,13 @@ public class TypeResolver {
 		if (typeRef.equals(qualified)) return typeRef;
 		
 		// When asking if 'Getter' could possibly be referring to 'lombok.Getter' if 'import lombok.Getter;' is in the source file, the answer is yes.
-		String fromExplicitImport = imports.getFullyQualifiedNameForSimpleName(typeRef);
+		int firstDot = typeRef.indexOf('.');
+		if (firstDot == -1) firstDot = typeRef.length();
+		String firstTypeRef = typeRef.substring(0, firstDot);
+		String fromExplicitImport = imports.getFullyQualifiedNameForSimpleName(firstTypeRef);
 		if (fromExplicitImport != null) {
 			// ... and if 'import foobar.Getter;' is in the source file, the answer is no.
-			return fromExplicitImport.equals(qualified) ? qualified : null;
+			return (fromExplicitImport + typeRef.substring(firstDot)).equals(qualified) ? qualified : null;
 		}
 		
 		// When asking if 'Getter' could possibly be referring to 'lombok.Getter' and 'import lombok.*; / package lombok;' isn't in the source file. the answer is no.
@@ -68,7 +71,7 @@ public class TypeResolver {
 		
 		mainLoop:
 		while (n != null) {
-			if (n.getKind() == Kind.TYPE && typeRef.equals(n.getName())) {
+			if (n.getKind() == Kind.TYPE && firstTypeRef.equals(n.getName())) {
 				// Our own class or one of our outer classes is named 'typeRef' so that's what 'typeRef' is referring to, not one of our type library classes.
 				return null;
 			}
@@ -81,7 +84,7 @@ public class TypeResolver {
 					for (LombokNode<?, ?, ?> child : newN.down()) {
 						// We found a method local with the same name above our code. That's the one 'typeRef' is referring to, not
 						// anything in the type library we're trying to find, so, no matches.
-						if (child.getKind() == Kind.TYPE && typeRef.equals(child.getName())) return null;
+						if (child.getKind() == Kind.TYPE && firstTypeRef.equals(child.getName())) return null;
 						if (child == n) break;
 					}
 				}
@@ -92,14 +95,13 @@ public class TypeResolver {
 			if (n.getKind() == Kind.TYPE || n.getKind() == Kind.COMPILATION_UNIT) {
 				for (LombokNode<?, ?, ?> child : n.down()) {
 					// Inner class that's visible to us has 'typeRef' as name, so that's the one being referred to, not one of our type library classes.
-					if (child.getKind() == Kind.TYPE && typeRef.equals(child.getName())) return null;
+					if (child.getKind() == Kind.TYPE && firstTypeRef.equals(child.getName())) return null;
 				}
 			}
 			
 			n = n.directUp();
 		}
 		
-		
 		return qualified;
 	}
 }
diff --git a/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java b/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java
index 836a51c6..0ff5a7f6 100644
--- a/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java
+++ b/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java
@@ -450,7 +450,7 @@ public class EclipseHandlerUtil {
 	 */
 	public static boolean annotationTypeMatches(Class<? extends java.lang.annotation.Annotation> type, EclipseNode node) {
 		if (node.getKind() != Kind.ANNOTATION) return false;
-		return typeMatches(type, node, ((Annotation)node.get()).type);
+		return typeMatches(type, node, ((Annotation) node.get()).type);
 	}
 	
 	public static TypeReference cloneSelfType(EclipseNode context) {
diff --git a/src/core/lombok/eclipse/handlers/HandleBuilder.java b/src/core/lombok/eclipse/handlers/HandleBuilder.java
index c1b0d8a3..ee6dfd70 100644
--- a/src/core/lombok/eclipse/handlers/HandleBuilder.java
+++ b/src/core/lombok/eclipse/handlers/HandleBuilder.java
@@ -69,6 +69,7 @@ import org.mangosdk.spi.ProviderFor;
 
 import lombok.AccessLevel;
 import lombok.Builder;
+import lombok.Builder.ObtainVia;
 import lombok.ConfigurationKeys;
 import lombok.Singular;
 import lombok.core.AST.Kind;
@@ -98,12 +99,33 @@ public class HandleBuilder extends EclipseAnnotationHandler<Builder> {
 	
 	private static class BuilderFieldData {
 		TypeReference type;
+		char[] rawName;
 		char[] name;
 		SingularData singularData;
+		ObtainVia obtainVia;
+		EclipseNode obtainViaNode;
 		
 		List<EclipseNode> createdFields = new ArrayList<EclipseNode>();
 	}
 	
+	private static boolean equals(String a, char[] b) {
+		if (a.length() != b.length) return false;
+		for (int i = 0; i < b.length; i++) {
+			if (a.charAt(i) != b[i]) return false;
+		}
+		return true;
+	}
+	
+	private static boolean equals(String a, char[][] b) {
+		if (a == null || a.isEmpty()) return b.length == 0;
+		String[] aParts = a.split("\\.");
+		if (aParts.length != b.length) return false;
+		for (int i = 0; i < b.length; i++) {
+			if (!equals(aParts[i], b[i])) return false;
+		}
+		return true;
+	}
+	
 	@Override public void handle(AnnotationValues<Builder> annotation, Annotation ast, EclipseNode annotationNode) {
 		long p = (long) ast.sourceStart << 32 | ast.sourceEnd;
 		
@@ -116,6 +138,9 @@ public class HandleBuilder extends EclipseAnnotationHandler<Builder> {
 		String builderMethodName = builderInstance.builderMethodName();
 		String buildMethodName = builderInstance.buildMethodName();
 		String builderClassName = builderInstance.builderClassName();
+		String toBuilderMethodName = "toBuilder";
+		boolean toBuilder = builderInstance.toBuilder();
+		List<char[]> typeArgsForToBuilder = null;
 		
 		if (builderMethodName == null) builderMethodName = "builder";
 		if (buildMethodName == null) builderMethodName = "build";
@@ -153,9 +178,11 @@ public class HandleBuilder extends EclipseAnnotationHandler<Builder> {
 				// Value will only skip making a field final if it has an explicit @NonFinal annotation, so we check for that.
 				if (fd.initialization != null && valuePresent && !hasAnnotation(NonFinal.class, fieldNode)) continue;
 				BuilderFieldData bfd = new BuilderFieldData();
+				bfd.rawName = fieldNode.getName().toCharArray();
 				bfd.name = removePrefixFromField(fieldNode);
 				bfd.type = fd.type;
 				bfd.singularData = getSingularData(fieldNode, ast);
+				addObtainVia(bfd, fieldNode);
 				builderFields.add(bfd);
 				allFields.add(fieldNode);
 			}
@@ -189,6 +216,72 @@ public class HandleBuilder extends EclipseAnnotationHandler<Builder> {
 				annotationNode.addError("@Builder is only supported on types, constructors, and static methods.");
 				return;
 			}
+			
+			if (toBuilder) {
+				final String TO_BUILDER_NOT_SUPPORTED = "@Builder(toBuilder=true) is only supported if you return your own type.";
+				char[] token;
+				char[][] pkg = null;
+				if (md.returnType.dimensions() > 0) {
+					annotationNode.addError(TO_BUILDER_NOT_SUPPORTED);
+					return;
+				}
+				
+				if (md.returnType instanceof SingleTypeReference) {
+					token = ((SingleTypeReference) md.returnType).token;
+				} else if (md.returnType instanceof QualifiedTypeReference) {
+					pkg = ((QualifiedTypeReference) md.returnType).tokens;
+					token = pkg[pkg.length];
+					char[][] pkg_ = new char[pkg.length - 1][];
+					System.arraycopy(pkg, 0, pkg_, 0, pkg_.length);
+					pkg = pkg_;
+				} else {
+					annotationNode.addError(TO_BUILDER_NOT_SUPPORTED);
+					return;
+				}
+				
+				if (pkg != null && !equals(parent.getPackageDeclaration(), pkg)) {
+					annotationNode.addError(TO_BUILDER_NOT_SUPPORTED);
+					return;
+				}
+				
+				if (tdParent == null || !equals(tdParent.getName(), token)) {
+					annotationNode.addError(TO_BUILDER_NOT_SUPPORTED);
+					return;
+				}
+				
+				TypeParameter[] tpOnType = ((TypeDeclaration) tdParent.get()).typeParameters;
+				TypeParameter[] tpOnMethod = md.typeParameters;
+				TypeReference[][] tpOnRet_ = md.returnType.getTypeArguments();
+				
+				if (tpOnRet_ != null) for (int i = 0; i < tpOnRet_.length - 1; i++) {
+					if (tpOnRet_[i] != null && tpOnRet_[i].length > 0) {
+						annotationNode.addError("@Builder(toBuilder=true) is not supported if returning a type with generics applied to an intermediate.");
+						return;
+					}
+				}
+				TypeReference[] tpOnRet = tpOnRet_ == null ? null : tpOnRet_[tpOnRet_.length - 1];
+				typeArgsForToBuilder = new ArrayList<char[]>();
+				
+				// Every typearg on this method needs to be found in the return type, but the reverse is not true.
+				// We also need to 'map' them.
+				
+				
+				if (tpOnMethod != null) for (TypeParameter onMethod : tpOnMethod) {
+					int pos = -1;
+					if (tpOnRet != null) for (int i = 0; i < tpOnRet.length; i++) {
+						if (tpOnRet[i].getClass() != SingleTypeReference.class) continue;
+						if (!Arrays.equals(((SingleTypeReference) tpOnRet[i]).token, onMethod.name)) continue;
+						pos = i;
+					}
+					if (pos == -1 || tpOnType == null || tpOnType.length <= pos) {
+						annotationNode.addError("@Builder(toBuilder=true) requires that each type parameter on the static method is part of the typeargs of the return value. Type parameter " + new String(onMethod.name) + " is not part of the return type.");
+						return;
+					}
+					
+					typeArgsForToBuilder.add(tpOnType[pos].name);
+				}
+			}
+			
 			returnType = copyType(md.returnType, ast);
 			typeParams = md.typeParameters;
 			thrownExceptions = md.thrownExceptions;
@@ -232,9 +325,11 @@ public class HandleBuilder extends EclipseAnnotationHandler<Builder> {
 				if (param.getKind() != Kind.ARGUMENT) continue;
 				BuilderFieldData bfd = new BuilderFieldData();
 				Argument arg = (Argument) param.get();
+				bfd.rawName = arg.name;
 				bfd.name = arg.name;
 				bfd.type = arg.type;
 				bfd.singularData = getSingularData(param, ast);
+				addObtainVia(bfd, param);
 				builderFields.add(bfd);
 			}
 		}
@@ -264,6 +359,16 @@ public class HandleBuilder extends EclipseAnnotationHandler<Builder> {
 					break;
 				}
 			}
+			if (bfd.obtainVia != null) {
+				if (bfd.obtainVia.field().isEmpty() == bfd.obtainVia.method().isEmpty()) {
+					bfd.obtainViaNode.addError("The syntax is either @ObtainVia(field = \"fieldName\") or @ObtainVia(method = \"methodName\").");
+					return;
+				}
+				if (bfd.obtainVia.method().isEmpty() && bfd.obtainVia.isStatic()) {
+					bfd.obtainViaNode.addError("@ObtainVia(isStatic = true) is not valid unless 'method' has been set.");
+					return;
+				}
+			}
 		}
 		
 		generateBuilderFields(builderType, builderFields, ast);
@@ -272,14 +377,13 @@ public class HandleBuilder extends EclipseAnnotationHandler<Builder> {
 			cleanDecl.declarationSourceEnd = -1;
 			cleanDecl.modifiers = ClassFileConstants.AccPrivate;
 			cleanDecl.type = TypeReference.baseTypeReference(TypeIds.T_boolean, 0);
-			System.out.println("INJECTING: cleaning");
 			injectFieldAndMarkGenerated(builderType, cleanDecl);
 		}
 		
 		if (constructorExists(builderType) == MemberExistsResult.NOT_EXISTS) {
 			ConstructorDeclaration cd = HandleConstructor.createConstructor(
-					AccessLevel.PACKAGE, builderType, Collections.<EclipseNode>emptyList(), null,
-					annotationNode, Collections.<Annotation>emptyList());
+				AccessLevel.PACKAGE, builderType, Collections.<EclipseNode>emptyList(), null,
+				annotationNode, Collections.<Annotation>emptyList());
 			if (cd != null) injectMethod(builderType, cd);
 		}
 		
@@ -310,6 +414,69 @@ public class HandleBuilder extends EclipseAnnotationHandler<Builder> {
 			MethodDeclaration md = generateBuilderMethod(builderMethodName, builderClassName, tdParent, typeParams, ast);
 			if (md != null) injectMethod(tdParent, md);
 		}
+		
+		if (toBuilder) switch (methodExists(toBuilderMethodName, tdParent, 0)) {
+		case EXISTS_BY_USER:
+			annotationNode.addWarning("Not generating toBuilder() as it already exists.");
+			break;
+		case NOT_EXISTS:
+			TypeParameter[] tps = typeParams;
+			if (typeArgsForToBuilder != null) {
+				tps = new TypeParameter[typeArgsForToBuilder.size()];
+				for (int i = 0; i < tps.length; i++) {
+					tps[i] = new TypeParameter();
+					tps[i].name = typeArgsForToBuilder.get(i);
+				}
+			}
+			MethodDeclaration md = generateToBuilderMethod(toBuilderMethodName, builderClassName, tdParent, tps, builderFields, fluent, ast);
+			
+			if (md != null) injectMethod(tdParent, md);
+		}
+	}
+	
+	private MethodDeclaration generateToBuilderMethod(String methodName, String builderClassName, EclipseNode type, TypeParameter[] typeParams, List<BuilderFieldData> builderFields, boolean fluent, ASTNode source) {
+		// return new ThingieBuilder<A, B>().setA(this.a).setB(this.b);
+		
+		int pS = source.sourceStart, pE = source.sourceEnd;
+		long p = (long) pS << 32 | pE;
+		
+		MethodDeclaration out = new MethodDeclaration(
+				((CompilationUnitDeclaration) type.top().get()).compilationResult);
+		out.selector = methodName.toCharArray();
+		out.modifiers = ClassFileConstants.AccPublic;
+		out.bits |= ECLIPSE_DO_NOT_TOUCH_FLAG;
+		out.returnType = namePlusTypeParamsToTypeReference(builderClassName.toCharArray(), typeParams, p);
+		AllocationExpression invoke = new AllocationExpression();
+		invoke.type = namePlusTypeParamsToTypeReference(builderClassName.toCharArray(), typeParams, p);
+		
+		Expression receiver = invoke;
+		for (BuilderFieldData bfd : builderFields) {
+			char[] setterName = fluent ? bfd.name : HandlerUtil.buildAccessorName("set", new String(bfd.name)).toCharArray();
+			MessageSend ms = new MessageSend();
+			if (bfd.obtainVia == null || !bfd.obtainVia.field().isEmpty()) {
+				char[] fieldName = bfd.obtainVia == null ? bfd.rawName : bfd.obtainVia.field().toCharArray();
+				FieldReference fr = new FieldReference(fieldName, 0);
+				fr.receiver = new ThisReference(0, 0);
+				ms.arguments = new Expression[] {fr};
+			} else {
+				String obtainName = bfd.obtainVia.method();
+				boolean obtainIsStatic = bfd.obtainVia.isStatic();
+				MessageSend obtainExpr = new MessageSend();
+				obtainExpr.receiver = obtainIsStatic ? new SingleNameReference(type.getName().toCharArray(), 0) : new ThisReference(0, 0);
+				obtainExpr.selector = obtainName.toCharArray();
+				if (obtainIsStatic) obtainExpr.arguments = new Expression[] {new ThisReference(0, 0)};
+				ms.arguments = new Expression[] {obtainExpr};
+			}
+			ms.receiver = receiver;
+			ms.selector = setterName;
+			receiver = ms;
+		}
+		
+		out.statements = new Statement[] {new ReturnStatement(receiver, pS, pE)};
+		
+		out.traverse(new SetGeneratedByVisitor(source), ((TypeDeclaration) type.get()).scope);
+		return out;
+
 	}
 	
 	private MethodDeclaration generateCleanMethod(List<BuilderFieldData> builderFields, EclipseNode builderType, ASTNode source) {
@@ -501,6 +668,16 @@ public class HandleBuilder extends EclipseAnnotationHandler<Builder> {
 		return injectType(tdParent, builder);
 	}
 	
+	private void addObtainVia(BuilderFieldData bfd, EclipseNode node) {
+		for (EclipseNode child : node.down()) {
+			if (!annotationTypeMatches(ObtainVia.class, child)) continue;
+			AnnotationValues<ObtainVia> ann = createAnnotation(ObtainVia.class, child);
+			bfd.obtainVia = ann.getInstance();
+			bfd.obtainViaNode = child;
+			return;
+		}
+	}
+	
 	/**
 	 * Returns the explicitly requested singular annotation on this node (field
 	 * or parameter), or null if there's no {@code @Singular} annotation on it.
@@ -509,53 +686,52 @@ public class HandleBuilder extends EclipseAnnotationHandler<Builder> {
 	 */
 	private SingularData getSingularData(EclipseNode node, ASTNode source) {
 		for (EclipseNode child : node.down()) {
-			if (child.getKind() == Kind.ANNOTATION && annotationTypeMatches(Singular.class, child)) {
-				char[] pluralName = node.getKind() == Kind.FIELD ? removePrefixFromField(node) : ((AbstractVariableDeclaration) node.get()).name;
-				AnnotationValues<Singular> ann = createAnnotation(Singular.class, child);
-				String explicitSingular = ann.getInstance().value();
-				if (explicitSingular.isEmpty()) {
-					if (Boolean.FALSE.equals(node.getAst().readConfiguration(ConfigurationKeys.SINGULAR_AUTO))) {
-						node.addError("The singular must be specified explicitly (e.g. @Singular(\"task\")) because auto singularization is disabled.");
+			if (!annotationTypeMatches(Singular.class, child)) continue;
+			char[] pluralName = node.getKind() == Kind.FIELD ? removePrefixFromField(node) : ((AbstractVariableDeclaration) node.get()).name;
+			AnnotationValues<Singular> ann = createAnnotation(Singular.class, child);
+			String explicitSingular = ann.getInstance().value();
+			if (explicitSingular.isEmpty()) {
+				if (Boolean.FALSE.equals(node.getAst().readConfiguration(ConfigurationKeys.SINGULAR_AUTO))) {
+					node.addError("The singular must be specified explicitly (e.g. @Singular(\"task\")) because auto singularization is disabled.");
+					explicitSingular = new String(pluralName);
+				} else {
+					explicitSingular = autoSingularize(node.getName());
+					if (explicitSingular == null) {
+						node.addError("Can't singularize this name; please specify the singular explicitly (i.e. @Singular(\"sheep\"))");
 						explicitSingular = new String(pluralName);
-					} else {
-						explicitSingular = autoSingularize(node.getName());
-						if (explicitSingular == null) {
-							node.addError("Can't singularize this name; please specify the singular explicitly (i.e. @Singular(\"sheep\"))");
-							explicitSingular = new String(pluralName);
-						}
 					}
 				}
-				char[] singularName = explicitSingular.toCharArray();
-				
-				TypeReference type = ((AbstractVariableDeclaration) node.get()).type;
-				TypeReference[] typeArgs = null;
-				String typeName;
-				if (type instanceof ParameterizedSingleTypeReference) {
-					typeArgs = ((ParameterizedSingleTypeReference) type).typeArguments;
-					typeName = new String(((ParameterizedSingleTypeReference) type).token);
-				} else if (type instanceof ParameterizedQualifiedTypeReference) {
-					TypeReference[][] tr = ((ParameterizedQualifiedTypeReference) type).typeArguments;
-					if (tr != null) typeArgs = tr[tr.length - 1];
-					char[][] tokens = ((ParameterizedQualifiedTypeReference) type).tokens;
-					StringBuilder sb = new StringBuilder();
-					for (int i = 0; i < tokens.length; i++) {
-						if (i > 0) sb.append(".");
-						sb.append(tokens[i]);
-					}
-					typeName = sb.toString();
-				} else {
-					typeName = type.toString();
-				}
-				
-				String targetFqn = EclipseSingularsRecipes.get().toQualified(typeName);
-				EclipseSingularizer singularizer = EclipseSingularsRecipes.get().getSingularizer(targetFqn);
-				if (singularizer == null) {
-					node.addError("Lombok does not know how to create the singular-form builder methods for type '" + typeName + "'; they won't be generated.");
-					return null;
+			}
+			char[] singularName = explicitSingular.toCharArray();
+			
+			TypeReference type = ((AbstractVariableDeclaration) node.get()).type;
+			TypeReference[] typeArgs = null;
+			String typeName;
+			if (type instanceof ParameterizedSingleTypeReference) {
+				typeArgs = ((ParameterizedSingleTypeReference) type).typeArguments;
+				typeName = new String(((ParameterizedSingleTypeReference) type).token);
+			} else if (type instanceof ParameterizedQualifiedTypeReference) {
+				TypeReference[][] tr = ((ParameterizedQualifiedTypeReference) type).typeArguments;
+				if (tr != null) typeArgs = tr[tr.length - 1];
+				char[][] tokens = ((ParameterizedQualifiedTypeReference) type).tokens;
+				StringBuilder sb = new StringBuilder();
+				for (int i = 0; i < tokens.length; i++) {
+					if (i > 0) sb.append(".");
+					sb.append(tokens[i]);
 				}
-				
-				return new SingularData(child, singularName, pluralName, typeArgs == null ? Collections.<TypeReference>emptyList() : Arrays.asList(typeArgs), targetFqn, singularizer, source);
+				typeName = sb.toString();
+			} else {
+				typeName = type.toString();
 			}
+			
+			String targetFqn = EclipseSingularsRecipes.get().toQualified(typeName);
+			EclipseSingularizer singularizer = EclipseSingularsRecipes.get().getSingularizer(targetFqn);
+			if (singularizer == null) {
+				node.addError("Lombok does not know how to create the singular-form builder methods for type '" + typeName + "'; they won't be generated.");
+				return null;
+			}
+			
+			return new SingularData(child, singularName, pluralName, typeArgs == null ? Collections.<TypeReference>emptyList() : Arrays.asList(typeArgs), targetFqn, singularizer, source);
 		}
 		
 		return null;
diff --git a/src/core/lombok/javac/handlers/HandleBuilder.java b/src/core/lombok/javac/handlers/HandleBuilder.java
index 7ef7b859..484a0b25 100644
--- a/src/core/lombok/javac/handlers/HandleBuilder.java
+++ b/src/core/lombok/javac/handlers/HandleBuilder.java
@@ -29,6 +29,7 @@ import org.mangosdk.spi.ProviderFor;
 import com.sun.tools.javac.code.Flags;
 import com.sun.tools.javac.tree.JCTree;
 import com.sun.tools.javac.tree.JCTree.JCAnnotation;
+import com.sun.tools.javac.tree.JCTree.JCArrayTypeTree;
 import com.sun.tools.javac.tree.JCTree.JCBlock;
 import com.sun.tools.javac.tree.JCTree.JCClassDecl;
 import com.sun.tools.javac.tree.JCTree.JCExpression;
@@ -49,6 +50,7 @@ import com.sun.tools.javac.util.Name;
 
 import lombok.AccessLevel;
 import lombok.Builder;
+import lombok.Builder.ObtainVia;
 import lombok.ConfigurationKeys;
 import lombok.Singular;
 import lombok.core.AST.Kind;
@@ -79,8 +81,11 @@ public class HandleBuilder extends JavacAnnotationHandler<Builder> {
 	
 	private static class BuilderFieldData {
 		JCExpression type;
+		Name rawName;
 		Name name;
 		SingularData singularData;
+		ObtainVia obtainVia;
+		JavacNode obtainViaNode;
 		
 		java.util.List<JavacNode> createdFields = new ArrayList<JavacNode>();
 	}
@@ -95,6 +100,9 @@ public class HandleBuilder extends JavacAnnotationHandler<Builder> {
 		String builderMethodName = builderInstance.builderMethodName();
 		String buildMethodName = builderInstance.buildMethodName();
 		String builderClassName = builderInstance.builderClassName();
+		String toBuilderMethodName = "toBuilder";
+		boolean toBuilder = builderInstance.toBuilder();
+		java.util.List<Name> typeArgsForToBuilder = null;
 		
 		if (builderMethodName == null) builderMethodName = "builder";
 		if (buildMethodName == null) buildMethodName = "build";
@@ -135,9 +143,11 @@ public class HandleBuilder extends JavacAnnotationHandler<Builder> {
 				// Value will only skip making a field final if it has an explicit @NonFinal annotation, so we check for that.
 				if (fd.init != null && valuePresent && !hasAnnotation(NonFinal.class, fieldNode)) continue;
 				BuilderFieldData bfd = new BuilderFieldData();
+				bfd.rawName = fd.name;
 				bfd.name = removePrefixFromField(fieldNode);
 				bfd.type = fd.vartype;
 				bfd.singularData = getSingularData(fieldNode);
+				addObtainVia(bfd, fieldNode);
 				builderFields.add(bfd);
 				allFields.append(fieldNode);
 			}
@@ -171,7 +181,8 @@ public class HandleBuilder extends JavacAnnotationHandler<Builder> {
 				annotationNode.addError("@Builder is only supported on types, constructors, and static methods.");
 				return;
 			}
-			returnType = jmd.restype;
+			JCExpression fullReturnType = jmd.restype;
+			returnType = fullReturnType;
 			typeParams = jmd.typarams;
 			thrownExceptions = jmd.thrown;
 			nameOfStaticBuilderMethod = jmd.name;
@@ -202,6 +213,70 @@ public class HandleBuilder extends JavacAnnotationHandler<Builder> {
 					builderClassName = td.name.toString() + "Builder";
 				}
 			}
+			if (toBuilder) {
+				final String TO_BUILDER_NOT_SUPPORTED = "@Builder(toBuilder=true) is only supported if you return your own type.";
+				if (returnType instanceof JCArrayTypeTree) {
+					annotationNode.addError(TO_BUILDER_NOT_SUPPORTED);
+					return;
+				}
+				
+				Name simpleName;
+				String pkg;
+				List<JCExpression> tpOnRet = List.nil();
+				
+				if (fullReturnType instanceof JCTypeApply) {
+					tpOnRet = ((JCTypeApply) fullReturnType).arguments;
+				}
+				
+				if (returnType instanceof JCIdent) {
+					simpleName = ((JCIdent) returnType).name;
+					pkg = null;
+				} else if (returnType instanceof JCFieldAccess) {
+					JCFieldAccess jcfa = (JCFieldAccess) returnType;
+					simpleName = jcfa.name;
+					pkg = unpack(jcfa.selected);
+					if (pkg.startsWith("ERR:")) {
+						String err = pkg.substring(4, pkg.indexOf("__ERR__"));
+						annotationNode.addError(err);
+						return;
+					}
+				} else {
+					annotationNode.addError("Expected a (parameterized) type here instead of a " + returnType.getClass().getName());
+					return;
+				}
+				
+				if (pkg != null && !parent.getPackageDeclaration().equals(pkg)) {
+					annotationNode.addError(TO_BUILDER_NOT_SUPPORTED);
+					return;
+				}
+				
+				if (!tdParent.getName().contentEquals(simpleName)) {
+					annotationNode.addError(TO_BUILDER_NOT_SUPPORTED);
+					return;
+				}
+				
+				List<JCTypeParameter> tpOnMethod = jmd.typarams;
+				List<JCTypeParameter> tpOnType = ((JCClassDecl) tdParent.get()).typarams;
+				typeArgsForToBuilder = new ArrayList<Name>();
+				
+				for (JCTypeParameter tp : tpOnMethod) {
+					int pos = -1;
+					int idx = -1;
+					for (JCExpression tOnRet : tpOnRet) {
+						idx++;
+						if (!(tOnRet instanceof JCIdent)) continue;
+						if (((JCIdent) tOnRet).name != tp.name) continue;
+						pos = idx;
+					}
+					
+					if (pos == -1 || tpOnType.size() <= pos) {
+						annotationNode.addError("**" + returnType.getClass().toString());
+//						annotationNode.addError("@Builder(toBuilder=true) requires that each type parameter on the static method is part of the typeargs of the return value. Type parameter " + tp.name + " is not part of the return type.");
+						return;
+					}
+					typeArgsForToBuilder.add(tpOnType.get(pos).name);
+				}
+			}
 		} else {
 			annotationNode.addError("@Builder is only supported on types, constructors, and static methods.");
 			return;
@@ -213,8 +288,10 @@ public class HandleBuilder extends JavacAnnotationHandler<Builder> {
 				BuilderFieldData bfd = new BuilderFieldData();
 				JCVariableDecl raw = (JCVariableDecl) param.get();
 				bfd.name = raw.name;
+				bfd.rawName = raw.name;
 				bfd.type = raw.vartype;
 				bfd.singularData = getSingularData(param);
+				addObtainVia(bfd, param);
 				builderFields.add(bfd);
 			}
 		}
@@ -245,6 +322,16 @@ public class HandleBuilder extends JavacAnnotationHandler<Builder> {
 					break;
 				}
 			}
+			if (bfd.obtainVia != null) {
+				if (bfd.obtainVia.field().isEmpty() == bfd.obtainVia.method().isEmpty()) {
+					bfd.obtainViaNode.addError("The syntax is either @ObtainVia(field = \"fieldName\") or @ObtainVia(method = \"methodName\").");
+					return;
+				}
+				if (bfd.obtainVia.method().isEmpty() && bfd.obtainVia.isStatic()) {
+					bfd.obtainViaNode.addError("@ObtainVia(isStatic = true) is not valid unless 'method' has been set.");
+					return;
+				}
+			}
 		}
 		
 		generateBuilderFields(builderType, builderFields, ast);
@@ -285,9 +372,95 @@ public class HandleBuilder extends JavacAnnotationHandler<Builder> {
 			if (md != null) injectMethod(tdParent, md);
 		}
 		
+		if (toBuilder) {
+			switch (methodExists(toBuilderMethodName, tdParent, 0)) {
+			case EXISTS_BY_USER:
+				annotationNode.addWarning("Not generating toBuilder() as it already exists.");
+				return;
+			case NOT_EXISTS:
+				List<JCTypeParameter> tps = typeParams;
+				if (typeArgsForToBuilder != null) {
+					ListBuffer<JCTypeParameter> lb = new ListBuffer<JCTypeParameter>();
+					JavacTreeMaker maker = tdParent.getTreeMaker();
+					for (Name n : typeArgsForToBuilder) {
+						lb.append(maker.TypeParameter(n, List.<JCExpression>nil()));
+					}
+					tps = lb.toList();
+				}
+				JCMethodDecl md = generateToBuilderMethod(toBuilderMethodName, builderClassName, tdParent, tps, builderFields, fluent, ast);
+				if (md != null) injectMethod(tdParent, md);
+			}
+		}
+		
 		recursiveSetGeneratedBy(builderType.get(), ast, annotationNode.getContext());
 	}
 	
+	private static String unpack(JCExpression expr) {
+		StringBuilder sb = new StringBuilder();
+		unpack(sb, expr);
+		return sb.toString();
+	}
+	
+	private static void unpack(StringBuilder sb, JCExpression expr) {
+		if (expr instanceof JCIdent) {
+			sb.append(((JCIdent) expr).name.toString());
+			return;
+		}
+		
+		if (expr instanceof JCFieldAccess) {
+			JCFieldAccess jcfa = (JCFieldAccess) expr;
+			unpack(sb, jcfa.selected);
+			sb.append(".").append(jcfa.name.toString());
+			return;
+		}
+		
+		if (expr instanceof JCTypeApply) {
+			sb.setLength(0);
+			sb.append("ERR:");
+			sb.append("@Builder(toBuilder=true) is not supported if returning a type with generics applied to an intermediate.");
+			sb.append("__ERR__");
+			return;
+		}
+		
+		sb.setLength(0);
+		sb.append("ERR:");
+		sb.append("Expected a type of some sort, not a " + expr.getClass().getName());
+		sb.append("__ERR__");
+	}
+	
+	private JCMethodDecl generateToBuilderMethod(String toBuilderMethodName, String builderClassName, JavacNode type, List<JCTypeParameter> typeParams, java.util.List<BuilderFieldData> builderFields, boolean fluent, JCAnnotation ast) {
+		// return new ThingieBuilder<A, B>().setA(this.a).setB(this.b);
+		JavacTreeMaker maker = type.getTreeMaker();
+		
+		ListBuffer<JCExpression> typeArgs = new ListBuffer<JCExpression>();
+		for (JCTypeParameter typeParam : typeParams) {
+			typeArgs.append(maker.Ident(typeParam.name));
+		}
+		
+		JCExpression call = maker.NewClass(null, List.<JCExpression>nil(), namePlusTypeParamsToTypeReference(maker, type.toName(builderClassName), typeParams), List.<JCExpression>nil(), null);
+		JCExpression invoke = call;
+		for (BuilderFieldData bfd : builderFields) {
+			Name setterName = fluent ? bfd.name : type.toName(HandlerUtil.buildAccessorName("set", bfd.name.toString()));
+			JCExpression arg;
+			if (bfd.obtainVia == null || !bfd.obtainVia.field().isEmpty()) {
+				arg = maker.Select(maker.Ident(type.toName("this")), bfd.obtainVia == null ? bfd.rawName : type.toName(bfd.obtainVia.field()));
+			} else {
+				if (bfd.obtainVia.isStatic()) {
+					JCExpression c = maker.Select(maker.Ident(type.toName(type.getName())), type.toName(bfd.obtainVia.method()));
+					arg = maker.Apply(List.<JCExpression>nil(), c, List.<JCExpression>of(maker.Ident(type.toName("this"))));
+				} else {
+					JCExpression c = maker.Select(maker.Ident(type.toName("this")), type.toName(bfd.obtainVia.method()));
+					arg = maker.Apply(List.<JCExpression>nil(), c, List.<JCExpression>nil());
+				}
+			}
+			invoke = maker.Apply(List.<JCExpression>nil(), maker.Select(invoke, setterName), List.of(arg));
+		}
+		JCStatement statement = maker.Return(invoke);
+		
+		JCBlock body = maker.Block(0, List.<JCStatement>of(statement));
+		return maker.MethodDef(maker.Modifiers(Flags.PUBLIC), type.toName(toBuilderMethodName), namePlusTypeParamsToTypeReference(maker, type.toName(builderClassName), typeParams), List.<JCTypeParameter>nil(), List.<JCVariableDecl>nil(), List.<JCExpression>nil(), body, null);
+	}
+	
 	private JCMethodDecl generateCleanMethod(java.util.List<BuilderFieldData> builderFields, JavacNode type, JCTree source) {
 		JavacTreeMaker maker = type.getTreeMaker();
 		ListBuffer<JCStatement> statements = new ListBuffer<JCStatement>();
@@ -449,6 +622,17 @@ public class HandleBuilder extends JavacAnnotationHandler<Builder> {
 		return injectType(tdParent, builder);
 	}
 	
+	private void addObtainVia(BuilderFieldData bfd, JavacNode node) {
+		for (JavacNode child : node.down()) {
+			if (!annotationTypeMatches(ObtainVia.class, child)) continue;
+			AnnotationValues<ObtainVia> ann = createAnnotation(ObtainVia.class, child);
+			bfd.obtainVia = ann.getInstance();
+			bfd.obtainViaNode = child;
+			deleteAnnotationIfNeccessary(child, ObtainVia.class);
+			return;
+		}
+	}
+	
 	/**
 	 * Returns the explicitly requested singular annotation on this node (field
 	 * or parameter), or null if there's no {@code @Singular} annotation on it.
@@ -457,48 +641,47 @@ public class HandleBuilder extends JavacAnnotationHandler<Builder> {
 	 */
 	private SingularData getSingularData(JavacNode node) {
 		for (JavacNode child : node.down()) {
-			if (child.getKind() == Kind.ANNOTATION && annotationTypeMatches(Singular.class, child)) {
-				Name pluralName = node.getKind() == Kind.FIELD ? removePrefixFromField(node) : ((JCVariableDecl) node.get()).name;
-				AnnotationValues<Singular> ann = createAnnotation(Singular.class, child);
-				deleteAnnotationIfNeccessary(child, Singular.class);
-				String explicitSingular = ann.getInstance().value();
-				if (explicitSingular.isEmpty()) {
-					if (Boolean.FALSE.equals(node.getAst().readConfiguration(ConfigurationKeys.SINGULAR_AUTO))) {
-						node.addError("The singular must be specified explicitly (e.g. @Singular(\"task\")) because auto singularization is disabled.");
+			if (!annotationTypeMatches(Singular.class, child)) continue;
+			Name pluralName = node.getKind() == Kind.FIELD ? removePrefixFromField(node) : ((JCVariableDecl) node.get()).name;
+			AnnotationValues<Singular> ann = createAnnotation(Singular.class, child);
+			deleteAnnotationIfNeccessary(child, Singular.class);
+			String explicitSingular = ann.getInstance().value();
+			if (explicitSingular.isEmpty()) {
+				if (Boolean.FALSE.equals(node.getAst().readConfiguration(ConfigurationKeys.SINGULAR_AUTO))) {
+					node.addError("The singular must be specified explicitly (e.g. @Singular(\"task\")) because auto singularization is disabled.");
+					explicitSingular = pluralName.toString();
+				} else {
+					explicitSingular = autoSingularize(node.getName());
+					if (explicitSingular == null) {
+						node.addError("Can't singularize this name; please specify the singular explicitly (i.e. @Singular(\"sheep\"))");
 						explicitSingular = pluralName.toString();
-					} else {
-						explicitSingular = autoSingularize(node.getName());
-						if (explicitSingular == null) {
-							node.addError("Can't singularize this name; please specify the singular explicitly (i.e. @Singular(\"sheep\"))");
-							explicitSingular = pluralName.toString();
-						}
 					}
 				}
-				Name singularName = node.toName(explicitSingular);
-				
-				JCExpression type = null;
-				if (node.get() instanceof JCVariableDecl) {
-					type = ((JCVariableDecl) node.get()).vartype;
-				}
-				
-				String name = null;
-				List<JCExpression> typeArgs = List.nil();
-				if (type instanceof JCTypeApply) {
-					typeArgs = ((JCTypeApply) type).arguments;
-					type = ((JCTypeApply) type).clazz;
-				}
-				
-				name = type.toString();
-				
-				String targetFqn = JavacSingularsRecipes.get().toQualified(name);
-				JavacSingularizer singularizer = JavacSingularsRecipes.get().getSingularizer(targetFqn);
-				if (singularizer == null) {
-					node.addError("Lombok does not know how to create the singular-form builder methods for type '" + name + "'; they won't be generated.");
-					return null;
-				}
-				
-				return new SingularData(child, singularName, pluralName, typeArgs, targetFqn, singularizer);
 			}
+			Name singularName = node.toName(explicitSingular);
+			
+			JCExpression type = null;
+			if (node.get() instanceof JCVariableDecl) {
+				type = ((JCVariableDecl) node.get()).vartype;
+			}
+			
+			String name = null;
+			List<JCExpression> typeArgs = List.nil();
+			if (type instanceof JCTypeApply) {
+				typeArgs = ((JCTypeApply) type).arguments;
+				type = ((JCTypeApply) type).clazz;
+			}
+			
+			name = type.toString();
+			
+			String targetFqn = JavacSingularsRecipes.get().toQualified(name);
+			JavacSingularizer singularizer = JavacSingularsRecipes.get().getSingularizer(targetFqn);
+			if (singularizer == null) {
+				node.addError("Lombok does not know how to create the singular-form builder methods for type '" + name + "'; they won't be generated.");
+				return null;
+			}
+			
+			return new SingularData(child, singularName, pluralName, typeArgs, targetFqn, singularizer);
 		}
 		
 		return null;