include/valgrind/pub_tool_seqmatch.h

0001
0002 /*--------------------------------------------------------------------*/
0003 /*--- A simple sequence matching facility.                         ---*/
0004 /*---                                          pub_tool_seqmatch.h ---*/
0005 /*--------------------------------------------------------------------*/
0006
0007 /*
0008    This file is part of Valgrind, a dynamic binary instrumentation
0009    framework.
0010
0011    Copyright (C) 2008-2017 OpenWorks Ltd
0012       info@open-works.co.uk
0013
0014    This program is free software; you can redistribute it and/or
0015    modify it under the terms of the GNU General Public License as
0016    published by the Free Software Foundation; either version 2 of the
0017    License, or (at your option) any later version.
0018
0019    This program is distributed in the hope that it will be useful, but
0020    WITHOUT ANY WARRANTY; without even the implied warranty of
0021    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0022    General Public License for more details.
0023
0024    You should have received a copy of the GNU General Public License
0025    along with this program; if not, see <http://www.gnu.org/licenses/>.
0026
0027    The GNU General Public License is contained in the file COPYING.
0028 */
0029
0030 #ifndef __PUB_TOOL_SEQMATCH_H
0031 #define __PUB_TOOL_SEQMATCH_H
0032
0033 #include "pub_tool_basics.h"   // UWord
0034
0035 /* Perform totally abstractified sequence matching, of an input
0036    sequence against a pattern sequence.  The pattern sequence may
0037    include '*' elements (matches any number of anything) and '?'
0038    elements (matches exactly one element).  '*' patterns are matched
0039    frugally, meaning that they are "assigned" the minimum amount of
0040    input needed to make the match work.
0041
0042    This routine is recursive.  The recursion depth is equal to the
0043    number of '*' elements in the pattern.  There is no guard against
0044    excessive recursion.  This function has no global state and so is
0045    thread-safe and re-entrant.  (It needs to be, since m_errormgr will
0046    effectively construct two simultaneous calls to it, once to match
0047    at the frame level, and whilst that is happening, once at the
0048    function/object-name level.)
0049
0050    When matchAll is True, the entire input sequence must match the
0051    pattern, else the match fails.  When False, it's ok for some tail
0052    of the input sequence to be unused -- so we're only matching a
0053    prefix.
0054
0055    The pattern array is starts at 'patt' and consists of 'nPatt'
0056    elements each of size 'szbPatt'.  For the initial call, pass a
0057    value of zero to 'ixPatt'.
0058
0059    The input sequence can be similarly described using
0060    input/nInput/szbInput/ixInput.
0061    Alternatively, the input can be lazily constructed using an
0062    inputCompleter. When using an inputCompleter, input/nInput/szbInput
0063    are unused.
0064
0065    pIsStar should return True iff the pointed-to pattern element is
0066    conceptually a '*'.
0067
0068    pIsQuery should return True iff the pointed-to-pattern element is
0069    conceptually a '?'.
0070
0071    pattEQinp takes a pointer to a pattern element and a pointer to an
0072    input element.  It should return True iff they are considered
0073    equal.  Note that the pattern element is guaranteed to be neither
0074    (conceptually) '*' nor '?', so it must be a literal (in the sense
0075    that all the input sequence elements are literal).
0076
0077    If inputCompleter is not NULL, the input will be lazily constructed
0078    when pattEQinp is called.
0079    For lazily constructing the input element, the two last arguments
0080    of pattEQinp are the inputCompleter and the index of the input
0081    element to complete.
0082    VG_(generic_match) calls (*haveInputInpC)(inputCompleter,ixInput) to
0083    check if there is an element ixInput in the input sequence.
0084 */
0085 Bool VG_(generic_match) (
0086         Bool matchAll,
0087         const void* patt,  SizeT szbPatt,  UWord nPatt,  UWord ixPatt,
0088         const void* input, SizeT szbInput, UWord nInput, UWord ixInput,
0089         Bool (*pIsStar)(const void*),
0090         Bool (*pIsQuery)(const void*),
0091         Bool (*pattEQinp)(const void*,const void*,void*,UWord),
0092         void* inputCompleter,
0093         Bool (*haveInputInpC)(void*,UWord)
0094      );
0095
0096 /* Mini-regexp function.  Searches for 'pat' in 'str'.  Supports
0097    meta-symbols '*' and '?'.  There is no way to escape meta-symbols
0098    in the pattern. */
0099 Bool VG_(string_match) ( const HChar* pat, const HChar* str );
0100
0101 #endif   // __PUB_TOOL_SEQMATCH_H
0102
0103 /*--------------------------------------------------------------------*/
0104 /*--- end                                      pub_tool_seqmatch.h ---*/
0105 /*--------------------------------------------------------------------*/