T - The concrete type, used to provide a fluent interface.U - The import container used by the writer to manage imports.SymbolWriter. This will be removed in a future release.@Deprecated public class CodegenWriter<T extends CodegenWriter<T,U>,U extends ImportContainer> extends CodeWriter implements SymbolDependencyContainer
CodeGenWriter is a specialized CodeWriter that makes it
easier to implement code generation that utilizes Symbols and
SymbolDependency values.
A CodegenWriter 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 CodegenWriter
should be created. CodegenWriters 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 CodegenWriter<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;
}
}
CodegenWriter 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 CodegenWriter, 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.
| Constructor and Description |
|---|
CodegenWriter(DocumentationWriter<T> documentationWriter,
U importContainer)
Deprecated.
|
| Modifier and Type | Method and Description |
|---|---|
T |
addDependency(SymbolDependencyContainer dependencies)
Deprecated.
Adds one or more dependencies to the generated code (represented as
a
SymbolDependency). |
T |
addImport(Symbol symbol,
java.lang.String alias,
SymbolReference.ContextOption... options)
Deprecated.
Imports a symbol (if necessary) using a specific alias and list of
context options.
|
T |
addUseImports(SymbolContainer container)
Deprecated.
Imports one or more USE symbols using the name of the symbol
(e.g.,
SymbolReference.ContextOption#USE references). |
T |
addUseImports(SymbolReference symbolReference)
Deprecated.
Imports a USE symbols possibly using an alias of the symbol
(e.g.,
SymbolReference.ContextOption#USE references). |
java.util.List<SymbolDependency> |
getDependencies()
Deprecated.
Gets the list of dependencies that this object introduces.
|
DocumentationWriter<T> |
getDocumentationWriter()
Deprecated.
Gets the documentation writer.
|
U |
getImportContainer()
Deprecated.
Gets the import container associated with the writer.
|
T |
setRelativizeSymbols(java.lang.String relativizeSymbols)
Deprecated.
Sets a string used to relativize Symbols formatted using the default
T
implementation used by CodegenWriter in the current state. |
T |
writeDocs(java.lang.Runnable runnable)
Deprecated.
Writes documentation comments.
|
T |
writeDocs(java.lang.String docs)
Deprecated.
Writes documentation comments from a string.
|
call, closeBlock, copySettingsFrom, createDefault, dedent, dedent, disableNewlines, enableNewlines, ensureNewline, indent, indent, insertTrailingNewline, insertTrailingNewline, onSection, onSectionAppend, onSectionPrepend, openBlock, openBlock, openBlock, openBlock, openBlock, openBlock, openBlock, openBlock, popState, pushFilteredState, pushState, pushState, putContext, putContext, putFormatter, removeContext, setExpressionStart, setIndentText, setNewline, setNewline, setNewlinePrefix, trimBlankLines, trimBlankLines, trimTrailingSpaces, trimTrailingSpaces, unwrite, write, writeInline, writeOptional, writeWithNoFormattingconsumer, copySettingsFrom, format, formatLiteral, getContext, getContext, getDebugInfo, getDebugInfo, getExpressionStart, getIndentLevel, getIndentText, getInsertTrailingNewline, getNewline, getNewlinePrefix, getTrimBlankLines, getTrimTrailingSpaces, injectSection, onSection, pushState, toString, writeInlineWithNoFormattingpublic CodegenWriter(DocumentationWriter<T> documentationWriter, U importContainer)
documentationWriter - Writes out documentation emitted by a Runnable.importContainer - Container used to persist and filter imports based on package names.public T setRelativizeSymbols(java.lang.String relativizeSymbols)
T
implementation used by CodegenWriter in the current state.
In many programming languages, when referring to types in the same namespace as
the current scope of a CodegenWriter, 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 CodegenWriter 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 DocumentationWriter<T> getDocumentationWriter()
public final U getImportContainer()
The AbstractCodeWriter.toString() method of the CodegenWriter 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 T addDependency(SymbolDependencyContainer dependencies)
SymbolDependency).
Tracking dependencies on a CodegenWriter 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 T 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 T addUseImports(SymbolReference symbolReference)
SymbolReference.ContextOption#USE references).
This method may be overridden as needed.
symbolReference - Symbol reference to import.addUseImports(SymbolContainer)public final T 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).public final T writeDocs(java.lang.Runnable runnable)
This method is responsible for setting up the writer to begin writing documentation comments. This includes writing any necessary opening tokens (e.g., "/*"), adding tokens to the beginning of lines (e.g., "*"), sanitizing documentation strings, and writing any tokens necessary to close documentation comments (e.g., "*\/").
This method does not automatically escape the expression
start character ("$" by default). Write calls made by the Runnable
should either use AbstractCodeWriter.writeWithNoFormatting(java.lang.Object) or escape
the expression start character manually.
This method may be overridden as needed.
runnable - Runnable that handles actually writing docs with the writer.public final T writeDocs(java.lang.String docs)
docs - Documentation to write.