From 08475bb0cc698211414fc34cbdb893aaf8314a65 Mon Sep 17 00:00:00 2001 From: Arkshine Date: Sun, 6 Jul 2014 00:25:44 +0200 Subject: [PATCH] Regex: Update documentation + add regex_match_simple stock. --- plugins/include/regex.inc | 335 ++++++++++++++++++++++---------------- 1 file changed, 196 insertions(+), 139 deletions(-) diff --git a/plugins/include/regex.inc b/plugins/include/regex.inc index 62b616da..976e25d1 100755 --- a/plugins/include/regex.inc +++ b/plugins/include/regex.inc @@ -1,21 +1,44 @@ -/* Regular Expression API - * (C)2004 by David "BAILOPAN" Anderson - * Licensed under the GNU General Public License. - * No warranties of any kind. +/** + * Regular Expressions API + * By the AMX Mod X Development Team + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at + * your option) any later version. + * + * this program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software Foundation, + * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * + * In addition, as a special exception, the author gives permission to + * link the code of this program with the Half-Life Game Engine ("HL + * Engine") and Modified Game Libraries ("MODs") developed by Valve, + * L.L.C ("Valve"). You must obey the GNU General Public License in all + * respects for all of the code used other than the HL Engine and MODs + * from Valve. If you modify this file, you may extend this exception + * to your version of the file, but you are not obligated to do so. If + * you do not wish to do so, delete this exception statement from your + * version. */ #if defined _regex_included - #endinput + #endinput #endif #define _regex_included #if AMXX_VERSION_NUM >= 175 - #pragma reqlib regex - #if !defined AMXMODX_NOAUTOLOAD - #pragma loadlib regex - #endif + #pragma reqlib regex + #if !defined AMXMODX_NOAUTOLOAD + #pragma loadlib regex + #endif #else - #pragma library regex + #pragma library regex #endif @@ -27,14 +50,125 @@ enum Regex REGEX_OK }; +/** + * Precompile a regular expression. + * + * @note Use this if you intend on using the ame expression multiple times. + * Pass the regex handle returned here to regex_match_c to check for matches. + * + * @note This handle is automatically freed on map change. However, + * if you are completely done with it before then, you should + * call regex_free on this handle. + * + * @param pattern The regular expression pattern. + * @param ret Error code encountered, if applicable. + * @param error Error message encountered, if applicable. + * @param maxLen Maximum string length of the error buffer. + * @param flags General flags for the regular expression. + * i = Ignore case + * m = Multilines (affects ^ and $ so that they match + * the start/end of a line rather than matching the + * start/end of the string). + * s = Single line (affects . so that it matches any character, + * even new line characters). + * x = Pattern extension (ignore whitespace and # comments). + * + * @return -1 on error in the pattern, > valid regex handle (> 0) on success. + */ +native Regex:regex_compile(const pattern[], &ret, error[], maxLen, const flags[]=""); /** - * @section Flags for compiling regex expressions. - * These come directly from the pcre library and can be used in MatchRegex and CompileRegex. + * Matches a string against a pre-compiled regular expression pattern. * - * @note To be used with regex_compile_ex. - * Only available in 1.8.3 and above. - */ + * @note You should free the returned handle with regex_free() + * when you are done with this pattern. + * + * @note Use the regex handle passed to this function to extract + * matches with regex_substr(). + * + * @param string The string to check. + * @param pattern The regular expression pattern. + * @param ret Error code, if applicable, or number of results on success. + * + * @return -2 = Matching error (error code is stored in ret) + * 0 = No match. + * >1 = Number of results. + */ +native regex_match_c(const string[], Regex:pattern, &ret); + +/** + * Matches a string against a regular expression pattern. + * + * @note If you intend on using the same regular expression pattern + * multiple times, consider using regex_compile and regex_match_ex + * instead of making this function reparse the expression each time. + * + * @note Flags only exist in amxmodx 1.8 and later. + * + * @note You should free the returned handle with regex_free() + * when you are done extracting all of the substrings. + * + * @param string The string to check. + * @param pattern The regular expression pattern. + * @param ret Error code, or result state of the match. + * @param error Error message, if applicable. + * @param maxLen Maximum length of the error buffer. + * @param flags General flags for the regular expression. + * i = Ignore case + * m = Multilines (affects ^ and $ so that they match + * the start/end of a line rather than matching the + * start/end of the string). + * s = Single line (affects . so that it matches any character, + * even new line characters). + * x = Pattern extension (ignore whitespace and # comments). + * + * @return -2 = Matching error (error code is stored in ret) + * -1 = Error in pattern (error message and offset # in error and ret) + * 0 = No match. + * >1 = Handle for getting more information (via regex_substr) + */ +native Regex:regex_match(const string[], const pattern[], &ret, error[], maxLen, const flags[] = ""); + +/** + * Returns a matched substring from a regex handle. + * + * @note Substring ids start at 0 and end at ret - 1, where ret is from the corresponding + * regex_match, regex_match_c or regex_match_ex function call. + * + * @param id The regex handle to extract data from. + * @param str_id The index of the expression to get - starts at 0, and ends at ret - 1. + * @param buffer The buffer to set to the matching substring. + * @param maxLen The maximum string length of the buffer. + * + * @return 1 on success, otherwise 0 on failure. + */ +native regex_substr(Regex:id, str_id, buffer[], maxLen); + +/** + * Frees the memory associated with a regex result, and sets the handle to 0. + * + * @note This must be called on all results from regex_match() when you are done extracting + * the results with regex_substr(). + * + * @note The results of regex_compile() or regex_compile_ex() (and subsequently, regex_match_c() or regex_match_ex()) + * only need to be freed when you are done using the pattern. + * + * @note Do not use the handle again after freeing it! + * + * @param id The regex handle to free. + * @noreturn + */ +native regex_free(&Regex:id); + + +/** + * The following natives are only available in 1.8.3 and above. + */ + +/** + * Flags for compiling regex expressions. + * These come directly from the pcre library and can be used in regex_compile_ex. + */ #define PCRE_CASELESS 0x00000001 /* Ignore Case */ #define PCRE_MULTILINE 0x00000002 /* Multilines (affects ^ and $ so that they match the start/end of a line rather than matching the start/end of the string). */ #define PCRE_DOTALL 0x00000004 /* Single line (affects . so that it matches any character, even new line characters). */ @@ -45,13 +179,13 @@ enum Regex #define PCRE_NOTEMPTY 0x00000400 /* An empty string is not a valid match. */ #define PCRE_UTF8 0x00000800 /* Use UTF-8 Chars */ #define PCRE_NO_UTF8_CHECK 0x00002000 /* Do not check the pattern for UTF-8 validity (only relevant if PCRE_UTF8 is set) */ +#define PCRE_FIRSTLINE 0x00040000 /* Force matching to be before newline */ +#define PCRE_DUPNAMES 0x00080000 /* Allow duplicate names for subpattern */ #define PCRE_UCP 0x20000000 /* Use Unicode properties for \ed, \ew, etc. */ /** * Regex expression error codes. - * - * @note To be used with regex_compile_ex and regex_match_ex natives. - * Only available in 1.8.3 and above. + * This can be used with regex_compile_ex and regex_match_ex. */ enum RegexError { @@ -88,72 +222,25 @@ enum RegexError REGEX_ERROR_DFA_BADRESTART = -30, REGEX_ERROR_JIT_BADOPTION = -31, REGEX_ERROR_BADLENGTH = -32, + REGEX_ERROR_UNSET = -33 }; - /** - * Precompile a regular expression. Use this if you intend on using the - * same expression multiple times. Pass the regex handle returned here to - * regex_match_c to check for matches. + * Precompile a regular expression. * - * @param pattern The regular expression pattern. - * @param errcode Error code encountered, if applicable. - * @param error Error message encountered, if applicable. - * @param maxLen Maximum string length of the error buffer. - * @param flags General flags for the regular expression. - * i = Ignore case - * m = Multilines (affects ^ and $ so that they match - * the start/end of a line rather than matching the - * start/end of the string). - * s = Single line (affects . so that it matches any character, - * even new line characters). - * x = Pattern extension (ignore whitespace and # comments). + * @note Use this if you intend on using the ame expression multiple times. + * Pass the regex handle returned here to regex_match_ex() to check for matches. * - * @return -1 on error in the pattern, > valid regex handle (> 0) on success. + * @note Unlike regex_compile(), this allows you to use directly PCRE flags, and + * to get a more complete set of regular expression error codes. * - * @note This handle is automatically freed on map change. However, - * if you are completely done with it before then, you should - * call regex_free on this handle. - */ -native Regex:regex_compile(const pattern[], &ret, error[], maxLen, const flags[]=""); - -/** - * Matches a string against a pre-compiled regular expression pattern. + * @param pattern The regular expression pattern. + * @param flags General flags for the regular expression, see PCRE_* defines. + * @param error Error message encountered, if applicable. + * @param maxLen Maximum string length of the error buffer. + * @param errcode Regex type error code encountered, if applicable. * - * - * @param pattern The regular expression pattern. - * @param string The string to check. - * @param ret Error code, if applicable, or number of results on success. - * - * @return -2 = Matching error (error code is stored in ret) - * 0 = No match. - * >1 = Number of results. - * - * @note You should free the returned handle (with regex_free()) - * when you are done with this pattern. - * - * @note Use the regex handle passed to this function to extract - * matches with regex_substr(). - */ -native regex_match_c(const string[], Regex:pattern, &ret); - -/** - * Precompile a regular expression. - * - * @note Use this if you intend on using the ame expression multiple times. - * Pass the regex handle returned here to regex_match_ex to check for matches. - * - * @note Unlike regex_compile, this allows you to use directly PCRE flags, and - * to get a more complete set of regular expression error codes. - * Only available in 1.8.3 and above. - * - * @param pattern The regular expression pattern. - * @param flags General flags for the regular expression, see PCRE_* defines. - * @param error Error message encountered, if applicable. - * @param maxLen Maximum string length of the error buffer. - * @param errcode Regex type error code encountered, if applicable. - * - * @return Valid regex handle (> 0) on success, or -1 on failure. + * @return Valid regex handle (> 0) on success, or -1 on failure. */ native Regex:regex_compile_ex(const pattern[], flags = 0, error[]= "", maxLen = 0, &RegexError:errcode = REGEX_ERROR_NONE); @@ -166,79 +253,49 @@ native Regex:regex_compile_ex(const pattern[], flags = 0, error[]= "", maxLen = * @note You should free the returned handle with regex_free() * when you are done with this pattern. * - * @note Unlike regex_match_c(), this allows you to get a more complete + * @note Unlike regex_match_c(), this allows you to get a more complete * set of regular expression error codes and parameter is optional. - * Only available in 1.8.3 and above. * - * @param str The string to check. - * @param regex Regex Handle from regex_compile_ex() - * @param ret Error code, if applicable. + * @param str The string to check. + * @param regex Regex Handle from regex_compile_ex() + * @param ret Error code, if applicable. * - * @return -2 = Matching error (error code is stored in ret) - * 0 = No match. - * >1 = Number of results. + * @return -2 = Matching error (error code is stored in ret) + * 0 = No match. + * >1 = Number of results. */ native regex_match_ex(Handle:regex, const str[], &RegexError:ret = REGEX_ERROR_NONE); /** * Matches a string against a regular expression pattern. * - * @note If you intend on using the same regular expression pattern - * multiple times, consider using regex_compile and regex_match_c - * instead of making this function reparse the expression each time. + * @note If you intend on using the same regular expression pattern + * multiple times, consider using compile regex_compilex_ex and regex_match_ex + * instead of making this function reparse the expression each time. * - * @param string The string to check. - * @param pattern The regular expression pattern. - * @param ret Error code, or result state of the match. - * @param error Error message, if applicable. - * @param maxLen Maximum length of the error buffer. - * @param flags General flags for the regular expression. - * i = Ignore case - * m = Multilines (affects ^ and $ so that they match - * the start/end of a line rather than matching the - * start/end of the string). - * s = Single line (affects . so that it matches any character, - * even new line characters). - * x = Pattern extension (ignore whitespace and # comments). + * @param str The string to check. + * @param pattern The regular expression pattern. + * @param flags General flags for the regular expression. + * @param error Error message, if applicable. + * @param maxLen Maximum length of the error buffer. * - * @return -2 = Matching error (error code is stored in ret) - * -1 = Error in pattern (error message and offset # in error and ret) - * 0 = No match. - * >1 = Handle for getting more information (via regex_substr) - * - * @note Flags only exist in amxmodx 1.8 and later. - * @note You should free the returned handle (with regex_free()) - * when you are done extracting all of the substrings. + * @return -2 = Matching error (error code is stored in ret) + * -1 = Pattern error (error code is stored in ret) + * 0 = No match. + * >1 = Number of results. */ -native Regex:regex_match(const string[], const pattern[], &ret, error[], maxLen, const flags[] = ""); +stock regex_match_simple(const str[], const pattern[], flags = 0, error[]="", maxLen = 0) +{ + new Regex:regex = regex_compile_ex(pattern, flags, error, maxLen); -/** - * Returns a matched substring from a regex handle. - * - * @note Substring ids start at 0 and end at ret - 1, where ret is from the corresponding - * regex_match, regex_match_c or regex_match_ex function call. - * - * @param id The regex handle to extract data from. - * @param str_id The index of the expression to get - starts at 0, and ends at ret - 1. - * @param buffer The buffer to set to the matching substring. - * @param maxLen The maximum string length of the buffer. - * - * @return 1 on success, otherwise 0 on failure. - */ -native regex_substr(Regex:id, str_id, buffer[], maxLen); + if (regex < 0) + { + return -1; + } -/** - * Frees the memory associated with a regex result, and sets the handle to 0. - * - * @note This must be called on all results from regex_match() when you are done extracting - * the results with regex_substr(). - * - * @note The results of regex_compile() or regex_compile_ex() (and subsequently, regex_match_c() or regex_match_ex()) - * only need to be freed when you are done using the pattern. - * - * @note Do not use the handle again after freeing it! - * - * @param id The regex handle to free. - * @noreturn - */ -native regex_free(&Regex:id); + new substrings = regex_match_ex(regex, str); + + regex_free(regex); + + return substrings; +}