script.h

最後變更在這個檔案是 108280,由 vboxsync 提交於 3 週前
Runtime/RTScriptLex*: Implement support for optionally returning parsed comments (single and multi line) as tokens when enabled in the lexer config, bugref:10321
屬性 svn:eol-style 設為 `native` 屬性 svn:keywords 設為 `Author Date Id Revision`
檔案大小: 41.1 KB

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

注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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

以其他格式下載: