W - The concrete type, used to provide a fluent interface.I - The import container used by the writer to manage imports.public abstract class SymbolWriter<W extends SymbolWriter<W,I>,I extends ImportContainer> extends AbstractCodeWriter<W> implements SymbolDependencyContainer
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 MyDocumentationWriter(), 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;
}
}
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.
| Modifier and Type | Class and Description |
|---|---|
static interface |
SymbolWriter.Factory<W extends SymbolWriter<W,? extends ImportContainer>>
Factory used to create a
SymbolWriter. |
| Constructor and Description |
|---|
SymbolWriter(I importContainer) |
| Modifier and Type | Method and Description |
|---|---|
W |
addDependency(SymbolDependencyContainer dependencies)
Adds one or more dependencies to the generated code (represented as
a
SymbolDependency). |
W |
addImport(Symbol symbol,
java.lang.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). |
java.util.List<SymbolDependency> |
getDependencies()
Gets the list of dependencies that this object introduces.
|
I |
getImportContainer()
Gets the import container associated with the writer.
|
W |
setRelativizeSymbols(java.lang.String relativizeSymbols)
Sets a string used to relativize Symbols formatted using the default
T
implementation used by SymbolWriter in the current state. |
call, closeBlock, consumer, copySettingsFrom, dedent, dedent, disableNewlines, enableNewlines, ensureNewline, format, formatLiteral, getContext, getContext, getDebugInfo, getDebugInfo, getExpressionStart, getIndentLevel, getIndentText, getInsertTrailingNewline, getNewline, getNewlinePrefix, getTrimBlankLines, getTrimTrailingSpaces, indent, indent, injectSection, insertTrailingNewline, insertTrailingNewline, 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, writeWithNoFormattingpublic SymbolWriter(I importContainer)
importContainer - Container used to persist and filter imports based on package names.public W setRelativizeSymbols(java.lang.String relativizeSymbols)
T
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 T
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 T has been
overridden with another implementation.
relativizeSymbols - The package name, namespace, etc to relativize symbols with.public final I getImportContainer()
The AbstractCodeWriter.toString() method of the SymbolWriter should
be overridden so that it includes the import container's contents in
the output as appropriate.
public final java.util.List<SymbolDependency> getDependencies()
SymbolDependencyContainerA 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.
getDependencies in interface SymbolDependencyContainerpublic final W addDependency(SymbolDependencyContainer dependencies)
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).
dependencies - Dependency to add.public W addUseImports(SymbolContainer container)
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.
container - Symbols to add.public W addUseImports(SymbolReference symbolReference)
SymbolReference.ContextOption.USE references).
This method may be overridden as needed.
symbolReference - Symbol reference to import.addUseImports(SymbolContainer)public final W addImport(Symbol symbol, java.lang.String alias, SymbolReference.ContextOption... 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.
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).