script.h@ 106131

Last change on this file since 106131 was 105760, checked in by vboxsync, 3 months ago
Runtime/script: Add a simple lexer API to turn a stream of characters into tokens for a defined configuration, bugref:10394 [scm]
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 37.9 KB

Line
1	/* $Id: script.h 105760 2024-08-21 12:15:14Z 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 RT_BIT(0)
315
316
317	/** Default character conversions (converting to lower case when the case insensitive flag is set). */
318	#define RTSCRIPT_LEX_CONV_F_DEFAULT 0
319	/** Don't apply any conversion but just return the character as read from the input. */
320	#define RTSCRIPT_LEX_CONV_F_NOTHING RT_BIT(0)
321
322	/**
323	* Lexer reader callback.
324	*
325	* @returns IPRT status code.
326	* @retval VINF_EOF if the end of the input was reached.
327	* @param hScriptLex The lexer handle.
328	* @param offBuf Offset from the start to read from.
329	* @param pchBuf Where to store the read data.
330	* @param cchBuf How much to read at maxmimum.
331	* @param pcchRead Where to store the amount of bytes read.
332	* @param pvUser Opaque user data passed when creating the lexer.
333	*/
334	typedef DECLCALLBACKTYPE(int, FNRTSCRIPTLEXRDR, (RTSCRIPTLEX hScriptLex, size_t offBuf, char *pchBuf, size_t cchBuf,
335	size_t pcchRead, void pvUser));
336	/** Pointer to a lexer reader callback. */
337	typedef FNRTSCRIPTLEXRDR *PFNRTSCRIPTLEXRDR;
338
339
340	/**
341	* Lexer destructor callback.
342	*
343	* @param hScriptLex The lexer handle.
344	* @param pvUser Opaque user data passed when creating the lexer.
345	*/
346	typedef DECLCALLBACKTYPE(void, FNRTSCRIPTLEXDTOR,(RTSCRIPTLEX hScriptLex, void *pvUser));
347	/** Pointer to a lexer destructor callback. */
348	typedef FNRTSCRIPTLEXDTOR *PFNRTSCRIPTLEXDTOR;
349
350
351	/**
352	* Creates a new lexer with the given reader and config.
353	*
354	* @returns IPRT status code.
355	* @param phScriptLex Where to store the handle to the lexer on success.
356	* @param pfnReader The read to use for reading chunks of the input.
357	* @param pfnDtor Destructor callback to call when the lexer is destroyed.
358	* @param pvUser Opaque user data passed to reader.
359	* @param cchBuf Buffer hint, if 0 a default is chosen.
360	* @param phStrCacheId Where to store the pointer to the string cache containing all
361	* scanned identifiers on success, optional.
362	* If not NULL the string cache must be freed by the caller when not used
363	* anymore.
364	* @param phStrCacheStringLit Where to store the pointer to the string cache containing all
365	* scanned string literals on success, optional.
366	* If not NULL the string cache must be freed by the caller when not used
367	* anymore.
368	* @param pCfg The lexer config to use for identifying the different tokens.
369	*/
370	RTDECL(int) RTScriptLexCreateFromReader(PRTSCRIPTLEX phScriptLex, PFNRTSCRIPTLEXRDR pfnReader,
371	PFNRTSCRIPTLEXDTOR pfnDtor, void *pvUser,
372	size_t cchBuf, PRTSTRCACHE phStrCacheId, PRTSTRCACHE phStrCacheStringLit,
373	PCRTSCRIPTLEXCFG pCfg);
374
375
376	/**
377	* Creates a new lexer for the given input string and config.
378	*
379	* @returns IPRT status code.
380	* @param phScriptLex Where to store the handle to the lexer on success.
381	* @param pszSrc The input string to scan.
382	* @param phStrCacheId Where to store the pointer to the string cache containing all
383	* scanned identifiers on success, optional.
384	* If not NULL the string cache must be freed by the caller when not used
385	* anymore.
386	* @param phStrCacheStringLit Where to store the pointer to the string cache containing all
387	* scanned string literals on success, optional.
388	* If not NULL the string cache must be freed by the caller when not used
389	* anymore.
390	* @param pCfg The lexer config to use for identifying the different tokens.
391	*/
392	RTDECL(int) RTScriptLexCreateFromString(PRTSCRIPTLEX phScriptLex, const char *pszSrc, PRTSTRCACHE phStrCacheId,
393	PRTSTRCACHE phStrCacheStringLit, PCRTSCRIPTLEXCFG pCfg);
394
395
396	/**
397	* Creates a new lexer from the given filename and config.
398	*
399	* @returns IPRT status code.
400	* @param phScriptLex Where to store the handle to the lexer on success.
401	* @param pszFilename The filename of the input.
402	* @param phStrCacheId Where to store the pointer to the string cache containing all
403	* scanned identifiers on success, optional.
404	* If not NULL the string cache must be freed by the caller when not used
405	* anymore.
406	* @param phStrCacheStringLit Where to store the pointer to the string cache containing all
407	* scanned string literals on success, optional.
408	* If not NULL the string cache must be freed by the caller when not used
409	* anymore.
410	* @param pCfg The lexer config to use for identifying the different tokens.
411	*/
412	RTDECL(int) RTScriptLexCreateFromFile(PRTSCRIPTLEX phScriptLex, const char *pszFilename, PRTSTRCACHE phStrCacheId,
413	PRTSTRCACHE phStrCacheStringLit, PCRTSCRIPTLEXCFG pCfg);
414
415
416	/**
417	* Destroys the given lexer handle.
418	*
419	* @param hScriptLex The lexer handle to destroy.
420	*/
421	RTDECL(void) RTScriptLexDestroy(RTSCRIPTLEX hScriptLex);
422
423
424	/**
425	* Queries the current identified token.
426	*
427	* @returns IPRT status code.
428	* @param hScriptLex The lexer handle.
429	* @param ppToken Where to store the pointer to the token on success.
430	*/
431	RTDECL(int) RTScriptLexQueryToken(RTSCRIPTLEX hScriptLex, PCRTSCRIPTLEXTOKEN *ppToken);
432
433
434	/**
435	* Returns the current token type.
436	*
437	* @returns Current token type.
438	* @param hScriptLex The lexer handle.
439	*/
440	RTDECL(RTSCRIPTLEXTOKTYPE) RTScriptLexGetTokenType(RTSCRIPTLEX hScriptLex);
441
442
443	/**
444	* Returns the next token type.
445	*
446	* @returns Next token type.
447	* @param hScriptLex The lexer handle.
448	*/
449	RTDECL(RTSCRIPTLEXTOKTYPE) RTScriptLexPeekNextTokenType(RTSCRIPTLEX hScriptLex);
450
451
452	/**
453	* Consumes the current token and moves to the next one.
454	*
455	* @returns Pointer to the next token.
456	* @param hScriptLex The lexer handle.
457	*/
458	RTDECL(PCRTSCRIPTLEXTOKEN) RTScriptLexConsumeToken(RTSCRIPTLEX hScriptLex);
459
460
461	/**
462	* Consumes the current input characters and moves to the next one.
463	*
464	* @returns Returns the next character in the input stream.
465	* @retval 0 indicates end of stream.
466	* @param hScriptLex The lexer handle.
467	*/
468	RTDECL(char) RTScriptLexConsumeCh(RTSCRIPTLEX hScriptLex);
469
470
471	/**
472	* Consumes the current input characters and moves to the next one - extended version.
473	*
474	* @returns Returns the next character in the input stream.
475	* @retval 0 indicates end of stream.
476	* @param hScriptLex The lexer handle.
477	* @param fFlags Flags controlling some basic conversions of characters,
478	* combination of RTSCRIPT_LEX_CONV_F_*.
479	*/
480	RTDECL(char) RTScriptLexConsumeChEx(RTSCRIPTLEX hScriptLex, uint32_t fFlags);
481
482
483	/**
484	* Returns the character at the curren input position.
485	*
486	* @returns Character at the current position in the input
487	* @retval 0 indicates end of stream.
488	* @param hScriptLex The lexer handle.
489	*/
490	RTDECL(char) RTScriptLexGetCh(RTSCRIPTLEX hScriptLex);
491
492
493	/**
494	* Returns the character at the curren input position - extended version.
495	*
496	* @returns Character at the current position in the input
497	* @retval 0 indicates end of stream.
498	* @param hScriptLex The lexer handle.
499	* @param fFlags Flags controlling some basic conversions of characters,
500	* combination of RTSCRIPT_LEX_CONV_F_*.
501	*/
502	RTDECL(char) RTScriptLexGetChEx(RTSCRIPTLEX hScriptLex, uint32_t fFlags);
503
504
505	/**
506	* Returns the current character in the input without moving to the next one.
507	*
508	* @returns Returns the current character.
509	* @retval 0 indicates end of stream.
510	* @param hScriptLex The lexer handle.
511	* @param idx Offset to peek at, 0 behaves like rtScriptLexGetCh().
512	*/
513	RTDECL(char) RTScriptLexPeekCh(RTSCRIPTLEX hScriptLex, unsigned idx);
514
515
516	/**
517	* Returns the current character in the input without moving to the next one - extended version.
518	*
519	* @returns Returns the current character.
520	* @retval 0 indicates end of stream.
521	* @param hScriptLex The lexer handle.
522	* @param idx Offset to peek at, 0 behaves like rtScriptLexGetCh().
523	* @param fFlags Flags controlling some basic conversions of characters,
524	* combination of RTSCRIPT_LEX_CONV_F_*.
525	*/
526	RTDECL(char) RTScriptLexPeekChEx(RTSCRIPTLEX hScriptLex, unsigned idx, uint32_t fFlags);
527
528
529	/**
530	* Skips everything declared as whitespace, including comments and newlines.
531	*
532	* @param hScriptLex The lexer handle.
533	*/
534	RTDECL(void) RTScriptLexSkipWhitespace(RTSCRIPTLEX hScriptLex);
535
536
537	/** @defgroup grp_rt_script_lex_builtin Builtin helpers to scan numbers, string literals, ...
538	* @{ */
539
540	/**
541	* Produces a numerical constant token from the number starting at the current position in the
542	* input stream on success or an appropriate error token.
543	*
544	* @returns IPRT status code.
545	* @param hScriptLex The lexer handle.
546	* @param uBase The base to parse the number in.
547	* @param fAllowReal Flag whether to allow parsing real numbers using the following
548	* layout [+-][0-9][.][e][+-][0-9].
549	* @param pTok The token to fill in.
550	*/
551	RTDECL(int) RTScriptLexScanNumber(RTSCRIPTLEX hScriptLex, uint8_t uBase, bool fAllowReal,
552	PRTSCRIPTLEXTOKEN pTok);
553
554	/**
555	* Production rule to create an identifier token with the given set of allowed characters.
556	*
557	* @returns IPRT status code.
558	* @param hScriptLex The lexer handle.
559	* @param ch The first character of the identifier.
560	* @param pTok The token to fill in.
561	* @param pvUser Opaque user data, must point to the allowed set of characters for identifiers as a
562	* zero terminated string. NULL will revert to a default set of characters including
563	* [_a-zA-Z0-9]*
564	*
565	* @note This version will allow a maximum identifier length of 512 characters (should be plenty).
566	* More characters will produce an error token. Must be used with the RTSCRIPT_LEX_RULE_CONSUME
567	* flag for the first character.
568	*/
569	RTDECL(int) RTScriptLexScanIdentifier(RTSCRIPTLEX hScriptLex, char ch, PRTSCRIPTLEXTOKEN pTok, void *pvUser);
570
571
572	/**
573	* Production rule to scan string literals conforming to the C standard.
574	*
575	* @returns IPRT status code.
576	* @param hScriptLex The lexer handle.
577	* @param ch The character starting the rule, unused.
578	* @param pTok The token to fill in.
579	* @param pvUser Opaque user data, unused.
580	*
581	* @note The RTSCRIPT_LEX_RULE_CONSUME must be used (or omitted) such that the current character
582	* in the input denotes the start of the string literal. The resulting literal is added to the respective
583	* cache on success.
584	*/
585	RTDECL(int) RTScriptLexScanStringLiteralC(RTSCRIPTLEX hScriptLex, char ch, PRTSCRIPTLEXTOKEN pTok, void *pvUser);
586
587
588	/**
589	* Production rule to scan string literals for pascal like languages, without support for escape
590	* sequences and where a ' is denoted by ''.
591	*
592	* @returns IPRT status code.
593	* @param hScriptLex The lexer handle.
594	* @param ch The character starting the rule, unused.
595	* @param pTok The token to fill in.
596	* @param pvUser Opaque user data, unused.
597	*
598	* @note The RTSCRIPT_LEX_RULE_CONSUME must be used (or omitted) such that the current character
599	* in the input denotes the start of the string literal. The resulting literal is added to the respective
600	* cache on success.
601	*/
602	RTDECL(int) RTScriptLexScanStringLiteralPascal(RTSCRIPTLEX hScriptLex, char ch, PRTSCRIPTLEXTOKEN pTok, void *pvUser);
603
604	/** @} */
605
606	/** @} */
607
608
609	#if 0 /* Later, maybe */
610
611	/** @defgroup grp_rt_script_typesys Scripting language type system API.
612	*
613	* @{
614	*/
615
616	/**
617	* Type class.
618	*/
619	typedef enum RTSCRIPTTSTYPECLASS
620	{
621	/** Invalid. */
622	RTSCRIPTTSTYPECLASS_INVALID = 0,
623	/** A native type. */
624	RTSCRIPTTSTYPECLASS_NATIVE,
625	/** Array type. */
626	RTSCRIPTTSTYPECLASS_ARRAY,
627	/** Struct type. */
628	RTSCRIPTTSTYPECLASS_STRUCT,
629	/** Union type. */
630	RTSCRIPTTSTYPECLASS_UNION,
631	/** Function type. */
632	RTSCRIPTTSTYPECLASS_FUNCTION,
633	/** Pointer type. */
634	RTSCRIPTTSTYPECLASS_POINTER,
635	/** Alias for another type. */
636	RTSCRIPTTSTYPECLASS_ALIAS
637	} RTSCRIPTTSTYPECLASS;
638
639
640	/** Pointer to a type descriptor. */
641	typedef struct RTSCRIPTTSTYPDESC *PRTSCRIPTTSTYPDESC;
642	/** Pointer to a const type descriptor. */
643	typedef const RTSCRIPTTSTYPDESC *PCRTSCRIPTTSTYPDESC;
644
645	/**
646	* Type descriptor.
647	*/
648	typedef struct RTSCRIPTTSTYPDESC
649	{
650	/** Type class */
651	RTSCRIPTTSTYPECLASS enmClass;
652	/** Identifier for this type. */
653	const char *pszIdentifier;
654	/** Class dependent data. */
655	union
656	{
657	/** Native type. */
658	struct
659	{
660	/** The native type. */
661	RTSCRIPTNATIVETYPE enmTypeNative;
662	/** Alignment for the native type in bits - 0 for default alignment. */
663	uint32_t cBitsAlign;
664	} Native;
665	/** Array type. */
666	struct
667	{
668	/** Type identifier. */
669	const char *pszTypeIde;
670	/** Number of elements. */
671	uint32_t cElems;
672	} Array;
673	/** Struct/Union type. */
674	struct
675	{
676	/* Flag whether this is packed. */
677	bool fPacked;
678	/** Number of members. */
679	uint32_t cMembers;
680	/** Pointer to the array of member identifiers for each member. */
681	const char **papszMember;
682	/** Pointer to the array of type identifiers for each member. */
683	const char **papszMemberType;
684	} UnionStruct;
685	/** Function type. */
686	struct
687	{
688	/** Return type - NULL for no return type. */
689	const char *pszTypeRet;
690	/** Number of typed arguments. */
691	uint32_t cArgsTyped;
692	/** Pointer to the array of type identifiers for the arguments. */
693	const char **papszMember;
694	/** Flag whether variable arguments are used. */
695	bool fVarArgs;
696	} Function;
697	/** Pointer. */
698	struct
699	{
700	/** The type identifier the pointer references. */
701	const char *pszTypeIde;
702	} Pointer;
703	/** Pointer. */
704	struct
705	{
706	/** The type identifier the alias references. */
707	const char *pszTypeIde;
708	} Alias;
709	} Class;
710	} RTSCRIPTTSTYPDESC;
711
712
713	/** Opaque type system handle. */
714	typedef struct RTSCRIPTTSINT *RTSCRIPTTS;
715	/** Pointer to an opaque type system handle. */
716	typedef RTSCRIPTTS *PRTSCRIPTTS;
717
718
719	/** Opaque type system type. */
720	typedef struct RTSCRIPTTSTYPEINT *RTSCRIPTTSTYPE;
721	/** Pointer to an opaque type system type. */
722	typedef RTSCRIPTTSTYPE *PRTSCRIPTTSTYPE;
723
724
725	/**
726	* Create a new empty type system.
727	*
728	* @returns IPRT status code.
729	* @param phScriptTs Where to store the handle to the type system on success.
730	* @param hScriptTsParent Parent type system to get declarations from. NULL if no parent.
731	* @param enmPtrType Native pointer type (only unsigned integer types allowed).
732	* @param cPtrAlignBits The native alignment of a pointer storage location.
733	*/
734	RTDECL(int) RTScriptTsCreate(PRTSCRIPTTS phScriptTs, RTSCRIPTTS hScriptTsParent,
735	RTSCRIPTNATIVETYPE enmPtrType, uint32_t cPtrAlignBits);
736
737
738	/**
739	* Retains a reference to the given type system.
740	*
741	* @returns New reference count.
742	* @param hScriptTs Type system handle.
743	*/
744	RTDECL(uint32_t) RTScriptTsRetain(RTSCRIPTTS hScriptTs);
745
746
747	/**
748	* Releases a reference to the given type system.
749	*
750	* @returns New reference count, on 0 the type system is destroyed.
751	* @param hScriptTs Type system handle.
752	*/
753	RTDECL(uint32_t) RTScriptTsRelease(RTSCRIPTTS hScriptTs);
754
755
756	/**
757	* Dumps the content of the type system.
758	*
759	* @returns IPRT status code.
760	* @param hScriptTs Type system handle.
761	*/
762	RTDECL(int) RTScriptTsDump(RTSCRIPTTS hScriptTs);
763
764
765	/**
766	* Add several types to the type system from the given descriptor array.
767	*
768	* @returns IPRT status code.
769	* @param hScriptTs Type system handle.
770	* @param paTypeDescs Pointer to the array of type descriptors.
771	* @param cTypeDescs Number of entries in the array.
772	*/
773	RTDECL(int) RTScriptTsAdd(RTSCRIPTTS hScriptTs, PCRTSCRIPTTSTYPDESC paTypeDescs,
774	uint32_t cTypeDescs);
775
776
777	/**
778	* Removes the given types from the type system.
779	*
780	* @returns IPRT status code.
781	* @param hScriptTs Type system handle.
782	* @param papszTypes Array of type identifiers to remove. Array terminated
783	* with a NULL entry.
784	*/
785	RTDECL(int) RTScriptTsRemove(RTSCRIPTTS hScriptTs, const char **papszTypes);
786
787
788	/**
789	* Queries the given type returning the type handle on success.
790	*
791	* @returns IPRT status code.
792	* @retval VERR_NOT_FOUND if the type could not be found.
793	* @param hScriptTs Type system handle.
794	* @param pszType The type identifier to look for.
795	* @param phType Where to store the handle to the type on success.
796	*/
797	RTDECL(int) RTScriptTsQueryType(RTSCRIPTTS hScriptTs, const char *pszType,
798	PRTSCRIPTTSTYPE phType);
799
800
801	/**
802	* Retains the given type reference.
803	*
804	* @returns New reference count.
805	* @param hScriptTsType Type system type handle.
806	*/
807	RTDECL(uint32_t) RTScriptTsTypeRetain(RTSCRIPTTSTYPE hScriptTsType);
808
809
810	/**
811	* Releases the given type reference.
812	*
813	* @returns New reference count.
814	* @param hScriptTsType Type system type handle.
815	*/
816	RTDECL(uint32_t) RTScriptTsTypeRelease(RTSCRIPTTSTYPE hScriptTsType);
817
818
819	/**
820	* Returns the class of the given type handle.
821	*
822	* @returns Type class for the given type handle.
823	* @param hScriptTsType Type system type handle.
824	*/
825	RTDECL(RTSCRIPTTSTYPECLASS) RTScriptTsTypeGetClass(RTSCRIPTTSTYPE hScriptTsType);
826
827
828	/**
829	* Returns the identifier of the given type handle.
830	*
831	* @returns Pointer to the identifier of the given type handle.
832	* @param hScriptTsType Type system type handle.
833	*/
834	RTDECL(const char *) RTScriptTsTypeGetIdentifier(RTSCRIPTTSTYPE hScriptTsType);
835
836
837	/**
838	* Returns the storage size of the given type in bits.
839	*
840	* @returns Size of the type in bits described by the given handle.
841	* @param hScriptTsType Type system type handle.
842	*/
843	RTDECL(size_t) RTScriptTsTypeGetBitCount(RTSCRIPTTSTYPE hScriptTsType);
844
845
846	/**
847	* Returns the necessary alignment of the given type in bits.
848	*
849	* @returns Alignmebt of the type in bits described by the given handle.
850	* @param hScriptTsType Type system type handle.
851	*/
852	RTDECL(size_t) RTScriptTsTypeGetAlignmentBitCount(RTSCRIPTTSTYPE hScriptTsType);
853
854
855	/**
856	* Return the native type for the given native type.
857	*
858	* @returns Native type enum.
859	* @param hScriptTsType Type system type handle.
860	*/
861	RTDECL(RTSCRIPTNATIVETYPE) RTScriptTsTypeNativeGetType(RTSCRIPTTSTYPE hScriptTsType);
862
863
864	/**
865	* Return the number of elements for the given array type.
866	*
867	* @returns Number of elements.
868	* @param hScriptTsType Type system type handle.
869	*/
870	RTDECL(uint32_t) RTScriptTsTypeArrayGetElemCount(RTSCRIPTTSTYPE hScriptTsType);
871
872
873	/**
874	* Return the type handle of element type for the given array type.
875	*
876	* @returns Number of elements.
877	* @param hScriptTsType Type system type handle.
878	*/
879	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeArrayGetElemType(RTSCRIPTTSTYPE hScriptTsType);
880
881
882	/**
883	* Returns whether the given union/struct type is packed.
884	*
885	* @returns Number of elements.
886	* @param hScriptTsType Type system type handle.
887	*/
888	RTDECL(bool) RTScriptTsTypeStructUnionGetPacked(RTSCRIPTTSTYPE hScriptTsType);
889
890	RTDECL(uint32_t) RTScriptTsTypeStructUnionGetMemberCount(RTSCRIPTTSTYPE hScriptTsType);
891
892	RTDECL(int) RTScriptTsTypeStructUnionQueryMember(RTSCRIPTTSTYPE hScriptTsType, uint32_t idxMember, uint32_t *poffMember,
893	uint32_t *pcMemberBits, PRTSCRIPTTSTYPE phScriptTsTypeMember);
894
895	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeFunctionGetRetType(RTSCRIPTTSTYPE hScriptTsType);
896
897	RTDECL(uint32_t) RTScriptTsTypeFunctionGetTypedArgCount(RTSCRIPTTSTYPE hScriptTsType);
898
899	RTDECL(bool) RTScriptTsTypeFunctionUsesVarArgs(RTSCRIPTTSTYPE hScriptTsType);
900
901	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeFunctionGetArgType(RTSCRIPTTSTYPE hScriptTsType, uint32_t idxArg);
902
903	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypePointerGetRefType(RTSCRIPTTSTYPE hScriptTsType);
904
905	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeAliasGetAliasedType(RTSCRIPTTSTYPE hScriptTsType);
906
907	RTDECL(bool) RTScriptTsTypeEquals(RTSCRIPTTSTYPE hScriptTsType1, RTSCRIPTTSTYPE hScriptTsType2);
908
909	RTDECL(bool) RTScriptTsTypeEqualsByOneName(RTSCRIPTTS hScriptTs, const char *pszType1, RTSCRIPTTSTYPE hScriptTsType2);
910
911	RTDECL(bool) RTScriptTsTypeEqualsByTwoNames(RTSCRIPTTS hScriptTs, const char pszType1, const char pszType2);
912
913	/** @} */
914
915
916
917	/** @defgroup grp_rt_script_ps Scripting program state API
918	*
919	* @{
920	*/
921
922	/** Opaque program state handle. */
923	typedef struct RTSCRIPTPSINT *RTSCRIPTPS;
924	/** Pointer to a program state handle. */
925	typedef RTSCRIPTPS *PRTSCRIPTPS;
926
927	RTDECL(int) RTScriptPsCreate(PRTSCRIPTPS phScriptPs, const char *pszId);
928
929	RTDECL(uint32_t) RTScriptPsRetain(RTSCRIPTPS hScriptPs);
930
931	RTDECL(uint32_t) RTScriptPsRelease(RTSCRIPTPS hScriptPs);
932
933	RTDECL(int) RTScriptPsDump(RTSCRIPTPS hScriptPs);
934
935	RTDECL(int) RTScriptPsBuildFromAst(RTSCRIPTPS hScriptPs, PRTSCRIPTASTCOMPILEUNIT pAstCompileUnit);
936
937	RTDECL(int) RTScriptPsCheckConsistency(RTSCRIPTPS hScriptPs);
938
939	/** @} */
940
941
942	/** @defgroup grp_rt_script_parse Scripting parsing API
943	*
944	* @{
945	*/
946
947	/**
948	* Creates a program state from the given pascal input source.
949	*
950	* @returns IPRT status code.
951	* @param phScriptPs Where to store the handle to the program state on success.
952	* @param pszId The program state ID.
953	* @param pszSrc The input to parse.
954	* @param pErrInfo Where to store error information, optional.
955	*/
956	RTDECL(int) RTScriptParsePascalFromString(PRTSCRIPTPS phScriptPs, const char pszId, const char pszSrc,
957	PRTERRINFO pErrInfo);
958
959	/** @} */
960
961
962	/** @defgroup grp_rt_script_vm Scripting bytecode VM API.
963	*
964	* @{
965	*/
966
967	/**
968	* Data value (for return values and arguments).
969	*/
970	typedef struct RTSCRIPTVMVAL
971	{
972	/** The value type. */
973	RTSCRIPTNATIVETYPE enmType;
974	/** Value, dependent on type. */
975	union
976	{
977	int8_t i8;
978	uint8_t u8;
979	int16_t i16;
980	uint16_t u16;
981	int32_t i32;
982	uint32_t u32;
983	int64_t i64;
984	uint64_t u64;
985	RTFLOAT64U r64;
986	} u;
987	} RTSCRIPTVMVAL;
988	/** Pointer to a VM value. */
989	typedef RTSCRIPTVMVAL *PRTSCRIPTVMVAL;
990	/** Pointer to a const value. */
991	typedef const RTSCRIPTVMVAL *PCRTSCRIPTVMVAL;
992
993	/** Opaque VM state handle. */
994	typedef struct RTSCRIPTVMINT *RTSCRIPTVM;
995	/** Pointer to a VM state handle. */
996	typedef RTSCRIPTVM *PRTSCRIPTVM;
997	/** Opaque VM execution context handle. */
998	typedef struct RTSCRIPTVMCTXINT *RTSCRIPTVMCTX;
999	/** Pointer to an opaque VM execution context handle. */
1000	typedef RTSCRIPTVMCTX *PRTSCRIPTVMCTX;
1001
1002	/**
1003	* Creates a new script VM.
1004	*
1005	* @returns IPRT status code.
1006	* @param phScriptVm Where to store the VM handle on success.
1007	*/
1008	RTDECL(int) RTScriptVmCreate(PRTSCRIPTVM phScriptVm);
1009
1010
1011	/**
1012	* Retains the VM reference.
1013	*
1014	* @returns New reference count.
1015	* @param hScriptVm The VM handle to retain.
1016	*/
1017	RTDECL(uint32_t) RTScriptVmRetain(RTSCRIPTVM hScriptVm);
1018
1019
1020	/**
1021	* Releases the VM reference.
1022	*
1023	* @returns New reference count, on 0 the VM is destroyed.
1024	* @param hScriptVm The VM handle to release.
1025	*/
1026	RTDECL(uint32_t) RTScriptVmRelease(RTSCRIPTVM hScriptVm);
1027
1028
1029	/**
1030	* Adds the given program state to the VM making it available for execution.
1031	*
1032	* @returns IPRT status code.
1033	* @param hScriptVm The VM handle.
1034	* @param hScriptPs The program state to add.
1035	* @param pErrInfo Where to store error information on failure.
1036	*/
1037	RTDECL(int) RTScriptVmAddPs(RTSCRIPTVM hScriptVm, RTSCRIPTPS hScriptPs, PRTERRINFO pErrInfo);
1038
1039
1040	/**
1041	* Creates a new execution context for running code in the VM.
1042	*
1043	* @returns IPRT status code.
1044	* @param hScriptVm The VM handle.
1045	* @param phScriptVmCtx Where to store the execution context handle on success.
1046	* @param cbStack Size of the stack in bytes, 0 if unlimited.
1047	*/
1048	RTDECL(int) RTScriptVmExecCtxCreate(RTSCRIPTVM hScriptVm, PRTSCRIPTVMCTX phScriptVmCtx, size_t cbStack);
1049
1050
1051	/**
1052	* Retains the VM execution context reference.
1053	*
1054	* @returns New reference count.
1055	* @param hScriptVmCtx The VM execution context handle to retain.
1056	*/
1057	RTDECL(uint32_t) RTScriptVmExecCtxRetain(RTSCRIPTVMCTX hScriptVmCtx);
1058
1059
1060	/**
1061	* Releases a VM execution context reference.
1062	*
1063	* @returns New reference count, on 0 the execution context is destroyed.
1064	* @param hScriptVmCtx The VM execution context handle to release.
1065	*/
1066	RTDECL(uint32_t) RTScriptVmExecCtxRelease(RTSCRIPTVMCTX hScriptVmCtx);
1067
1068
1069	/**
1070	* Sets the initial state for execution.
1071	*
1072	* @returns IPRT status code.
1073	* @param hScriptVmCtx The VM execution context handle.
1074	* @param pszFn The method to execute, NULL for the main program if existing.
1075	* @param paArgs Arguments to supply to the executed method.
1076	* @param cArgs Number of arguments supplied.
1077	*/
1078	RTDECL(int) RTScriptVmExecCtxInit(RTSCRIPTVMCTX hScriptVmCtx, const char *pszFn,
1079	PCRTSCRIPTVMVAL paArgs, uint32_t cArgs);
1080
1081
1082	/**
1083	* Continues executing the current state.
1084	*
1085	* @returns IPRT status code.
1086	* @param hScriptVmCtx The VM execution context handle.
1087	* @param msTimeout Maximum amount of time to execute, RT_INDEFINITE_WAIT
1088	* for an unrestricted amount of time.
1089	* @param pRetVal Where to store the return value on success, optional.
1090	*/
1091	RTDECL(int) RTScriptVmExecCtxRun(RTSCRIPTVMCTX hScriptVmCtx, RTMSINTERVAL msTimeout,
1092	PRTSCRIPTVMVAL pRetVal);
1093
1094
1095	/**
1096	* Interrupts the current execution.
1097	*
1098	* @returns IPRT status code.
1099	* @param hScriptVmCtx The VM execution context handle.
1100	*/
1101	RTDECL(int) RTScriptVmExecCtxInterrupt(RTSCRIPTVMCTX hScriptVmCtx);
1102
1103
1104
1105	/** @} */
1106	#endif
1107
1108	/** @} */
1109
1110	RT_C_DECLS_END
1111
1112	#endif /* !IPRT_INCLUDED_script_h */
1113

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

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

Download in other formats: