horok-backports/virtualbox
1
0
Fork 0
Code Activity
virtualbox/include/iprt/script.h
Daniel Baumann 6b15cd43cb
Merging upstream version 7.1.10-dfsg. 
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
2025-06-24 21:15:14 +02:00

1171 lines
41 KiB
C
Raw Blame History

/* $Id: script.h $ */
/** @file
* IPRT - RTScript, Script language support in IPRT.
*/
/*
* Copyright (C) 2024 Oracle and/or its affiliates.
*
* This file is part of VirtualBox base platform packages, as
* available from https://www.virtualbox.org.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, in version 3 of the
* License.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses>.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
* in the VirtualBox distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
*/
#ifndef IPRT_INCLUDED_script_h
#define IPRT_INCLUDED_script_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
#include <iprt/cdefs.h>
#include <iprt/types.h>
#include <iprt/strcache.h>
#include <iprt/scriptbase.h>
//#include <iprt/scriptast.h>
RT_C_DECLS_BEGIN
/** @defgroup grp_rt_script RTScript - IPRT scripting language support
* @ingroup grp_rt
*
* The scripting APIs provide a simple framework to implement simple scripting
* languages. They are meant to provide building blocks which can be put together
* in an easy way to add scripting capablities to the software using it.
*
* The API is oriented on the traditional compiler pipeline providing sub APIs for the following
* parts:
* - RTScriptLex*: For building a lexer to generate tokens from an input character stream.
* - RTScriptTs*: A simple type system providing a way to get type storage sizes and alignments.
* - RTScriptPs*: For maintaining the required state for the complete script and provide
* a way to check for correct typing.
* - RTScriptAst*: Providing helpers and definitions for the abstract syntax tree.
* - RTScriptParse*: For building parsers which generate ASTs.
* - RTScriptVm*: Providing a simple bytecode VM which takes a checked program state
* converting it into bytecode and executing it.
*
* Note: Only RTScriptLex is partially implemented right now!
* @{
*/
/** @defgroup grp_rt_script_lex Scripting lexer support
*
* This part provides support for lexing input and generating tokens which can be
* digested by a parser.
*
* @{
*/
/**
* The lexer token type.
*/
typedef enum RTSCRIPTLEXTOKTYPE
{
/** Invalid type. */
RTSCRIPTLEXTOKTYPE_INVALID = 0,
/** Identifier. */
RTSCRIPTLEXTOKTYPE_IDENTIFIER,
/** Numerical constant. */
RTSCRIPTLEXTOKTYPE_NUMBER,
/** String literal. */
RTSCRIPTLEXTOKTYPE_STRINGLIT,
/** An operator (unary or binary). */
RTSCRIPTLEXTOKTYPE_OPERATOR,
/** Some predefined keyword. */
RTSCRIPTLEXTOKTYPE_KEYWORD,
/** Some punctuator. */
RTSCRIPTLEXTOKTYPE_PUNCTUATOR,
/** A single line comment. */
RTSCRIPTLEXTOKTYPE_COMMENT_SINGLE_LINE,
/** A multi line comment. */
RTSCRIPTLEXTOKTYPE_COMMENT_MULTI_LINE,
/** Special error token, conveying an error message from the lexer. */
RTSCRIPTLEXTOKTYPE_ERROR,
/** End of stream token. */
RTSCRIPTLEXTOKTYPE_EOS
} RTSCRIPTLEXTOKTYPE;
/** Pointer to a lexer token type. */
typedef RTSCRIPTLEXTOKTYPE *PRTSCRIPTLEXTOKTYPE;
/**
* Lexer token number type.
*/
typedef enum RTSCRIPTLEXTOKNUMTYPE
{
/** Invalid token number type. */
RTSCRIPTLEXTOKNUMTYPE_INVALID = 0,
/** Natural number (all positive upwards including 0). */
RTSCRIPTLEXTOKNUMTYPE_NATURAL,
/** Integers (natural numbers and their additive inverse). */
RTSCRIPTLEXTOKNUMTYPE_INTEGER,
/** Real numbers. */
RTSCRIPTLEXTOKNUMTYPE_REAL
} RTSCRIPTLEXTOKNUMTYPE;
/**
* Lexer exact token match descriptor.
*/
typedef struct RTSCRIPTLEXTOKMATCH
{
/** Matching string. */
const char *pszMatch;
/** Size if of the matching string in characters excluding the zero terminator. */
size_t cchMatch;
/** Resulting token type. */
RTSCRIPTLEXTOKTYPE enmTokType;
/** Whether the token can be the beginning of an identifer
* and to check whether the identifer has a longer match. */
bool fMaybeIdentifier;
/** User defined value when the token matched. */
uint64_t u64Val;
} RTSCRIPTLEXTOKMATCH;
/** Pointer to a lexer exact token match descriptor. */
typedef RTSCRIPTLEXTOKMATCH *PRTSCRIPTLEXTOKMATCH;
/** Pointer to a const lexer exact token match descriptor. */
typedef const RTSCRIPTLEXTOKMATCH *PCRTSCRIPTLEXTOKMATCH;
/**
* Lexer token.
*/
typedef struct RTSCRIPTLEXTOKEN
{
/** Token type. */
RTSCRIPTLEXTOKTYPE enmType;
/** Position in the source buffer where the token started matching. */
RTSCRIPTPOS PosStart;
/** Position in the source buffer where the token ended matching. */
RTSCRIPTPOS PosEnd;
/** Data based on the token type. */
union
{
/** Identifier. */
struct
{
/** Pointer to the start of the identifier. */
const char *pszIde;
/** Number of characters for the identifier excluding the null terminator. */
size_t cchIde;
} Id;
/** Numerical constant. */
struct
{
/** Flag whether the number is negative. */
RTSCRIPTLEXTOKNUMTYPE enmType;
/** Optimal storage size for the value (1, 2, 4 or 8 bytes). */
uint32_t cBytes;
/** Type dependent data. */
union
{
/** For natural numbers. */
uint64_t u64;
/** For integer numbers. */
int64_t i64;
/** Real numbers. */
RTFLOAT64U r64;
} Type;
} Number;
/** String literal */
struct
{
/** Pointer to the start of the string constant. */
const char *pszString;
/** Number of characters of the string, including the null terminator. */
size_t cchString;
} StringLit;
/** Operator */
struct
{
/** Pointer to the operator descriptor. */
PCRTSCRIPTLEXTOKMATCH pOp;
} Operator;
/** Keyword. */
struct
{
/** Pointer to the keyword descriptor. */
PCRTSCRIPTLEXTOKMATCH pKeyword;
} Keyword;
/** Punctuator. */
struct
{
/** Pointer to the matched punctuator descriptor. */
PCRTSCRIPTLEXTOKMATCH pPunctuator;
} Punctuator;
/** Comment */
struct
{
/** Pointer to the start of the comment (including the symbols starting the comment). */
const char *pszComment;
/** Number of characters of the comment, including the null terminator. */
size_t cchComment;
} Comment;
/** Error. */
struct
{
/** Pointer to the internal error info structure, readonly. */
PCRTERRINFO pErr;
} Error;
} Type;
} RTSCRIPTLEXTOKEN;
/** Pointer to a script token. */
typedef RTSCRIPTLEXTOKEN *PRTSCRIPTLEXTOKEN;
/** Pointer to a const script token. */
typedef const RTSCRIPTLEXTOKEN *PCRTSCRIPTLEXTOKEN;
/** Opaque lexer handle. */
typedef struct RTSCRIPTLEXINT *RTSCRIPTLEX;
/** Pointer to a lexer handle. */
typedef RTSCRIPTLEX *PRTSCRIPTLEX;
/**
* Production rule callback.
*
* @returns IPRT status code.
* @param hScriptLex The lexer handle.
* @param ch The character which caused the production rule to be called.
* @param pToken The token to fill in.
* @param pvUser Opaque user data.
*/
typedef DECLCALLBACKTYPE(int, FNRTSCRIPTLEXPROD,(RTSCRIPTLEX hScriptLex, char ch, PRTSCRIPTLEXTOKEN pToken, void *pvUser));
/** Pointer to a production rule callback. */
typedef FNRTSCRIPTLEXPROD *PFNRTSCRIPTLEXPROD;
/**
* Lexer rule.
*/
typedef struct RTSCRIPTLEXRULE
{
/** First character for starting the production rule. */
char chStart;
/** Last character for starting the production rule. */
char chEnd;
/** Flags for this rule. */
uint32_t fFlags;
/** The producer to call. */
PFNRTSCRIPTLEXPROD pfnProd;
/** Opaque user data passed to the production rule. */
void *pvUser;
} RTSCRIPTLEXRULE;
/** Pointer to a lexer rule. */
typedef RTSCRIPTLEXRULE *PRTSCRIPTLEXRULE;
/** Pointer to a const lexer rule. */
typedef const RTSCRIPTLEXRULE *PCRTSCRIPTLEXRULE;
/** Default rule flags. */
#define RTSCRIPT_LEX_RULE_DEFAULT 0
/** Consume the first character before calling the producer. */
#define RTSCRIPT_LEX_RULE_CONSUME RT_BIT(0)
/**
* Lexer config.
*/
typedef struct RTSCRIPTLEXCFG
{
/** Config name. */
const char *pszName;
/** Config description. */
const char *pszDesc;
/** Flags for the lexer. */
uint32_t fFlags;
/** Set of whitespace characters, excluding newline. NULL indicates default characters.
* " " | "\t". */
const char *pszWhitespace;
/** Set of newline characters, NULL indicates
* default characters including "\n" | "\r\n". */
const char **papszNewline;
/** Start for a multiline comment, NULL indicates no support for multi line comments. */
const char **papszCommentMultiStart;
/** End for a multiline comment, NULL indicates no support for multi line comments. */
const char **papszCommentMultiEnd;
/** Start of single line comment, NULL indicates no support for single line comments. */
const char **papszCommentSingleStart;
/** Exact token match descriptor table, optional. Must be terminated with a NULL entry. */
PCRTSCRIPTLEXTOKMATCH paTokMatches;
/** Pointer to the rule table, optional. */
PCRTSCRIPTLEXRULE paRules;
/** The default rule to call when no other rule applies, optional. */
PFNRTSCRIPTLEXPROD pfnProdDef;
/** Opaque user data for default production rule. */
void *pvProdDefUser;
} RTSCRIPTLEXCFG;
/** Pointer to a lexer config. */
typedef RTSCRIPTLEXCFG *PRTSCRIPTLEXCFG;
/** Pointer to a const lexer config. */
typedef const RTSCRIPTLEXCFG *PCRTSCRIPTLEXCFG;
/** Default lexer config flags. */
#define RTSCRIPT_LEX_CFG_F_DEFAULT 0
/** Case insensitive lexing, keywords and so on must be used lowercase to match
* as the lexer will convert everything to lowercase internally. */
#define RTSCRIPT_LEX_CFG_F_CASE_INSENSITIVE_LOWER RT_BIT(0)
/** Case insensitive lexing, keywords and so on must be used uppercase to match
* as the lexer will convert everything to uppercase internally. */
#define RTSCRIPT_LEX_CFG_F_CASE_INSENSITIVE_UPPER RT_BIT(1)
/** Comments are not skipped but passed back as tokens. */
#define RTSCRIPT_LEX_CFG_F_COMMENTS_AS_TOKENS RT_BIT(2)
/** Default character conversions (converting to lower case when the case insensitive flag is set). */
#define RTSCRIPT_LEX_CONV_F_DEFAULT 0
/** Don't apply any conversion but just return the character as read from the input. */
#define RTSCRIPT_LEX_CONV_F_NOTHING RT_BIT(0)
/**
* Lexer reader callback.
*
* @returns IPRT status code.
* @retval VINF_EOF if the end of the input was reached.
* @param hScriptLex The lexer handle.
* @param offBuf Offset from the start to read from.
* @param pchBuf Where to store the read data.
* @param cchBuf How much to read at maxmimum.
* @param pcchRead Where to store the amount of bytes read.
* @param pvUser Opaque user data passed when creating the lexer.
*/
typedef DECLCALLBACKTYPE(int, FNRTSCRIPTLEXRDR, (RTSCRIPTLEX hScriptLex, size_t offBuf, char *pchBuf, size_t cchBuf,
size_t *pcchRead, void *pvUser));
/** Pointer to a lexer reader callback. */
typedef FNRTSCRIPTLEXRDR *PFNRTSCRIPTLEXRDR;
/**
* Lexer destructor callback.
*
* @param hScriptLex The lexer handle.
* @param pvUser Opaque user data passed when creating the lexer.
*/
typedef DECLCALLBACKTYPE(void, FNRTSCRIPTLEXDTOR,(RTSCRIPTLEX hScriptLex, void *pvUser));
/** Pointer to a lexer destructor callback. */
typedef FNRTSCRIPTLEXDTOR *PFNRTSCRIPTLEXDTOR;
/**
* Creates a new lexer with the given reader and config.
*
* @returns IPRT status code.
* @param phScriptLex Where to store the handle to the lexer on success.
* @param pfnReader The read to use for reading chunks of the input.
* @param pfnDtor Destructor callback to call when the lexer is destroyed.
* @param pvUser Opaque user data passed to reader.
* @param cchBuf Buffer hint, if 0 a default is chosen.
* @param phStrCacheId Where to store the pointer to the string cache containing all
* scanned identifiers on success, optional.
* If not NULL the string cache must be freed by the caller when not used
* anymore.
* @param phStrCacheStringLit Where to store the pointer to the string cache containing all
* scanned string literals on success, optional.
* If not NULL the string cache must be freed by the caller when not used
* anymore.
* @param phStrCacheComments Where to store the pointer to the string cache containing all
* comments on success when RTSCRIPT_LEX_CFG_F_COMMENTS_AS_TOKENS
* is given, optional.
* If not NULL the string cache must be freed by the caller when not used
* anymore.
* @param pCfg The lexer config to use for identifying the different tokens.
*/
RTDECL(int) RTScriptLexCreateFromReader(PRTSCRIPTLEX phScriptLex, PFNRTSCRIPTLEXRDR pfnReader,
PFNRTSCRIPTLEXDTOR pfnDtor, void *pvUser,
size_t cchBuf, PRTSTRCACHE phStrCacheId, PRTSTRCACHE phStrCacheStringLit,
PRTSTRCACHE phStrCacheComments, PCRTSCRIPTLEXCFG pCfg);
/**
* Creates a new lexer for the given input string and config.
*
* @returns IPRT status code.
* @param phScriptLex Where to store the handle to the lexer on success.
* @param pszSrc The input string to scan.
* @param phStrCacheId Where to store the pointer to the string cache containing all
* scanned identifiers on success, optional.
* If not NULL the string cache must be freed by the caller when not used
* anymore.
* @param phStrCacheStringLit Where to store the pointer to the string cache containing all
* scanned string literals on success, optional.
* If not NULL the string cache must be freed by the caller when not used
* anymore.
* @param phStrCacheComments Where to store the pointer to the string cache containing all
* comments on success when RTSCRIPT_LEX_CFG_F_COMMENTS_AS_TOKENS
* is given, optional.
* If not NULL the string cache must be freed by the caller when not used
* anymore.
* @param pCfg The lexer config to use for identifying the different tokens.
*/
RTDECL(int) RTScriptLexCreateFromString(PRTSCRIPTLEX phScriptLex, const char *pszSrc, PRTSTRCACHE phStrCacheId,
PRTSTRCACHE phStrCacheStringLit, PRTSTRCACHE phStrCacheComments,
PCRTSCRIPTLEXCFG pCfg);
/**
* Creates a new lexer from the given filename and config.
*
* @returns IPRT status code.
* @param phScriptLex Where to store the handle to the lexer on success.
* @param pszFilename The filename of the input.
* @param phStrCacheId Where to store the pointer to the string cache containing all
* scanned identifiers on success, optional.
* If not NULL the string cache must be freed by the caller when not used
* anymore.
* @param phStrCacheStringLit Where to store the pointer to the string cache containing all
* scanned string literals on success, optional.
* If not NULL the string cache must be freed by the caller when not used
* anymore.
* @param phStrCacheComments Where to store the pointer to the string cache containing all
* comments on success when RTSCRIPT_LEX_CFG_F_COMMENTS_AS_TOKENS
* is given, optional.
* If not NULL the string cache must be freed by the caller when not used
* anymore.
* @param pCfg The lexer config to use for identifying the different tokens.
*/
RTDECL(int) RTScriptLexCreateFromFile(PRTSCRIPTLEX phScriptLex, const char *pszFilename, PRTSTRCACHE phStrCacheId,
PRTSTRCACHE phStrCacheStringLit, PRTSTRCACHE phStrCacheComments,
PCRTSCRIPTLEXCFG pCfg);
/**
* Destroys the given lexer handle.
*
* @param hScriptLex The lexer handle to destroy.
*/
RTDECL(void) RTScriptLexDestroy(RTSCRIPTLEX hScriptLex);
/**
* Queries the current identified token.
*
* @returns IPRT status code.
* @param hScriptLex The lexer handle.
* @param ppToken Where to store the pointer to the token on success.
*/
RTDECL(int) RTScriptLexQueryToken(RTSCRIPTLEX hScriptLex, PCRTSCRIPTLEXTOKEN *ppToken);
/**
* Returns the current token type.
*
* @returns Current token type.
* @param hScriptLex The lexer handle.
*/
RTDECL(RTSCRIPTLEXTOKTYPE) RTScriptLexGetTokenType(RTSCRIPTLEX hScriptLex);
/**
* Returns the next token type.
*
* @returns Next token type.
* @param hScriptLex The lexer handle.
*/
RTDECL(RTSCRIPTLEXTOKTYPE) RTScriptLexPeekNextTokenType(RTSCRIPTLEX hScriptLex);
/**
* Consumes the current token and moves to the next one.
*
* @returns Pointer to the next token.
* @param hScriptLex The lexer handle.
*/
RTDECL(PCRTSCRIPTLEXTOKEN) RTScriptLexConsumeToken(RTSCRIPTLEX hScriptLex);
/**
* Consumes the current input characters and moves to the next one.
*
* @returns Returns the next character in the input stream.
* @retval 0 indicates end of stream.
* @param hScriptLex The lexer handle.
*/
RTDECL(char) RTScriptLexConsumeCh(RTSCRIPTLEX hScriptLex);
/**
* Consumes the current input characters and moves to the next one - extended version.
*
* @returns Returns the next character in the input stream.
* @retval 0 indicates end of stream.
* @param hScriptLex The lexer handle.
* @param fFlags Flags controlling some basic conversions of characters,
* combination of RTSCRIPT_LEX_CONV_F_*.
*/
RTDECL(char) RTScriptLexConsumeChEx(RTSCRIPTLEX hScriptLex, uint32_t fFlags);
/**
* Returns the character at the curren input position.
*
* @returns Character at the current position in the input
* @retval 0 indicates end of stream.
* @param hScriptLex The lexer handle.
*/
RTDECL(char) RTScriptLexGetCh(RTSCRIPTLEX hScriptLex);
/**
* Returns the character at the curren input position - extended version.
*
* @returns Character at the current position in the input
* @retval 0 indicates end of stream.
* @param hScriptLex The lexer handle.
* @param fFlags Flags controlling some basic conversions of characters,
* combination of RTSCRIPT_LEX_CONV_F_*.
*/
RTDECL(char) RTScriptLexGetChEx(RTSCRIPTLEX hScriptLex, uint32_t fFlags);
/**
* Returns the current character in the input without moving to the next one.
*
* @returns Returns the current character.
* @retval 0 indicates end of stream.
* @param hScriptLex The lexer handle.
* @param idx Offset to peek at, 0 behaves like rtScriptLexGetCh().
*/
RTDECL(char) RTScriptLexPeekCh(RTSCRIPTLEX hScriptLex, unsigned idx);
/**
* Returns the current character in the input without moving to the next one - extended version.
*
* @returns Returns the current character.
* @retval 0 indicates end of stream.
* @param hScriptLex The lexer handle.
* @param idx Offset to peek at, 0 behaves like rtScriptLexGetCh().
* @param fFlags Flags controlling some basic conversions of characters,
* combination of RTSCRIPT_LEX_CONV_F_*.
*/
RTDECL(char) RTScriptLexPeekChEx(RTSCRIPTLEX hScriptLex, unsigned idx, uint32_t fFlags);
/**
* Skips everything declared as whitespace, including comments and newlines.
*
* @param hScriptLex The lexer handle.
*/
RTDECL(void) RTScriptLexSkipWhitespace(RTSCRIPTLEX hScriptLex);
/** @defgroup grp_rt_script_lex_builtin Builtin helpers to scan numbers, string literals, ...
* @{ */
/**
* Produces a numerical constant token from the number starting at the current position in the
* input stream on success or an appropriate error token.
*
* @returns IPRT status code.
* @param hScriptLex The lexer handle.
* @param uBase The base to parse the number in.
* @param fAllowReal Flag whether to allow parsing real numbers using the following
* layout [+-][0-9]*[.][e][+-][0-9]*.
* @param pTok The token to fill in.
*/
RTDECL(int) RTScriptLexScanNumber(RTSCRIPTLEX hScriptLex, uint8_t uBase, bool fAllowReal,
PRTSCRIPTLEXTOKEN pTok);
/**
* Production rule to create an identifier token with the given set of allowed characters.
*
* @returns IPRT status code.
* @param hScriptLex The lexer handle.
* @param ch The first character of the identifier.
* @param pTok The token to fill in.
* @param pvUser Opaque user data, must point to the allowed set of characters for identifiers as a
* zero terminated string. NULL will revert to a default set of characters including
* [_a-zA-Z0-9]*
*
* @note This version will allow a maximum identifier length of 512 characters (should be plenty).
* More characters will produce an error token. Must be used with the RTSCRIPT_LEX_RULE_CONSUME
* flag for the first character.
*/
RTDECL(int) RTScriptLexScanIdentifier(RTSCRIPTLEX hScriptLex, char ch, PRTSCRIPTLEXTOKEN pTok, void *pvUser);
/**
* Production rule to scan string literals conforming to the C standard.
*
* @returns IPRT status code.
* @param hScriptLex The lexer handle.
* @param ch The character starting the rule, unused.
* @param pTok The token to fill in.
* @param pvUser Opaque user data, unused.
*
* @note The RTSCRIPT_LEX_RULE_CONSUME must be used (or omitted) such that the current character
* in the input denotes the start of the string literal. The resulting literal is added to the respective
* cache on success.
*/
RTDECL(int) RTScriptLexScanStringLiteralC(RTSCRIPTLEX hScriptLex, char ch, PRTSCRIPTLEXTOKEN pTok, void *pvUser);
/**
* Production rule to scan string literals for pascal like languages, without support for escape
* sequences and where a ' is denoted by ''.
*
* @returns IPRT status code.
* @param hScriptLex The lexer handle.
* @param ch The character starting the rule, unused.
* @param pTok The token to fill in.
* @param pvUser Opaque user data, unused.
*
* @note The RTSCRIPT_LEX_RULE_CONSUME must be used (or omitted) such that the current character
* in the input denotes the start of the string literal. The resulting literal is added to the respective
* cache on success.
*/
RTDECL(int) RTScriptLexScanStringLiteralPascal(RTSCRIPTLEX hScriptLex, char ch, PRTSCRIPTLEXTOKEN pTok, void *pvUser);
/**
* Produces an error token with the given message, used for custom lexer rule implementations.
*
* @returns IPRT status code.
* @param hScriptLex The lexer handle.
* @param pTok The token to fill.
* @param rc The status code to use in the message.
* @param pszMsg The format string for the error message.
* @param ... Arguments to the format string.
*/
RTDECL(int) RTScriptLexProduceTokError(RTSCRIPTLEX hScriptLex, PRTSCRIPTLEXTOKEN pTok, int rc, const char *pszMsg, ...);
/**
* Produces an identifier token with the given identifier, used for custom lexer rule implementations.
*
* @returns IPRT status code.
* @param hScriptLex The lexer handle.
* @param pTok The token to fill.
* @param pszIde The identifier to add.
* @param cchIde Number of characters in the identifier.
*/
RTDECL(int) RTScriptLexProduceTokIde(RTSCRIPTLEX hScriptLex, PRTSCRIPTLEXTOKEN pTok, const char *pszIde, size_t cchIde);
/** @} */
/** @} */
#if 0 /* Later, maybe */
/** @defgroup grp_rt_script_typesys Scripting language type system API.
*
* @{
*/
/**
* Type class.
*/
typedef enum RTSCRIPTTSTYPECLASS
{
/** Invalid. */
RTSCRIPTTSTYPECLASS_INVALID = 0,
/** A native type. */
RTSCRIPTTSTYPECLASS_NATIVE,
/** Array type. */
RTSCRIPTTSTYPECLASS_ARRAY,
/** Struct type. */
RTSCRIPTTSTYPECLASS_STRUCT,
/** Union type. */
RTSCRIPTTSTYPECLASS_UNION,
/** Function type. */
RTSCRIPTTSTYPECLASS_FUNCTION,
/** Pointer type. */
RTSCRIPTTSTYPECLASS_POINTER,
/** Alias for another type. */
RTSCRIPTTSTYPECLASS_ALIAS
} RTSCRIPTTSTYPECLASS;
/** Pointer to a type descriptor. */
typedef struct RTSCRIPTTSTYPDESC *PRTSCRIPTTSTYPDESC;
/** Pointer to a const type descriptor. */
typedef const RTSCRIPTTSTYPDESC *PCRTSCRIPTTSTYPDESC;
/**
* Type descriptor.
*/
typedef struct RTSCRIPTTSTYPDESC
{
/** Type class */
RTSCRIPTTSTYPECLASS enmClass;
/** Identifier for this type. */
const char *pszIdentifier;
/** Class dependent data. */
union
{
/** Native type. */
struct
{
/** The native type. */
RTSCRIPTNATIVETYPE enmTypeNative;
/** Alignment for the native type in bits - 0 for default alignment. */
uint32_t cBitsAlign;
} Native;
/** Array type. */
struct
{
/** Type identifier. */
const char *pszTypeIde;
/** Number of elements. */
uint32_t cElems;
} Array;
/** Struct/Union type. */
struct
{
/* Flag whether this is packed. */
bool fPacked;
/** Number of members. */
uint32_t cMembers;
/** Pointer to the array of member identifiers for each member. */
const char **papszMember;
/** Pointer to the array of type identifiers for each member. */
const char **papszMemberType;
} UnionStruct;
/** Function type. */
struct
{
/** Return type - NULL for no return type. */
const char *pszTypeRet;
/** Number of typed arguments. */
uint32_t cArgsTyped;
/** Pointer to the array of type identifiers for the arguments. */
const char **papszMember;
/** Flag whether variable arguments are used. */
bool fVarArgs;
} Function;
/** Pointer. */
struct
{
/** The type identifier the pointer references. */
const char *pszTypeIde;
} Pointer;
/** Pointer. */
struct
{
/** The type identifier the alias references. */
const char *pszTypeIde;
} Alias;
} Class;
} RTSCRIPTTSTYPDESC;
/** Opaque type system handle. */
typedef struct RTSCRIPTTSINT *RTSCRIPTTS;
/** Pointer to an opaque type system handle. */
typedef RTSCRIPTTS *PRTSCRIPTTS;
/** Opaque type system type. */
typedef struct RTSCRIPTTSTYPEINT *RTSCRIPTTSTYPE;
/** Pointer to an opaque type system type. */
typedef RTSCRIPTTSTYPE *PRTSCRIPTTSTYPE;
/**
* Create a new empty type system.
*
* @returns IPRT status code.
* @param phScriptTs Where to store the handle to the type system on success.
* @param hScriptTsParent Parent type system to get declarations from. NULL if no parent.
* @param enmPtrType Native pointer type (only unsigned integer types allowed).
* @param cPtrAlignBits The native alignment of a pointer storage location.
*/
RTDECL(int) RTScriptTsCreate(PRTSCRIPTTS phScriptTs, RTSCRIPTTS hScriptTsParent,
RTSCRIPTNATIVETYPE enmPtrType, uint32_t cPtrAlignBits);
/**
* Retains a reference to the given type system.
*
* @returns New reference count.
* @param hScriptTs Type system handle.
*/
RTDECL(uint32_t) RTScriptTsRetain(RTSCRIPTTS hScriptTs);
/**
* Releases a reference to the given type system.
*
* @returns New reference count, on 0 the type system is destroyed.
* @param hScriptTs Type system handle.
*/
RTDECL(uint32_t) RTScriptTsRelease(RTSCRIPTTS hScriptTs);
/**
* Dumps the content of the type system.
*
* @returns IPRT status code.
* @param hScriptTs Type system handle.
*/
RTDECL(int) RTScriptTsDump(RTSCRIPTTS hScriptTs);
/**
* Add several types to the type system from the given descriptor array.
*
* @returns IPRT status code.
* @param hScriptTs Type system handle.
* @param paTypeDescs Pointer to the array of type descriptors.
* @param cTypeDescs Number of entries in the array.
*/
RTDECL(int) RTScriptTsAdd(RTSCRIPTTS hScriptTs, PCRTSCRIPTTSTYPDESC paTypeDescs,
uint32_t cTypeDescs);
/**
* Removes the given types from the type system.
*
* @returns IPRT status code.
* @param hScriptTs Type system handle.
* @param papszTypes Array of type identifiers to remove. Array terminated
* with a NULL entry.
*/
RTDECL(int) RTScriptTsRemove(RTSCRIPTTS hScriptTs, const char **papszTypes);
/**
* Queries the given type returning the type handle on success.
*
* @returns IPRT status code.
* @retval VERR_NOT_FOUND if the type could not be found.
* @param hScriptTs Type system handle.
* @param pszType The type identifier to look for.
* @param phType Where to store the handle to the type on success.
*/
RTDECL(int) RTScriptTsQueryType(RTSCRIPTTS hScriptTs, const char *pszType,
PRTSCRIPTTSTYPE phType);
/**
* Retains the given type reference.
*
* @returns New reference count.
* @param hScriptTsType Type system type handle.
*/
RTDECL(uint32_t) RTScriptTsTypeRetain(RTSCRIPTTSTYPE hScriptTsType);
/**
* Releases the given type reference.
*
* @returns New reference count.
* @param hScriptTsType Type system type handle.
*/
RTDECL(uint32_t) RTScriptTsTypeRelease(RTSCRIPTTSTYPE hScriptTsType);
/**
* Returns the class of the given type handle.
*
* @returns Type class for the given type handle.
* @param hScriptTsType Type system type handle.
*/
RTDECL(RTSCRIPTTSTYPECLASS) RTScriptTsTypeGetClass(RTSCRIPTTSTYPE hScriptTsType);
/**
* Returns the identifier of the given type handle.
*
* @returns Pointer to the identifier of the given type handle.
* @param hScriptTsType Type system type handle.
*/
RTDECL(const char *) RTScriptTsTypeGetIdentifier(RTSCRIPTTSTYPE hScriptTsType);
/**
* Returns the storage size of the given type in bits.
*
* @returns Size of the type in bits described by the given handle.
* @param hScriptTsType Type system type handle.
*/
RTDECL(size_t) RTScriptTsTypeGetBitCount(RTSCRIPTTSTYPE hScriptTsType);
/**
* Returns the necessary alignment of the given type in bits.
*
* @returns Alignmebt of the type in bits described by the given handle.
* @param hScriptTsType Type system type handle.
*/
RTDECL(size_t) RTScriptTsTypeGetAlignmentBitCount(RTSCRIPTTSTYPE hScriptTsType);
/**
* Return the native type for the given native type.
*
* @returns Native type enum.
* @param hScriptTsType Type system type handle.
*/
RTDECL(RTSCRIPTNATIVETYPE) RTScriptTsTypeNativeGetType(RTSCRIPTTSTYPE hScriptTsType);
/**
* Return the number of elements for the given array type.
*
* @returns Number of elements.
* @param hScriptTsType Type system type handle.
*/
RTDECL(uint32_t) RTScriptTsTypeArrayGetElemCount(RTSCRIPTTSTYPE hScriptTsType);
/**
* Return the type handle of element type for the given array type.
*
* @returns Number of elements.
* @param hScriptTsType Type system type handle.
*/
RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeArrayGetElemType(RTSCRIPTTSTYPE hScriptTsType);
/**
* Returns whether the given union/struct type is packed.
*
* @returns Number of elements.
* @param hScriptTsType Type system type handle.
*/
RTDECL(bool) RTScriptTsTypeStructUnionGetPacked(RTSCRIPTTSTYPE hScriptTsType);
RTDECL(uint32_t) RTScriptTsTypeStructUnionGetMemberCount(RTSCRIPTTSTYPE hScriptTsType);
RTDECL(int) RTScriptTsTypeStructUnionQueryMember(RTSCRIPTTSTYPE hScriptTsType, uint32_t idxMember, uint32_t *poffMember,
uint32_t *pcMemberBits, PRTSCRIPTTSTYPE phScriptTsTypeMember);
RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeFunctionGetRetType(RTSCRIPTTSTYPE hScriptTsType);
RTDECL(uint32_t) RTScriptTsTypeFunctionGetTypedArgCount(RTSCRIPTTSTYPE hScriptTsType);
RTDECL(bool) RTScriptTsTypeFunctionUsesVarArgs(RTSCRIPTTSTYPE hScriptTsType);
RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeFunctionGetArgType(RTSCRIPTTSTYPE hScriptTsType, uint32_t idxArg);
RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypePointerGetRefType(RTSCRIPTTSTYPE hScriptTsType);
RTDECL(RTSCRIPTTSTYPE) RTScriptTsTypeAliasGetAliasedType(RTSCRIPTTSTYPE hScriptTsType);
RTDECL(bool) RTScriptTsTypeEquals(RTSCRIPTTSTYPE hScriptTsType1, RTSCRIPTTSTYPE hScriptTsType2);
RTDECL(bool) RTScriptTsTypeEqualsByOneName(RTSCRIPTTS hScriptTs, const char *pszType1, RTSCRIPTTSTYPE hScriptTsType2);
RTDECL(bool) RTScriptTsTypeEqualsByTwoNames(RTSCRIPTTS hScriptTs, const char *pszType1, const char *pszType2);
/** @} */
/** @defgroup grp_rt_script_ps Scripting program state API
*
* @{
*/
/** Opaque program state handle. */
typedef struct RTSCRIPTPSINT *RTSCRIPTPS;
/** Pointer to a program state handle. */
typedef RTSCRIPTPS *PRTSCRIPTPS;
RTDECL(int) RTScriptPsCreate(PRTSCRIPTPS phScriptPs, const char *pszId);
RTDECL(uint32_t) RTScriptPsRetain(RTSCRIPTPS hScriptPs);
RTDECL(uint32_t) RTScriptPsRelease(RTSCRIPTPS hScriptPs);
RTDECL(int) RTScriptPsDump(RTSCRIPTPS hScriptPs);
RTDECL(int) RTScriptPsBuildFromAst(RTSCRIPTPS hScriptPs, PRTSCRIPTASTCOMPILEUNIT pAstCompileUnit);
RTDECL(int) RTScriptPsCheckConsistency(RTSCRIPTPS hScriptPs);
/** @} */
/** @defgroup grp_rt_script_parse Scripting parsing API
*
* @{
*/
/**
* Creates a program state from the given pascal input source.
*
* @returns IPRT status code.
* @param phScriptPs Where to store the handle to the program state on success.
* @param pszId The program state ID.
* @param pszSrc The input to parse.
* @param pErrInfo Where to store error information, optional.
*/
RTDECL(int) RTScriptParsePascalFromString(PRTSCRIPTPS phScriptPs, const char *pszId, const char *pszSrc,
PRTERRINFO pErrInfo);
/** @} */
/** @defgroup grp_rt_script_vm Scripting bytecode VM API.
*
* @{
*/
/**
* Data value (for return values and arguments).
*/
typedef struct RTSCRIPTVMVAL
{
/** The value type. */
RTSCRIPTNATIVETYPE enmType;
/** Value, dependent on type. */
union
{
int8_t i8;
uint8_t u8;
int16_t i16;
uint16_t u16;
int32_t i32;
uint32_t u32;
int64_t i64;
uint64_t u64;
RTFLOAT64U r64;
} u;
} RTSCRIPTVMVAL;
/** Pointer to a VM value. */
typedef RTSCRIPTVMVAL *PRTSCRIPTVMVAL;
/** Pointer to a const value. */
typedef const RTSCRIPTVMVAL *PCRTSCRIPTVMVAL;
/** Opaque VM state handle. */
typedef struct RTSCRIPTVMINT *RTSCRIPTVM;
/** Pointer to a VM state handle. */
typedef RTSCRIPTVM *PRTSCRIPTVM;
/** Opaque VM execution context handle. */
typedef struct RTSCRIPTVMCTXINT *RTSCRIPTVMCTX;
/** Pointer to an opaque VM execution context handle. */
typedef RTSCRIPTVMCTX *PRTSCRIPTVMCTX;
/**
* Creates a new script VM.
*
* @returns IPRT status code.
* @param phScriptVm Where to store the VM handle on success.
*/
RTDECL(int) RTScriptVmCreate(PRTSCRIPTVM phScriptVm);
/**
* Retains the VM reference.
*
* @returns New reference count.
* @param hScriptVm The VM handle to retain.
*/
RTDECL(uint32_t) RTScriptVmRetain(RTSCRIPTVM hScriptVm);
/**
* Releases the VM reference.
*
* @returns New reference count, on 0 the VM is destroyed.
* @param hScriptVm The VM handle to release.
*/
RTDECL(uint32_t) RTScriptVmRelease(RTSCRIPTVM hScriptVm);
/**
* Adds the given program state to the VM making it available for execution.
*
* @returns IPRT status code.
* @param hScriptVm The VM handle.
* @param hScriptPs The program state to add.
* @param pErrInfo Where to store error information on failure.
*/
RTDECL(int) RTScriptVmAddPs(RTSCRIPTVM hScriptVm, RTSCRIPTPS hScriptPs, PRTERRINFO pErrInfo);
/**
* Creates a new execution context for running code in the VM.
*
* @returns IPRT status code.
* @param hScriptVm The VM handle.
* @param phScriptVmCtx Where to store the execution context handle on success.
* @param cbStack Size of the stack in bytes, 0 if unlimited.
*/
RTDECL(int) RTScriptVmExecCtxCreate(RTSCRIPTVM hScriptVm, PRTSCRIPTVMCTX phScriptVmCtx, size_t cbStack);
/**
* Retains the VM execution context reference.
*
* @returns New reference count.
* @param hScriptVmCtx The VM execution context handle to retain.
*/
RTDECL(uint32_t) RTScriptVmExecCtxRetain(RTSCRIPTVMCTX hScriptVmCtx);
/**
* Releases a VM execution context reference.
*
* @returns New reference count, on 0 the execution context is destroyed.
* @param hScriptVmCtx The VM execution context handle to release.
*/
RTDECL(uint32_t) RTScriptVmExecCtxRelease(RTSCRIPTVMCTX hScriptVmCtx);
/**
* Sets the initial state for execution.
*
* @returns IPRT status code.
* @param hScriptVmCtx The VM execution context handle.
* @param pszFn The method to execute, NULL for the main program if existing.
* @param paArgs Arguments to supply to the executed method.
* @param cArgs Number of arguments supplied.
*/
RTDECL(int) RTScriptVmExecCtxInit(RTSCRIPTVMCTX hScriptVmCtx, const char *pszFn,
PCRTSCRIPTVMVAL paArgs, uint32_t cArgs);
/**
* Continues executing the current state.
*
* @returns IPRT status code.
* @param hScriptVmCtx The VM execution context handle.
* @param msTimeout Maximum amount of time to execute, RT_INDEFINITE_WAIT
* for an unrestricted amount of time.
* @param pRetVal Where to store the return value on success, optional.
*/
RTDECL(int) RTScriptVmExecCtxRun(RTSCRIPTVMCTX hScriptVmCtx, RTMSINTERVAL msTimeout,
PRTSCRIPTVMVAL pRetVal);
/**
* Interrupts the current execution.
*
* @returns IPRT status code.
* @param hScriptVmCtx The VM execution context handle.
*/
RTDECL(int) RTScriptVmExecCtxInterrupt(RTSCRIPTVMCTX hScriptVmCtx);
/** @} */
#endif
/** @} */
RT_C_DECLS_END
#endif /* !IPRT_INCLUDED_script_h */
View git blame Copy permalink