Package software.amazon.smithy.codegen.core

Class SymbolWriter<W extends SymbolWriter<W,I>,I extends ImportContainer>

java.lang.Object

software.amazon.smithy.utils.AbstractCodeWriter<W>

software.amazon.smithy.codegen.core.SymbolWriter<W,I>

Type Parameters:

W - The concrete type, used to provide a fluent interface.

I - The import container used by the writer to manage imports.

All Implemented Interfaces:

SymbolDependencyContainer

Direct Known Subclasses:

DocWriter, TraitCodegenWriter

public abstract class SymbolWriter<W extends SymbolWriter<W,I>,I extends ImportContainer>
extends AbstractCodeWriter<W>
implements SymbolDependencyContainer

A SymbolWriter is a specialized AbstractCodeWriter that makes it easier to implement code generation that utilizes Symbols and SymbolDependency values.

A SymbolWriter is expected to be subclassed, and the subclass is expected to implement language-specific functionality like writing documentation comments, tracking "imports", and adding any other kinds of helpful functionality for generating source code for a programming language.

The following example shows how a subclass of SymbolWriter should be created. SymbolWriters are expected to define a recursive type signature (notice that MyWriter is a generic parametric type in its own type definition).

 public final class MyWriter extends SymbolWriter<MyWriter, MyImportContainer> {
     public MyWriter(String namespace) {
         super(new MyImportContainer(namespace));
     }

     \@Override
     public String toString() {
         return getImportContainer().toString() + "\n\n" + super.toString();
     }

     public MyWriter someCustomMethod() {
         // You can implement custom methods that are specific to whatever
         // language you're implementing a generator for.
         return this;
     }
 }
 

Formatting symbols with "T"

SymbolWriter registers a default formatter for "T" that writes Symbols and SymbolReferences. Imports needed by these types are automatically registered with addUseImports(software.amazon.smithy.codegen.core.SymbolContainer) for a Symbol and addImport(software.amazon.smithy.codegen.core.Symbol, java.lang.String, software.amazon.smithy.codegen.core.SymbolReference.ContextOption...) for a SymbolReference. Programming languages that have a concept of namespaces can use setRelativizeSymbols(java.lang.String) to the namespace of the SymbolWriter, and then the default symbol formatter will relativize symbols against that namespace using Symbol.relativize(java.lang.String) when writing the symbol as a string.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	SymbolWriter.Factory<W extends SymbolWriter<W,? extends ImportContainer>>	Factory used to create a SymbolWriter.

Constructor Summary

Constructors

Constructor	Description
SymbolWriter(I importContainer)

Method Summary

Modifier and Type	Method	Description
final W	addDependency(SymbolDependencyContainer dependencies)	Adds one or more dependencies to the generated code (represented as a SymbolDependency).
final W	addImport(Symbol symbol, String alias, SymbolReference.ContextOption... options)	Imports a symbol (if necessary) using a specific alias and list of context options.
W	addUseImports(SymbolContainer container)	Imports one or more USE symbols using the name of the symbol (e.g., SymbolReference.ContextOption.USE references).
W	addUseImports(SymbolReference symbolReference)	Imports a USE symbols possibly using an alias of the symbol (e.g., SymbolReference.ContextOption.USE references).
final List<SymbolDependency>	getDependencies()	Gets the list of dependencies that this object introduces.
final I	getImportContainer()	Gets the import container associated with the writer.
W	setRelativizeSymbols(String relativizeSymbols)	Sets a string used to relativize Symbols formatted using the default W implementation used by SymbolWriter in the current state.

Methods inherited from class software.amazon.smithy.utils.AbstractCodeWriter

call, closeBlock, consumer, copySettingsFrom, dedent, dedent, disableNewlines, enableNewlines, enableStackTraceComments, ensureNewline, format, formatLiteral, formatWithStackTraceElement, getContext, getContext, getDebugInfo, getDebugInfo, getExpressionStart, getIndentLevel, getIndentText, getInsertTrailingNewline, getNewline, getNewlinePrefix, getTrimBlankLines, getTrimTrailingSpaces, indent, indent, injectSection, insertTrailingNewline, insertTrailingNewline, isStackTraceRelevant, onSection, onSection, openBlock, openBlock, openBlock, openBlock, openBlock, openBlock, openBlock, openBlock, popState, pushFilteredState, pushState, pushState, pushState, putContext, putContext, putFormatter, removeContext, setExpressionStart, setIndentText, setNewline, setNewline, setNewlinePrefix, toString, trimBlankLines, trimBlankLines, trimTrailingSpaces, trimTrailingSpaces, unwrite, write, writeInline, writeInlineWithNoFormatting, writeOptional, writeWithNoFormatting

Methods inherited from class java.lang.Object

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

Constructor Details

SymbolWriter

public SymbolWriter(I importContainer)

Parameters:

importContainer - Container used to persist and filter imports based on package names.

Method Details

setRelativizeSymbols

public W setRelativizeSymbols(String relativizeSymbols)

Sets a string used to relativize Symbols formatted using the default W implementation used by SymbolWriter in the current state.

In many programming languages, when referring to types in the same namespace as the current scope of a SymbolWriter, the symbols written in that scope don't need to be fully-qualified. They can just reference the unqualified type name. By setting a value for relativizeSymbols, if the result of Symbol.getNamespace() is equal to relativizeSymbols, then the unqualified name of the symbol is written to the SymbolWriter when the default implementation of W is written. Symbols that refer to types in other namespaces will write the fully qualified type.

Note: This method may have no effect if a programming language does not use namespaces or concepts like namespaces or if W has been overridden with another implementation.

Parameters:

relativizeSymbols - The package name, namespace, etc to relativize symbols with.

Returns:

Returns the SymbolWriter.

getImportContainer

public final I getImportContainer()

Gets the import container associated with the writer.

The AbstractCodeWriter.toString() method of the SymbolWriter should be overridden so that it includes the import container's contents in the output as appropriate.

Returns:

Returns the import container.

getDependencies

public final List<SymbolDependency> getDependencies()

Description copied from interface: SymbolDependencyContainer

Gets the list of dependencies that this object introduces.

A dependency is a dependency on another package that a Symbol or type requires. It is quite different from a reference since a reference only refers to a symbol; a reference provides no context as to whether or not a dependency is required or the dependency's coordinates.

Specified by:

getDependencies in interface SymbolDependencyContainer

Returns:

Returns the dependencies.

addDependency

public final W addDependency(SymbolDependencyContainer dependencies)

Adds one or more dependencies to the generated code (represented as a SymbolDependency).

Tracking dependencies on a SymbolWriter allows dependencies to be automatically aggregated and collected in order to generate configuration files for dependency management tools (e.g., npm, maven, etc).

Parameters:

dependencies - Dependency to add.

Returns:

Returns the writer.

addUseImports

public W addUseImports(SymbolContainer container)

Imports one or more USE symbols using the name of the symbol (e.g., SymbolReference.ContextOption.USE references).

USE references are only necessary when referring to a symbol, not declaring the symbol. For example, when referring to a List<Foo>, the USE references would be both the List type and Foo type.

This method may be overridden as needed.

Parameters:

container - Symbols to add.

Returns:

Returns the writer.

addUseImports

public W addUseImports(SymbolReference symbolReference)

Imports a USE symbols possibly using an alias of the symbol (e.g., SymbolReference.ContextOption.USE references).

This method may be overridden as needed.

Parameters:

symbolReference - Symbol reference to import.

Returns:

Returns the writer.

See Also:

• addUseImports(SymbolContainer)

addImport

public final W addImport(Symbol symbol,
 String alias,
 SymbolReference.ContextOption... options)

Imports a symbol (if necessary) using a specific alias and list of context options.

This method automatically adds any dependencies of the symbol to the writer, calls ImportContainer.importSymbol(software.amazon.smithy.codegen.core.Symbol, java.lang.String), and automatically calls addImportReferences(software.amazon.smithy.codegen.core.Symbol, software.amazon.smithy.codegen.core.SymbolReference.ContextOption...) for the provided symbol.

When called with no options, both USE and DECLARE symbols are imported from any references the Symbol might contain.

Parameters:

symbol - Symbol to optionally import.

alias - The alias to refer to the symbol by.

options - The list of context options (e.g., is it a USE or DECLARE symbol).

Returns:

Returns the writer.