Enum

In Dart, the `Enum` class represents a collection of predefined constants, known as entries, that are static and determined at runtime. Each entry in an `Enum` can hold different parameters, allowing for the storage of associated data when needed.

Note: All enums automatically extend the Enum class. They are also sealed, meaning they cannot be subclassed, implemented, mixed in, or otherwise explicitly instantiated. Abstract classes and mixins can explicitly implement or extend Enum, but unless they are then implemented by or mixed into an enum declaration, no objects can actually implement the type of that class or mixin.

In the project, enumerations are a specialized type of class. This means their instantiation may differ from other class types. Generally, the builder structure for enumerations includes additional methods compared to regular classes. While this approach introduces more code into the API, which requires maintenance, it reduces the likelihood of errors due to its design choices.

To create an enum class, you must initialize a builder reference using the ClassSpec.enumClass("<name>") method, which is consistent with the general class implementation process. This method call returns a builder reference, allowing you to define the enumeration

Simple enumerations:

Now create an enumeration that contains only some basic value without any parameters or other code parts. So we got our builder reference over the `ClassSpec` now we can add our entries for the enumeration. DartPoet binds each entry to a `EnumEntrySpec` which can have additional "parameters". For a simple enumeration we can ignore the addition of parameters.

An EnumEntrySpec can be created through various methods provided by the spec object. For this tutorial, the positional() method is relevant. Other methods are necessary if your use case involves enhanced enumerations. If so, please refer to the "Enhanced Enumeration" section.

To create an entry, you need to provide the value you want to store, along with an optional format if you intend to parse it later. It is important to note that each entry can only accept one value per object. Adding multiple entries to a single object will result in an exception.

 val simpleEnumClass = ClassSpec.enumClass("Vehicle")
     .enumProperty(EnumEntrySpec.builder("car").build())
     .enumProperty(EnumEntrySpec.builder("bus").build())
     .build()

Enhanced enumerations:

In this section, we will extend our previous example to create an enhanced enumeration in the Dart programming language. Before diving into a more complex enumeration, it is important to discuss certain restrictions and requirements.

Points which are good to know:

  1. Instance variables must be final, including those added by mixins

  2. All generative constructors must be constant

  3. Factory constructors can only return one of the fixed, known enum instances

  4. No other class can be extended as Enum is automatically extended

  5. There cannot be overrides for index, hashCode, the equality operator ==

  6. A member named values cannot be declared in an enum, as it would conflict with the automatically generated static values' getter

  7. All instances of the enum must be declared in the beginning of the declaration, and there must be at least one instance declared

It's possible that the given implementation lacks some requirements, if this is true, please open an issue at the GitHub repository.

Now, let's enhance our current example to create an advanced enumeration. To add a parameter to an EnumEntrySpec, we need to use the EnumParameterSpec, which is required to describe each parameter. However, note that an EnumParameterSpec can only hold a single property. Attempting to add multiple parameters will result in an error. This limitation exists because the internal structure maps the provided data to a CodeBlock, which is capable of handling an unspecified amount of data.

When adding a parameter to an Enum class, you must use the appropriate method for its creation. Dart offers various parameter types, and if you're unsure about the available types, refer to the relevant documentation. The API sorts parameters based on their type to prevent invalid generation.

 val simpleEnumClass = ClassSpec.enumClass("Vehicle")
     .enumProperty(EnumEntrySpec.builder("car").parameter {
         EnumParameterSpec.positional("%C", "BMW")
     }.build())
     .enumProperty(EnumEntrySpec.builder("bus").parameter {
         EnumParameterSpec.positional("%C", "MAN")
     }.build())
     .property(
         PropertySpec.builder("name", String::class)
             .modifier { DartModifier.FINAL }.build()
     )
     .constructor(
         ConstructorSpec.builder("Vehicle")
             .modifier(DartModifier.CONST)
             .parameter(
                 ParameterSpec.positional("name").build()
             )
             .build()
     )
     .build()

DartPoet has some checks to enusures that the data from the spec matches with the requirements from Dart. If you try to create an enhanced enum where the parameters from the entries are different to the class properties, you will raise an exception.

PreviousClassesNextAbstract

Last updated