Encoder

The Encoder class makes it easy to serialize and deserialize data for a variety of purposes. This class optionally depends on the C_EncodingUtil APIs provided by WoW, but LibTSMUtil also provides its own implementation for non-WoW environments with the help of the embedded LibDeflate and LibSerialize libraries. The only limitation in a non-WoW environment is that CBOR is not supported, which can be detected at runtime via the Encoder.SupportsCBOR() static function.

The serialization process performs 3 steps:

  1. Serialization - There are 3 different serialization types: "FAST", "STABLE", and "CBOR" or "NONE" can be specified to skip serialization entirely. The "FAST" and "STABLE" options leverage LibSerialize, with the former setting the stable option to to ensure that the result is stable, even for key-value tables. The :SetSerializationFilter() method allows for specifying the filter option to pass to LibSerialize. The last option leverages WoW’s C_EncodingUtil APIs for CBOR encoding.

  2. Compression - Compression is achieved either via WoW’s C_EncodingUtil APIs or LibDeflate to compress the data.

  3. Encoding - The resulting string is then encoded based on how it will be ultiized with three options being available: "PRINT" for ensuring the result is safely printable (via LibDeflate:EncodeForPrint()), "ADDON" for ensuring the result can be sent over the in-game addon comms channel (via LibDeflate:EncodeForWoWAddonChannel()), and "BASE64" for base64 encoding using the standard alphabet (includes “+” and “/”).

The deserialization process simply reverses the order of the 3 steps listed above.

Example

Here’s some code that shows how serialization and deserialization of data could be used to implement an RPC mechanism.

local MyModule = select(2, ...).MyModule
local Encoder = MyModule:From("LibTSMUtil"):IncludeClassType("Encoder")

local encoder = Encoder.Create()
   :SetEncodingType("ADDON")
   :SetSerializationType("FAST")

local request = encoder:Serialize("SWAP_ORDER", 11, 62)

local response = SendRequest(request) -- assume this is defined elsewhere

local success, result1, result2 = encoder:Deserialize(response)
assert(success)
print(result1, result2) -- 62    11

API

class Encoder: Class
staticmethod Create(): Encoder

Creates an encoder.

staticmethod SupportsCBOR(): boolean

Returns whether or not the encoder supports CBOR.

SetEncodingType(self: Encoder, encodingType: EncoderEncodingType): Encoder

Sets the encoding type to use.

SetSerializationType(
    self: Encoder,
    serializationType: EncoderSerializationType
): Encoder

Sets the serialization type to use.

SetSerializationFilter(
    self: Encoder,
    func: fun(tbl: table, k: any, v: any): boolean
): Encoder

Sets a serialization filter function.

Parameters:

func (fun(tbl: table, k: any, v: any): boolean) – The filter function

Serialize(self: Encoder, ...: any): string

Serializes, compresses, and encodes the given data.

Parameters:

... (any) – The data to serialize

Deserialize(self: Encoder, str: string): (success: boolean, ...: unknown)

Decodes, decompresses, and deserializes the given data.

Parameters:

str (string) – The data to deserialize