VirtualBox

source: vbox/trunk/include/iprt/expreval.h@ 103224

Last change on this file since 103224 was 99760, checked in by vboxsync, 17 months ago

IPRT: doxygen tweaks. bugref:10442

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 5.7 KB
Line 
1/* $Id: expreval.h 99760 2023-05-11 22:10:41Z vboxsync $ */
2/** @file
3 * IPRT - Expression Evaluator.
4 */
5
6/*
7 * Copyright (C) 2022-2023 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_expreval_h
38#define IPRT_INCLUDED_expreval_h
39#ifndef RT_WITHOUT_PRAGMA_ONCE
40# pragma once
41#endif
42
43#include <iprt/types.h>
44
45RT_C_DECLS_BEGIN
46
47/** @defgroup grp_rt_expr_eval RTExprEval - Expression Evaluator
48 * @ingroup grp_rt
49 * @{ */
50
51/** Handle to an expression evaluator. */
52typedef struct RTEXPREVALINT *RTEXPREVAL;
53/** Pointer to an expression evaluator handle. */
54typedef RTEXPREVAL *PRTEXPREVAL;
55/** NIL expression evaluator handle. */
56#define NIL_RTEXPREVAL ((RTEXPREVAL)~(uintptr_t)0)
57
58/**
59 * Variable getter (supplied by user).
60 *
61 * @returns IPRT status code.
62 * @retval VERR_NOT_FOUND if the variable does not exist.
63 */
64typedef DECLCALLBACKTYPE(int, FNRTEXPREVALQUERYVARIABLE,(const char *pchName, size_t cchName, void *pvUser, char **ppszValue));
65/** Pointer to a variable getter. */
66typedef FNRTEXPREVALQUERYVARIABLE *PFNRTEXPREVALQUERYVARIABLE;
67
68/** @name Expression evaluator flags.
69 * @sa RTExprEvalCreate
70 * @{ */
71/** Default to hexadecimal instead of decimal numbers. */
72#define RTEXPREVAL_F_DEFAULT_BASE_16 RT_BIT_64(0)
73/** Enables C-ish octal style, i.e. 0777 be read as 0x1ff (in hex). */
74#define RTEXPREVAL_F_C_OCTAL RT_BIT_64(1)
75/** Enables the 'exists' operator that can be used to check if a path exists.
76 * @sa RTPathExists */
77#define RTEXPREVAL_F_EXISTS_OP RT_BIT_64(2)
78/** Valid mask. */
79#define RTEXPREVAL_F_VALID_MASK UINT64_MAX(3)
80/** @} */
81
82/**
83 * Creates an expression evaluator.
84 *
85 * @returns IPRT status code.
86 * @param phEval Where to return the handle to the evaluator.
87 * @param fFlags RTEXPREVAL_F_XXX.
88 * @param pszName The evaluator name (for logging).
89 * @param pvUser User argument for callbacks.
90 * @param pfnQueryVariable Callback for querying variables. Optional.
91 */
92RTDECL(int) RTExprEvalCreate(PRTEXPREVAL phEval, uint64_t fFlags, const char *pszName,
93 void *pvUser, PFNRTEXPREVALQUERYVARIABLE pfnQueryVariable);
94
95/**
96 * Retains a reference to the evaluator.
97 *
98 * @returns New reference count, UINT32_MAX if @a hEval is not valid.
99 * @param hEval Handle to the evaluator.
100 */
101RTDECL(uint32_t) RTExprEvalRetain(RTEXPREVAL hEval);
102
103/**
104 * Releases a reference to the evaluator.
105 *
106 * @returns New reference count, UINT32_MAX if @a hEval is not valid. (The
107 * evaluator was destroyed when 0 is returned.)
108 * @param hEval Handle to the evaluator.
109 */
110RTDECL(uint32_t) RTExprEvalRelease(RTEXPREVAL hEval);
111
112/**
113 * Evaluates the given if expression to a boolean result.
114 *
115 * @returns IPRT status code
116 * @param hEval Handle to the evaluator.
117 * @param pch The expression string. Does not need to be zero
118 * terminated.
119 * @param cch The length of the expression. Pass RTSTR_MAX if not
120 * known.
121 * @param pfResult Where to return the result.
122 * @param pErrInfo Where to return additional error info.
123 */
124RTDECL(int) RTExprEvalToBool(RTEXPREVAL hEval, const char *pch, size_t cch, bool *pfResult, PRTERRINFO pErrInfo);
125
126/**
127 * Evaluates the given if expression to an integer (signed 64-bit) result.
128 *
129 * @returns IPRT status code
130 * @param hEval Handle to the evaluator.
131 * @param pch The expression string. Does not need to be zero
132 * terminated.
133 * @param cch The length of the expression. Pass RTSTR_MAX if not
134 * known.
135 * @param piResult Where to return the result.
136 * @param pErrInfo Where to return additional error info.
137 */
138RTDECL(int) RTExprEvalToInteger(RTEXPREVAL hEval, const char *pch, size_t cch, int64_t *piResult, PRTERRINFO pErrInfo);
139
140/**
141 * Evaluates the given if expression to a string result.
142 *
143 * @returns IPRT status code
144 * @param hEval Handle to the evaluator.
145 * @param pch The expression string. Does not need to be zero
146 * terminated.
147 * @param cch The length of the expression. Pass RTSTR_MAX if not
148 * known.
149 * @param ppszResult Where to return the result. This must be freed using
150 * RTStrFree.
151 * @param pErrInfo Where to return additional error info.
152 */
153RTDECL(int) RTExprEvalToString(RTEXPREVAL hEval, const char *pch, size_t cch, char **ppszResult, PRTERRINFO pErrInfo);
154
155/** @} */
156
157RT_C_DECLS_END
158
159#endif /* !IPRT_INCLUDED_expreval_h */
160
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette