Lulu Enums — Constructors

Introduction

Enum:new(...) and Enum(...)

These functions create an Enum instance from various sources:

The function call Enum(...) is a synonym for Enum:new(...).
  1. The arguments can be an array of strings, which are the enumerator names.
    The strings can optionally have ordinal values for the enumerators embedded in them.
  2. The argument can be a long string from which we parse enumerator names.
    The string can optionally have ordinal values for the enumerators embedded in it.
  3. The argument can be a Lua table with string keys and number values.
    The table keys are the enumerator names, and the table values are the ordinals.
  4. The argument can be a Lua table with string keys and arbitrary associated data for the corresponding enumerators.
    The table keys are the enumerator names, and the table values are the arbitrary associated data.
    The ordinals can be specified or generated as consecutive integers starting at 1.
  5. The argument can be missing.
    Enum()returns an empty Enum instance you can fill using the add_enumerator method.
In all cases, the enumerator names must be unique.
The enumerator ordinals can have duplicates.
If the ordinals are not specified, we use consecutive integers starting at 1.
If you set a custom ordinal value for an enumerator the rest of the ordinal values increment from there.

From Strings

1Suit_1 = Enum{ 'Clubs', 'Diamonds', 'Hearts', 'Spades' }
2Suit_2 = Enum{ 'Clubs', 'Diamonds = 20', 'Hearts', 'Spades = 40' }
3Suit_3 = Enum{ 'Clubs = 1', 'Diamonds = 2', 'Hearts = 4', 'Spades = 8' }
4Suit_4 = Enum[[Clubs, Diamonds, Hearts, Spades]]
5Suit_5 = Enum[[Clubs = 0, Diamond, Hearts = 3, Spades = 3]]
1
The default ordinal values are 1, 2, 3, 4.
2
The ordinal values are 1, 20, 21, 40.
3
The ordinal values are 1, 2, 4, 8.
4
The ordinal values are 1, 2, 3, 4.
5
The ordinal values are 0, 1, 3, 3.
In each case, the default type of the Enum instance is Enum. If you want a different type you can set it using the Enum:set_type method. 
Suit_1:set_type('Suit_1')
Suit_2:set_type('Suit_2')
Suit_3:set_type('Suit_3')
Suit_4:set_type('Suit_4')
Suit_5:set_type('Suit_5')

If we print those Enum instances we get:

1Suit_1: [1] Clubs, [2] Diamonds, [3] Hearts, [4] Spades
Suit_2: [1] Clubs, [20] Diamonds, [21] Hearts, [40] Spades
Suit_3: [1] Clubs, [2] Diamonds, [4] Hearts, [8] Spades
Suit_4: [1] Clubs, [2] Diamonds, [3] Hearts, [4] Spades
Suit_5: [0] Clubs, [1] Diamond, [3] Hearts, [3] Spades
1
As promised, the ordinal values are 1, 2, 3, 4 etc.

From Tables

You can create an Enum instance from a table with string keys and number values:

1Suit_6 = Enum{ Clubs = 0, Diamonds = 1, Hearts = 2, Spades = 3 }
1
The ordinal values are 0, 1 2, 3.

More complex enums can have associated data for each enumerator:

Suit_7 = Enum{
    Clubs    = { abbrev = 'C', colour = 'black', icon = '♣' },
    Diamonds = { abbrev = 'D', colour = 'red',   icon = '♦' },
    Hearts   = { abbrev = 'H', colour = 'red',   icon = '♥' },
    Spades   = { abbrev = 'S', colour = 'black', icon = '♠' },
}
Suit_7:set_type('Suit_7')
print(Suit_7:pretty())

Output:

Suit_7:
1    [1] Diamonds = { abbrev = "D", colour = "red", icon = "♦" },
    [2] Spades = { abbrev = "S", colour = "black", icon = "♠" },
    [3] Hearts = { abbrev = "H", colour = "red", icon = "♥" },
    [4] Clubs = { abbrev = "C", colour = "black", icon = "♣" }
1
The ordinal values are automatically generated as 1, 2, 3, 4.

You can retrieve any associated data for an enumerator using the abbrev, color, or icon fields. For example, Suit.Diamonds.abbrev returns 'D'.

Here’s an example of an enum with manually set ordinal values:

Suit_8 = Enum{
    Clubs    = { abbrev = 'C', colour = 'black', icon = '♣', ordinal = 1 },
    Diamonds = { abbrev = 'D', colour = 'red',   icon = '♦', ordinal = 2 },
    Hearts   = { abbrev = 'H', colour = 'red',   icon = '♥', ordinal = 4 },
    Spades   = { abbrev = 'S', colour = 'black', icon = '♠', ordinal = 8 },
}
Suit_8:set_type('Suit_8')
putln("%T", Suit_8)

Output:

Suit_8:
1    [1] Clubs = { abbrev = "C", colour = "black", icon = "♣" },
    [2] Diamonds = { abbrev = "D", colour = "red", icon = "♦" },
    [4] Hearts = { abbrev = "H", colour = "red", icon = "♥" },
    [8] Spades = { abbrev = "S", colour = "black", icon = "♠" }
1
The ordinal values were manually set to 1, 2, 4, 8.
If you are using enums with associated data and custom ordinal values, you should set all the ordinal values when you create the Enum instance.

Using the ENUM Function

The lulu.Enum module exports the Enum class.

It also exports an ENUM function that gives you another way to create an Enum instance with preset types.

ENUM 'Suit' { 'Clubs', 'Diamonds', 'Hearts', 'Spades' }

This is equivalent to:

local Suit = Enum:new{ 'Clubs', 'Diamonds', 'Hearts', 'Spades' }
Suit:set_type('Suit')

A more complex example:

ENUM 'Suit' {
    Clubs    = { abbrev = 'C', colour = 'black', icon = '♣', ordinal = 1 },
    Diamonds = { abbrev = 'D', colour = 'red',   icon = '♦', ordinal = 2 },
    Hearts   = { abbrev = 'H', colour = 'red',   icon = '♥', ordinal = 4 },
    Spades   = { abbrev = 'S', colour = 'black', icon = '♠', ordinal = 8 },
}

This is equivalent to:

local Suit = Enum:new{
    Clubs    = { abbrev = 'C', colour = 'black', icon = '♣', ordinal = 1 },
    Diamonds = { abbrev = 'D', colour = 'red',   icon = '♦', ordinal = 2 },
    Hearts   = { abbrev = 'H', colour = 'red',   icon = '♥', ordinal = 4 },
    Spades   = { abbrev = 'S', colour = 'black', icon = '♠', ordinal = 8 },
}
Suit:set_type('Suit')

See Also

Enum:add_enumerator
Enum:set_type
Enum:type
Enum:tostring

Back to top