feat(embind): add a way to register enums valus as plain string (#24324, #19387, #18585)

Author: FelixNumworks

site/source/docs/api_reference/bind.h.rst

@@ -804,11 +804,12 @@ Enums
       A typedef of ``EnumType`` (a typename for the class).
 
 
-   .. cpp:function::  enum_(const char* name)
+   .. cpp:function::  enum_(const char* name, bool asString = false)
 
       Constructor.
 
       :param const char* name:
+      :param bool asString: *Experimental.* If true, the enum values are represented by plain strings in JavaScript, which is handy for basic operations like comparison and serialization.
 
 
    .. cpp:function::  enum_& value(const char* name, EnumType value)

site/source/docs/porting/connecting_cpp_and_javascript/embind.rst

@@ -825,6 +825,21 @@ type.
     Module.OldStyle.ONE;
     Module.NewStyle.TWO;
 
+If you set the `asString` parameter to `true` when registering the enum, the enum values will be represented as plain strings in JavaScript.
+
+.. code:: cpp
+
+    EMSCRIPTEN_BINDINGS(my_enum_example) {
+        enum_<MyEnum>("MyEnum", true)
+            .value("ONE", MyEnum::ONE)
+            .value("TWO", MyEnum::TWO)
+            ;
+    }
+
+.. code:: javascript
+
+    Module.MyEnum.ONE === "ONE"; // true
+
 .. _embind-constants:
 
 Constants

src/lib/libembind.js

@@ -2199,38 +2199,68 @@ var LibraryEmbind = {
   _embind_register_enum__docs: '/** @suppress {globalThis} */',
   _embind_register_enum__deps: ['$exposePublicSymbol', '$enumReadValueFromPointer',
     '$AsciiToString', '$registerType'],
-  _embind_register_enum: (rawType, name, size, isSigned) => {
+  _embind_register_enum: (rawType, name, size, isSigned, asString) => {
     name = AsciiToString(name);
 
-    function ctor() {}
-    ctor.values = {};
-
-    registerType(rawType, {
-      name,
-      constructor: ctor,
-      fromWireType: function(c) {
-        return this.constructor.values[c];
-      },
-      toWireType: (destructors, c) => c.value,
-      readValueFromPointer: enumReadValueFromPointer(name, size, isSigned),
-      destructorFunction: null,
-    });
-    exposePublicSymbol(name, ctor);
+    if (asString) {
+      var valuesMap = {};
+      var reverseMap = {};
+      var keysMap = {};
+
+      registerType(rawType, {
+        name: name,
+        valuesMap,
+        reverseMap,
+        keysMap,
+        asString,
+        fromWireType: function(c) {
+          return this.reverseMap[c];
+        },
+        toWireType: function(destructors, c) {
+          return this.valuesMap[c];
+        },
+        readValueFromPointer: enumReadValueFromPointer(name, size, isSigned),
+        destructorFunction: null,
+      });
+      exposePublicSymbol(name, keysMap);
+      // Just exposes a simple dict. argCount is meaningless here,
+      delete Module[name].argCount;
+    } else {
+      function ctor() {}
+      ctor.values = {};
+
+      registerType(rawType, {
+        name,
+        constructor: ctor,
+        fromWireType: function(c) {
+          return this.constructor.values[c];
+        },
+        toWireType: (destructors, c) => c.value,
+        readValueFromPointer: enumReadValueFromPointer(name, size, isSigned),
+        destructorFunction: null,
+      });
+      exposePublicSymbol(name, ctor);
+    }
   },
 
   _embind_register_enum_value__deps: ['$createNamedFunction', '$AsciiToString', '$requireRegisteredType'],
   _embind_register_enum_value: (rawEnumType, name, enumValue) => {
     var enumType = requireRegisteredType(rawEnumType, 'enum');
     name = AsciiToString(name);
 
-    var Enum = enumType.constructor;
-
-    var Value = Object.create(enumType.constructor.prototype, {
-      value: {value: enumValue},
-      constructor: {value: createNamedFunction(`${enumType.name}_${name}`, function() {})},
-    });
-    Enum.values[enumValue] = Value;
-    Enum[name] = Value;
+    if (enumType.asString) {
+      enumType.valuesMap[name] = enumValue;
+      enumType.reverseMap[enumValue] = name;
+      enumType.keysMap[name] = name;
+    } else {
+      var Enum = enumType.constructor;
+      var Value = Object.create(enumType.constructor.prototype, {
+        value: {value: enumValue},
+        constructor: {value: createNamedFunction(`${enumType.name}_${name}`, function() {})},
+      });
+      Enum.values[enumValue] = Value;
+      Enum[name] = Value;
+    }
   },
 
   _embind_register_constant__deps: ['$AsciiToString', '$whenDependentTypesAreResolved'],

src/lib/libembind_gen.js

@@ -279,23 +279,30 @@ var LibraryEmbind = {
   },
   $EnumDefinition: class {
     hasPublicSymbol = true;
-    constructor(typeId, name) {
+    constructor(typeId, name, asString) {
       this.typeId = typeId;
       this.name = name;
       this.items = [];
       this.destructorType = 'none';
+      this.asString = asString;
     }
 
     print(nameMap, out) {
-      out.push(`export interface ${this.name}Value<T extends number> {\n`);
-      out.push('  value: T;\n}\n');
+      if (!this.asString) {
+        out.push(`export interface ${this.name}Value<T extends number> {\n`);
+        out.push('  value: T;\n}\n');
+      }
       out.push(`export type ${this.name} = `);
       if (this.items.length === 0) {
         out.push('never/* Empty Enumerator */');
       } else {
         const outItems = [];
         for (const [name, value] of this.items) {
-          outItems.push(`${this.name}Value<${value}>`);
+          if (this.asString) {
+            outItems.push(`'${name}'`);
+          } else {
+            outItems.push(`${this.name}Value<${value}>`);
+          }
         }
         out.push(outItems.join('|'));
       }
@@ -306,7 +313,11 @@ var LibraryEmbind = {
       out.push(`  ${this.name}: {`);
       const outItems = [];
       for (const [name, value] of this.items) {
-        outItems.push(`${name}: ${this.name}Value<${value}>`);
+        if (this.asString) {
+          outItems.push(`${name}: '${name}'`);
+        } else {
+          outItems.push(`${name}: ${this.name}Value<${value}>`);
+        }
       }
       out.push(outItems.join(', '));
       out.push('};\n');
@@ -712,9 +723,9 @@ var LibraryEmbind = {
   // Stub function. This is called a when extending an object and not needed for TS generation.
   _embind_create_inheriting_constructor: (constructorName, wrapperType, properties) => {},
   _embind_register_enum__deps: ['$AsciiToString', '$EnumDefinition', '$moduleDefinitions'],
-  _embind_register_enum: function(rawType, name, size, isSigned) {
+  _embind_register_enum: function(rawType, name, size, isSigned, asString) {
     name = AsciiToString(name);
-    const enumDef = new EnumDefinition(rawType, name);
+    const enumDef = new EnumDefinition(rawType, name, asString);
     registerType(rawType, enumDef);
     moduleDefinitions.push(enumDef);
   },

system/include/emscripten/bind.h

@@ -228,7 +228,8 @@ void _embind_register_enum(
     TYPEID enumType,
     const char* name,
     size_t size,
-    bool isSigned);
+    bool isSigned,
+    bool asString);
 
 void _embind_register_smart_ptr(
     TYPEID pointerType,
@@ -2168,13 +2169,14 @@ class enum_ {
 public:
     typedef EnumType enum_type;
 
-    enum_(const char* name) {
+    enum_(const char* name, bool asString = false) {
         using namespace internal;
         _embind_register_enum(
             internal::TypeID<EnumType>::get(),
             name,
             sizeof(EnumType),
-            std::is_signed<typename std::underlying_type<EnumType>::type>::value);
+            std::is_signed<typename std::underlying_type<EnumType>::type>::value,
+            asString);
     }
 
     enum_& value(const char* name, EnumType value) {

test/embind/embind.test.js

@@ -2031,6 +2031,26 @@ module({
         });
     });
 
+    BaseFixture.extend("enums with string values", function() {
+        test("can compare enumeration values", function() {
+            assert.equal(cm.EnumStr.ONE, cm.EnumStr.ONE);
+            assert.equal(cm.EnumStr.ONE, 'ONE');
+            assert.notEqual(cm.EnumStr.ONE, cm.EnumStr.TWO);
+        });
+
+        if (typeof INVOKED_FROM_EMSCRIPTEN_TEST_RUNNER === "undefined") { // TODO: Enable this to work in Emscripten runner as well!
+            test("repr includes enum value", function() {
+                assert.equal('ONE', IMVU.repr(cm.EnumStr.ONE));
+                assert.equal('TWO', IMVU.repr(cm.EnumStr.TWO));
+            });
+        }
+
+        test("can pass and return enumeration values to functions", function() {
+            assert.equal(cm.EnumStr.TWO, cm.emval_test_take_and_return_EnumStr(cm.EnumStr.TWO));
+            assert.equal('TWO', cm.emval_test_take_and_return_EnumStr('TWO'));
+        });
+    });
+
     BaseFixture.extend("emval call tests", function() {
         test("can call functions from C++", function() {
             var called = false;

test/embind/embind_test.cpp

@@ -1016,6 +1016,12 @@ EnumClass emval_test_take_and_return_EnumClass(EnumClass e) {
   return e;
 }
 
+enum class EnumStr { ONE, TWO };
+
+EnumStr emval_test_take_and_return_EnumStr(EnumStr e) {
+  return e;
+}
+
 void emval_test_call_function(val v, int i, float f, TupleVector tv, StructVector sv) {
   v(i, f, tv, sv);
 }
@@ -2350,6 +2356,12 @@ EMSCRIPTEN_BINDINGS(tests) {
     ;
   function("emval_test_take_and_return_EnumClass", &emval_test_take_and_return_EnumClass);
 
+  enum_<EnumStr>("EnumStr", true)
+    .value("ONE", EnumStr::ONE)
+    .value("TWO", EnumStr::TWO)
+    ;
+  function("emval_test_take_and_return_EnumStr", &emval_test_take_and_return_EnumStr);
+
   function("emval_test_call_function", &emval_test_call_function);
 
   function("emval_test_return_unique_ptr", &emval_test_return_unique_ptr);

test/other/embind_tsgen.cpp

@@ -47,10 +47,14 @@ std::unique_ptr<Test> class_unique_ptr_returning_fn() {
 
 enum Bar { kValueOne, kValueTwo, kValueThree };
 
+enum Baz { kValueA, kValueB, kValueC };
+
 enum EmptyEnum {};
 
 Bar enum_returning_fn() { return kValueOne; }
 
+Baz str_enum_returning_fn() { return kValueA; }
+
 struct ValArr {
   int x, y, z;
 };
@@ -59,6 +63,7 @@ EMSCRIPTEN_DECLARE_VAL_TYPE(CallbackType);
 
 struct ValObj {
   Bar bar;
+  Baz baz;
   std::string string;
   CallbackType callback;
   ValObj() : callback(val::undefined()) {}
@@ -181,9 +186,14 @@ EMSCRIPTEN_BINDINGS(Test) {
       .value("valueOne", Bar::kValueOne)
       .value("valueTwo", Bar::kValueTwo)
       .value("valueThree", Bar::kValueThree);
+  enum_<Baz>("Baz", true)
+      .value("valueA", Baz::kValueA)
+      .value("valueB", Baz::kValueB)
+      .value("valueC", Baz::kValueC);
   enum_<EmptyEnum>("EmptyEnum");
 
   function("enum_returning_fn", &enum_returning_fn);
+  function("str_enum_returning_fn", &str_enum_returning_fn);
 
   value_array<ValArr>("ValArr")
       .element(&ValArr::x)
@@ -199,6 +209,7 @@ EMSCRIPTEN_BINDINGS(Test) {
   value_object<ValObj>("ValObj")
       .field("string", &ValObj::string)
       .field("bar", &ValObj::bar)
+      .field("baz", &ValObj::baz)
       .field("callback", &ValObj::callback);
   function("getValObj", &getValObj);
   function("setValObj", &setValObj);

test/other/embind_tsgen.d.ts

@@ -36,6 +36,8 @@ export interface BarValue<T extends number> {
 }
 export type Bar = BarValue<0>|BarValue<1>|BarValue<2>;
 
+export type Baz = 'valueA'|'valueB'|'valueC';
+
 export interface EmptyEnumValue<T extends number> {
   value: T;
 }
@@ -94,6 +96,7 @@ export type ValArr = [ number, number, number ];
 export type ValObj = {
   string: EmbindString,
   bar: Bar,
+  baz: Baz,
   callback: (message: string) => void
 };
 
@@ -113,8 +116,10 @@ interface EmbindModule {
   a_class_instance: Test;
   an_enum: Bar;
   Bar: {valueOne: BarValue<0>, valueTwo: BarValue<1>, valueThree: BarValue<2>};
+  Baz: {valueA: 'valueA', valueB: 'valueB', valueC: 'valueC'};
   EmptyEnum: {};
   enum_returning_fn(): Bar;
+  str_enum_returning_fn(): Baz;
   IntVec: {
     new(): IntVec;
   };

test/other/embind_tsgen_ignore_1.d.ts

@@ -47,6 +47,8 @@ export interface BarValue<T extends number> {
 }
 export type Bar = BarValue<0>|BarValue<1>|BarValue<2>;
 
+export type Baz = 'valueA'|'valueB'|'valueC';
+
 export interface EmptyEnumValue<T extends number> {
   value: T;
 }
@@ -105,6 +107,7 @@ export type ValArr = [ number, number, number ];
 export type ValObj = {
   string: EmbindString,
   bar: Bar,
+  baz: Baz,
   callback: (message: string) => void
 };
 
@@ -124,8 +127,10 @@ interface EmbindModule {
   a_class_instance: Test;
   an_enum: Bar;
   Bar: {valueOne: BarValue<0>, valueTwo: BarValue<1>, valueThree: BarValue<2>};
+  Baz: {valueA: 'valueA', valueB: 'valueB', valueC: 'valueC'};
   EmptyEnum: {};
   enum_returning_fn(): Bar;
+  str_enum_returning_fn(): Baz;
   IntVec: {
     new(): IntVec;
   };