Package software.amazon.smithy.codegen.core.writer

Class CodegenWriter<T extends CodegenWriter<T,U>,U extends ImportContainer>

java.lang.Object
software.amazon.smithy.utils.CodeWriter
software.amazon.smithy.codegen.core.writer.CodegenWriter<T,U>
Type Parameters:
T - The concrete type, used to provide a fluent interface.
U - The import container used by the writer to manage imports.
All Implemented Interfaces:
SymbolDependencyContainer
public class CodegenWriter<T extends CodegenWriter<T,U>,U extends ImportContainer> extends CodeWriter implements SymbolDependencyContainer
A 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;
     }
 }

  • Constructor Details

    • CodegenWriter

      public CodegenWriter(DocumentationWriter<T> documentationWriter, U importContainer)
      Parameters:
      documentationWriter - Writes out documentation emitted by a Runnable.
      importContainer - Container used to persist and filter imports based on package names.

  • Method Details

    • getImportContainer

      public final U getImportContainer()
      Gets the import container associated with the writer.

      The CodeWriter.toString() method of the CodegenWriter 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 T addDependency(SymbolDependencyContainer dependencies)
      Adds one or more dependencies to the generated code (represented as a 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).

      Parameters:
      dependencies - Dependency to add.
      Returns:
      Returns the writer.

    • addUseImports

      public T 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 T 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:

    • addImport

      public final T 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.

    • writeDocs

      public final T writeDocs(Runnable runnable)
      Writes documentation comments.

      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 CodeWriter.writeWithNoFormatting(java.lang.Object) or escape the expression start character manually.

      This method may be overridden as needed.

      Parameters:
      runnable - Runnable that handles actually writing docs with the writer.
      Returns:
      Returns the writer.

    • writeDocs

      public final T writeDocs(String docs)
      Writes documentation comments from a string.
      Parameters:
      docs - Documentation to write.
      Returns:
      Returns the writer.