script.h@ 108014

Last change on this file since 108014 was 108014, checked in by vboxsync, 3 months ago
Runtime/common/script/scriptlex.cpp: Fix C string literal scanning and add some helper APIs to create tokens for errors and identifiers, bugref:10733
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 38.9 KB

Line
1	/* $Id: script.h 108014 2025-02-01 19:20:09Z 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	* Produces an error token with the given message, used for custom lexer rule implementations.
607	*
608	* @returns IPRT status code.
609	* @param hScriptLex The lexer handle.
610	* @param pTok The token to fill.
611	* @param rc The status code to use in the message.
612	* @param pszMsg The format string for the error message.
613	* @param ... Arguments to the format string.
614	*/
615	RTDECL(int) RTScriptLexProduceTokError(RTSCRIPTLEX hScriptLex, PRTSCRIPTLEXTOKEN pTok, int rc, const char *pszMsg, ...);
616
617
618	/**
619	* Produces an identifier token with the given identifier, used for custom lexer rule implementations.
620	*
621	* @returns IPRT status code.
622	* @param hScriptLex The lexer handle.
623	* @param pTok The token to fill.
624	* @param pszIde The identifier to add.
625	* @param cchIde Number of characters in the identifier.
626	*/
627	RTDECL(int) RTScriptLexProduceTokIde(RTSCRIPTLEX hScriptLex, PRTSCRIPTLEXTOKEN pTok, const char *pszIde, size_t cchIde);
628	/** @} */
629
630	/** @} */
631
632
633	#if 0 /* Later, maybe */
634
635	/** @defgroup grp_rt_script_typesys Scripting language type system API.
636	*
637	* @{
638	*/
639
640	/**
641	* Type class.
642	*/
643	typedef enum RTSCRIPTTSTYPECLASS
644	{
645	/** Invalid. */
646	RTSCRIPTTSTYPECLASS_INVALID = 0,
647	/** A native type. */
648	RTSCRIPTTSTYPECLASS_NATIVE,
649	/** Array type. */
650	RTSCRIPTTSTYPECLASS_ARRAY,
651	/** Struct type. */
652	RTSCRIPTTSTYPECLASS_STRUCT,
653	/** Union type. */
654	RTSCRIPTTSTYPECLASS_UNION,
655	/** Function type. */
656	RTSCRIPTTSTYPECLASS_FUNCTION,
657	/** Pointer type. */
658	RTSCRIPTTSTYPECLASS_POINTER,
659	/** Alias for another type. */
660	RTSCRIPTTSTYPECLASS_ALIAS
661	} RTSCRIPTTSTYPECLASS;
662
663
664	/** Pointer to a type descriptor. */
665	typedef struct RTSCRIPTTSTYPDESC *PRTSCRIPTTSTYPDESC;
666	/** Pointer to a const type descriptor. */
667	typedef const RTSCRIPTTSTYPDESC *PCRTSCRIPTTSTYPDESC;
668
669	/**
670	* Type descriptor.
671	*/
672	typedef struct RTSCRIPTTSTYPDESC
673	{
674	/** Type class */
675	RTSCRIPTTSTYPECLASS enmClass;
676	/** Identifier for this type. */
677	const char *pszIdentifier;
678	/** Class dependent data. */
679	union
680	{
681	/** Native type. */
682	struct
683	{
684	/** The native type. */
685	RTSCRIPTNATIVETYPE enmTypeNative;
686	/** Alignment for the native type in bits - 0 for default alignment. */
687	uint32_t cBitsAlign;
688	} Native;
689	/** Array type. */
690	struct
691	{
692	/** Type identifier. */
693	const char *pszTypeIde;
694	/** Number of elements. */
695	uint32_t cElems;
696	} Array;
697	/** Struct/Union type. */
698	struct
699	{
700	/* Flag whether this is packed. */
701	bool fPacked;
702	/** Number of members. */
703	uint32_t cMembers;
704	/** Pointer to the array of member identifiers for each member. */
705	const char **papszMember;
706	/** Pointer to the array of type identifiers for each member. */
707	const char **papszMemberType;
708	} UnionStruct;
709	/** Function type. */
710	struct
711	{
712	/** Return type - NULL for no return type. */
713	const char *pszTypeRet;
714	/** Number of typed arguments. */
715	uint32_t cArgsTyped;
716	/** Pointer to the array of type identifiers for the arguments. */
717	const char **papszMember;
718	/** Flag whether variable arguments are used. */
719	bool fVarArgs;
720	} Function;
721	/** Pointer. */
722	struct
723	{
724	/** The type identifier the pointer references. */
725	const char *pszTypeIde;
726	} Pointer;
727	/** Pointer. */
728	struct
729	{
730	/** The type identifier the alias references. */
731	const char *pszTypeIde;
732	} Alias;
733	} Class;
734	} RTSCRIPTTSTYPDESC;
735
736
737	/** Opaque type system handle. */
738	typedef struct RTSCRIPTTSINT *RTSCRIPTTS;
739	/** Pointer to an opaque type system handle. */
740	typedef RTSCRIPTTS *PRTSCRIPTTS;
741
742
743	/** Opaque type system type. */
744	typedef struct RTSCRIPTTSTYPEINT *RTSCRIPTTSTYPE;
745	/** Pointer to an opaque type system type. */
746	typedef RTSCRIPTTSTYPE *PRTSCRIPTTSTYPE;
747
748
749	/**
750	* Create a new empty type system.
751	*
752	* @returns IPRT status code.
753	* @param phScriptTs Where to store the handle to the type system on success.
754	* @param hScriptTsParent Parent type system to get declarations from. NULL if no parent.
755	* @param enmPtrType Native pointer type (only unsigned integer types allowed).
756	* @param cPtrAlignBits The native alignment of a pointer storage location.
757	*/
758	RTDECL(int) RTScriptTsCreate(PRTSCRIPTTS phScriptTs, RTSCRIPTTS hScriptTsParent,
759	RTSCRIPTNATIVETYPE enmPtrType, uint32_t cPtrAlignBits);
760
761
762	/**
763	* Retains a reference to the given type system.
764	*
765	* @returns New reference count.
766	* @param hScriptTs Type system handle.
767	*/
768	RTDECL(uint32_t) RTScriptTsRetain(RTSCRIPTTS hScriptTs);
769
770
771	/**
772	* Releases a reference to the given type system.
773	*
774	* @returns New reference count, on 0 the type system is destroyed.
775	* @param hScriptTs Type system handle.
776	*/
777	RTDECL(uint32_t) RTScriptTsRelease(RTSCRIPTTS hScriptTs);
778
779
780	/**
781	* Dumps the content of the type system.
782	*
783	* @returns IPRT status code.
784	* @param hScriptTs Type system handle.
785	*/
786	RTDECL(int) RTScriptTsDump(RTSCRIPTTS hScriptTs);
787
788
789	/**
790	* Add several types to the type system from the given descriptor array.
791	*
792	* @returns IPRT status code.
793	* @param hScriptTs Type system handle.
794	* @param paTypeDescs Pointer to the array of type descriptors.
795	* @param cTypeDescs Number of entries in the array.
796	*/
797	RTDECL(int) RTScriptTsAdd(RTSCRIPTTS hScriptTs, PCRTSCRIPTTSTYPDESC paTypeDescs,
798	uint32_t cTypeDescs);
799
800
801	/**
802	* Removes the given types from the type system.
803	*
804	* @returns IPRT status code.
805	* @param hScriptTs Type system handle.
806	* @param papszTypes Array of type identifiers to remove. Array terminated
807	* with a NULL entry.
808	*/
809	RTDECL(int) RTScriptTsRemove(RTSCRIPTTS hScriptTs, const char **papszTypes);
810
811
812	/**
813	* Queries the given type returning the type handle on success.
814	*
815	* @returns IPRT status code.
816	* @retval VERR_NOT_FOUND if the type could not be found.
817	* @param hScriptTs Type system handle.
818	* @param pszType The type identifier to look for.
819	* @param phType Where to store the handle to the type on success.
820	*/
821	RTDECL(int) RTScriptTsQueryType(RTSCRIPTTS hScriptTs, const char *pszType,
822	PRTSCRIPTTSTYPE phType);
823
824
825	/**
826	* Retains the given type reference.
827	*
828	* @returns New reference count.
829	* @param hScriptTsType Type system type handle.
830	*/
831	RTDECL(uint32_t) RTScriptTsTypeRetain(RTSCRIPTTSTYPE hScriptTsType);
832
833
834	/**
835	* Releases the given type reference.
836	*
837	* @returns New reference count.
838	* @param hScriptTsType Type system type handle.
839	*/
840	RTDECL(uint32_t) RTScriptTsTypeRelease(RTSCRIPTTSTYPE hScriptTsType);
841
842
843	/**
844	* Returns the class of the given type handle.
845	*
846	* @returns Type class for the given type handle.
847	* @param hScriptTsType Type system type handle.
848	*/
849	RTDECL(RTSCRIPTTSTYPECLASS) RTScriptTsTypeGetClass(RTSCRIPTTSTYPE hScriptTsType);
850
851
852	/**
853	* Returns the identifier of the given type handle.
854	*
855	* @returns Pointer to the identifier of the given type handle.
856	* @param hScriptTsType Type system type handle.
857	*/
858	RTDECL(const char *) RTScriptTsTypeGetIdentifier(RTSCRIPTTSTYPE hScriptTsType);
859
860
861	/**
862	* Returns the storage size of the given type in bits.
863	*
864	* @returns Size of the type in bits described by the given handle.
865	* @param hScriptTsType Type system type handle.
866	*/
867	RTDECL(size_t) RTScriptTsTypeGetBitCount(RTSCRIPTTSTYPE hScriptTsType);
868
869
870	/**
871	* Returns the necessary alignment of the given type in bits.
872	*
873	* @returns Alignmebt of the type in bits described by the given handle.
874	* @param hScriptTsType Type system type handle.
875	*/
876	RTDECL(size_t) RTScriptTsTypeGetAlignmentBitCount(RTSCRIPTTSTYPE hScriptTsType);
877
878
879	/**
880	* Return the native type for the given native type.
881	*
882	* @returns Native type enum.
883	* @param hScriptTsType Type system type handle.
884	*/
885	RTDECL(RTSCRIPTNATIVETYPE) RTScriptTsTypeNativeGetType(RTSCRIPTTSTYPE hScriptTsType);
886
887
888	/**
889	* Return the number of elements for the given array type.
890	*
891	* @returns Number of elements.
892	* @param hScriptTsType Type system type handle.
893	*/
894	RTDECL(uint32_t) RTScriptTsTypeArrayGetElemCount(RTSCRIPTTSTYPE hScriptTsType);
895
896
897	/**
898	* Return the type handle of element type for the given array type.
899	*
900	* @returns Number of elements.
901	* @param hScriptTsType Type system type handle.
902	*/
903	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeArrayGetElemType(RTSCRIPTTSTYPE hScriptTsType);
904
905
906	/**
907	* Returns whether the given union/struct type is packed.
908	*
909	* @returns Number of elements.
910	* @param hScriptTsType Type system type handle.
911	*/
912	RTDECL(bool) RTScriptTsTypeStructUnionGetPacked(RTSCRIPTTSTYPE hScriptTsType);
913
914	RTDECL(uint32_t) RTScriptTsTypeStructUnionGetMemberCount(RTSCRIPTTSTYPE hScriptTsType);
915
916	RTDECL(int) RTScriptTsTypeStructUnionQueryMember(RTSCRIPTTSTYPE hScriptTsType, uint32_t idxMember, uint32_t *poffMember,
917	uint32_t *pcMemberBits, PRTSCRIPTTSTYPE phScriptTsTypeMember);
918
919	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeFunctionGetRetType(RTSCRIPTTSTYPE hScriptTsType);
920
921	RTDECL(uint32_t) RTScriptTsTypeFunctionGetTypedArgCount(RTSCRIPTTSTYPE hScriptTsType);
922
923	RTDECL(bool) RTScriptTsTypeFunctionUsesVarArgs(RTSCRIPTTSTYPE hScriptTsType);
924
925	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeFunctionGetArgType(RTSCRIPTTSTYPE hScriptTsType, uint32_t idxArg);
926
927	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypePointerGetRefType(RTSCRIPTTSTYPE hScriptTsType);
928
929	RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeAliasGetAliasedType(RTSCRIPTTSTYPE hScriptTsType);
930
931	RTDECL(bool) RTScriptTsTypeEquals(RTSCRIPTTSTYPE hScriptTsType1, RTSCRIPTTSTYPE hScriptTsType2);
932
933	RTDECL(bool) RTScriptTsTypeEqualsByOneName(RTSCRIPTTS hScriptTs, const char *pszType1, RTSCRIPTTSTYPE hScriptTsType2);
934
935	RTDECL(bool) RTScriptTsTypeEqualsByTwoNames(RTSCRIPTTS hScriptTs, const char pszType1, const char pszType2);
936
937	/** @} */
938
939
940
941	/** @defgroup grp_rt_script_ps Scripting program state API
942	*
943	* @{
944	*/
945
946	/** Opaque program state handle. */
947	typedef struct RTSCRIPTPSINT *RTSCRIPTPS;
948	/** Pointer to a program state handle. */
949	typedef RTSCRIPTPS *PRTSCRIPTPS;
950
951	RTDECL(int) RTScriptPsCreate(PRTSCRIPTPS phScriptPs, const char *pszId);
952
953	RTDECL(uint32_t) RTScriptPsRetain(RTSCRIPTPS hScriptPs);
954
955	RTDECL(uint32_t) RTScriptPsRelease(RTSCRIPTPS hScriptPs);
956
957	RTDECL(int) RTScriptPsDump(RTSCRIPTPS hScriptPs);
958
959	RTDECL(int) RTScriptPsBuildFromAst(RTSCRIPTPS hScriptPs, PRTSCRIPTASTCOMPILEUNIT pAstCompileUnit);
960
961	RTDECL(int) RTScriptPsCheckConsistency(RTSCRIPTPS hScriptPs);
962
963	/** @} */
964
965
966	/** @defgroup grp_rt_script_parse Scripting parsing API
967	*
968	* @{
969	*/
970
971	/**
972	* Creates a program state from the given pascal input source.
973	*
974	* @returns IPRT status code.
975	* @param phScriptPs Where to store the handle to the program state on success.
976	* @param pszId The program state ID.
977	* @param pszSrc The input to parse.
978	* @param pErrInfo Where to store error information, optional.
979	*/
980	RTDECL(int) RTScriptParsePascalFromString(PRTSCRIPTPS phScriptPs, const char pszId, const char pszSrc,
981	PRTERRINFO pErrInfo);
982
983	/** @} */
984
985
986	/** @defgroup grp_rt_script_vm Scripting bytecode VM API.
987	*
988	* @{
989	*/
990
991	/**
992	* Data value (for return values and arguments).
993	*/
994	typedef struct RTSCRIPTVMVAL
995	{
996	/** The value type. */
997	RTSCRIPTNATIVETYPE enmType;
998	/** Value, dependent on type. */
999	union
1000	{
1001	int8_t i8;
1002	uint8_t u8;
1003	int16_t i16;
1004	uint16_t u16;
1005	int32_t i32;
1006	uint32_t u32;
1007	int64_t i64;
1008	uint64_t u64;
1009	RTFLOAT64U r64;
1010	} u;
1011	} RTSCRIPTVMVAL;
1012	/** Pointer to a VM value. */
1013	typedef RTSCRIPTVMVAL *PRTSCRIPTVMVAL;
1014	/** Pointer to a const value. */
1015	typedef const RTSCRIPTVMVAL *PCRTSCRIPTVMVAL;
1016
1017	/** Opaque VM state handle. */
1018	typedef struct RTSCRIPTVMINT *RTSCRIPTVM;
1019	/** Pointer to a VM state handle. */
1020	typedef RTSCRIPTVM *PRTSCRIPTVM;
1021	/** Opaque VM execution context handle. */
1022	typedef struct RTSCRIPTVMCTXINT *RTSCRIPTVMCTX;
1023	/** Pointer to an opaque VM execution context handle. */
1024	typedef RTSCRIPTVMCTX *PRTSCRIPTVMCTX;
1025
1026	/**
1027	* Creates a new script VM.
1028	*
1029	* @returns IPRT status code.
1030	* @param phScriptVm Where to store the VM handle on success.
1031	*/
1032	RTDECL(int) RTScriptVmCreate(PRTSCRIPTVM phScriptVm);
1033
1034
1035	/**
1036	* Retains the VM reference.
1037	*
1038	* @returns New reference count.
1039	* @param hScriptVm The VM handle to retain.
1040	*/
1041	RTDECL(uint32_t) RTScriptVmRetain(RTSCRIPTVM hScriptVm);
1042
1043
1044	/**
1045	* Releases the VM reference.
1046	*
1047	* @returns New reference count, on 0 the VM is destroyed.
1048	* @param hScriptVm The VM handle to release.
1049	*/
1050	RTDECL(uint32_t) RTScriptVmRelease(RTSCRIPTVM hScriptVm);
1051
1052
1053	/**
1054	* Adds the given program state to the VM making it available for execution.
1055	*
1056	* @returns IPRT status code.
1057	* @param hScriptVm The VM handle.
1058	* @param hScriptPs The program state to add.
1059	* @param pErrInfo Where to store error information on failure.
1060	*/
1061	RTDECL(int) RTScriptVmAddPs(RTSCRIPTVM hScriptVm, RTSCRIPTPS hScriptPs, PRTERRINFO pErrInfo);
1062
1063
1064	/**
1065	* Creates a new execution context for running code in the VM.
1066	*
1067	* @returns IPRT status code.
1068	* @param hScriptVm The VM handle.
1069	* @param phScriptVmCtx Where to store the execution context handle on success.
1070	* @param cbStack Size of the stack in bytes, 0 if unlimited.
1071	*/
1072	RTDECL(int) RTScriptVmExecCtxCreate(RTSCRIPTVM hScriptVm, PRTSCRIPTVMCTX phScriptVmCtx, size_t cbStack);
1073
1074
1075	/**
1076	* Retains the VM execution context reference.
1077	*
1078	* @returns New reference count.
1079	* @param hScriptVmCtx The VM execution context handle to retain.
1080	*/
1081	RTDECL(uint32_t) RTScriptVmExecCtxRetain(RTSCRIPTVMCTX hScriptVmCtx);
1082
1083
1084	/**
1085	* Releases a VM execution context reference.
1086	*
1087	* @returns New reference count, on 0 the execution context is destroyed.
1088	* @param hScriptVmCtx The VM execution context handle to release.
1089	*/
1090	RTDECL(uint32_t) RTScriptVmExecCtxRelease(RTSCRIPTVMCTX hScriptVmCtx);
1091
1092
1093	/**
1094	* Sets the initial state for execution.
1095	*
1096	* @returns IPRT status code.
1097	* @param hScriptVmCtx The VM execution context handle.
1098	* @param pszFn The method to execute, NULL for the main program if existing.
1099	* @param paArgs Arguments to supply to the executed method.
1100	* @param cArgs Number of arguments supplied.
1101	*/
1102	RTDECL(int) RTScriptVmExecCtxInit(RTSCRIPTVMCTX hScriptVmCtx, const char *pszFn,
1103	PCRTSCRIPTVMVAL paArgs, uint32_t cArgs);
1104
1105
1106	/**
1107	* Continues executing the current state.
1108	*
1109	* @returns IPRT status code.
1110	* @param hScriptVmCtx The VM execution context handle.
1111	* @param msTimeout Maximum amount of time to execute, RT_INDEFINITE_WAIT
1112	* for an unrestricted amount of time.
1113	* @param pRetVal Where to store the return value on success, optional.
1114	*/
1115	RTDECL(int) RTScriptVmExecCtxRun(RTSCRIPTVMCTX hScriptVmCtx, RTMSINTERVAL msTimeout,
1116	PRTSCRIPTVMVAL pRetVal);
1117
1118
1119	/**
1120	* Interrupts the current execution.
1121	*
1122	* @returns IPRT status code.
1123	* @param hScriptVmCtx The VM execution context handle.
1124	*/
1125	RTDECL(int) RTScriptVmExecCtxInterrupt(RTSCRIPTVMCTX hScriptVmCtx);
1126
1127
1128
1129	/** @} */
1130	#endif
1131
1132	/** @} */
1133
1134	RT_C_DECLS_END
1135
1136	#endif /* !IPRT_INCLUDED_script_h */
1137

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

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

Download in other formats: