Package software.amazon.smithy.codegen.core

Class Symbol

java.lang.Object
software.amazon.smithy.codegen.core.Symbol
All Implemented Interfaces:
SymbolContainer, SymbolDependencyContainer, ToSmithyBuilder<Symbol>
public final class Symbol extends Object implements SymbolContainer, SymbolDependencyContainer, ToSmithyBuilder<Symbol>
A "symbol" is created by a SymbolProvider, and represents the qualified name of a type in a target programming language.

A symbol contains an optional namespace, optional namespace delimiter, name, a map of additional properties, a declaration file the determines where the symbol is declared, and a definition file that determines where a symbol is defined.

A namespace can be used when the target language supports namespaces. The provided namespace can be in whatever format is useful to the target language. A namespace delimiter is injected between the namespace and the name when creating the fully-qualified symbol name. The "name" is the unqualified name of the symbol (e.g., "str", or "MyShape").

Additional properties can be included when it's useful to provide more information about a symbol. For example, it might be useful to identify the name of a dependency that needs to be pulled in through a package manager when a symbol is used.

The following example shows how a Java type could be made into a symbol: 

 
 Class<Symbol> klass = Symbol.class;
 Symbol symbol = Symbol.builder()
         .namespace(klass.getPackage().toString(), ".")
         .name(klass.getSimpleName())
         .build();
 System.out.println(symbol);
 // ^ outputs "software.amazon.smithy.codegen.Symbol"
 System.out.println(symbol.relativize("software.amazon.smithy.codegen");
 // ^ outputs "Symbol"

  • Method Details

    • builder

      public static Symbol.Builder builder()
      Creates a new Symbol builder.
      Returns:
      Returns the created symbol builder.

    • getNamespace

      public String getNamespace()
      Provides the namespace of the symbol or "" if empty.
      Returns:
      Returns the optional namespace.

    • getNamespaceDelimiter

      public String getNamespaceDelimiter()
      Provides the namespace delimiter of the symbol or "" if empty.

      This delimiter is injected between the namespace and name when creating the full name.

      Returns:
      Returns the optional namespace.

    • getName

      public String getName()
      Gets the unqualified name of the symbol, that is, a name without namespace.
      Returns:
      Returns the name of the symbol.

    • getDeclarationFile

      public String getDeclarationFile()
      Gets the location/filename in which the symbol is declared.

      Code generators should write the generated code for this symbol's declaration in a file with the same name that is returned from this method. Not all languages separate a symbol's definition from its declaration. This method is useful for things like C and C++ header files.

      This method returns an empty string if no value was provided in the builder.

      Returns:
      The name of the file the symbol is declared.

    • getDefinitionFile

      public String getDefinitionFile()
      Gets the location/filename in which the symbol is defined.

      Code generators should write the generated code for a symbol in a file with the same name that is returned from this method.

      This method returns an empty string if no value was provided for either the declaration file or the definition file.

      Returns:
      The name of the file the symbol is defined.

    • getFullName

      public String getFullName()
      Gets the full name of the symbol.

      The full name is the concatenation of the namespace, the namespace delimiter, and the name.

      Returns:
      Returns the fully qualified name of the symbol.

    • relativize

      public String relativize(String namespace)
      Creates a relativized Symbol for the given namespace.

      If this symbol is in the same namespace as the provided namespace, then only the symbol name is returned. Otherwise, the fully-qualified symbol is returned.

      Parameters:
      namespace - Namespace to relativize against.
      Returns:
      Returns the relativized symbol.

    • toReference

      public SymbolReference toReference(String alias, SymbolReference.Option... options)
      Converts the symbol to a SymbolReference using the given alias.
      Parameters:
      alias - Alias to use to refer to the symbol.
      options - Variadic array of SymbolReference.Options.
      Returns:
      Returns the created SymbolReference.

    • toReferencedSymbol

      public Symbol toReferencedSymbol(String alias)
      Converts the symbol to a Symbol that refers to this Symbol using a SymbolReference. This makes it easier to refer to a type using an alias but still through a Symbol to be compatible with SymbolProvider.

      The following example creates a Symbol that is referred to as "__Document" in code, but is an alias of "foo.Document". 

      
 Symbol aliasedSymbol = Symbol.builder()
         .name("Document")
         .namespace("foo", ".")
         .build()
         .toReferenceSymbol("__Document");

      When used with a SymbolWriter, the writer should add an import on "foo.Document" and alias it to "__Document".

      The created symbol uses an empty namespace (""). If this is not compatible with specific ImportContainers to understand that the aliased symbol itself needs no imports, then you can augment the symbol with other metadata by instead using toReferencedSymbolBuilder(String).

      Note that this does not work with every programming language. For example, Java does not support aliasing whereas TypeScript does.

      Parameters:
      alias - Alias to use to refer to the symbol.
      Returns:
      Returns the created Symbol.
      See Also:

    • toReferencedSymbolBuilder

      public Symbol.Builder toReferencedSymbolBuilder(String alias)
      Converts the symbol to a Symbol.Builder that refers to this Symbol using a SymbolReference via an alias. This makes it easier to refer to type using an alias but still use a Symbol to be compatible with SymbolProviders.
      Parameters:
      alias - Alias to use to refer to the symbol.
      Returns:
      Returns a SymbolBuilder that is prepared with the symbol and alias.
      See Also:

    • getReferences

      public List<SymbolReference> getReferences()
      Gets the list of symbols that are referenced by this symbol.
      Returns:
      Returns the Symbol references.

    • getDependencies

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

    • getSymbols

      public List<Symbol> getSymbols()
      Description copied from interface: SymbolContainer
      Returns any Symbol objects contained in the object.
      Specified by:
      getSymbols in interface SymbolContainer
      Returns:
      Returns a collection of Symbols.

    • toBuilder

      public Symbol.Builder toBuilder()
      Description copied from interface: ToSmithyBuilder
      Take this object and create a builder that contains all of the current property values of this object.
      Specified by:
      toBuilder in interface ToSmithyBuilder<Symbol>
      Returns:
      a builder for type T

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)

    • hashCode

      public int hashCode()

    • getProperties

      public Map<String,Object> getProperties()
      Gets the additional properties of the object.
      Returns:
      Returns a map of additional property strings.

    • getProperty

      public Optional<Object> getProperty(String name)
      Gets a specific property if present.
      Parameters:
      name - Property to retrieve.
      Returns:
      Returns the optionally found property.

    • getProperty

      public <T> Optional<T> getProperty(String name, Class<T> type)
      Gets an additional property of a specific type.
      Type Parameters:
      T - Type of value to expect.
      Parameters:
      name - Name of the property to get.
      type - Type of value to expect.
      Returns:
      Returns a map of additional property strings.
      Throws:
      IllegalArgumentException - if the value is not of the given type.

    • expectProperty

      public Object expectProperty(String name)
      Gets a specific additional property or throws if missing.
      Parameters:
      name - Property to retrieve.
      Returns:
      Returns the found property.
      Throws:
      IllegalArgumentException - if the property is not present.

    • expectProperty

      public <T> T expectProperty(String name, Class<T> type)
      Gets a specific additional property or throws if missing or if the property is not an instance of the given type.
      Type Parameters:
      T - Type of value to expect.
      Parameters:
      name - Property to retrieve.
      type - Type of value to expect.
      Returns:
      Returns the found property.
      Throws:
      IllegalArgumentException - if the property is not present.
      IllegalArgumentException - if the value is not of the given type.