OpenShot Library | libopenshot-audio 0.2.0
juce_Javascript.h
1
2/** @weakgroup juce_core-javascript
3 * @{
4 */
5/*
6 ==============================================================================
7
8 This file is part of the JUCE library.
9 Copyright (c) 2017 - ROLI Ltd.
10
11 JUCE is an open source library subject to commercial or open-source
12 licensing.
13
14 The code included in this file is provided under the terms of the ISC license
15 http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16 To use, copy, modify, and/or distribute this software for any purpose with or
17 without fee is hereby granted provided that the above copyright notice and
18 this permission notice appear in all copies.
19
20 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22 DISCLAIMED.
23
24 ==============================================================================
25*/
26
27namespace juce
28{
29
30//==============================================================================
31/**
32 A simple javascript interpreter!
33
34 It's not fully standards-compliant, and won't be as fast as the fancy JIT-compiled
35 engines that you get in browsers, but this is an extremely compact, low-overhead javascript
36 interpreter, which is integrated with the juce var and DynamicObject classes. If you need
37 a few simple bits of scripting in your app, and want to be able to easily let the JS
38 work with native objects defined as DynamicObject subclasses, then this might do the job.
39
40 To use, simply create an instance of this class and call execute() to run your code.
41 Variables that the script sets can be retrieved with evaluate(), and if you need to provide
42 native objects for the script to use, you can add them with registerNativeObject().
43
44 One caveat: Because the values and objects that the engine works with are DynamicObject
45 and var objects, they use reference-counting rather than garbage-collection, so if your
46 script creates complex connections between objects, you run the risk of creating cyclic
47 dependencies and hence leaking.
48
49 @tags{Core}
50*/
52{
53public:
54 /** Creates an instance of the engine.
55 This creates a root namespace and defines some basic Object, String, Array
56 and Math library methods.
57 */
59
60 /** Destructor. */
62
63 /** Attempts to parse and run a block of javascript code.
64 If there's a parse or execution error, the error description is returned in
65 the result.
66 You can specify a maximum time for which the program is allowed to run, and
67 it'll return with an error message if this time is exceeded.
68 */
69 Result execute (const String& javascriptCode);
70
71 /** Attempts to parse and run a javascript expression, and returns the result.
72 If there's a syntax error, or the expression can't be evaluated, the return value
73 will be var::undefined(). The errorMessage parameter gives you a way to find out
74 any parsing errors.
75 You can specify a maximum time for which the program is allowed to run, and
76 it'll return with an error message if this time is exceeded.
77 */
78 var evaluate (const String& javascriptCode,
79 Result* errorMessage = nullptr);
80
81 /** Calls a function in the root namespace, and returns the result.
82 The function arguments are passed in the same format as used by native
83 methods in the var class.
84 */
85 var callFunction (const Identifier& function,
87 Result* errorMessage = nullptr);
88
89 /** Calls a function object in the namespace of a dynamic object, and returns the result.
90 The function arguments are passed in the same format as used by native
91 methods in the var class.
92 */
93 var callFunctionObject (DynamicObject* objectScope,
94 const var& functionObject,
96 Result* errorMessage = nullptr);
97
98 /** Adds a native object to the root namespace.
99 The object passed-in is reference-counted, and will be retained by the
100 engine until the engine is deleted. The name must be a simple JS identifier,
101 without any dots.
102 */
103 void registerNativeObject (const Identifier& objectName, DynamicObject* object);
104
105 /** This value indicates how long a call to one of the evaluate methods is permitted
106 to run before timing-out and failing.
107 The default value is a number of seconds, but you can change this to whatever value
108 suits your application.
109 */
111
112 /** When called from another thread, causes the interpreter to time-out as soon as possible */
113 void stop() noexcept;
114
115 /** Provides access to the set of properties of the root namespace object. */
116 const NamedValueSet& getRootObjectProperties() const noexcept;
117
118private:
119 JUCE_PUBLIC_IN_DLL_BUILD (struct RootObject)
121 void prepareTimeout() const noexcept;
122
123 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (JavascriptEngine)
124};
125
126} // namespace juce
127
128/** @}*/
Holds a resizable array of primitive or copy-by-value objects.
Definition juce_Array.h:60
Represents a dynamically implemented object.
Represents a string identifier, designed for accessing properties by name.
A simple javascript interpreter!
RelativeTime maximumExecutionTime
This value indicates how long a call to one of the evaluate methods is permitted to run before timing...
Holds a set of named var objects.
A smart-pointer class which points to a reference-counted object.
A relative measure of time.
Represents the 'success' or 'failure' of an operation, and holds an associated error message to descr...
Definition juce_Result.h:61
The JUCE String class!
Definition juce_String.h:43
A variant class, that can be used to hold a range of primitive values.
#define JUCE_API
This macro is added to all JUCE public class declarations.
This structure is passed to a NativeFunction callback, and contains invocation details about the func...