============================================================================== An execution context which you use for running javascript code. These are really simple to use: call one of the creation functions such as choc::javascript::createQuickJSContext() which will give you a shared_ptr to a context. Then you can add any native bindings that you need with regis
| 85 | block, or make system calls. |
| 86 | */ |
| 87 | class Context |
| 88 | { |
| 89 | public: |
| 90 | /// To create a Context, use a function such as choc::javascript::createQuickJSContext(); |
| 91 | Context() = default; |
| 92 | Context (Context&&); |
| 93 | Context& operator= (Context&&); |
| 94 | ~Context(); |
| 95 | |
| 96 | /// Returns true if the context is valid. |
| 97 | operator bool() const { return pimpl != nullptr; } |
| 98 | |
| 99 | //============================================================================== |
| 100 | /// This callback is used by the run() method. |
| 101 | using CompletionHandler = std::function<void(const std::string& error, |
| 102 | const choc::value::ValueView& result)>; |
| 103 | |
| 104 | /// Executes some javascript asynchronously. |
| 105 | /// If a CompletionHandler callback is provided, it will be called asynchronously |
| 106 | /// with the return value and any errors that occurred. Note that if you want to execute |
| 107 | /// the script as a module, use runModule() instead. |
| 108 | void run (const std::string& javascriptCode, |
| 109 | CompletionHandler handleResult = {}); |
| 110 | |
| 111 | /// When parsing modules, this function is expected to take a path to a module, and |
| 112 | /// to return the content of that module, or an empty optional if not found. |
| 113 | using ReadModuleContentFn = std::function<std::optional<std::string>(std::string_view)>; |
| 114 | |
| 115 | /// This callback will asynchronously parse the script as a module, and will use the |
| 116 | /// ReadModuleContentFn functor to resolve any imported modules that it needs. If a |
| 117 | /// CompletionHandler callback is provided, it will be called asynchronously with the |
| 118 | /// return value and any errors that occurred. |
| 119 | /// NB: Not all engines support modules. |
| 120 | void runModule (const std::string& moduleCode, |
| 121 | ReadModuleContentFn, |
| 122 | CompletionHandler handleResult = {}); |
| 123 | |
| 124 | /// Evaluates a javascript expression synchronously, and returns the result. |
| 125 | /// If there are any parse errors, this will throw a choc::javascript::Error exception. |
| 126 | /// Note that if you want to execute the script as a module, use runModule() instead. |
| 127 | choc::value::Value evaluateExpression (const std::string& javascriptCode); |
| 128 | |
| 129 | /// Attempts to synchronously invoke a global function with no arguments. |
| 130 | /// Any errors will throw a choc::javascript::Error exception. |
| 131 | /// None of the methods in this class are either thread-safe or realtime-safe, so you'll |
| 132 | /// need to organise your own locking if you're calling into a single Context from |
| 133 | /// multiple threads. |
| 134 | choc::value::Value invoke (std::string_view functionName); |
| 135 | |
| 136 | /// Attempts to invoke a global function with the arguments provided. |
| 137 | /// The arguments can be primitives, strings, choc::value::ValueView or |
| 138 | /// choc::value::Value types. |
| 139 | /// Any errors will throw a choc::javascript::Error exception. |
| 140 | /// None of the methods in this class are either thread-safe or realtime-safe, so you'll |
| 141 | /// need to organise your own locking if you're calling into a single Context from |
| 142 | /// multiple threads. |
| 143 | template <typename... Args> |
| 144 | choc::value::Value invoke (std::string_view functionName, Args&&... args); |