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 Symbol
s 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
Symbol
s and SymbolReference
s. 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, writeWithNoFormatting
consumer, copySettingsFrom, format, formatLiteral, getContext, getContext, getDebugInfo, getDebugInfo, getExpressionStart, getIndentLevel, getIndentText, getInsertTrailingNewline, getNewline, getNewlinePrefix, getTrimBlankLines, getTrimTrailingSpaces, injectSection, onSection, pushState, toString, writeInlineWithNoFormatting
public 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()
SymbolDependencyContainer
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.
getDependencies
in interface SymbolDependencyContainer
public 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.