script.h@ 105755

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

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

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

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

Download in other formats: