Improve C and JS API module inspection features (#3464)

* BinaryenGetFunction, BinaryenGetGlobal, BinaryenGetEvent now return NULL if an element does not exist
* Adds BinaryenGetExport, BinaryenGetNumGlobals, BinaryenGetGlobalByIndex
* Corrects BinaryenGetNumFunctions return type
* Adds related descriptions of C API functions

3 files changed, 82 insertions, 37 deletions

diff --git a/src/binaryen-c.cpp b/src/binaryen-c.cpp
index 7b2ef9214..b6e14d694 100644
--- a/src/binaryen-c.cpp
+++ b/src/binaryen-c.cpp
@@ -3011,21 +3011,21 @@ BinaryenFunctionRef BinaryenAddFunction(BinaryenModuleRef module,
 }
 BinaryenFunctionRef BinaryenGetFunction(BinaryenModuleRef module,
                                         const char* name) {
-  return ((Module*)module)->getFunction(name);
+  return ((Module*)module)->getFunctionOrNull(name);
 }
 void BinaryenRemoveFunction(BinaryenModuleRef module, const char* name) {
   ((Module*)module)->removeFunction(name);
 }
-uint32_t BinaryenGetNumFunctions(BinaryenModuleRef module) {
+BinaryenIndex BinaryenGetNumFunctions(BinaryenModuleRef module) {
   return ((Module*)module)->functions.size();
 }
 BinaryenFunctionRef BinaryenGetFunctionByIndex(BinaryenModuleRef module,
-                                               BinaryenIndex id) {
+                                               BinaryenIndex index) {
   const auto& functions = ((Module*)module)->functions;
-  if (functions.size() <= id) {
-    Fatal() << "invalid function id.";
+  if (functions.size() <= index) {
+    Fatal() << "invalid function index.";
   }
-  return functions[id].get();
+  return functions[index].get();
 }
 
 // Globals
@@ -3045,11 +3045,22 @@ BinaryenGlobalRef BinaryenAddGlobal(BinaryenModuleRef module,
 }
 BinaryenGlobalRef BinaryenGetGlobal(BinaryenModuleRef module,
                                     const char* name) {
-  return ((Module*)module)->getGlobal(name);
+  return ((Module*)module)->getGlobalOrNull(name);
 }
 void BinaryenRemoveGlobal(BinaryenModuleRef module, const char* name) {
   ((Module*)module)->removeGlobal(name);
 }
+BinaryenIndex BinaryenGetNumGlobals(BinaryenModuleRef module) {
+  return ((Module*)module)->globals.size();
+}
+BinaryenGlobalRef BinaryenGetGlobalByIndex(BinaryenModuleRef module,
+                                           BinaryenIndex index) {
+  const auto& globals = ((Module*)module)->globals;
+  if (globals.size() <= index) {
+    Fatal() << "invalid global index.";
+  }
+  return globals[index].get();
+}
 
 // Events
 
@@ -3067,7 +3078,7 @@ BinaryenEventRef BinaryenAddEvent(BinaryenModuleRef module,
 }
 
 BinaryenEventRef BinaryenGetEvent(BinaryenModuleRef module, const char* name) {
-  return ((Module*)module)->getEvent(name);
+  return ((Module*)module)->getEventOrNull(name);
 }
 void BinaryenRemoveEvent(BinaryenModuleRef module, const char* name) {
   ((Module*)module)->removeEvent(name);
@@ -3192,9 +3203,24 @@ BinaryenExportRef BinaryenAddEventExport(BinaryenModuleRef module,
   ((Module*)module)->addExport(ret);
   return ret;
 }
+BinaryenExportRef BinaryenGetExport(BinaryenModuleRef module,
+                                    const char* externalName) {
+  return ((Module*)module)->getExportOrNull(externalName);
+}
 void BinaryenRemoveExport(BinaryenModuleRef module, const char* externalName) {
   ((Module*)module)->removeExport(externalName);
 }
+BinaryenIndex BinaryenGetNumExports(BinaryenModuleRef module) {
+  return ((Module*)module)->exports.size();
+}
+BinaryenExportRef BinaryenGetExportByIndex(BinaryenModuleRef module,
+                                           BinaryenIndex index) {
+  const auto& exports = ((Module*)module)->exports;
+  if (exports.size() <= index) {
+    Fatal() << "invalid export index.";
+  }
+  return exports[index].get();
+}
 
 // Function table. One per module
 
@@ -3812,17 +3838,6 @@ const char* BinaryenExportGetName(BinaryenExportRef export_) {
 const char* BinaryenExportGetValue(BinaryenExportRef export_) {
   return ((Export*)export_)->value.c_str();
 }
-uint32_t BinaryenGetNumExports(BinaryenModuleRef module) {
-  return ((Module*)module)->exports.size();
-}
-BinaryenExportRef BinaryenGetExportByIndex(BinaryenModuleRef module,
-                                           BinaryenIndex id) {
-  const auto& exports = ((Module*)module)->exports;
-  if (exports.size() <= id) {
-    Fatal() << "invalid export id.";
-  }
-  return exports[id].get();
-}
 
 //
 // ========= Custom sections =========
diff --git a/src/binaryen-c.h b/src/binaryen-c.h
index c4517257a..33ada13b1 100644
--- a/src/binaryen-c.h
+++ b/src/binaryen-c.h
@@ -1872,7 +1872,8 @@ BinaryenAddFunction(BinaryenModuleRef module,
                     BinaryenType* varTypes,
                     BinaryenIndex numVarTypes,
                     BinaryenExpressionRef body);
-// Gets a function reference by name.
+// Gets a function reference by name. Returns NULL if the function does not
+// exist.
 BINARYEN_API BinaryenFunctionRef BinaryenGetFunction(BinaryenModuleRef module,
                                                      const char* name);
 // Removes a function by name.
@@ -1880,10 +1881,10 @@ BINARYEN_API void BinaryenRemoveFunction(BinaryenModuleRef module,
                                          const char* name);
 
 // Gets the number of functions in the module.
-BINARYEN_API uint32_t BinaryenGetNumFunctions(BinaryenModuleRef module);
-// Get function pointer from its index.
+BINARYEN_API BinaryenIndex BinaryenGetNumFunctions(BinaryenModuleRef module);
+// Gets the function at the specified index.
 BINARYEN_API BinaryenFunctionRef
-BinaryenGetFunctionByIndex(BinaryenModuleRef module, BinaryenIndex id);
+BinaryenGetFunctionByIndex(BinaryenModuleRef module, BinaryenIndex index);
 
 // Imports
 
@@ -1923,47 +1924,72 @@ BINARYEN_REF(Export);
 WASM_DEPRECATED BinaryenExportRef BinaryenAddExport(BinaryenModuleRef module,
                                                     const char* internalName,
                                                     const char* externalName);
+// Adds a function export to the module.
 BINARYEN_API BinaryenExportRef BinaryenAddFunctionExport(
   BinaryenModuleRef module, const char* internalName, const char* externalName);
+// Adds a table export to the module.
 BINARYEN_API BinaryenExportRef BinaryenAddTableExport(BinaryenModuleRef module,
                                                       const char* internalName,
                                                       const char* externalName);
+// Adds a memory export to the module.
 BINARYEN_API BinaryenExportRef BinaryenAddMemoryExport(
   BinaryenModuleRef module, const char* internalName, const char* externalName);
+// Adds a global export to the module.
 BINARYEN_API BinaryenExportRef BinaryenAddGlobalExport(
   BinaryenModuleRef module, const char* internalName, const char* externalName);
+// Adds an event export to the module.
 BINARYEN_API BinaryenExportRef BinaryenAddEventExport(BinaryenModuleRef module,
                                                       const char* internalName,
                                                       const char* externalName);
+// Gets an export reference by external name. Returns NULL if the export does
+// not exist.
+BINARYEN_API BinaryenExportRef BinaryenGetExport(BinaryenModuleRef module,
+                                                 const char* externalName);
+// Removes an export by external name.
 BINARYEN_API void BinaryenRemoveExport(BinaryenModuleRef module,
                                        const char* externalName);
+// Gets the number of exports in the module.
+BINARYEN_API BinaryenIndex BinaryenGetNumExports(BinaryenModuleRef module);
+// Gets the export at the specified index.
+BINARYEN_API BinaryenExportRef
+BinaryenGetExportByIndex(BinaryenModuleRef module, BinaryenIndex index);
 
 // Globals
 
 BINARYEN_REF(Global);
 
+// Adds a global to the module.
 BINARYEN_API BinaryenGlobalRef BinaryenAddGlobal(BinaryenModuleRef module,
                                                  const char* name,
                                                  BinaryenType type,
                                                  int8_t mutable_,
                                                  BinaryenExpressionRef init);
-// Gets a global reference by name.
+// Gets a global reference by name. Returns NULL if the global does not exist.
 BINARYEN_API BinaryenGlobalRef BinaryenGetGlobal(BinaryenModuleRef module,
                                                  const char* name);
+// Removes a global by name.
 BINARYEN_API void BinaryenRemoveGlobal(BinaryenModuleRef module,
                                        const char* name);
+// Gets the number of globals in the module.
+BINARYEN_API BinaryenIndex BinaryenGetNumGlobals(BinaryenModuleRef module);
+// Gets the global at the specified index.
+BINARYEN_API BinaryenGlobalRef
+BinaryenGetGlobalByIndex(BinaryenModuleRef module, BinaryenIndex index);
 
 // Events
 
 BINARYEN_REF(Event);
 
+// Adds an event to the module.
 BINARYEN_API BinaryenEventRef BinaryenAddEvent(BinaryenModuleRef module,
                                                const char* name,
                                                uint32_t attribute,
                                                BinaryenType params,
                                                BinaryenType results);
+// Gets an event reference by name. Returns NULL if the event does not exist.
 BINARYEN_API BinaryenEventRef BinaryenGetEvent(BinaryenModuleRef module,
                                                const char* name);
+// Removes an event by name.
 BINARYEN_API void BinaryenRemoveEvent(BinaryenModuleRef module,
                                       const char* name);
 
@@ -2331,11 +2357,6 @@ BinaryenExportGetKind(BinaryenExportRef export_);
 BINARYEN_API const char* BinaryenExportGetName(BinaryenExportRef export_);
 // Gets the internal name of the specified export.
 BINARYEN_API const char* BinaryenExportGetValue(BinaryenExportRef export_);
-// Gets the number of exports in the module.
-BINARYEN_API uint32_t BinaryenGetNumExports(BinaryenModuleRef module);
-// Get export pointer from its index.
-BINARYEN_API BinaryenExportRef
-BinaryenGetExportByIndex(BinaryenModuleRef module, BinaryenIndex id);
 
 //
 // ========= Custom sections =========
diff --git a/src/js/binaryen.js-post.js b/src/js/binaryen.js-post.js
index bbf2ae237..128e148e2 100644
--- a/src/js/binaryen.js-post.js
+++ b/src/js/binaryen.js-post.js
@@ -2340,18 +2340,27 @@ function wrapModule(module, self = {}) {
       Module['_BinaryenAddCustomSection'](module, strToStack(name), i8sToStack(contents), contents.length)
     );
   };
+  self['getExport'] = function(externalName) {
+    return preserveStack(() => Module['_BinaryenGetExport'](module, strToStack(externalName)));
+  };
   self['getNumExports'] = function() {
     return Module['_BinaryenGetNumExports'](module);
-  }
-  self['getExportByIndex'] = function(id) {
-    return Module['_BinaryenGetExportByIndex'](module, id);
-  }
+  };
+  self['getExportByIndex'] = function(index) {
+    return Module['_BinaryenGetExportByIndex'](module, index);
+  };
   self['getNumFunctions'] = function() {
     return Module['_BinaryenGetNumFunctions'](module);
-  }
-  self['getFunctionByIndex'] = function(id) {
-    return Module['_BinaryenGetFunctionByIndex'](module, id);
-  }
+  };
+  self['getFunctionByIndex'] = function(index) {
+    return Module['_BinaryenGetFunctionByIndex'](module, index);
+  };
+  self['getNumGlobals'] = function() {
+    return Module['_BinaryenGetNumGlobals'](module);
+  };
+  self['getGlobalByIndex'] = function(index) {
+    return Module['_BinaryenGetGlobalByIndex'](module, index);
+  };
   self['emitText'] = function() {
     const old = out;
     let ret = '';