Skip to content
Flecs v4.2
script_shell.h
Go to the documentation of this file.
1/**
2 * @file addons/script_shell.h
3 * @brief Command line interface for interacting with a world.
4 */
5
6#ifdef FLECS_SCRIPT_SHELL
7
8#ifndef FLECS_SCRIPT
9#define FLECS_SCRIPT
10#endif
11
12#ifndef FLECS_QUERY_DSL
13#define FLECS_QUERY_DSL
14#endif
15
16#ifndef FLECS_FRAME
17#define FLECS_FRAME
18#endif
19
20#ifndef FLECS_JSON
21#define FLECS_JSON
22#endif
23
24/**
25 * @defgroup c_addons_script_shell Script Shell
26 * @ingroup c_addons
27 * Command line interface for interacting with a world.
28 *
29 * Commands are script functions. The command_paths member of the
30 * EcsScriptShell singleton lists the scopes that contain commands. When
31 * running a command, the scopes are searched in order and the first function
32 * with a matching name is used. The builtin commands are stored in:
33 *
34 * - flecs.script.shell.commands.core
35 * - flecs.script.shell.commands.input
36 * - flecs.script.shell.commands.script
37 *
38 * Applications can add commands by appending their own scopes to
39 * command_paths.
40 *
41 * Each command has typed parameters and a typed return value. A command line
42 * is parsed into a command name and arguments, where arguments are separated
43 * by whitespace:
44 *
45 * - A token that starts with `"` ends at the next unescaped `"`. The quotes are
46 * removed and escape sequences (`\n`, `\t`, ...) are processed.
47 * - A token that starts with three backticks ends at the next three backticks.
48 * The backticks are removed, the text in between is not processed.
49 * - `()`, `{}` and `[]` group a token and can be nested. They are passed to
50 * the command unchanged.
51 *
52 * Arguments for string parameters are passed as is. Arguments for other
53 * parameters are parsed as expressions of the parameter type. Identifiers are
54 * resolved relative to the scope of the session. For entity parameters `$`
55 * means the singleton, which uses the component argument as entity.
56 *
57 * Commands with optional parameters can be called with fewer arguments. Use
58 * the help command to list the commands and their parameters.
59 *
60 * A command line can contain multiple commands separated by `;`. Commands run
61 * in order, and each command sees the session state left by the previous one.
62 * When a command fails the remaining commands do not run. A `;` in a quoted
63 * string, between backticks or in a group is not a separator.
64 *
65 * Commands can store files, like images, as resources of the session with
66 * ecs_shell_resource_create(). A command signals that it returned a resource
67 * by returning the flecs.script.shell.resource type (ecs_shell_resource_t).
68 * Clients can then fetch the content of the resource with the REST API:
69 *
70 * @code
71 * GET /shell/session/<session>/resource/<name>
72 * @endcode
73 *
74 * Resources are stored in CWD/.flecs/shell/<session>/<name>. The directory is
75 * created when the first resource of a session is created, and is deleted
76 * together with the session.
77 * @{
78 */
79
80#ifndef FLECS_SCRIPT_SHELL_H
81#define FLECS_SCRIPT_SHELL_H
82
83#ifdef __cplusplus
84extern "C" {
85#endif
86
87/** Default number of commands kept in the history of a session. */
88#ifndef FLECS_SCRIPT_SHELL_HISTORY_SIZE
89#define FLECS_SCRIPT_SHELL_HISTORY_SIZE (256)
90#endif
91
92/** Result of running a command line. */
93typedef struct ecs_shell_result_t {
94 /** Values returned by the commands that ran, one entry per command in the
95 * order of the command line (vec<ecs_value_t>). The last entry belongs to
96 * the command that failed, if any. An entry is empty when the command has
97 * no return value or failed. Commands that edit script code are the
98 * exception: when the edit was applied but reloading the script failed,
99 * the entry is set together with the errors of the reload. */
100 ecs_vec_t results;
101
102 /** Errors logged while the commands ran, one entry per error (vec<char*>). */
103 ecs_vec_t errors;
104} ecs_shell_result_t;
105
106/** Resource created by a command, see ecs_shell_resource_create(). */
107typedef struct ecs_shell_resource_t {
108 char *name; /**< Name of the resource, unique within the session. */
109 char *content_type; /**< Content type (for example "image/png"). */
110} ecs_shell_resource_t;
111
112/** Command session.
113 * A session stores the scope relative to which commands resolve identifiers,
114 * and a bounded history of the commands that ran in the session together with
115 * their results.
116 *
117 * The results are stored as JSON objects with the scope in which the command
118 * ran, and the type, result and errors of the command:
119 *
120 * @code
121 * {"scope":"parent", "type":"flecs.meta.string", "result":"...", "errors":[]}
122 * @endcode
123 *
124 * The type and result members are omitted when the command did not return a
125 * value. The results and resources members are not reflected.
126 */
127typedef struct EcsCommandSession {
128 ecs_entity_t scope; /**< Current scope, 0 for the root. */
129 ecs_vec_t history; /**< Commands that ran, oldest first (vec<char*>). */
130 int32_t history_size; /**< Maximum number of commands in the history. */
131 ecs_vec_t results; /**< JSON results of the commands in the history (vec<char*>). */
132 ecs_vec_t resources; /**< Resources created by commands (vec<ecs_shell_resource_t>). */
133 char *resource_path; /**< Directory with the resource files, NULL if no resources were created. */
134} EcsCommandSession;
135
136/** Shell singleton. */
137typedef struct EcsScriptShell {
138 ecs_vec_t command_paths; /**< Scopes that contain commands, searched in order (vec<ecs_entity_t>). */
139} EcsScriptShell;
140
141/** Used with ecs_shell_session_init(). */
142typedef struct ecs_shell_session_desc_t {
143 ecs_entity_t entity; /**< Entity to use for the session (optional). */
144 ecs_entity_t scope; /**< Initial scope (optional, default is root). */
145 int32_t history_size; /**< History size (optional, default is FLECS_SCRIPT_SHELL_HISTORY_SIZE). */
146} ecs_shell_session_desc_t;
147
148/** Parameter of a command, returned by help. */
149typedef struct ecs_shell_param_info_t {
150 char *name; /**< Parameter name. */
151 ecs_entity_t type; /**< Parameter type. */
152 bool optional; /**< Whether the parameter is optional. */
153 char *brief; /**< Parameter description. */
154} ecs_shell_param_info_t;
155
156/** Command, returned by help. */
157typedef struct ecs_shell_info_t {
158 char *name; /**< Command name. */
159 char *brief; /**< Command description. */
160 ecs_vec_t params; /**< Parameters (vec<ecs_shell_param_info_t>). */
161 ecs_entity_t return_type; /**< Return type, 0 if the command has no result. */
162} ecs_shell_info_t;
163
164/** Entity in a tree, returned by tree. */
165typedef struct ecs_shell_tree_node_t {
166 ecs_entity_t entity; /**< The entity. */
167 int32_t depth; /**< Depth relative to the scope, 0 for children. */
168} ecs_shell_tree_node_t;
169
170/** Component and value. */
171typedef struct ecs_shell_component_value_t {
172 ecs_id_t id; /**< Component id. */
173 ecs_value_t value; /**< Component value. */
174} ecs_shell_component_value_t;
175
176/** Entity information, returned by cat. */
177typedef struct ecs_shell_entity_info_t {
178 ecs_entity_t entity; /**< The entity. */
179 uint64_t id; /**< Numeric entity id. */
180 ecs_vec_t components; /**< Components with values (vec<ecs_shell_component_value_t>). */
181 ecs_vec_t ids; /**< Ids without values (vec<ecs_id_t>). */
182} ecs_shell_entity_info_t;
183
184/** Documentation, returned by man. */
185typedef struct ecs_shell_doc_info_t {
186 ecs_entity_t entity; /**< The entity. */
187 char *name; /**< Doc name. */
188 char *brief; /**< Brief description. */
189 char *detail; /**< Detailed description. */
190 char *link; /**< Link to external documentation. */
191 char *color; /**< Color. */
192} ecs_shell_doc_info_t;
193
194/** Query result row, returned by query. */
195typedef struct ecs_shell_query_row_t {
196 ecs_entity_t entity; /**< Matched entity, 0 if the query has no $this. */
197 ecs_vec_t fields; /**< Fields with a value (vec<ecs_shell_component_value_t>). */
198} ecs_shell_query_row_t;
199
200/** Match returned by grep. */
201typedef struct ecs_shell_grep_match_t {
202 ecs_entity_t entity; /**< Entity that matched. */
203 ecs_id_t id; /**< Component that matched, 0 for the name. */
204 char *text; /**< Text that matched (name, id or value). */
205} ecs_shell_grep_match_t;
206
207/** Script, returned by scripts. */
208typedef struct ecs_shell_script_info_t {
209 ecs_entity_t script; /**< Script entity. */
210 char *filename; /**< Filename, NULL if not loaded from a file. */
211 int32_t lines; /**< Number of lines. */
212 bool unsaved; /**< Whether the code differs from the saved code. */
213 char *error; /**< Error of last evaluation, NULL if none. */
214} ecs_shell_script_info_t;
215
216/** Line of script code. */
217typedef struct ecs_shell_script_line_t {
218 int32_t line; /**< Line number (1 based). */
219 char *text; /**< Text of the line. */
220} ecs_shell_script_line_t;
221
222/** Match returned by script_grep. */
223typedef struct ecs_shell_script_match_t {
224 ecs_entity_t script; /**< Script entity. */
225 int32_t line; /**< Line number (1 based). */
226 char *text; /**< Text of the line. */
227} ecs_shell_script_match_t;
228
229/** Location of an entity statement, returned by script_where. */
230typedef struct ecs_shell_script_location_t {
231 ecs_entity_t script; /**< Script that declares the entity. */
232 int32_t line; /**< Line of the statement (1 based). */
233 int32_t column; /**< Column of the statement (1 based). */
234 ecs_entity_t template_; /**< Template that declares the statement, if any. */
235 char *statement; /**< First line of the statement. */
236} ecs_shell_script_location_t;
237
238/** Script error, returned by script_errors. */
239typedef struct ecs_shell_script_error_t {
240 ecs_entity_t script; /**< Script entity. */
241 char *error; /**< Error message. */
242} ecs_shell_script_error_t;
243
244#ifdef FLECS_SCRIPT_INPUT
245/** Pointer state, returned by pointer. */
246typedef struct ecs_shell_pointer_state_t {
247 EcsScriptMouseEvent event; /**< Last mouse event. */
248 ecs_entity_t pressed; /**< Entity pressed by held buttons, 0 if none. */
249} ecs_shell_pointer_state_t;
250#endif
251
252/** Shell component. */
253FLECS_API
254extern ECS_COMPONENT_DECLARE(EcsScriptShell);
255
256/** Session component. */
257FLECS_API
258extern ECS_COMPONENT_DECLARE(EcsCommandSession);
259
260/** Resource type (flecs.script.shell.resource). */
261FLECS_API
262extern ECS_COMPONENT_DECLARE(ecs_shell_resource_t);
263
264/** Create a command session.
265 * When no entity is provided, the session is created in the
266 * script.shell.sessions scope.
267 *
268 * @param world The world.
269 * @param desc Session parameters (optional).
270 * @return The session entity, 0 if failed.
271 */
272FLECS_API
273ecs_entity_t ecs_shell_session_init(
274 ecs_world_t *world,
275 const ecs_shell_session_desc_t *desc);
276
277/** Run a command line.
278 * Parses the command line, runs its commands and returns their results and the
279 * errors that were logged while they ran. Commands are separated by `;`. When a
280 * command fails the remaining commands do not run. Each command that ran and a
281 * JSON snapshot of its result are added to the history of the session. The
282 * result must be freed with ecs_shell_result_fini().
283 *
284 * @param world The world.
285 * @param session The session.
286 * @param cmd The command line.
287 * @return The results of the commands.
288 */
289FLECS_API
290ecs_shell_result_t ecs_shell_run(
291 ecs_world_t *world,
292 ecs_entity_t session,
293 const char *cmd);
294
295/** Free the resources of a command result.
296 *
297 * @param world The world.
298 * @param result The result.
299 */
300FLECS_API
301void ecs_shell_result_fini(
302 ecs_world_t *world,
303 ecs_shell_result_t *result);
304
305/** Get the session of the running command.
306 * Commands use this to access the session that they run in.
307 *
308 * @param world The world.
309 * @return The session, or 0 when called outside of ecs_shell_run().
310 */
311FLECS_API
312ecs_entity_t ecs_shell_get_session(
313 const ecs_world_t *world);
314
315/** Create a resource in a session.
316 * Writes the data to a new file in the resource directory of the session, and
317 * adds the resource to the session. The resource directory is created when the
318 * first resource is created. Files are written with the OS API.
319 *
320 * A command that returns a resource typically does:
321 *
322 * @code
323 * ecs_shell_resource_create(ctx->world, ecs_shell_get_session(ctx->world),
324 * "image/png", data, size, result->ptr);
325 * @endcode
326 *
327 * @param world The world.
328 * @param session The session.
329 * @param content_type The content type of the data (optional).
330 * @param data The data to store.
331 * @param size The size of the data.
332 * @param resource Out parameter for the created resource (optional). The
333 * members must be freed by the caller.
334 * @return Zero if success, non-zero if failed.
335 */
336FLECS_API
337int ecs_shell_resource_create(
338 ecs_world_t *world,
339 ecs_entity_t session,
340 const char *content_type,
341 const void *data,
342 ecs_size_t size,
343 ecs_shell_resource_t *resource);
344
345/** Read a resource of a session.
346 * Only resources that were created in the session can be read.
347 *
348 * @param world The world.
349 * @param session The session.
350 * @param name The name of the resource.
351 * @param size Out parameter for the size of the data.
352 * @param content_type Out parameter for the content type (optional). The
353 * string is owned by the session.
354 * @return The data, NULL if the resource does not exist or could not be read.
355 * The data must be freed with ecs_os_free().
356 */
357FLECS_API
358void* ecs_shell_resource_read(
359 const ecs_world_t *world,
360 ecs_entity_t session,
361 const char *name,
362 ecs_size_t *size,
363 const char **content_type);
364
365/** Script shell import function.
366 * Usage:
367 * @code
368 * ECS_IMPORT(world, FlecsScriptShell)
369 * @endcode
370 *
371 * @param world The world.
372 */
373FLECS_API
374void FlecsScriptShellImport(
375 ecs_world_t *world);
376
377#ifdef __cplusplus
378}
379#endif
380
381#endif
382
383/** @} */
384
385#endif
struct ecs_value_t ecs_value_t
Value of a dynamic type.
ecs_id_t ecs_entity_t
An entity identifier.
Definition flecs.h:396
struct ecs_world_t ecs_world_t
A world is the container for all ECS data and supporting features.
Definition flecs.h:440
uint64_t ecs_id_t
IDs are the things that can be added to an entity.
Definition flecs.h:389
script_builder script(const char *name=nullptr) const
Build a script.
Definition mixin.inl:31
#define ECS_COMPONENT_DECLARE(id)
Forward declare a component.
Definition flecs_c.h:65
flecs::entity entity(Args &&... args) const
Create an entity.
flecs::id id(E value) const
Convert an enum constant to an entity.
flecs::event_builder event(flecs::entity_t evt) const
Create a new event.