Enum::ValueConverter(T) - Crystal 1.19.1

# module Enum::ValueConverter(T)

##
Overview

Converter for value-based serialization and deserialization of enum type `T`.

The serialization format of `Enum#to_json` and `Enum.from_json` is based on the member name. This converter offers an alternative based on the member value.

This converter can be used for its standalone serialization methods as a replacement of the default strategy of `Enum`. It also works as a serialization converter with `JSON::Field` and `YAML::Field`

    require "json"
    require "yaml"

    enum MyEnum
      ONE = 1
      TWO = 2
    end

    class Foo
      include JSON::Serializable
      include YAML::Serializable

      @[JSON::Field(converter: Enum::ValueConverter(MyEnum))]
      @[YAML::Field(converter: Enum::ValueConverter(MyEnum))]
      property foo : MyEnum = MyEnum::ONE

      def initialize(@foo)
      end
    end

    foo = Foo.new(MyEnum::ONE)
    foo.to_json # => %({"foo":1})
    foo.to_yaml # => %(---\nfoo: 1\n)

NOTE Automatically assigned enum values are subject to change when the order of members by adding, removing or reordering them. This can affect the integrity of serialized data between two instances of a program based on different code versions. A way to avoid this is to explicitly assign fixed values to enum members.

##
Defined in:

json/from_json.cr
json/to_json.cr
yaml/from_yaml.cr
yaml/to_yaml.cr

##
Constructors

- .new(ctx : YAML::ParseContext, node : YAML::Nodes::Node) : T
- .new(pull : JSON::PullParser) : T

##
Class Method Summary

- .from_json(pull : JSON::PullParser) : T

  Reads a serialized enum member by value from pull.

- .from_yaml(ctx : YAML::ParseContext, node : YAML::Nodes::Node) : T

  Reads a serialized enum member by value from ctx and node.

- .to_json(value : T, io : IO)
- .to_json(member : T, json : JSON::Builder)

  Serializes enum member member by value.

- .to_json(value : T)
- .to_yaml(value : T, io : IO)
- .to_yaml(member : T, yaml : YAML::Nodes::Builder)

  Serializes enum member member by value.

- .to_yaml(value : T)

##
Constructor Detail

def self.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node) : T #
def self.new(pull : JSON::PullParser) : T #

##
Class Method Detail

def self.from_json(pull : JSON::PullParser) : T #

Reads a serialized enum member by value from pull.

See `.to_json` for reference.

Raises `JSON::ParseException` if the deserialization fails.

def self.from_yaml(ctx : YAML::ParseContext, node : YAML::Nodes::Node) : T #

Reads a serialized enum member by value from ctx and node.

See `.to_yaml` for reference.

Raises `YAML::ParseException` if the deserialization fails.

def self.to_json(value : T, io : IO) #
def self.to_json(member : T, json : JSON::Builder) #

Serializes enum member member by value.

For both flags enums and non-flags enums, the value of the enum member is used for serialization.

    enum Stages
      INITIAL
      SECOND_STAGE
    end

    Enum::ValueConverter.to_json(Stages::INITIAL)      # => %(0)
    Enum::ValueConverter.to_json(Stages::SECOND_STAGE) # => %(1)

    @[Flags]
    enum Sides
      LEFT
      RIGHT
    end

    Enum::ValueConverter.to_json(Sides::LEFT)                # => %(1)
    Enum::ValueConverter.to_json(Sides::LEFT | Sides::RIGHT) # => %(3)
    Enum::ValueConverter.to_json(Sides::All)                 # => %(3)
    Enum::ValueConverter.to_json(Sides::None)                # => %(0)

`Enum#to_json` offers a different serialization strategy based on the member name.

def self.to_json(value : T) #
def self.to_yaml(value : T, io : IO) #
def self.to_yaml(member : T, yaml : YAML::Nodes::Builder) #

Serializes enum member member by value.

For both flags enums and non-flags enums, the value of the enum member is used for serialization.

    enum Stages
      INITIAL
      SECOND_STAGE
    end

    Enum::ValueConverter.to_yaml(Stages::INITIAL)      # => %(--- 0\n)
    Enum::ValueConverter.to_yaml(Stages::SECOND_STAGE) # => %(--- 1\n)

    @[Flags]
    enum Sides
      LEFT
      RIGHT
    end

    Enum::ValueConverter.to_yaml(Sides::LEFT)                # => %(--- 1\n)
    Enum::ValueConverter.to_yaml(Sides::LEFT | Sides::RIGHT) # => %(--- 3\n)
    Enum::ValueConverter.to_yaml(Sides::All)                 # => %(--- 3\n)
    Enum::ValueConverter.to_yaml(Sides::None)                # => %(--- 0\n)

`Enum#to_yaml` offers a different serialization strategy based on the member name.

def self.to_yaml(value : T) #