Add support for named arguments to CodeBlock

Relative and positional arguments are fine for small statements, but
larger code blocks benefit from having named arguments.

https://github.com/square/javapoet/issues/518

1 files changed, 45 insertions, 9 deletions

diff --git a/README.md b/README.md
index 539d8de..9ee7d61 100644
--- a/README.md
+++ b/README.md
@@ -166,10 +166,10 @@ public static void main(String[] args) throws Exception {
       .addMethod(whatsMyName("eminem"))
       .addMethod(whatsMyName("marshallMathers"))
       .build();
-      
+
   JavaFile javaFile = JavaFile.builder("com.example.helloworld", helloWorld)
       .build();
-      
+
   javaFile.writeTo(System.out);
 }
 
@@ -210,15 +210,15 @@ MethodSpec today = MethodSpec.methodBuilder("today")
     .returns(Date.class)
     .addStatement("return new $T()", Date.class)
     .build();
-    
+
 TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
     .addModifiers(Modifier.PUBLIC, Modifier.FINAL)
     .addMethod(today)
     .build();
-    
+
 JavaFile javaFile = JavaFile.builder("com.example.helloworld", helloWorld)
     .build();
-    
+
 javaFile.writeTo(System.out);
 ```
 
@@ -387,7 +387,7 @@ MethodSpec hexDigit = MethodSpec.methodBuilder("hexDigit")
     .returns(char.class)
     .addStatement("return (char) (i < 10 ? i + '0' : i - 10 + 'a')")
     .build();
-    
+
 MethodSpec byteToHex = MethodSpec.methodBuilder("byteToHex")
     .addParameter(int.class, "b")
     .returns(String.class)
@@ -398,6 +398,42 @@ MethodSpec byteToHex = MethodSpec.methodBuilder("byteToHex")
     .build();
 ```
 
+### Code block format strings
+
+Code blocks may specify the values for their placeholders in a few ways. Only one style may be used
+for each operation on a code block.
+
+#### Relative Arguments
+
+Pass an argument value for each placeholder in the format string to `CodeBlock.add()`. In each
+example, we generate code to say "I ate 3 tacos"
+
+```java
+CodeBlock.builder().add("I ate $L $L", 3, "tacos")
+```
+
+#### Positional Arguments
+
+Place an integer index (1-based) before the placeholder in the format string to specify which
+ argument to use.
+
+```java
+CodeBlock.builder().add("I ate $2L $1L", "tacos", 3)
+```
+
+#### Named Arguments
+
+Use the syntax `$argumentName:X` where `X` is the format character and call `CodeBlock.addNamed()`
+with a map containing all argument keys in the format string. Argument names use characters in
+`a-z`, `A-Z`, `0-9`, and `_`, and must start with a lowercase character.
+
+```java
+Map<String, Object> map = new LinkedHashMap<>();
+map.put("food", "tacos");
+map.put("count", 3);
+CodeBlock.builder().addNamed("I ate $count:L $food:L", map)
+```
+
 ### Methods
 
 All of the above methods have a code body. Use `Modifiers.ABSTRACT` to get a method without any
@@ -407,7 +443,7 @@ body. This is only legal if the enclosing class is either abstract or an interfa
 MethodSpec flux = MethodSpec.methodBuilder("flux")
     .addModifiers(Modifier.ABSTRACT, Modifier.PROTECTED)
     .build();
-    
+
 TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
     .addModifiers(Modifier.PUBLIC, Modifier.ABSTRACT)
     .addMethod(flux)
@@ -440,7 +476,7 @@ MethodSpec flux = MethodSpec.constructorBuilder()
     .addParameter(String.class, "greeting")
     .addStatement("this.$N = $N", "greeting", "greeting")
     .build();
-    
+
 TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
     .addModifiers(Modifier.PUBLIC)
     .addField(String.class, "greeting", Modifier.PRIVATE, Modifier.FINAL)
@@ -497,7 +533,7 @@ Like parameters, fields can be created either with builders or by using convenie
 FieldSpec android = FieldSpec.builder(String.class, "android")
     .addModifiers(Modifier.PRIVATE, Modifier.FINAL)
     .build();
-    
+
 TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
     .addModifiers(Modifier.PUBLIC)
     .addField(android)