Simplify C/C++ Module Creation #2186
Description
This may not be the same Module API as what is currently available, but I figured most users would like a straight forward method to register custom Modules using the current strings api. For the most part the custom modules should automatically get cleaned out by garbage collection, and are straight forward on usage. This is a slight variation on issue #2112, but has a different approach and is meant for users who are embedding ChakraCore in cases where they do not wish to have the global object get polluted needlessly.
Note: This Feature request still has a lot of work needed for implementation, but in general the way to access the items contained from within the modules is to make use of the import keyword usage.
New Data Types:
/// <summary>
/// A module identifier.
/// </summary>
/// <remarks>
/// Module identifiers are used to refer to JavaScript Modules.
/// </remarks>
typedef JsRef JsModuleIdRef;New Functions
With this request there is a need for a few new functions to make this task easier to implement for users.
JsCreateModuleId
This function works like the C JsCreatePropertyIdUtf8 function except for it specifies a Module ID using the specified string.
/// <summary>
/// Creates the Module ID associated with a Custom C-Module.
/// </summary>
/// <remarks>
/// <para>
/// Module IDs are specific to a context and cannot be used across contexts.
/// </para>
/// <para>
/// Requires an active script context.
/// </para>
/// </remarks>
/// <param name="name">
/// The name of the Module ID to get or create. The name may consist of only digits.
/// The string is expected to be ASCII / utf8 encoded.
/// </param>
/// <param name="length">length of the name in bytes</param>
/// <param name="moduleId">The Module ID in this runtime for the given name.</param>
/// <returns>
/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.
/// </returns>
CHAKRA_API
JsCreateModuleId(
_In_z_ const char *name,
_In_ size_t length,
_Out_ JsModuleIdRef *moduleId);JsSetModuleProperty
This function is loosely based around the JsSetProperty function, but it instead places the new objects/Classes into the Module instead of the global object.
/// <summary>
/// Puts a Module's property.
/// </summary>
/// <remarks>
/// Requires an active script context.
/// </remarks>
/// <param name="module">The module that contains the property.</param>
/// <param name="propertyId">The ID of the property.</param>
/// <param name="value">The new value of the property.</param>
/// <param name="useStrictRules">The property set should follow strict mode rules.</param>
/// <returns>
/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.
/// </returns>
CHAKRA_API
JsSetModuleProperty(
_In_ JsModuleIdRef module,
_In_ JsPropertyIdRef propertyId,
_In_ JsValueRef value,
_In_ bool useStrictRules);Example Usage
Usage itself is relatively straight forward for those familiar with the current system. This example is loosely based on the Hello World and OpenGL Engine example.
void setModuleCallback(JsModuleIdRef module, const char *propertyName, JsNativeFunction callback, void *callbackState)
{
JsPropertyIdRef propertyId;
JsValueRef function;
size_t properyNameLen = strlen(propertyName);
JsCreatePropertyIdUtf8(propertyName, propertyNameLen,&propertyId);
JsCreateFunction(callback, callbackState, &function);
JsSetModuleProperty(module, propertyId, function, true);
}
void registerConsole()
{
JsModuleIdRef moduleId;
const char *consoleName = "Console";
size_t consoleNameLen = strlen(consoleName);
JsCreateModuleId(consoleName,consoleNameLen,&moduleId)
setModuleCallback(moduleId, "log", JSLog, nullptr);
}/* This is from the C-API */
import * as MyConsole from "Console";
MyConsole.log("Hello World");