1  /* $Id: expreval.h 99760 20230511 22:10:41Z vboxsync $ */


2  /** @file


3  * IPRT  Expression Evaluator.


4  */


5 


6  /*


7  * Copyright (C) 20222023 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  * SPDXLicenseIdentifier: GPL3.0only OR CDDL1.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 


45  RT_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. */


52  typedef struct RTEXPREVALINT *RTEXPREVAL;


53  /** Pointer to an expression evaluator handle. */


54  typedef 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  */


64  typedef DECLCALLBACKTYPE(int, FNRTEXPREVALQUERYVARIABLE,(const char *pchName, size_t cchName, void *pvUser, char **ppszValue));


65  /** Pointer to a variable getter. */


66  typedef 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 Cish 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  */


92  RTDECL(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  */


101  RTDECL(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  */


110  RTDECL(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  */


124  RTDECL(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 64bit) 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  */


138  RTDECL(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  */


153  RTDECL(int) RTExprEvalToString(RTEXPREVAL hEval, const char *pch, size_t cch, char **ppszResult, PRTERRINFO pErrInfo);


154 


155  /** @} */


156 


157  RT_C_DECLS_END


158 


159  #endif /* !IPRT_INCLUDED_expreval_h */


160 

