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 
27 namespace 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 {
53 public:
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,
86  const var::NativeFunctionArgs& args,
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,
95  const var::NativeFunctionArgs& args,
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 
118 private:
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 /** @}*/
#define JUCE_API
This macro is added to all JUCE public class declarations.
Represents a string identifier, designed for accessing properties by name.
A variant class, that can be used to hold a range of primitive values.
Definition: juce_Variant.h:45
The JUCE String class!
Definition: juce_String.h:42
A relative measure of time.
Represents a dynamically implemented object.
Holds a set of named var objects.
Represents the 'success' or 'failure' of an operation, and holds an associated error message to descr...
Definition: juce_Result.h:60
RelativeTime maximumExecutionTime
This value indicates how long a call to one of the evaluate methods is permitted to run before timing...
This structure is passed to a NativeFunction callback, and contains invocation details about the func...
Definition: juce_Variant.h:52
A smart-pointer class which points to a reference-counted object.
A simple javascript interpreter!