script.h@ 108049

Last change on this file since 108049 was 108049, checked in by vboxsync, 2 weeks ago
Runtime/RTScriptLex*: Allow case insensitivity with converting all characters [a-z] to upper case [A-Z] internally, bugref:10733
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 39.1 KB

Line
1	/* $Id: script.h 108049 2025-02-04 06:01:30Z vboxsync $ */
2	/** @file
3	* IPRT - RTScript, Script language support in IPRT.
4	*/
5
6	/*
7	* Copyright (C) 2024 Oracle and/or its affiliates.
8	*
9	* This file is part of VirtualBox base platform packages, as
10	* available from https://www.virtualbox.org.
11	*
12	* This program is free software; you can redistribute it and/or
13	* modify it under the terms of the GNU General Public License
14	* as published by the Free Software Foundation, in version 3 of the
15	* License.
16	*
17	* This program is distributed in the hope that it will be useful, but
18	* WITHOUT ANY WARRANTY; without even the implied warranty of
19	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20	* General Public License for more details.
21	*
22	* You should have received a copy of the GNU General Public License
23	* along with this program; if not, see <https://www.gnu.org/licenses>.
24	*
25	* The contents of this file may alternatively be used under the terms
26	* of the Common Development and Distribution License Version 1.0
27	* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
28	* in the VirtualBox distribution, in which case the provisions of the
29	* CDDL are applicable instead of those of the GPL.
30	*
31	* You may elect to license modified versions of this file under the
32	* terms and conditions of either the GPL or the CDDL or both.
33	*
34	* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
35	*/
36
37	#ifndef IPRT_INCLUDED_script_h
38	#define IPRT_INCLUDED_script_h
39	#ifndef RT_WITHOUT_PRAGMA_ONCE
40	# pragma once
41	#endif
42
43	#include <iprt/cdefs.h>
44	#include <iprt/types.h>
45	#include <iprt/strcache.h>
46	#include <iprt/scriptbase.h>
47	//#include <iprt/scriptast.h>
48
49	RT_C_DECLS_BEGIN
50
51	/** @defgroup grp_rt_script RTScript - IPRT scripting language support
52	* @ingroup grp_rt
53	*
54	* The scripting APIs provide a simple framework to implement simple scripting
55	* languages. They are meant to provide building blocks which can be put together
56	* in an easy way to add scripting capablities to the software using it.
57	*
58	* The API is oriented on the traditional compiler pipeline providing sub APIs for the following
59	* parts:
60	* - RTScriptLex*: For building a lexer to generate tokens from an input character stream.
61	* - RTScriptTs*: A simple type system providing a way to get type storage sizes and alignments.
62	* - RTScriptPs*: For maintaining the required state for the complete script and provide
63	* a way to check for correct typing.
64	* - RTScriptAst*: Providing helpers and definitions for the abstract syntax tree.
65	* - RTScriptParse*: For building parsers which generate ASTs.
66	* - RTScriptVm*: Providing a simple bytecode VM which takes a checked program state
67	* converting it into bytecode and executing it.
68	*
69	* Note: Only RTScriptLex is partially implemented right now!
70	* @{
71	*/
72
73	/** @defgroup grp_rt_script_lex Scripting lexer support
74	*
75	* This part provides support for lexing input and generating tokens which can be
76	* digested by a parser.
77	*
78	* @{
79	*/
80
81	/**
82	* The lexer token type.
83	*/
84	typedef enum RTSCRIPTLEXTOKTYPE
85	{
86	/** Invalid type. */
87	RTSCRIPTLEXTOKTYPE_INVALID = 0,
88	/** Identifier. */
89	RTSCRIPTLEXTOKTYPE_IDENTIFIER,
90	/** Numerical constant. */
91	RTSCRIPTLEXTOKTYPE_NUMBER,
92	/** String literal. */
93	RTSCRIPTLEXTOKTYPE_STRINGLIT,
94	/** An operator (unary or binary). */
95	RTSCRIPTLEXTOKTYPE_OPERATOR,
96	/** Some predefined keyword. */
97	RTSCRIPTLEXTOKTYPE_KEYWORD,
98	/** Some punctuator. */
99	RTSCRIPTLEXTOKTYPE_PUNCTUATOR,
100	/** Special error token, conveying an error message from the lexer. */
101	RTSCRIPTLEXTOKTYPE_ERROR,
102	/** End of stream token. */
103	RTSCRIPTLEXTOKTYPE_EOS
104	} RTSCRIPTLEXTOKTYPE;
105	/** Pointer to a lexer token type. */
106	typedef RTSCRIPTLEXTOKTYPE *PRTSCRIPTLEXTOKTYPE;
107
108
109	/**
110	* Lexer token number type.
111	*/
112	typedef enum RTSCRIPTLEXTOKNUMTYPE
113	{
114	/** Invalid token number type. */
115	RTSCRIPTLEXTOKNUMTYPE_INVALID = 0,
116	/** Natural number (all positive upwards including 0). */
117	RTSCRIPTLEXTOKNUMTYPE_NATURAL,
118	/** Integers (natural numbers and their additive inverse). */
119	RTSCRIPTLEXTOKNUMTYPE_INTEGER,
120	/** Real numbers. */
121	RTSCRIPTLEXTOKNUMTYPE_REAL
122	} RTSCRIPTLEXTOKNUMTYPE;
123
124
125	/**
126	* Lexer exact token match descriptor.
127	*/
128	typedef struct RTSCRIPTLEXTOKMATCH
129	{
130	/** Matching string. */
131	const char *pszMatch;
132	/** Size if of the matching string in characters excluding the zero terminator. */
133	size_t cchMatch;
134	/** Resulting token type. */
135	RTSCRIPTLEXTOKTYPE enmTokType;
136	/** Whether the token can be the beginning of an identifer
137	* and to check whether the identifer has a longer match. */
138	bool fMaybeIdentifier;
139	/** User defined value when the token matched. */
140	uint64_t u64Val;
141	} RTSCRIPTLEXTOKMATCH;
142	/** Pointer to a lexer exact token match descriptor. */
143	typedef RTSCRIPTLEXTOKMATCH *PRTSCRIPTLEXTOKMATCH;
144	/** Pointer to a const lexer exact token match descriptor. */
145	typedef const RTSCRIPTLEXTOKMATCH *PCRTSCRIPTLEXTOKMATCH;
146
147
148	/**
149	* Lexer token.
150	*/
151	typedef struct RTSCRIPTLEXTOKEN
152	{
153	/** Token type. */
154	RTSCRIPTLEXTOKTYPE enmType;
155	/** Position in the source buffer where the token started matching. */
156	RTSCRIPTPOS PosStart;
157	/** Position in the source buffer where the token ended matching. */
158	RTSCRIPTPOS PosEnd;
159	/** Data based on the token type. */
160	union
161	{
162	/** Identifier. */
163	struct
164	{
165	/** Pointer to the start of the identifier. */
166	const char *pszIde;
167	/** Number of characters for the identifier excluding the null terminator. */
168	size_t cchIde;
169	} Id;
170	/** Numerical constant. */
171	struct
172	{
173	/** Flag whether the number is negative. */
174	RTSCRIPTLEXTOKNUMTYPE enmType;
175	/** Optimal storage size for the value (1, 2, 4 or 8 bytes). */
176	uint32_t cBytes;
177	/** Type dependent data. */
178	union
179	{
180	/** For natural numbers. */
181	uint64_t u64;
182	/** For integer numbers. */
183	int64_t i64;
184	/** Real numbers. */
185	RTFLOAT64U r64;
186	} Type;
187	} Number;
188	/** String literal */
189	struct
190	{
191	/** Pointer to the start of the string constant. */
192	const char *pszString;
193	/** Number of characters of the string, including the null terminator. */
194	size_t cchString;
195	} StringLit;
196	/** Operator */
197	struct
198	{
199	/** Pointer to the operator descriptor. */
200	PCRTSCRIPTLEXTOKMATCH pOp;
201	} Operator;
202	/** Keyword. */
203	struct
204	{
205	/** Pointer to the keyword descriptor. */
206	PCRTSCRIPTLEXTOKMATCH pKeyword;
207	} Keyword;
208	/** Punctuator. */
209	struct
210	{
211	/** Pointer to the matched punctuator descriptor. */
212	PCRTSCRIPTLEXTOKMATCH pPunctuator;
213	} Punctuator;
214	/** Error. */
215	struct
216	{
217	/** Pointer to the internal error info structure, readonly. */
218	PCRTERRINFO pErr;
219	} Error;
220	} Type;
221	} RTSCRIPTLEXTOKEN;
222	/** Pointer to a script token. */
223	typedef RTSCRIPTLEXTOKEN *PRTSCRIPTLEXTOKEN;
224	/** Pointer to a const script token. */
225	typedef const RTSCRIPTLEXTOKEN *PCRTSCRIPTLEXTOKEN;
226
227
228	/** Opaque lexer handle. */
229	typedef struct RTSCRIPTLEXINT *RTSCRIPTLEX;
230	/** Pointer to a lexer handle. */
231	typedef RTSCRIPTLEX *PRTSCRIPTLEX;
232
233
234	/**
235	* Production rule callback.
236	*
237	* @returns IPRT status code.
238	* @param hScriptLex The lexer handle.
239	* @param ch The character which caused the production rule to be called.
240	* @param pToken The token to fill in.
241	* @param pvUser Opaque user data.
242	*/
243	typedef DECLCALLBACKTYPE(int, FNRTSCRIPTLEXPROD,(RTSCRIPTLEX hScriptLex, char ch, PRTSCRIPTLEXTOKEN pToken, void *pvUser));
244	/** Pointer to a production rule callback. */
245	typedef FNRTSCRIPTLEXPROD *PFNRTSCRIPTLEXPROD;
246
247	/**
248	* Lexer rule.
249	*/
250	typedef struct RTSCRIPTLEXRULE
251	{
252	/** First character for starting the production rule. */
253	char chStart;
254	/** Last character for starting the production rule. */
255	char chEnd;
256	/** Flags for this rule. */
257	uint32_t fFlags;
258	/** The producer to call. */
259	PFNRTSCRIPTLEXPROD pfnProd;
260	/** Opaque user data passed to the production rule. */
261	void *pvUser;
262	} RTSCRIPTLEXRULE;
263	/** Pointer to a lexer rule. */
264	typedef RTSCRIPTLEXRULE *PRTSCRIPTLEXRULE;
265	/** Pointer to a const lexer rule. */
266	typedef const RTSCRIPTLEXRULE *PCRTSCRIPTLEXRULE;
267
268	/** Default rule flags. */
269	#define RTSCRIPT_LEX_RULE_DEFAULT 0
270	/** Consume the first character before calling the producer. */
271	#define RTSCRIPT_LEX_RULE_CONSUME RT_BIT(0)
272
273	/**
274	* Lexer config.
275	*/
276	typedef struct RTSCRIPTLEXCFG
277	{
278	/** Config name. */
279	const char *pszName;
280	/** Config description. */
281	const char *pszDesc;
282	/** Flags for the lexer. */
283	uint32_t fFlags;
284	/** Set of whitespace characters, excluding newline. NULL indicates default characters.
285	* " " \| "\t". */
286	const char *pszWhitespace;
287	/** Set of newline characters, NULL indicates
288	* default characters including "\n" \| "\r\n". */
289	const char **papszNewline;
290	/** Start for a multiline comment, NULL indicates no support for multi line comments. */
291	const char **papszCommentMultiStart;
292	/** End for a multiline comment, NULL indicates no support for multi line comments. */
293	const char **papszCommentMultiEnd;
294	/** Start of single line comment, NULL indicates no support for single line comments. */
295	const char **papszCommentSingleStart;
296	/** Exact token match descriptor table, optional. Must be terminated with a NULL entry. */
297	PCRTSCRIPTLEXTOKMATCH paTokMatches;
298	/** Pointer to the rule table, optional. */
299	PCRTSCRIPTLEXRULE paRules;
300	/** The default rule to call when no other rule applies, optional. */
301	PFNRTSCRIPTLEXPROD pfnProdDef;
302	/** Opaque user data for default production rule. */
303	void *pvProdDefUser;
304	} RTSCRIPTLEXCFG;
305	/** Pointer to a lexer config. */
306	typedef RTSCRIPTLEXCFG *PRTSCRIPTLEXCFG;
307	/** Pointer to a const lexer config. */
308	typedef const RTSCRIPTLEXCFG *PCRTSCRIPTLEXCFG;
309
310	/** Default lexer config flags. */
311	#define RTSCRIPT_LEX_CFG_F_DEFAULT 0
312	/** Case insensitive lexing, keywords and so on must be used lowercase to match
313	* as the lexer will convert everything to lowercase internally. */
314	#define RTSCRIPT_LEX_CFG_F_CASE_INSENSITIVE_LOWER RT_BIT(0)
315	/** Case insensitive lexing, keywords and so on must be used uppercase to match
316	* as the lexer will convert everything to uppercase internally. */
317	#define RTSCRIPT_LEX_CFG_F_CASE_INSENSITIVE_UPPER RT_BIT(1)
318
319
320	/** Default character conversions (converting to lower case when the case insensitive flag is set). */
321	#define RTSCRIPT_LEX_CONV_F_DEFAULT 0
322	/** Don't apply any conversion but just return the character as read from the input. */
323	#define RTSCRIPT_LEX_CONV_F_NOTHING RT_BIT(0)
324
325	/**
326	* Lexer reader callback.
327	*
328	* @returns IPRT status code.
329	* @retval VINF_EOF if the end of the input was reached.
330	* @param hScriptLex The lexer handle.
331	* @param offBuf Offset from the start to read from.
332	* @param pchBuf Where to store the read data.
333	* @param cchBuf How much to read at maxmimum.
334	* @param pcchRead Where to store the amount of bytes read.
335	* @param pvUser Opaque user data passed when creating the lexer.
336	*/
337	typedef DECLCALLBACKTYPE(int, FNRTSCRIPTLEXRDR, (RTSCRIPTLEX hScriptLex, size_t offBuf, char *pchBuf, size_t cchBuf,
338	size_t pcchRead, void pvUser));
339	/** Pointer to a lexer reader callback. */
340	typedef FNRTSCRIPTLEXRDR *PFNRTSCRIPTLEXRDR;
341
342
343	/**
344	* Lexer destructor callback.
345	*
346	* @param hScriptLex The lexer handle.
347	* @param pvUser Opaque user data passed when creating the lexer.
348	*/
349	typedef DECLCALLBACKTYPE(void, FNRTSCRIPTLEXDTOR,(RTSCRIPTLEX hScriptLex, void *pvUser));
350	/** Pointer to a lexer destructor callback. */
351	typedef FNRTSCRIPTLEXDTOR *PFNRTSCRIPTLEXDTOR;
352
353
354	/**
355	* Creates a new lexer with the given reader and config.
356	*
357	* @returns IPRT status code.
358	* @param phScriptLex Where to store the handle to the lexer on success.
359	* @param pfnReader The read to use for reading chunks of the input.
360	* @param pfnDtor Destructor callback to call when the lexer is destroyed.
361	* @param pvUser Opaque user data passed to reader.
362	* @param cchBuf Buffer hint, if 0 a default is chosen.
363	* @param phStrCacheId Where to store the pointer to the string cache containing all
364	* scanned identifiers on success, optional.
365	* If not NULL the string cache must be freed by the caller when not used
366	* anymore.
367	* @param phStrCacheStringLit Where to store the pointer to the string cache containing all
368	* scanned string literals on success, optional.
369	* If not NULL the string cache must be freed by the caller when not used
370	* anymore.
371	* @param pCfg The lexer config to use for identifying the different tokens.
372	*/
373	RTDECL(int) RTScriptLexCreateFromReader(PRTSCRIPTLEX phScriptLex, PFNRTSCRIPTLEXRDR pfnReader,
374	PFNRTSCRIPTLEXDTOR pfnDtor, void *pvUser,
375	size_t cchBuf, PRTSTRCACHE phStrCacheId, PRTSTRCACHE phStrCacheStringLit,
376	PCRTSCRIPTLEXCFG pCfg);
377
378
379	/**
380	* Creates a new lexer for the given input string and config.
381	*
382	* @returns IPRT status code.
383	* @param phScriptLex Where to store the handle to the lexer on success.
384	* @param pszSrc The input string to scan.
385	* @param phStrCacheId Where to store the pointer to the string cache containing all
386	* scanned identifiers on success, optional.
387	* If not NULL the string cache must be freed by the caller when not used
388	* anymore.
389	* @param phStrCacheStringLit Where to store the pointer to the string cache containing all
390	* scanned string literals on success, optional.
391	* If not NULL the string cache must be freed by the caller when not used
392	* anymore.
393	* @param pCfg The lexer config to use for identifying the different tokens.
394	*/
395	RTDECL(int) RTScriptLexCreateFromString(PRTSCRIPTLEX phScriptLex, const char *pszSrc, PRTSTRCACHE phStrCacheId,
396	PRTSTRCACHE phStrCacheStringLit, PCRTSCRIPTLEXCFG pCfg);
397
398
399	/**
400	* Creates a new lexer from the given filename and config.
401	*
402	* @returns IPRT status code.
403	* @param phScriptLex Where to store the handle to the lexer on success.
404	* @param pszFilename The filename of the input.
405	* @param phStrCacheId Where to store the pointer to the string cache containing all
406	* scanned identifiers on success, optional.
407	* If not NULL the string cache must be freed by the caller when not used
408	* anymore.
409	* @param phStrCacheStringLit Where to store the pointer to the string cache containing all
410	* scanned string literals on success, optional.
411	* If not NULL the string cache must be freed by the caller when not used
412	* anymore.
413	* @param pCfg The lexer config to use for identifying the different tokens.
414	*/
415	RTDECL(int) RTScriptLexCreateFromFile(PRTSCRIPTLEX phScriptLex, const char *pszFilename, PRTSTRCACHE phStrCacheId,
416	PRTSTRCACHE phStrCacheStringLit, PCRTSCRIPTLEXCFG pCfg);
417
418
419	/**
420	* Destroys the given lexer handle.
421	*
422	* @param hScriptLex The lexer handle to destroy.
423	*/
424	RTDECL(void) RTScriptLexDestroy(RTSCRIPTLEX hScriptLex);
425
426
427	/**
428	* Queries the current identified token.
429	*
430	* @returns IPRT status code.
431	* @param hScriptLex The lexer handle.
432	* @param ppToken Where to store the pointer to the token on success.
433	*/
434	RTDECL(int) RTScriptLexQueryToken(RTSCRIPTLEX hScriptLex, PCRTSCRIPTLEXTOKEN *ppToken);
435
436
437	/**
438	* Returns the current token type.
439	*
440	* @returns Current token type.
441	* @param hScriptLex The lexer handle.
442	*/
443	RTDECL(RTSCRIPTLEXTOKTYPE) RTScriptLexGetTokenType(RTSCRIPTLEX hScriptLex);
444
445
446	/**
447	* Returns the next token type.
448	*
449	* @returns Next token type.
450	* @param hScriptLex The lexer handle.
451	*/
452	RTDECL(RTSCRIPTLEXTOKTYPE) RTScriptLexPeekNextTokenType(RTSCRIPTLEX hScriptLex);
453
454
455	/**
456	* Consumes the current token and moves to the next one.
457	*
458	* @returns Pointer to the next token.
459	* @param hScriptLex The lexer handle.
460	*/
461	RTDECL(PCRTSCRIPTLEXTOKEN) RTScriptLexConsumeToken(RTSCRIPTLEX hScriptLex);
462
463
464	/**
465	* Consumes the current input characters and moves to the next one.
466	*
467	* @returns Returns the next character in the input stream.
468	* @retval 0 indicates end of stream.
469	* @param hScriptLex The lexer handle.
470	*/
471	RTDECL(char) RTScriptLexConsumeCh(RTSCRIPTLEX hScriptLex);
472
473
474	/**
475	* Consumes the current input characters and moves to the next one - extended version.
476	*
477	* @returns Returns the next character in the input stream.
478	* @retval 0 indicates end of stream.
479	* @param hScriptLex The lexer handle.
480	* @param fFlags Flags controlling some basic conversions of characters,
481	* combination of RTSCRIPT_LEX_CONV_F_*.
482	*/
483	RTDECL(char) RTScriptLexConsumeChEx(RTSCRIPTLEX hScriptLex, uint32_t fFlags);
484
485
486	/**
487	* Returns the character at the curren input position.
488	*
489	* @returns Character at the current position in the input
490	* @retval 0 indicates end of stream.
491	* @param hScriptLex The lexer handle.
492	*/
493	RTDECL(char) RTScriptLexGetCh(RTSCRIPTLEX hScriptLex);
494
495
496	/**
497	* Returns the character at the curren input position - extended version.
498	*
499	* @returns Character at the current position in the input
500	* @retval 0 indicates end of stream.
501	* @param hScriptLex The lexer handle.
502	* @param fFlags Flags controlling some basic conversions of characters,
503	* combination of RTSCRIPT_LEX_CONV_F_*.
504	*/
505	RTDECL(char) RTScriptLexGetChEx(RTSCRIPTLEX hScriptLex, uint32_t fFlags);
506
507
508	/**
509	* Returns the current character in the input without moving to the next one.
510	*
511	* @returns Returns the current character.
512	* @retval 0 indicates end of stream.
513	* @param hScriptLex The lexer handle.
514	* @param idx Offset to peek at, 0 behaves like rtScriptLexGetCh().
515	*/
516	RTDECL(char) RTScriptLexPeekCh(RTSCRIPTLEX hScriptLex, unsigned idx);
517
518
519	/**
520	* Returns the current character in the input without moving to the next one - extended version.
521	*
522	* @returns Returns the current character.
523	* @retval 0 indicates end of stream.
524	* @param hScriptLex The lexer handle.
525	* @param idx Offset to peek at, 0 behaves like rtScriptLexGetCh().
526	* @param fFlags Flags controlling some basic conversions of characters,
527	* combination of RTSCRIPT_LEX_CONV_F_*.
528	*/
529	RTDECL(char) RTScriptLexPeekChEx(RTSCRIPTLEX hScriptLex, unsigned idx, uint32_t fFlags);
530
531
532	/**
533	* Skips everything declared as whitespace, including comments and newlines.
534	*
535	* @param hScriptLex The lexer handle.
536	*/
537	RTDECL(void) RTScriptLexSkipWhitespace(RTSCRIPTLEX hScriptLex);
538
539
540	/** @defgroup grp_rt_script_lex_builtin Builtin helpers to scan numbers, string literals, ...
541	* @{ */
542
543	/**
544	* Produces a numerical constant token from the number starting at the current position in the
545	* input stream on success or an appropriate error token.
546	*
547	* @returns IPRT status code.
548	* @param hScriptLex The lexer handle.
549	* @param uBase The base to parse the number in.
550	* @param fAllowReal Flag whether to allow parsing real numbers using the following
551	* layout [+-][0-9][.][e][+-][0-9].
552	* @param pTok The token to fill in.
553	*/
554	RTDECL(int) RTScriptLexScanNumber(RTSCRIPTLEX hScriptLex, uint8_t uBase, bool fAllowReal,
555	PRTSCRIPTLEXTOKEN pTok);
556
557	/**
558	* Production rule to create an identifier token with the given set of allowed characters.
559	*
560	* @returns IPRT status code.
561	* @param hScriptLex The lexer handle.
562	* @param ch The first character of the identifier.
563	* @param pTok The token to fill in.
564	* @param pvUser Opaque user data, must point to the allowed set of characters for identifiers as a
565	* zero terminated string. NULL will revert to a default set of characters including
566	* [_a-zA-Z0-9]*
567	*
568	* @note This version will allow a maximum identifier length of 512 characters (should be plenty).
569	* More characters will produce an error token. Must be used with the RTSCRIPT_LEX_RULE_CONSUME
570	* flag for the first character.
571	*/
572	RTDECL(int) RTScriptLexScanIdentifier(RTSCRIPTLEX hScriptLex, char ch, PRTSCRIPTLEXTOKEN pTok, void *pvUser);
573
574
575	/**
576	* Production rule to scan string literals conforming to the C standard.
577	*
578	* @returns IPRT status code.
579	* @param hScriptLex The lexer handle.
580	* @param ch The character starting the rule, unused.
581	* @param pTok The token to fill in.
582	* @param pvUser Opaque user data, unused.
583	*
584	* @note The RTSCRIPT_LEX_RULE_CONSUME must be used (or omitted) such that the current character
585	* in the input denotes the start of the string literal. The resulting literal is added to the respective
586	* cache on success.
587	*/
588	RTDECL(int) RTScriptLexScanStringLiteralC(RTSCRIPTLEX hScriptLex, char ch, PRTSCRIPTLEXTOKEN pTok, void *pvUser);
589
590
591	/**
592	* Production rule to scan string literals for pascal like languages, without support for escape
593	* sequences and where a ' is denoted by ''.
594	*
595	* @returns IPRT status code.
596	* @param hScriptLex The lexer handle.
597	* @param ch The character starting the rule, unused.
598	* @param pTok The token to fill in.
599	* @param pvUser Opaque user data, unused.
600	*
601	* @note The RTSCRIPT_LEX_RULE_CONSUME must be used (or omitted) such that the current character
602	* in the input denotes the start of the string literal. The resulting literal is added to the respective
603	* cache on success.
604	*/
605	RTDECL(int) RTScriptLexScanStringLiteralPascal(RTSCRIPTLEX hScriptLex, char ch, PRTSCRIPTLEXTOKEN pTok, void *pvUser);
606
607
608	/**
609	* Produces an error token with the given message, used for custom lexer rule implementations.
610	*
611	* @returns IPRT status code.
612	* @param hScriptLex The lexer handle.
613	* @param pTok The token to fill.
614	* @param rc The status code to use in the message.
615	* @param pszMsg The format string for the error message.
616	* @param ... Arguments to the format string.
617	*/
618	RTDECL(int) RTScriptLexProduceTokError(RTSCRIPTLEX hScriptLex, PRTSCRIPTLEXTOKEN pTok, int rc, const char *pszMsg, ...);
619
620
621	/**
622	* Produces an identifier token with the given identifier, used for custom lexer rule implementations.
623	*
624	* @returns IPRT status code.
625	* @param hScriptLex The lexer handle.
626	* @param pTok The token to fill.
627	* @param pszIde The identifier to add.
628	* @param cchIde Number of characters in the identifier.
629	*/
630	RTDECL(int) RTScriptLexProduceTokIde(RTSCRIPTLEX hScriptLex, PRTSCRIPTLEXTOKEN pTok, const char *pszIde, size_t cchIde);
631	/** @} */
632
633	/** @} */
634
635
636	#if 0 /* Later, maybe */
637
638	/** @defgroup grp_rt_script_typesys Scripting language type system API.
639	*
640	* @{
641	*/
642
643	/**
644	* Type class.
645	*/
646	typedef enum RTSCRIPTTSTYPECLASS
647	{
648	/** Invalid. */
649	RTSCRIPTTSTYPECLASS_INVALID = 0,
650	/** A native type. */
651	RTSCRIPTTSTYPECLASS_NATIVE,
652	/** Array type. */
653	RTSCRIPTTSTYPECLASS_ARRAY,
654	/** Struct type. */
655	RTSCRIPTTSTYPECLASS_STRUCT,
656	/** Union type. */
657	RTSCRIPTTSTYPECLASS_UNION,
658	/** Function type. */
659	RTSCRIPTTSTYPECLASS_FUNCTION,
660	/** Pointer type. */
661	RTSCRIPTTSTYPECLASS_POINTER,
662	/** Alias for another type. */
663	RTSCRIPTTSTYPECLASS_ALIAS
664	} RTSCRIPTTSTYPECLASS;
665
666
667	/** Pointer to a type descriptor. */
668	typedef struct RTSCRIPTTSTYPDESC *PRTSCRIPTTSTYPDESC;
669	/** Pointer to a const type descriptor. */
670	typedef const RTSCRIPTTSTYPDESC *PCRTSCRIPTTSTYPDESC;
671
672	/**
673	* Type descriptor.
674	*/
675	typedef struct RTSCRIPTTSTYPDESC
676	{
677	/** Type class */
678	RTSCRIPTTSTYPECLASS enmClass;
679	/** Identifier for this type. */
680	const char *pszIdentifier;
681	/** Class dependent data. */
682	union
683	{
684	/** Native type. */
685	struct
686	{
687	/** The native type. */
688	RTSCRIPTNATIVETYPE enmTypeNative;
689	/** Alignment for the native type in bits - 0 for default alignment. */
690	uint32_t cBitsAlign;
691	} Native;
692	/** Array type. */
693	struct
694	{
695	/** Type identifier. */
696	const char *pszTypeIde;
697	/** Number of elements. */
698	uint32_t cElems;
699	} Array;
700	/** Struct/Union type. */
701	struct
702	{
703	/* Flag whether this is packed. */
704	bool fPacked;
705	/** Number of members. */
706	uint32_t cMembers;
707	/** Pointer to the array of member identifiers for each member. */
708	const char **papszMember;
709	/** Pointer to the array of type identifiers for each member. */
710	const char **papszMemberType;
711	} UnionStruct;
712	/** Function type. */
713	struct
714	{
715	/** Return type - NULL for no return type. */
716	const char *pszTypeRet;
717	/** Number of typed arguments. */
718	uint32_t cArgsTyped;
719	/** Pointer to the array of type identifiers for the arguments. */
720	const char **papszMember;
721	/** Flag whether variable arguments are used. */
722	bool fVarArgs;
723	} Function;
724	/** Pointer. */
725	struct
726	{
727	/** The type identifier the pointer references. */
728	const char *pszTypeIde;
729	} Pointer;
730	/** Pointer. */
731	struct
732	{
733	/** The type identifier the alias references. */
734	const char *pszTypeIde;
735	} Alias;
736	} Class;
737	} RTSCRIPTTSTYPDESC;
738
739
740	/** Opaque type system handle. */
741	typedef struct RTSCRIPTTSINT *RTSCRIPTTS;
742	/** Pointer to an opaque type system handle. */
743	typedef RTSCRIPTTS *PRTSCRIPTTS;
744
745
746	/** Opaque type system type. */
747	typedef struct RTSCRIPTTSTYPEINT *RTSCRIPTTSTYPE;
748	/** Pointer to an opaque type system type. */
749	typedef RTSCRIPTTSTYPE *PRTSCRIPTTSTYPE;
750
751
752	/**
753	* Create a new empty type system.
754	*
755	* @returns IPRT status code.
756	* @param phScriptTs Where to store the handle to the type system on success.
757	* @param hScriptTsParent Parent type system to get declarations from. NULL if no parent.
758	* @param enmPtrType Native pointer type (only unsigned integer types allowed).
759	* @param cPtrAlignBits The native alignment of a pointer storage location.
760	*/
761	RTDECL(int) RTScriptTsCreate(PRTSCRIPTTS phScriptTs, RTSCRIPTTS hScriptTsParent,
762	RTSCRIPTNATIVETYPE enmPtrType, uint32_t cPtrAlignBits);
763
764
765	/**
766	* Retains a reference to the given type system.
767	*
768	* @returns New reference count.
769	* @param hScriptTs Type system handle.
770	*/
771	RTDECL(uint32_t) RTScriptTsRetain(RTSCRIPTTS hScriptTs);
772
773
774	/**
775	* Releases a reference to the given type system.
776	*
777	* @returns New reference count, on 0 the type system is destroyed.
778	* @param hScriptTs Type system handle.
779	*/
780	RTDECL(uint32_t) RTScriptTsRelease(RTSCRIPTTS hScriptTs);
781
782
783	/**
784	* Dumps the content of the type system.
785	*
786	* @returns IPRT status code.
787	* @param hScriptTs Type system handle.
788	*/
789	RTDECL(int) RTScriptTsDump(RTSCRIPTTS hScriptTs);
790
791
792	/**
793	* Add several types to the type system from the given descriptor array.
794	*
795	* @returns IPRT status code.
796	* @param hScriptTs Type system handle.
797	* @param paTypeDescs Pointer to the array of type descriptors.
798	* @param cTypeDescs Number of entries in the array.
799	*/
800	RTDECL(int) RTScriptTsAdd(RTSCRIPTTS hScriptTs, PCRTSCRIPTTSTYPDESC paTypeDescs,
801	uint32_t cTypeDescs);
802
803
804	/**
805	* Removes the given types from the type system.
806	*
807	* @returns IPRT status code.
808	* @param hScriptTs Type system handle.
809	* @param papszTypes Array of type identifiers to remove. Array terminated
810	* with a NULL entry.
811	*/
812	RTDECL(int) RTScriptTsRemove(RTSCRIPTTS hScriptTs, const char **papszTypes);
813
814
815	/**
816	* Queries the given type returning the type handle on success.
817	*
818	* @returns IPRT status code.
819	* @retval VERR_NOT_FOUND if the type could not be found.
820	* @param hScriptTs Type system handle.
821	* @param pszType The type identifier to look for.
822	* @param phType Where to store the handle to the type on success.
823	*/
824	RTDECL(int) RTScriptTsQueryType(RTSCRIPTTS hScriptTs, const char *pszType,
825	PRTSCRIPTTSTYPE phType);
826
827
828	/**
829	* Retains the given type reference.
830	*
831	* @returns New reference count.
832	* @param hScriptTsType Type system type handle.
833	*/
834	RTDECL(uint32_t) RTScriptTsTypeRetain(RTSCRIPTTSTYPE hScriptTsType);
835
836
837	/**
838	* Releases the given type reference.
839	*
840	* @returns New reference count.
841	* @param hScriptTsType Type system type handle.
842	*/
843	RTDECL(uint32_t) RTScriptTsTypeRelease(RTSCRIPTTSTYPE hScriptTsType);
844
845
846	/**
847	* Returns the class of the given type handle.
848	*
849	* @returns Type class for the given type handle.
850	* @param hScriptTsType Type system type handle.
851	*/
852	RTDECL(RTSCRIPTTSTYPECLASS) RTScriptTsTypeGetClass(RTSCRIPTTSTYPE hScriptTsType);
853
854
855	/**
856	* Returns the identifier of the given type handle.
857	*
858	* @returns Pointer to the identifier of the given type handle.
859	* @param hScriptTsType Type system type handle.
860	*/
861	RTDECL(const char *) RTScriptTsTypeGetIdentifier(RTSCRIPTTSTYPE hScriptTsType);
862
863
864	/**
865	* Returns the storage size of the given type in bits.
866	*
867	* @returns Size of the type in bits described by the given handle.
868	* @param hScriptTsType Type system type handle.
869	*/
870	RTDECL(size_t) RTScriptTsTypeGetBitCount(RTSCRIPTTSTYPE hScriptTsType);
871
872
873	/**
874	* Returns the necessary alignment of the given type in bits.
875	*
876	* @returns Alignmebt of the type in bits described by the given handle.
877	* @param hScriptTsType Type system type handle.
878	*/
879	RTDECL(size_t) RTScriptTsTypeGetAlignmentBitCount(RTSCRIPTTSTYPE hScriptTsType);
880
881
882	/**
883	* Return the native type for the given native type.
884	*
885	* @returns Native type enum.
886	* @param hScriptTsType Type system type handle.
887	*/
888	RTDECL(RTSCRIPTNATIVETYPE) RTScriptTsTypeNativeGetType(RTSCRIPTTSTYPE hScriptTsType);
889
890
891	/**
892	* Return the number of elements for the given array type.
893	*
894	* @returns Number of elements.
895	* @param hScriptTsType Type system type handle.
896	*/
897	RTDECL(uint32_t) RTScriptTsTypeArrayGetElemCount(RTSCRIPTTSTYPE hScriptTsType);
898
899
900	/**
901	* Return the type handle of element type for the given array type.
902	*
903	* @returns Number of elements.
904	* @param hScriptTsType Type system type handle.
905	*/
906	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeArrayGetElemType(RTSCRIPTTSTYPE hScriptTsType);
907
908
909	/**
910	* Returns whether the given union/struct type is packed.
911	*
912	* @returns Number of elements.
913	* @param hScriptTsType Type system type handle.
914	*/
915	RTDECL(bool) RTScriptTsTypeStructUnionGetPacked(RTSCRIPTTSTYPE hScriptTsType);
916
917	RTDECL(uint32_t) RTScriptTsTypeStructUnionGetMemberCount(RTSCRIPTTSTYPE hScriptTsType);
918
919	RTDECL(int) RTScriptTsTypeStructUnionQueryMember(RTSCRIPTTSTYPE hScriptTsType, uint32_t idxMember, uint32_t *poffMember,
920	uint32_t *pcMemberBits, PRTSCRIPTTSTYPE phScriptTsTypeMember);
921
922	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeFunctionGetRetType(RTSCRIPTTSTYPE hScriptTsType);
923
924	RTDECL(uint32_t) RTScriptTsTypeFunctionGetTypedArgCount(RTSCRIPTTSTYPE hScriptTsType);
925
926	RTDECL(bool) RTScriptTsTypeFunctionUsesVarArgs(RTSCRIPTTSTYPE hScriptTsType);
927
928	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeFunctionGetArgType(RTSCRIPTTSTYPE hScriptTsType, uint32_t idxArg);
929
930	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypePointerGetRefType(RTSCRIPTTSTYPE hScriptTsType);
931
932	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeAliasGetAliasedType(RTSCRIPTTSTYPE hScriptTsType);
933
934	RTDECL(bool) RTScriptTsTypeEquals(RTSCRIPTTSTYPE hScriptTsType1, RTSCRIPTTSTYPE hScriptTsType2);
935
936	RTDECL(bool) RTScriptTsTypeEqualsByOneName(RTSCRIPTTS hScriptTs, const char *pszType1, RTSCRIPTTSTYPE hScriptTsType2);
937
938	RTDECL(bool) RTScriptTsTypeEqualsByTwoNames(RTSCRIPTTS hScriptTs, const char pszType1, const char pszType2);
939
940	/** @} */
941
942
943
944	/** @defgroup grp_rt_script_ps Scripting program state API
945	*
946	* @{
947	*/
948
949	/** Opaque program state handle. */
950	typedef struct RTSCRIPTPSINT *RTSCRIPTPS;
951	/** Pointer to a program state handle. */
952	typedef RTSCRIPTPS *PRTSCRIPTPS;
953
954	RTDECL(int) RTScriptPsCreate(PRTSCRIPTPS phScriptPs, const char *pszId);
955
956	RTDECL(uint32_t) RTScriptPsRetain(RTSCRIPTPS hScriptPs);
957
958	RTDECL(uint32_t) RTScriptPsRelease(RTSCRIPTPS hScriptPs);
959
960	RTDECL(int) RTScriptPsDump(RTSCRIPTPS hScriptPs);
961
962	RTDECL(int) RTScriptPsBuildFromAst(RTSCRIPTPS hScriptPs, PRTSCRIPTASTCOMPILEUNIT pAstCompileUnit);
963
964	RTDECL(int) RTScriptPsCheckConsistency(RTSCRIPTPS hScriptPs);
965
966	/** @} */
967
968
969	/** @defgroup grp_rt_script_parse Scripting parsing API
970	*
971	* @{
972	*/
973
974	/**
975	* Creates a program state from the given pascal input source.
976	*
977	* @returns IPRT status code.
978	* @param phScriptPs Where to store the handle to the program state on success.
979	* @param pszId The program state ID.
980	* @param pszSrc The input to parse.
981	* @param pErrInfo Where to store error information, optional.
982	*/
983	RTDECL(int) RTScriptParsePascalFromString(PRTSCRIPTPS phScriptPs, const char pszId, const char pszSrc,
984	PRTERRINFO pErrInfo);
985
986	/** @} */
987
988
989	/** @defgroup grp_rt_script_vm Scripting bytecode VM API.
990	*
991	* @{
992	*/
993
994	/**
995	* Data value (for return values and arguments).
996	*/
997	typedef struct RTSCRIPTVMVAL
998	{
999	/** The value type. */
1000	RTSCRIPTNATIVETYPE enmType;
1001	/** Value, dependent on type. */
1002	union
1003	{
1004	int8_t i8;
1005	uint8_t u8;
1006	int16_t i16;
1007	uint16_t u16;
1008	int32_t i32;
1009	uint32_t u32;
1010	int64_t i64;
1011	uint64_t u64;
1012	RTFLOAT64U r64;
1013	} u;
1014	} RTSCRIPTVMVAL;
1015	/** Pointer to a VM value. */
1016	typedef RTSCRIPTVMVAL *PRTSCRIPTVMVAL;
1017	/** Pointer to a const value. */
1018	typedef const RTSCRIPTVMVAL *PCRTSCRIPTVMVAL;
1019
1020	/** Opaque VM state handle. */
1021	typedef struct RTSCRIPTVMINT *RTSCRIPTVM;
1022	/** Pointer to a VM state handle. */
1023	typedef RTSCRIPTVM *PRTSCRIPTVM;
1024	/** Opaque VM execution context handle. */
1025	typedef struct RTSCRIPTVMCTXINT *RTSCRIPTVMCTX;
1026	/** Pointer to an opaque VM execution context handle. */
1027	typedef RTSCRIPTVMCTX *PRTSCRIPTVMCTX;
1028
1029	/**
1030	* Creates a new script VM.
1031	*
1032	* @returns IPRT status code.
1033	* @param phScriptVm Where to store the VM handle on success.
1034	*/
1035	RTDECL(int) RTScriptVmCreate(PRTSCRIPTVM phScriptVm);
1036
1037
1038	/**
1039	* Retains the VM reference.
1040	*
1041	* @returns New reference count.
1042	* @param hScriptVm The VM handle to retain.
1043	*/
1044	RTDECL(uint32_t) RTScriptVmRetain(RTSCRIPTVM hScriptVm);
1045
1046
1047	/**
1048	* Releases the VM reference.
1049	*
1050	* @returns New reference count, on 0 the VM is destroyed.
1051	* @param hScriptVm The VM handle to release.
1052	*/
1053	RTDECL(uint32_t) RTScriptVmRelease(RTSCRIPTVM hScriptVm);
1054
1055
1056	/**
1057	* Adds the given program state to the VM making it available for execution.
1058	*
1059	* @returns IPRT status code.
1060	* @param hScriptVm The VM handle.
1061	* @param hScriptPs The program state to add.
1062	* @param pErrInfo Where to store error information on failure.
1063	*/
1064	RTDECL(int) RTScriptVmAddPs(RTSCRIPTVM hScriptVm, RTSCRIPTPS hScriptPs, PRTERRINFO pErrInfo);
1065
1066
1067	/**
1068	* Creates a new execution context for running code in the VM.
1069	*
1070	* @returns IPRT status code.
1071	* @param hScriptVm The VM handle.
1072	* @param phScriptVmCtx Where to store the execution context handle on success.
1073	* @param cbStack Size of the stack in bytes, 0 if unlimited.
1074	*/
1075	RTDECL(int) RTScriptVmExecCtxCreate(RTSCRIPTVM hScriptVm, PRTSCRIPTVMCTX phScriptVmCtx, size_t cbStack);
1076
1077
1078	/**
1079	* Retains the VM execution context reference.
1080	*
1081	* @returns New reference count.
1082	* @param hScriptVmCtx The VM execution context handle to retain.
1083	*/
1084	RTDECL(uint32_t) RTScriptVmExecCtxRetain(RTSCRIPTVMCTX hScriptVmCtx);
1085
1086
1087	/**
1088	* Releases a VM execution context reference.
1089	*
1090	* @returns New reference count, on 0 the execution context is destroyed.
1091	* @param hScriptVmCtx The VM execution context handle to release.
1092	*/
1093	RTDECL(uint32_t) RTScriptVmExecCtxRelease(RTSCRIPTVMCTX hScriptVmCtx);
1094
1095
1096	/**
1097	* Sets the initial state for execution.
1098	*
1099	* @returns IPRT status code.
1100	* @param hScriptVmCtx The VM execution context handle.
1101	* @param pszFn The method to execute, NULL for the main program if existing.
1102	* @param paArgs Arguments to supply to the executed method.
1103	* @param cArgs Number of arguments supplied.
1104	*/
1105	RTDECL(int) RTScriptVmExecCtxInit(RTSCRIPTVMCTX hScriptVmCtx, const char *pszFn,
1106	PCRTSCRIPTVMVAL paArgs, uint32_t cArgs);
1107
1108
1109	/**
1110	* Continues executing the current state.
1111	*
1112	* @returns IPRT status code.
1113	* @param hScriptVmCtx The VM execution context handle.
1114	* @param msTimeout Maximum amount of time to execute, RT_INDEFINITE_WAIT
1115	* for an unrestricted amount of time.
1116	* @param pRetVal Where to store the return value on success, optional.
1117	*/
1118	RTDECL(int) RTScriptVmExecCtxRun(RTSCRIPTVMCTX hScriptVmCtx, RTMSINTERVAL msTimeout,
1119	PRTSCRIPTVMVAL pRetVal);
1120
1121
1122	/**
1123	* Interrupts the current execution.
1124	*
1125	* @returns IPRT status code.
1126	* @param hScriptVmCtx The VM execution context handle.
1127	*/
1128	RTDECL(int) RTScriptVmExecCtxInterrupt(RTSCRIPTVMCTX hScriptVmCtx);
1129
1130
1131
1132	/** @} */
1133	#endif
1134
1135	/** @} */
1136
1137	RT_C_DECLS_END
1138
1139	#endif /* !IPRT_INCLUDED_script_h */
1140

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/iprt/script.h@ 108049

Download in other formats: