Module org.tquadrat.foundation.javacomposer

Package org.tquadrat.foundation.javacomposer.internal

Class CodeWriter

java.lang.Object

org.tquadrat.foundation.javacomposer.internal.CodeWriter

@ClassVersion(sourceVersion="$Id: CodeWriter.java 1105 2024-02-28 12:58:46Z tquadrat $")
@API(status=INTERNAL,
     since="0.0.5")
public final class CodeWriter
extends Object

Converts a JavaFile to a string suitable to both human- and javac-consumption. This honours imports, indentation, and deferred variable names.

Author:

Square,Inc.

Modified by:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: CodeWriter.java 1105 2024-02-28 12:58:46Z tquadrat $

Since:

0.0.5

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.javacomposer.internal.CodeWriter"

⁠

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static enum	CodeWriter.CommentType	The comment types.

Field Summary

Fields

Modifier and Type	Field	Description
private final JavaComposer	m_Composer	The reference to the factory.
private CodeWriter.CommentType	m_CurrentlyEmittingComment	Flag that indicates that we are currently writing a normal comment.
private final Map<String,ClassNameImpl>	m_ImportableTypes	The types that can be imported.
private final Map<String,ClassNameImpl>	m_ImportedTypes	The imported types.
private final String	m_Indent	The indentation.
private int	m_IndentLevel	The indentation level.
private final Layout	m_Layout	The layout for the output.
private final LineWrapper	m_LineWrapper	The output target.
private String	m_PackageName	The current package name.
private final Collection<String>	m_ReferencedNames	The referenced names.
private int	m_StatementLine	When a statement will be emitted, this is the line of the statement currently being written.
private final Set<String>	m_StaticImportClassNames	The names of statically imported classes.
private final Set<String>	m_StaticImports	The static imports.
private boolean	m_TrailingNewline	A flag that controls the trailing new line.
private final List<TypeSpecImpl>	m_TypeSpecStack	The types.
private static final String	NO_PACKAGE	Sentinel value that indicates that no user-provided package has been set.

Constructor Summary

Constructors

Constructor	Description
CodeWriter(Appendable out)	Deprecated, for removal: This API element is subject to removal in a future version. Use CodeWriter(JavaComposer, Appendable) instead.
CodeWriter(Appendable out, Layout layout, String indent, Map<String,ClassNameImpl> importedTypes, Set<String> staticImports)	Deprecated, for removal: This API element is subject to removal in a future version. Use CodeWriter(JavaComposer, Appendable) instead.
CodeWriter(Appendable out, Layout layout, Set<String> staticImports)	Deprecated, for removal: This API element is subject to removal in a future version. Use CodeWriter(JavaComposer, Appendable) instead.
CodeWriter(JavaComposer composer, Appendable out)	Creates a new CodeWriter instance.
CodeWriter(JavaComposer composer, Appendable out, Map<String,ClassNameImpl> importedTypes, Set<String> staticImports)	Creates a new CodeWriter instance.
CodeWriter(JavaComposer composer, Appendable out, Set<String> staticImports)	Creates a new CodeWriter instance.

Method Summary

Modifier and Type	Method	Description
final CodeWriter	emit(CharSequence input)	Emits the given String to the output target.
final CodeWriter	emit(String format, Object... args)	Emits a CodeBlockImpl instance to the output target that is created on the fly from the given arguments.
final CodeWriter	emit(CodeBlockImpl codeBlock)	Emits the given CodeBlockImpl instance to the output target.
final CodeWriter	emitAndIndent(CharSequence input)	Emits the given String to the output target with indentation as required.
final void	emitAnnotations(Iterable<AnnotationSpecImpl> annotations, boolean inline)	Emits the given annotations to the output target.
final void	emitBlockComment(CodeBlockImpl codeBlock)	Emits the given CodeBlockImpl instance as a block comment to the output target.
private final void	emitIndentation()	Writes the indentation to the output target.
final void	emitJavadoc(CodeBlockImpl codeBlock)	Emits the given CodeBlockImpl instance as a JavaDoc comment to the output target.
final void	emitLineComment(CodeBlockImpl codeBlock)	Emits the given CodeBlockImpl instance as a line comment to the output target.
private final void	emitLiteral(Object o)	Emits the given argument literally to the output target.
final void	emitModifiers(Collection<Modifier> modifiers)	Emits modifiers to the output target in the standard order.
final void	emitModifiers(Collection<Modifier> modifiers, Collection<Modifier> implicitModifiers)	Emits modifiers to the output target in the standard order.
private final boolean	emitStaticImportMember(String canonical, String part)	Emits a static import entry to the output target.
final void	emitTypeVariables(List<TypeVariableNameImpl> typeVariables)	Emits type variables with their bounds.
final CodeWriter	emitWrappingSpace()	Emits wrapping space to the output target.
private static final String	extractMemberName(String part)	Extracts a member name from the given part.
private final void	importableType(ClassNameImpl className)	Marks the given type as importable.
final Map<String,ClassNameImpl>	importedTypes()	Returns the imported types.
final CodeWriter	indent()	Increments the indentation level.
final CodeWriter	indent(int levels)	Increases the indentation level by the given value.
final Layout	layout()	Returns the layout for the output.
final String	lookupName(ClassNameImpl className)	Returns the best name to identify className within the current context.
final CodeWriter	popPackage()	Pops the package name.
final CodeWriter	popType()	Pops the top most type.
final CodeWriter	pushPackage(String packageName)	Pushes the given package name.
final CodeWriter	pushType(TypeSpecImpl type)	Pushes the give type.
private final Optional<ClassNameImpl>	resolve(String simpleName)	Returns the class referenced by simpleName, using the current nesting context and imports.
private final ClassNameImpl	stackClassName(int stackDepth, String simpleName)	Returns the class named simpleName when nested in the class at stackDepth.
final int	statementLine()	Returns the current statement line.
final void	statementLine(int statementLine)	Sets the current statement line.
final Map<String,ClassNameImpl>	suggestedImports()	Returns the types that should have been imported for this code.
final CodeWriter	unindent()	Decrements the indentation level.
final CodeWriter	unindent(int levels)	Decreases the indentation level by the given value.

Methods inherited from class java.lang.Object

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

Field Details

NO_PACKAGE

private static final String NO_PACKAGE

Sentinel value that indicates that no user-provided package has been set.

m_Composer

private final JavaComposer m_Composer

The reference to the factory.

m_CurrentlyEmittingComment

private CodeWriter.CommentType m_CurrentlyEmittingComment

Flag that indicates that we are currently writing a normal comment.

m_ImportableTypes

private final Map<String,ClassNameImpl> m_ImportableTypes

The types that can be imported.

m_ImportedTypes

private final Map<String,ClassNameImpl> m_ImportedTypes

The imported types.

m_Indent

private final String m_Indent

The indentation.

m_IndentLevel

private int m_IndentLevel

The indentation level.

m_Layout

private final Layout m_Layout

The layout for the output.

m_LineWrapper

private final LineWrapper m_LineWrapper

The output target.

m_PackageName

private String m_PackageName

The current package name.

m_ReferencedNames

private final Collection<String> m_ReferencedNames

The referenced names.

m_StatementLine

private int m_StatementLine

When a statement will be emitted, this is the line of the statement currently being written. The first line of a statement is indented normally and subsequent wrapped lines are double-indented. This is -1 when the currently-written line isn't part of a statement.

m_StaticImportClassNames

private final Set<String> m_StaticImportClassNames

The names of statically imported classes.

m_StaticImports

private final Set<String> m_StaticImports

The static imports.

m_TrailingNewline

private boolean m_TrailingNewline

A flag that controls the trailing new line.

m_TypeSpecStack

private final List<TypeSpecImpl> m_TypeSpecStack

The types.

Constructor Details

CodeWriter

@Deprecated(since="0.2.0",
            forRemoval=true)
public CodeWriter(Appendable out)

Deprecated, for removal: This API element is subject to removal in a future version.

Use CodeWriter(JavaComposer, Appendable) instead.

Creates a new CodeWriter instance.

Parameters:

out - The output target.

CodeWriter

@Deprecated(since="0.2.0",
            forRemoval=true)
public CodeWriter(Appendable out,
 Layout layout,
 Set<String> staticImports)

Deprecated, for removal: This API element is subject to removal in a future version.

Use CodeWriter(JavaComposer, Appendable) instead.

Creates a new CodeWriter instance.

Parameters:

out - The output target.

layout - The layout for the output.

staticImports - The static imports.

CodeWriter

@Deprecated(since="0.2.0",
            forRemoval=true)
public CodeWriter(Appendable out,
 Layout layout,
 String indent,
 Map<String,ClassNameImpl> importedTypes,
 Set<String> staticImports)

Deprecated, for removal: This API element is subject to removal in a future version.

Use CodeWriter(JavaComposer, Appendable) instead.

Creates a new CodeWriter instance.

Parameters:

out - The output target.

layout - The layout for the output.

indent - The indentation; will be ignored.

importedTypes - The imported types.

staticImports - The static imports.

CodeWriter

public CodeWriter(JavaComposer composer,
 Appendable out)

Creates a new CodeWriter instance.

Parameters:

composer - The reference to the factory that created this code writer instance.

out - The output target.

CodeWriter

public CodeWriter(JavaComposer composer,
 Appendable out,
 Set<String> staticImports)

Creates a new CodeWriter instance.

Parameters:

composer - The reference to the factory that created this code writer instance.

out - The output target.

staticImports - The static imports.

CodeWriter

public CodeWriter(JavaComposer composer,
 Appendable out,
 Map<String,ClassNameImpl> importedTypes,
 Set<String> staticImports)

Creates a new CodeWriter instance.

Parameters:

composer - The reference to the factory that created this code writer instance.

out - The output target.

importedTypes - The imported types.

staticImports - The static imports.

Method Details

emit

public final CodeWriter emit(CharSequence input)
                      throws UncheckedIOException

Emits the given String to the output target.

Delegates to emitAndIndent(CharSequence).

Parameters:

input - The String.

Returns:

This CodeWriter instance.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emit

public final CodeWriter emit(String format,
 Object... args)
                      throws UncheckedIOException

Emits a CodeBlockImpl instance to the output target that is created on the fly from the given arguments.

Parameters:

format - The format.

args - The arguments.

Returns:

This CodeWriter instance.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emit

public final CodeWriter emit(CodeBlockImpl codeBlock)
                      throws UncheckedIOException

Emits the given CodeBlockImpl instance to the output target.

Parameters:

codeBlock - The code block.

Returns:

This CodeWriter instance.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emitAndIndent

public final CodeWriter emitAndIndent(CharSequence input)
                               throws UncheckedIOException

Emits the given String to the output target with indentation as required. It's important that all code that writes to m_LineWrapper does it through here, since we emit indentation lazily in order to avoid unnecessary trailing whitespace.

Parameters:

input - The String.

Returns:

This CodeWriter instance.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emitAnnotations

public final void emitAnnotations(Iterable<AnnotationSpecImpl> annotations,
 boolean inline)
                           throws UncheckedIOException

Emits the given annotations to the output target.

Parameters:

annotations - The annotations.

inline - true if the annotations should be placed on the same line as the annotated element, false otherwise.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emitBlockComment

public final void emitBlockComment(CodeBlockImpl codeBlock)
                            throws UncheckedIOException

Emits the given CodeBlockImpl instance as a block comment to the output target.

Parameters:

codeBlock - The code block with the comment.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emitIndentation

private final void emitIndentation()
                            throws UncheckedIOException

Writes the indentation to the output target.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emitJavadoc

public final void emitJavadoc(CodeBlockImpl codeBlock)
                       throws UncheckedIOException

Emits the given CodeBlockImpl instance as a JavaDoc comment to the output target.

Parameters:

codeBlock - The code block with the JavaDoc comment.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emitLineComment

public final void emitLineComment(CodeBlockImpl codeBlock)
                           throws UncheckedIOException

Emits the given CodeBlockImpl instance as a line comment to the output target.

Parameters:

codeBlock - The code block with the comment.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emitLiteral

private final void emitLiteral(Object o)
                        throws UncheckedIOException

Emits the given argument literally to the output target.

Parameters:

o - The object to emit.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emitModifiers

public final void emitModifiers(Collection<Modifier> modifiers,
 Collection<Modifier> implicitModifiers)
                         throws UncheckedIOException

Emits modifiers to the output target in the standard order. Modifiers in implicitModifiers will not be emitted.

Parameters:

modifiers - The modifiers to emit.

implicitModifiers - The modifiers to omit.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emitModifiers

public final void emitModifiers(Collection<Modifier> modifiers)
                         throws UncheckedIOException

Emits modifiers to the output target in the standard order.

Parameters:

modifiers - The modifiers to emit.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emitStaticImportMember

private final boolean emitStaticImportMember(String canonical,
 String part)
                                      throws UncheckedIOException

Emits a static import entry to the output target.

Parameters:

canonical - The canonical name of the class to import.

part - The part to emit.

Returns:

true if something was emitted, false otherwise.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emitTypeVariables

public final void emitTypeVariables(List<TypeVariableNameImpl> typeVariables)
                             throws UncheckedIOException

Emits type variables with their bounds. This should only be used when declaring type variables; everywhere else bounds are omitted.

Parameters:

typeVariables - The type variables.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

emitWrappingSpace

public final CodeWriter emitWrappingSpace()
                                   throws UncheckedIOException

Emits wrapping space to the output target.

Returns:

This CodeWriter instance.

Throws:

UncheckedIOException - A problem occurred when writing to the output target.

extractMemberName

private static final String extractMemberName(String part)

Extracts a member name from the given part.

Parameters:

part - The part.

Returns:

The member name, or if none could be found, the given part.

importableType

private final void importableType(ClassNameImpl className)

Marks the given type as importable.

Parameters:

className - The type.

importedTypes

public final Map<String,ClassNameImpl> importedTypes()

Returns the imported types.

Returns:

The imported types.

indent

public final CodeWriter indent()

Increments the indentation level.

Returns:

This CodeWriter instance.

indent

public final CodeWriter indent(int levels)

Increases the indentation level by the given value.

Parameters:

levels - The increase value.

Returns:

This CodeWriter instance.

layout

public final Layout layout()

Returns the layout for the output.

Returns:

The layout.

lookupName

public final String lookupName(ClassNameImpl className)

Returns the best name to identify className within the current context. This uses the available imports and the current scope to find the shortest name available. It does not honour names that are visible due to inheritance.

Parameters:

className - The name of the class.

Returns:

The shortest possible name for the given class.

popPackage

public final CodeWriter popPackage()

Pops the package name.

Returns:

This CodeWriter instance.

popType

public final CodeWriter popType()

Pops the top most type.

Returns:

This CodeWriter instance.

pushPackage

public final CodeWriter pushPackage(String packageName)

Pushes the given package name.

Parameters:

packageName - The name of the package.

Returns:

This CodeWriter instance.

pushType

public final CodeWriter pushType(TypeSpecImpl type)

Pushes the give type.

Parameters:

type - The type.

Returns:

This CodeWriter instance.

resolve

private final Optional<ClassNameImpl> resolve(String simpleName)

Returns the class referenced by simpleName, using the current nesting context and imports.

Parameters:

simpleName - The name of the class we search for.

Returns:

An instance of Optional that holds the ClassName instance for the resolved class.

stackClassName

private final ClassNameImpl stackClassName(int stackDepth,
 String simpleName)

Returns the class named simpleName when nested in the class at stackDepth.

Parameters:

stackDepth - The search depth.

simpleName - The class name.

Returns:

The found class.

statementLine

public final int statementLine()

Returns the current statement line.

When a statement will be emitted, this method returns the line of the statement currently being written. The first line of a statement is indented normally and subsequent wrapped lines are double-indented. This is -1 when the currently-written line isn't part of a statement.

Returns:

The statement line, or -1.

statementLine

public final void statementLine(int statementLine)

Sets the current statement line.

Parameters:

statementLine - The new value for the current statement line.

See Also:

• statementLine()

suggestedImports

public final Map<String,ClassNameImpl> suggestedImports()

Returns the types that should have been imported for this code. If there were any simple name collisions, that type's first use is imported.

Returns:

The types that should have been imported.

unindent

public final CodeWriter unindent()

Decrements the indentation level.

Returns:

This CodeWriter instance.

unindent

public final CodeWriter unindent(int levels)

Decreases the indentation level by the given value.

Parameters:

levels - The decrease value.

Returns:

This CodeWriter instance.