pcreMatchAssocList

pcreMatchAssocList( 
g_pattern 
l_subjects 
[ x_compOptBits ] 
[ x_execOptBits ]
) 
=> l_results / nil / error message(s)

Description

Matches the keys of an association list of subjects (strings or symbols) against a regular expression pattern (g_pattern) and returns an association list of those elements that match. The keys are the first elements of each key/value pair in the association list. You can use optional arguments to specify independent option bits for controlling pattern compiling and matching. The compiling and matching algorithms are PCRE/Perl-compatible.

The specified regular expression pattern overwrites the previously-compiled pattern and is used for subsequent matching until you provide a new pattern. The function reports any errors in the given pattern.

You can set and unset the PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and PCRE_EXTENDED independent option bits from within the pattern. The content of the options argument specifies the initial setting at the start of compilation. You can set the PCRE_ANCHORED option at matching time and at compile time.

If pcreObject is specified as the g_pattern, pcreMatchAssocList skips pattern compilation and ignores x_compOptBits.

Arguments

g_pattern	String containing regular expression string to be compiled or a `pcreObject`.
l_subjects	Association list whose keys are strings or symbols.
x_compOptBits	(Optional) Independent option bits that affect the compilation. Valid values for this argument are the same as those for the x_options argument to the pcreCompile SKILL function.
x_execOptBits	(Optional) Independent option bits that affect pattern matching. Valid values for this argument are the same as those for the x_options argument to the pcreExecute SKILL function.

Value Returned

l_results	Association list of elements from the subject association list whose keys match the pattern.
`nil`	No keys in the subject association list match the pattern.
error message(s)	Zero or more error messages that appear if the function fails for any reason, if the subject association list is not valid, or if the pattern compilation fails (indicating the cause of the failure).

Examples

pcreMatchAssocList( "^[a-z][0-9]*$" 
'((abc "ascii") ("123" "number") (a123 "alphanum")
(a12z "ana")) )
=> ((a123 "alphanum"))

pcreMatchAssocList("^[a-z][0-9]*$" 
'((abc "ascii") ("123" "number") ("yy\na123"  "alphanum") (a12z "ana")) 
pcreGenCompileOptBits(?multiLine t) pcreGenExecOptBits( ?notbol t) )
=> (("yy\na123" "alphanum"))

pcreMatchAssocList( "box[0-9]*" '(square circle "cell9" "123") ) => 
*Error* pcreMatchAssocList: element in the list given as argument #2 is not a valid association because its car() (taken as a key) is not either a symbol or a string - square

Cadence SKILL Language Reference
Product Version IC23.1, November 2023