|
|
The core library provides a minimal set of basic operations.
|
LIBCOM_API long epicsStdCall | macCreateHandle (MAC_HANDLE **handle, const char *pairs[]) |
| Creates a new macro substitution context. More...
|
|
LIBCOM_API void epicsStdCall | macSuppressWarning (MAC_HANDLE *handle, int falseTrue) |
| Disable or enable warning messages. More...
|
|
LIBCOM_API long epicsStdCall | macExpandString (MAC_HANDLE *handle, const char *src, char *dest, long capacity) |
| Expand a string which may contain macro references. More...
|
|
LIBCOM_API long epicsStdCall | macPutValue (MAC_HANDLE *handle, const char *name, const char *value) |
| Sets the value of a specific macro. More...
|
|
LIBCOM_API long epicsStdCall | macGetValue (MAC_HANDLE *handle, const char *name, char *value, long capacity) |
| Returns the value of a macro. More...
|
|
LIBCOM_API long epicsStdCall | macDeleteHandle (MAC_HANDLE *handle) |
| Marks a handle invalid, and frees all storage associated with it. More...
|
|
LIBCOM_API long epicsStdCall | macPushScope (MAC_HANDLE *handle) |
| Marks the start of a new scoping level. More...
|
|
LIBCOM_API long epicsStdCall | macPopScope (MAC_HANDLE *handle) |
| Retrieve the last pushed scope (like stack operations) More...
|
|
LIBCOM_API long epicsStdCall | macReportMacros (MAC_HANDLE *handle) |
| Reports details of current definitions. More...
|
|
|
These convenience functions are intended for applications to use and provide a more convenient interface for some purposes.
|
LIBCOM_API long epicsStdCall | macParseDefns (MAC_HANDLE *handle, const char *defns, char **pairs[]) |
| Parse macro definitions into an array of {name, value} pairs. More...
|
|
LIBCOM_API long epicsStdCall | macInstallMacros (MAC_HANDLE *handle, char *pairs[]) |
| Install set of {name, value} pairs as definitions. More...
|
|
LIBCOM_API char *epicsStdCall | macEnvExpand (const char *str) |
| Expand environment variables in a string. More...
|
|
LIBCOM_API char *epicsStdCall | macDefExpand (const char *str, MAC_HANDLE *macros) |
| Expands macros and environment variables in a string. More...
|
|
- Author
- William Lupton, W. M. Keck Observatory
This general purpose macro substitution library is used for all macro substitutions in EPICS Base.
Most routines return 0 (OK) on success, -1 (ERROR) on failure, or small positive values for extra info. The macGetValue() and macExpandString() routines depart from this and return information both on success / failure and on value length. Errors and warnings are reported using errlogPrintf().
Definition in file macLib.h.
LIBCOM_API long epicsStdCall macGetValue |
( |
MAC_HANDLE * |
handle, |
|
|
const char * |
name, |
|
|
char * |
value, |
|
|
long |
capacity |
|
) |
| |
- Returns
- Returns the length of the value string, <0 if undefined
value
will be zero-terminated if the length of the value is less than capacity
. The return value is the number of characters copied to value
(see below for behavior if the macro is undefined). If capacity
is zero, no characters will be copied to value
(which may be NULL) and the call can be used to check whether the macro is defined.
- Note
- Truncation of the value is not reported, applications should assume that truncation has occurred if the return value is equal to capacity.
If the macro is undefined, the macro reference will be returned in the value string (if permitted by maxlen) and the function value will be minus the number of characters copied. Note that treatment of capacity
is intended to be consistent with the strncpy() routine.
If the value contains macro references, these references will be expanded recursively. This expansion will detect a direct or indirect self reference.
Macro references begin with a "$" immediately followed by either a "(" or a "{" character. The macro name comes next, and may optionally be succeeded by an "=" and a default value, which will be returned if the named macro is undefined at the moment of expansion. A reference is terminated by the matching ")" or "}" character.
- Parameters
-
handle | opaque handle |
name | macro name or reference |
value | string to receive macro value or name argument if macro is undefined |
capacity | capacity of destination buffer (value) |
LIBCOM_API long epicsStdCall macParseDefns |
( |
MAC_HANDLE * |
handle, |
|
|
const char * |
defns, |
|
|
char ** |
pairs[] |
|
) |
| |
- Returns
- Number of macros found; <0 = ERROR
This takes a set of macro definitions in "a=xxx,b=yyy" format and converts them into an array of pointers to character strings which are, in order, "first name", "first value", "second name", "second
value" etc. The array is terminated with two NULL pointers and all storage is allocated contiguously so that it can be freed with a single call to free().
This routine is independent of any handle and provides a generally useful service which may be used elsewhere. Any macro references in values are not expanded at this point since the referenced macros may be defined or redefined before the macro actually has to be translated.
Shell-style escapes and quotes are supported, as are things like "A=B,B=$(C$(A)),CA=CA,CB=CB" (sets B to "CB"). White space is significant within values but ignored elsewhere (i.e. surrounding "=" and "," characters).
The function returns the number of definitions encountered, or -1 if the supplied string is invalid.
- Parameters
-
handle | opaque handle; may be NULL if debug messages are not required. |
defns | macro definitions in "a=xxx,b=yyy" format |
pairs | address of variable to receive pointer to NULL-terminated array of {name, value} pair strings; all storage is allocated contiguously |