1 /*
2 Copyright 2015 Google Inc. All rights reserved.
3 
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7 
8     http://www.apache.org/licenses/LICENSE-2.0
9 
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16 
17 #ifndef JSONNET_VM_H
18 #define JSONNET_VM_H
19 
20 #include <libjsonnet.h>
21 
22 #include "ast.h"
23 
24 /** A single line of a stack trace from a runtime error.
25  */
26 struct TraceFrame {
27     LocationRange location;
28     std::string name;
29     TraceFrame(const LocationRange &location, const std::string &name = "")
locationTraceFrame30         : location(location), name(name)
31     {
32     }
33 };
34 
35 /** Exception that is thrown by the interpreter when it reaches an error construct, or divide by
36  * zero, array bounds error, dynamic type error, etc.
37  */
38 struct RuntimeError {
39     std::vector<TraceFrame> stackTrace;
40     std::string msg;
RuntimeErrorRuntimeError41     RuntimeError(const std::vector<TraceFrame> stack_trace, const std::string &msg)
42         : stackTrace(stack_trace), msg(msg)
43     {
44     }
45 };
46 
47 /** Holds native callback and context. */
48 struct VmNativeCallback {
49     JsonnetNativeCallback *cb;
50     void *ctx;
51     std::vector<std::string> params;
52 };
53 
54 typedef std::map<std::string, VmNativeCallback> VmNativeCallbackMap;
55 
56 /** Stores external values / code. */
57 struct VmExt {
58     std::string data;
59     bool isCode;
VmExtVmExt60     VmExt() : isCode(false) {}
VmExtVmExt61     VmExt(const std::string &data, bool is_code) : data(data), isCode(is_code) {}
62 };
63 
64 /** Execute the program and return the value as a JSON string.
65  *
66  * \param alloc The allocator used to create the ast.
67  * \param ast The program to execute.
68  * \param ext The external vars / code.
69  * \param max_stack Recursion beyond this level gives an error.
70  * \param gc_min_objects The garbage collector does not run when the heap is this small.
71  * \param gc_growth_trigger Growth since last garbage collection cycle to trigger a new cycle.
72  * \param import_callback A callback to handle imports
73  * \param import_callback_ctx Context param for the import callback.
74  * \param string_output Whether to expect a string and output it without JSON encoding
75  * \throws RuntimeError reports runtime errors in the program.
76  * \returns The JSON result in string form.
77  */
78 std::string jsonnet_vm_execute(Allocator *alloc, const AST *ast,
79                                const std::map<std::string, VmExt> &ext, unsigned max_stack,
80                                double gc_min_objects, double gc_growth_trigger,
81                                const VmNativeCallbackMap &natives,
82                                JsonnetImportCallback *import_callback, void *import_callback_ctx,
83                                bool string_output);
84 
85 /** Execute the program and return the value as a number of named JSON files.
86  *
87  * This assumes the given program yields an object whose keys are filenames.
88  *
89  * \param alloc The allocator used to create the ast.
90  * \param ast The program to execute.
91  * \param ext The external vars / code.
92  * \param tla The top-level arguments (strings or code).
93  * \param max_stack Recursion beyond this level gives an error.
94  * \param gc_min_objects The garbage collector does not run when the heap is this small.
95  * \param gc_growth_trigger Growth since last garbage collection cycle to trigger a new cycle.
96  * \param import_callback A callback to handle imports
97  * \param import_callback_ctx Context param for the import callback.
98  * \param string_output Whether to expect a string and output it without JSON encoding
99  * \throws RuntimeError reports runtime errors in the program.
100  * \returns A mapping from filename to the JSON strings for that file.
101  */
102 std::map<std::string, std::string> jsonnet_vm_execute_multi(
103     Allocator *alloc, const AST *ast, const std::map<std::string, VmExt> &ext, unsigned max_stack,
104     double gc_min_objects, double gc_growth_trigger, const VmNativeCallbackMap &natives,
105     JsonnetImportCallback *import_callback, void *import_callback_ctx, bool string_output);
106 
107 /** Execute the program and return the value as a stream of JSON files.
108  *
109  * This assumes the given program yields an array whose elements are individual
110  * JSON files.
111  *
112  * \param alloc The allocator used to create the ast.
113  * \param ast The program to execute.
114  * \param ext The external vars / code.
115  * \param tla The top-level arguments (strings or code).
116  * \param max_stack Recursion beyond this level gives an error.
117  * \param gc_min_objects The garbage collector does not run when the heap is this small.
118  * \param gc_growth_trigger Growth since last garbage collection cycle to trigger a new cycle.
119  * \param import_callback A callback to handle imports
120  * \param import_callback_ctx Context param for the import callback.
121  * \param string_output Whether to expect a string and output it without JSON encoding
122  * \throws RuntimeError reports runtime errors in the program.
123  * \returns A mapping from filename to the JSON strings for that file.
124  */
125 std::vector<std::string> jsonnet_vm_execute_stream(
126     Allocator *alloc, const AST *ast, const std::map<std::string, VmExt> &ext, unsigned max_stack,
127     double gc_min_objects, double gc_growth_trigger, const VmNativeCallbackMap &natives,
128     JsonnetImportCallback *import_callback, void *import_callback_ctx, bool string_output);
129 
130 #endif
131