Package software.amazon.smithy.utils

Class CodeWriter

  • public class CodeWriter
extends java.lang.Object
    Helper class for generating code.

    A CodeWriter can be used to write basically any kind of code, including whitespace sensitive and brace-based.

    The following example generates some Python code: 

    
 CodeWriter writer = CodeWriter.createDefault();
 writer.write("def Foo(str):")
       .indent()
       .write("print str");
 String code = writer.toString();

    Code interpolation

    The write(java.lang.Object, java.lang.Object...), openBlock(java.lang.String, java.lang.Object...), and closeBlock(java.lang.String, java.lang.Object...) methods take a code expression and a variadic list of arguments that are interpolated into the expression. Consider the following call to write: 

    
 CodeWriter writer = CodeWriter.createDefault();
 writer.write("Hello, $L", "there!");
 String code = writer.toString();

    In the above example, $L is interpolated and replaced with the relative argument there!.

    A CodeWriter supports three kinds of interpolations: relative, positional, and named. Each of these kinds of interpolations pass a value to a formatter.

    Formatters

    Formatters are named functions that accept an object as input, accepts a string that contains the current indentation (it can be ignored if not useful), and returns a string as output. The CodeWriter registers two built-in formatters:

    • L: Outputs a literal value of an Object using the following implementation: (1) A null value is formatted as "". (2) An empty Optional value is formatted as "". (3) A non-empty Optional value is recursively formatted using the value inside of the Optional. (3) All other valeus are formatted using the result of calling String.valueOf(java.lang.Object).
    • S: Adds double quotes around the result of formatting a value first using the default literal "L" implementation described above and then wrapping the value in an escaped string safe for use in Java according to https://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.10.6. This formatter can be overridden if needed to support other programming languages.

    Custom formatters can be registered using putFormatter(char, java.util.function.BiFunction<java.lang.Object, java.lang.String, java.lang.String>). The identifier given to a formatter must match the following ABNF: 

     %x21-23    ; ( '!' - '#' )
 / %x25-2F  ; ( '%' - '/' )
 / %x3A-60  ; ( ':' - '`' )
 / %x7B-7E  ; ( '{' - '~' )

    Relative parameters

    Placeholders in the form of "$" followed by a formatter name are treated as relative parameters. The first instance of a relative parameter interpolates the first positional argument, the second the second, etc. 

    
 CodeWriter writer = CodeWriter.createDefault();
 writer.write("$L $L $L", "a", "b", "c");
 System.out.println(writer.toString());
 // Outputs: "a b c"

    All relative arguments must be used as part of an expression and relative interpolation cannot be mixed with positional variables.

    Positional parameters

    Placeholders in the form of "$" followed by a positive number, followed by a formatter name are treated as positional parameters. The number refers to the 1-based index of the argument to interpolate. 

    
 CodeWriter writer = CodeWriter.createDefault();
 writer.write("$1L $2L $3L, $3L $2L $1L", "a", "b", "c");
 System.out.println(writer.toString());
 // Outputs: "a b c c b a"

    All positional arguments must be used as part of an expression and relative interpolation cannot be mixed with positional variables.

    Named parameters

    Named parameters are parameters that take a value from the context of the current state. They take the following form $<variable>:<formatter>, where <variable> is a string that starts with a lowercase letter, followed by any number of [A-Za-z0-9_#$.] characters, and <formatter> is the name of a formatter. 

    
 CodeWriter writer = CodeWriter.createDefault();
 writer.putContext("foo", "a");
 writer.putContext("baz.bar", "b");
 writer.write("$foo:L $baz.bar:L");
 System.out.println(writer.toString());
 // Outputs: "a b"

    Escaping interpolation

    You can escape the "$" character using two "$$". 

    
 CodeWriter writer = new CodeWriter().write("$$L");
 System.out.println(writer.toString());
 // Outputs: "$L"

    Opening and closing blocks

    CodeWriter provides a short cut for opening code blocks that that have an opening an closing delimiter (for example, "{" and "}") and that require indentation inside of the delimiters. Calling openBlock(java.lang.String, java.lang.Object...) and providing the opening statement will write and format a line followed by indenting one level. Calling closeBlock(java.lang.String, java.lang.Object...) will first dedent and then print a formatted statement. 

    
 CodeWriter writer = CodeWriter.createDefault()
       .openBlock("if ($L) {", someValue)
       .write("System.out.println($S);", "Hello!")
       .closeBlock("}");

    The above example outputs (assuming someValue is equal to "foo"): 

    
 if (foo) {
     System.out.println("Hello!");
 }

    Pushing and popping state

    The CodeWriter can maintain a stack of transformation states, including the text used to indent, a prefix to add before each line, the number of times to indent, a map of context values, and whether or not whitespace is trimmed from the end of newlines. State can be pushed onto the stack using pushState() which copies the current state. Mutations can then be made to the top-most state of the CodeWriter and do not affect previous states. The previous transformation state of the CodeWriter can later be restored using popState().

    The CodeWriter is stateful, and a prefix can be added before each line. This is useful for doing things like create Javadoc strings: 

    
 CodeWriter writer = CodeWriter.createDefault();
 writer
       .pushState()
       .write("/**")
       .setNewlinePrefix(" * ")
       .write("This is some docs.")
       .write("And more docs.\n\n\n")
       .write("Foo.")
       .popState()
       .write(" *\/");

    The above example outputs: 

    
 /**
  * This is some docs.
  * And more docs.
  *
  * Foo.
  *\/

   ^ Minus this escape character

    The CodeWriter maintains some global state that is not affected by pushState() and popState():

    Limiting blank lines

    Many coding standards recommend limiting the number of successive blank lines. This can be handled automatically by CodeWriter by calling trimBlankLines. The removal of blank lines is handled when the CodeWriter is converted to a string. Lines that consist solely of spaces or tabs are considered blank. If the number of blank lines exceeds the allowed threshold, they are omitted from the result.

    Trimming trailing spaces

    Trailing spaces can be automatically trimmed from each line by calling trimTrailingSpaces().

    In the the following example: 

    
 CodeWriter writer = CodeWriter.createDefault();
 String result = writer.trimTrailingSpaces().write("hello  ").toString();

    The value of result contains "hello"

    Extending CodeWriter

    CodeWriter can be extended to add functionality for specific programming languages. For example, Java specific code generator could be implemented that makes it easier to write Javadocs. 

    
 class JavaCodeWriter extends CodeWriter {
     public JavaCodeWriter javadoc(Runnable runnable) {
         pushState()
         write("/**")
         setNewlinePrefix(" * ")
         runnable.run();
         popState()
         write(" *\/");
         return this;
     }
 }

 JavaCodeWriter writer = new JavaCodeWriter();
 writer.javadoc(() -> {
     writer.write("This is an example.");
 });

    Code sections

    Named sections can be marked in the code writer that can be intercepted and modified by section interceptors. This gives the CodeWriter a lightweight extension system for augmenting generated code.

    A section of code can be captured using a block state or an inline section. Section names must match the following regular expression: ^[a-z]+[a-zA-Z0-9_.#$]*$.

    Block states

    A block section is created by passing a string to pushState(). This string gives the state a name and captures all of the output written inside of this state to an internal buffer. This buffer is then passed to each registered interceptor for that name. These interceptors can choose to use the default contents of the section or emit entirely different content. Interceptors are expected to make calls to the CodeWriter in order to emit content. Interceptors need to have a reference to the CodeWriter as one is not provided to them when they are invoked. Interceptors are invoked in the order in which they are added to the CodeBuilder. 

    
 CodeWriter writer = CodeWriter.createDefault();
 writer.onSection("example", text -> writer.write("Intercepted: " + text));
 writer.pushState("example");
 writer.write("Original contents");
 writer.popState();
 System.out.println(writer.toString());
 // Outputs: "Intercepted: Original contents\n"

    Inline sections

    An inline section is created using a special CodeWriter interpolation format that appends "@" followed by the section name. Inline sections are function just like block sections, but they can appear inline inside of other content passed in calls to write(java.lang.Object, java.lang.Object...). An inline section that makes no calls to write(java.lang.Object, java.lang.Object...) expands to an empty string.

    Inline sections are created in a format string inside of braced arguments after the formatter. For example, ${L@foo} is an inline section that uses the literal "L" value of a relative argument as the default value of the section and allows interceptors registered for the "foo" section to make calls to the CodeWriter to modify the section. 

    
 CodeWriter writer = CodeWriter.createDefault();
 writer.onSection("example", text -> writer.write("Intercepted: " + text));
 writer.write("Leading text...${L@example}...Trailing text...", "foo");
 System.out.println(writer.toString());
 // Outputs: "Leading text...Intercepted: foo...Trailing text...\n"

    • Constructor Summary

      Constructors 
      Constructor Description
      CodeWriter()
      Creates a new CodeWriter that uses "\n" for a newline, four spaces for indentation, does not strip trailing whitespace, does not flatten multiple successive blank lines into a single blank line, and adds no trailing new line.

    • Method Summary

      Modifier and Type Method Description
      CodeWriter call​(java.lang.Runnable task)
      Allows calling out to arbitrary code for things like looping or conditional writes without breaking method chaining.
      CodeWriter closeBlock​(java.lang.String textAfterNewline, java.lang.Object... args)
      Closes a block of syntax by writing a newline, dedenting, then writing text.
      static CodeWriter createDefault()
      Creates a default instance of a CodeWriter that uses "\n" for newlines, flattens multiple successive blank lines into a single blank line, and adds a trailing new line if needed when converting the CodeWriter to a string.
      CodeWriter dedent()
      Removes one level of indentation from all lines.
      CodeWriter dedent​(int levels)
      Removes a specific number of indentations from all lines.
      static java.lang.String formatLiteral​(java.lang.Object value)
      Provides the default functionality for formatting literal values.
      java.lang.Object getContext​(java.lang.String key)
      Gets a named contextual key-value pair from the current state.
      CodeWriter indent()
      Indents all text one level.
      CodeWriter indent​(int levels)
      Indents all text a specific number of levels.
      CodeWriter insertTrailingNewline()
      Configures the CodeWriter to always append a newline at the end of the text if one is not already present.
      CodeWriter insertTrailingNewline​(boolean trailingNewline)
      Configures the CodeWriter to always append a newline at the end of the text if one is not already present.
      CodeWriter onSection​(java.lang.String sectionName, java.util.function.Consumer<java.lang.Object> interceptor)
      Registers a function that intercepts the contents of a section and the current context map and writes to the CodeWriter with the updated contents.
      CodeWriter openBlock​(java.lang.String textBeforeNewline, java.lang.Object... args)
      Opens a block of syntax by writing text, a newline, then indenting.
      CodeWriter openBlock​(java.lang.String textBeforeNewline, java.lang.String textAfterNewline, java.lang.Object[] args, java.lang.Runnable f)
      Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
      CodeWriter openBlock​(java.lang.String textBeforeNewline, java.lang.String textAfterNewline, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3, java.lang.Object arg4, java.lang.Object arg5, java.lang.Runnable f)
      Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
      CodeWriter openBlock​(java.lang.String textBeforeNewline, java.lang.String textAfterNewline, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3, java.lang.Object arg4, java.lang.Runnable f)
      Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
      CodeWriter openBlock​(java.lang.String textBeforeNewline, java.lang.String textAfterNewline, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3, java.lang.Runnable f)
      Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
      CodeWriter openBlock​(java.lang.String textBeforeNewline, java.lang.String textAfterNewline, java.lang.Object arg1, java.lang.Object arg2, java.lang.Runnable f)
      Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
      CodeWriter openBlock​(java.lang.String textBeforeNewline, java.lang.String textAfterNewline, java.lang.Object arg1, java.lang.Runnable f)
      Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
      CodeWriter openBlock​(java.lang.String textBeforeNewline, java.lang.String textAfterNewline, java.lang.Runnable f)
      Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
      CodeWriter popState()
      Pops the current CodeWriter state from the state stack.
      CodeWriter pushState()
      Copies and pushes the current state to the state stack.
      CodeWriter pushState​(java.lang.String sectionName)
      Copies and pushes the current state to the state stack using a named state that can be intercepted by functions registered with onSection(java.lang.String, java.util.function.Consumer<java.lang.Object>).
      CodeWriter putContext​(java.lang.String key, java.lang.Object value)
      Adds a named key-value pair to the context of the current state.
      CodeWriter putContext​(java.util.Map<java.lang.String,​java.lang.Object> mappings)
      Adds a map of named key-value pair to the context of the current state.
      CodeWriter putFormatter​(char identifier, java.util.function.BiFunction<java.lang.Object,​java.lang.String,​java.lang.String> formatter)
      Adds a custom formatter expression to the CodeWriter.
      CodeWriter removeContext​(java.lang.String key)
      Removes a named key-value pair from the context of the current state.
      CodeWriter setIndentText​(java.lang.String indentText)
      Sets the text used for indentation (defaults to four spaces).
      CodeWriter setNewline​(java.lang.String newline)
      Sets the character that represents newlines ("\n" is the default).
      CodeWriter setNewlinePrefix​(java.lang.String newlinePrefix)
      Sets a prefix to prepend to every line after a new line is added (except for an inserted trailing newline).
      java.lang.String toString()
      Gets the contents of the generated code.
      CodeWriter trimBlankLines()
      Ensures that no more than one blank line occurs in succession.
      CodeWriter trimBlankLines​(int trimBlankLines)
      Ensures that no more than the given number of newlines can occur in succession, removing consecutive newlines that exceed the given threshold.
      CodeWriter trimTrailingSpaces()
      Enables the trimming of trailing spaces on a line.
      CodeWriter trimTrailingSpaces​(boolean trimTrailingSpaces)
      Configures if trailing spaces on a line are removed.
      CodeWriter write​(java.lang.Object content, java.lang.Object... args)
      Writes text to the CodeWriter and appends a newline.
      CodeWriter writeInline​(java.lang.Object content, java.lang.Object... args)
      Writes text to the CodeWriter without appending a newline or prefixing indentation.
      CodeWriter writeOptional​(java.lang.Object content)
      Optionally writes text to the CodeWriter and appends a newline if a value is present.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • CodeWriter

        public CodeWriter()
        Creates a new CodeWriter that uses "\n" for a newline, four spaces for indentation, does not strip trailing whitespace, does not flatten multiple successive blank lines into a single blank line, and adds no trailing new line.

    • Method Detail

      • createDefault

        public static CodeWriter createDefault()
        Creates a default instance of a CodeWriter that uses "\n" for newlines, flattens multiple successive blank lines into a single blank line, and adds a trailing new line if needed when converting the CodeWriter to a string.
        Returns:
        Returns the created and configured CodeWriter.

      • formatLiteral

        public static java.lang.String formatLiteral​(java.lang.Object value)
        Provides the default functionality for formatting literal values.

        This formatter is registered by default as the literal "L" formatter, and is called in the default string "S" formatter before escaping any characters in the string.

        • null: Formatted as an empty string.
        • Empty Optional: Formatted as an empty string.
        • Optional with value: Formatted as the formatted value in the optional.
        • Everything else: Formatted as the result of String.valueOf(java.lang.Object).
        Parameters:
        value - Value to format.
        Returns:
        Returns the formatted value.

      • putFormatter

        public final CodeWriter putFormatter​(char identifier,
                                     java.util.function.BiFunction<java.lang.Object,​java.lang.String,​java.lang.String> formatter)
        Adds a custom formatter expression to the CodeWriter.

        The provided identifier string must match the following ABNF: 

         %x21-23    ; ( '!' - '#' )
 / %x25-2F  ; ( '%' - '/' )
 / %x3A-60  ; ( ':' - '`' )
 / %x7B-7E  ; ( '{' - '~' )
        Parameters:
        identifier - Formatter identifier to associate with this formatter.
        formatter - Formatter function that formats the given object as a String.
        Returns:
        Returns the CodeWriter.

      • toString

        public java.lang.String toString()
        Gets the contents of the generated code.

        The result will have an appended newline if the CodeWriter is configured to always append a newline. A newline is only appended in these cases if the result does not already end with a newline.

        Overrides:
        toString in class java.lang.Object
        Returns:
        Returns the generated code.

      • pushState

        public final CodeWriter pushState()
        Copies and pushes the current state to the state stack.

        This method is used to prepare for a corresponding popState() operation later. It stores the current state of the CodeWriter into a stack and keeps it active. After pushing, mutations can be made to the state of the CodeWriter without affecting the previous state on the stack. Changes to the state of the CodeWriter can be undone by using popState(), which returns the CodeWriter state to the state it was in before calling pushState.

        Returns:
        Returns the code writer.

      • pushState

        public CodeWriter pushState​(java.lang.String sectionName)
        Copies and pushes the current state to the state stack using a named state that can be intercepted by functions registered with onSection(java.lang.String, java.util.function.Consumer<java.lang.Object>).

        The text written while in this state is buffered and passed to each state interceptor. If no text is written by the section or an interceptor, nothing is changed on the CodeWriter. This behavior allows for placeholder sections to be added into CodeWriter generators in order to provide extension points that can be otherwise empty.

        Parameters:
        sectionName - Name of the section to set on the state.
        Returns:
        Returns the code writer.

      • popState

        public CodeWriter popState()
        Pops the current CodeWriter state from the state stack.

        This method is used to reverse a previous pushState() operation. It configures the current CodeWriter state to what it was before the last preceding pushState call.

        Returns:
        Returns the CodeWriter.
        Throws:
        java.lang.IllegalStateException - if there a no states to pop.

      • onSection

        public CodeWriter onSection​(java.lang.String sectionName,
                            java.util.function.Consumer<java.lang.Object> interceptor)
        Registers a function that intercepts the contents of a section and the current context map and writes to the CodeWriter with the updated contents.

        These section interceptors provide a simple hook system for CodeWriters that add extension points when generating code. The function has the ability to completely ignore the original contents of the section, to prepend text to it, and append text to it. Intercepting functions are expected to have a reference to the CodeWriter and to mutate it when they are invoked. Each interceptor is invoked it their own isolated pushed/popped states.

        Interceptors are registered on the current state of the CodeWriter. When the state to which an interceptor is registered is popped, the interceptor is no longer in effect.

        The text provided to the intercepting function does not contain a trailing new line. A trailing new line will be injected automatically when the results of intercepting the contents are written to the CodeWriter. A result is only written if the interceptors write a non-null, non-empty string, allowing for empty placeholders to be added that don't affect the resulting layout of the code.

        Parameters:
        sectionName - The name of the section to intercept.
        interceptor - The function to intercept with.
        Returns:
        Returns the CodeWriter.

      • setNewline

        public final CodeWriter setNewline​(java.lang.String newline)
        Sets the character that represents newlines ("\n" is the default).
        Parameters:
        newline - Newline character to use.
        Returns:
        Returns the CodeWriter.

      • setIndentText

        public final CodeWriter setIndentText​(java.lang.String indentText)
        Sets the text used for indentation (defaults to four spaces).
        Parameters:
        indentText - Indentation text.
        Returns:
        Returns the CodeWriter.

      • trimTrailingSpaces

        public final CodeWriter trimTrailingSpaces()
        Enables the trimming of trailing spaces on a line.
        Returns:
        Returns the CodeWriter.

      • trimTrailingSpaces

        public final CodeWriter trimTrailingSpaces​(boolean trimTrailingSpaces)
        Configures if trailing spaces on a line are removed.
        Parameters:
        trimTrailingSpaces - Set to true to trim trailing spaces.
        Returns:
        Returns the CodeWriter.

      • trimBlankLines

        public final CodeWriter trimBlankLines()
        Ensures that no more than one blank line occurs in succession.
        Returns:
        Returns the CodeWriter.

      • trimBlankLines

        public final CodeWriter trimBlankLines​(int trimBlankLines)
        Ensures that no more than the given number of newlines can occur in succession, removing consecutive newlines that exceed the given threshold.
        Parameters:
        trimBlankLines - Number of allowed consecutive newlines. Set to -1 to perform no trimming. Set to 0 to allow no blank lines. Set to 1 or more to allow for no more than N consecutive blank lines.
        Returns:
        Returns the CodeWriter.

      • insertTrailingNewline

        public final CodeWriter insertTrailingNewline()
        Configures the CodeWriter to always append a newline at the end of the text if one is not already present.

        This setting is not captured as part of push/popState.

        Returns:
        Returns the CodeWriter.

      • insertTrailingNewline

        public final CodeWriter insertTrailingNewline​(boolean trailingNewline)
        Configures the CodeWriter to always append a newline at the end of the text if one is not already present.

        This setting is not captured as part of push/popState.

        Parameters:
        trailingNewline - The newline behavior. True to add, false to strip.
        Returns:
        Returns the CodeWriter.

      • setNewlinePrefix

        public final CodeWriter setNewlinePrefix​(java.lang.String newlinePrefix)
        Sets a prefix to prepend to every line after a new line is added (except for an inserted trailing newline).
        Parameters:
        newlinePrefix - Newline prefix to use.
        Returns:
        Returns the CodeWriter.

      • indent

        public final CodeWriter indent()
        Indents all text one level.
        Returns:
        Returns the CodeWriter.

      • indent

        public final CodeWriter indent​(int levels)
        Indents all text a specific number of levels.
        Parameters:
        levels - Number of levels to indent.
        Returns:
        Returns the CodeWriter.

      • dedent

        public final CodeWriter dedent()
        Removes one level of indentation from all lines.
        Returns:
        Returns the CodeWriter.

      • dedent

        public final CodeWriter dedent​(int levels)
        Removes a specific number of indentations from all lines.

        Set to -1 to dedent back to 0 (root).

        Parameters:
        levels - Number of levels to remove.
        Returns:
        Returns the CodeWriter.
        Throws:
        java.lang.IllegalStateException - when trying to dedent too far.

      • openBlock

        public final CodeWriter openBlock​(java.lang.String textBeforeNewline,
                                  java.lang.Object... args)
        Opens a block of syntax by writing text, a newline, then indenting. 
         
 String result = CodeWriter.createDefault()
         .openBlock("public final class $L {", "Foo")
             .openBlock("public void main(String[] args) {")
                 .write("System.out.println(args[0]);")
             .closeBlock("}")
         .closeBlock("}")
         .toString();
        Parameters:
        textBeforeNewline - Text to write before writing a newline and indenting.
        args - String arguments to use for formatting.
        Returns:
        Returns the CodeWriter.

      • openBlock

        public final CodeWriter openBlock​(java.lang.String textBeforeNewline,
                                  java.lang.String textAfterNewline,
                                  java.lang.Runnable f)
        Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline. 
        
 CodeWriter writer = CodeWriter.createDefault();
 writer.openBlock("public final class $L {", "}", "Foo", () -> {
     writer.openBlock("public void main(String[] args) {", "}", () -> {
         writer.write("System.out.println(args[0]);");
     })
 });
        Parameters:
        textBeforeNewline - Text to write before writing a newline and indenting.
        textAfterNewline - Text to write after writing a newline and indenting.
        f - Runnable function to execute inside of the block.
        Returns:
        Returns the CodeWriter.

      • openBlock

        public final CodeWriter openBlock​(java.lang.String textBeforeNewline,
                                  java.lang.String textAfterNewline,
                                  java.lang.Object arg1,
                                  java.lang.Runnable f)
        Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
        Parameters:
        textBeforeNewline - Text to write before writing a newline and indenting.
        textAfterNewline - Text to write after writing a newline and indenting.
        arg1 - First positional argument to substitute into textBeforeNewline.
        f - Runnable function to execute inside of the block.
        Returns:
        Returns the CodeWriter.

      • openBlock

        public final CodeWriter openBlock​(java.lang.String textBeforeNewline,
                                  java.lang.String textAfterNewline,
                                  java.lang.Object arg1,
                                  java.lang.Object arg2,
                                  java.lang.Runnable f)
        Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
        Parameters:
        textBeforeNewline - Text to write before writing a newline and indenting.
        textAfterNewline - Text to write after writing a newline and indenting.
        arg1 - First positional argument to substitute into textBeforeNewline.
        arg2 - Second positional argument to substitute into textBeforeNewline.
        f - Runnable function to execute inside of the block.
        Returns:
        Returns the CodeWriter.

      • openBlock

        public final CodeWriter openBlock​(java.lang.String textBeforeNewline,
                                  java.lang.String textAfterNewline,
                                  java.lang.Object arg1,
                                  java.lang.Object arg2,
                                  java.lang.Object arg3,
                                  java.lang.Runnable f)
        Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
        Parameters:
        textBeforeNewline - Text to write before writing a newline and indenting.
        textAfterNewline - Text to write after writing a newline and indenting.
        arg1 - First positional argument to substitute into textBeforeNewline.
        arg2 - Second positional argument to substitute into textBeforeNewline.
        arg3 - Third positional argument to substitute into textBeforeNewline.
        f - Runnable function to execute inside of the block.
        Returns:
        Returns the CodeWriter.

      • openBlock

        public final CodeWriter openBlock​(java.lang.String textBeforeNewline,
                                  java.lang.String textAfterNewline,
                                  java.lang.Object arg1,
                                  java.lang.Object arg2,
                                  java.lang.Object arg3,
                                  java.lang.Object arg4,
                                  java.lang.Runnable f)
        Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
        Parameters:
        textBeforeNewline - Text to write before writing a newline and indenting.
        textAfterNewline - Text to write after writing a newline and indenting.
        arg1 - First positional argument to substitute into textBeforeNewline.
        arg2 - Second positional argument to substitute into textBeforeNewline.
        arg3 - Third positional argument to substitute into textBeforeNewline.
        arg4 - Fourth positional argument to substitute into textBeforeNewline.
        f - Runnable function to execute inside of the block.
        Returns:
        Returns the CodeWriter.

      • openBlock

        public final CodeWriter openBlock​(java.lang.String textBeforeNewline,
                                  java.lang.String textAfterNewline,
                                  java.lang.Object arg1,
                                  java.lang.Object arg2,
                                  java.lang.Object arg3,
                                  java.lang.Object arg4,
                                  java.lang.Object arg5,
                                  java.lang.Runnable f)
        Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
        Parameters:
        textBeforeNewline - Text to write before writing a newline and indenting.
        textAfterNewline - Text to write after writing a newline and indenting.
        arg1 - First positional argument to substitute into textBeforeNewline.
        arg2 - Second positional argument to substitute into textBeforeNewline.
        arg3 - Third positional argument to substitute into textBeforeNewline.
        arg4 - Fourth positional argument to substitute into textBeforeNewline.
        arg5 - Fifth positional argument to substitute into textBeforeNewline.
        f - Runnable function to execute inside of the block.
        Returns:
        Returns the CodeWriter.

      • openBlock

        public final CodeWriter openBlock​(java.lang.String textBeforeNewline,
                                  java.lang.String textAfterNewline,
                                  java.lang.Object[] args,
                                  java.lang.Runnable f)
        Opens a block of syntax by writing textBeforeNewline, a newline, then indenting, then executes the given Runnable, then closes the block of syntax by writing a newline, dedenting, then writing textAfterNewline.
        Parameters:
        textBeforeNewline - Text to write before writing a newline and indenting.
        textAfterNewline - Text to write after writing a newline and indenting.
        args - Arguments to substitute into textBeforeNewline.
        f - Runnable function to execute inside of the block.
        Returns:
        Returns the CodeWriter.

      • closeBlock

        public final CodeWriter closeBlock​(java.lang.String textAfterNewline,
                                   java.lang.Object... args)
        Closes a block of syntax by writing a newline, dedenting, then writing text.
        Parameters:
        textAfterNewline - Text to write after writing a newline and dedenting.
        args - String arguments to use for formatting.
        Returns:
        Returns the CodeWriter.

      • write

        public final CodeWriter write​(java.lang.Object content,
                              java.lang.Object... args)
        Writes text to the CodeWriter and appends a newline.

        The provided text is automatically formatted using variadic arguments.

        Parameters:
        content - Content to write.
        args - String arguments to use for formatting.
        Returns:
        Returns the CodeWriter.

      • writeInline

        public final CodeWriter writeInline​(java.lang.Object content,
                                    java.lang.Object... args)
        Writes text to the CodeWriter without appending a newline or prefixing indentation.

        If newlines are present in the given string, each of those lines will receive proper indentation.

        Parameters:
        content - Content to write.
        args - String arguments to use for formatting.
        Returns:
        Returns the CodeWriter.

      • writeOptional

        public final CodeWriter writeOptional​(java.lang.Object content)
        Optionally writes text to the CodeWriter and appends a newline if a value is present.

        If the provided content value is null, nothing is written. If the provided content value is an empty Optional, nothing is written. If the result of calling toString on content results in an empty string, nothing is written. Finally, if the value is a non-empty string, the content is written to the CodeWriter at the current level of indentation, and a newline is appended.

        Parameters:
        content - Content to write if present.
        Returns:
        Returns the CodeWriter.

      • call

        public final CodeWriter call​(java.lang.Runnable task)
        Allows calling out to arbitrary code for things like looping or conditional writes without breaking method chaining.
        Parameters:
        task - Method to invoke.
        Returns:
        Returns the CodeWriter.

      • putContext

        public CodeWriter putContext​(java.lang.String key,
                             java.lang.Object value)
        Adds a named key-value pair to the context of the current state.

        These context values can be referenced by named interpolated parameters.

        Parameters:
        key - Key to add to the context.
        value - Value to associate with the key.
        Returns:
        Returns the CodeWriter.

      • putContext

        public final CodeWriter putContext​(java.util.Map<java.lang.String,​java.lang.Object> mappings)
        Adds a map of named key-value pair to the context of the current state.

        These context values can be referenced by named interpolated parameters.

        Parameters:
        mappings - Key value pairs to add.
        Returns:
        Returns the CodeWriter.

      • removeContext

        public CodeWriter removeContext​(java.lang.String key)
        Removes a named key-value pair from the context of the current state.
        Parameters:
        key - Key to add to remove from the current context.
        Returns:
        Returns the CodeWriter.

      • getContext

        public java.lang.Object getContext​(java.lang.String key)
        Gets a named contextual key-value pair from the current state.
        Parameters:
        key - Key to retrieve.
        Returns:
        Returns the associated value or null if not present.