From 2109dedc473944dbb38756cd48d0c44f996304c4 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Wed, 9 Aug 2023 08:54:37 +0200 Subject: Complete and cleanup function documentation in preparation for auto-extraction Also: - Move the $target.*() function family from functions-name.cxx to separate functions-target.cxx. - Get rid of the separate $process_path_ex.*() family, merging it with $process_path.*(). --- libbuild2/functions-regex.cxx | 140 ++++++++++++++++++++---------------------- 1 file changed, 66 insertions(+), 74 deletions(-) (limited to 'libbuild2/functions-regex.cxx') diff --git a/libbuild2/functions-regex.cxx b/libbuild2/functions-regex.cxx index 1465108..a7fcf55 100644 --- a/libbuild2/functions-regex.cxx +++ b/libbuild2/functions-regex.cxx @@ -588,16 +588,16 @@ namespace build2 // // Match a value of an arbitrary type against the regular expression. // Convert the value to string prior to matching. Return the boolean value - // unless return_subs flag is specified (see below), in which case return - // names (NULL if no match). + // unless `return_subs` flag is specified (see below), in which case + // return names (or `null` if no match). // // The following flags are supported: // - // icase - match ignoring case + // icase - match ignoring case // - // return_subs - return names (rather than boolean), that contain - // sub-strings that match the marked sub-expressions and - // NULL if no match + // return_subs - return names (rather than boolean), that contain + // sub-strings that match the marked sub-expressions + // and null if no match // f[".match"] += [](value v, string re, optional flags) { @@ -616,7 +616,7 @@ namespace build2 // // The following flags are supported: // - // icase - match ignoring case + // icase - match ignoring case // f[".find_match"] += [](names ns, string re, optional flags) { @@ -631,13 +631,13 @@ namespace build2 // $regex.filter_match(, [, ]) // $regex.filter_out_match(, [, ]) // - // Return elements of a list that match (filter) or do not match - // (filter_out) the regular expression. Convert the elements to strings + // Return elements of a list that match (`filter`) or do not match + // (`filter_out`) the regular expression. Convert the elements to strings // prior to matching. // // The following flags are supported: // - // icase - match ignoring case + // icase - match ignoring case // f[".filter_match"] += [](names ns, string re, optional flags) { @@ -669,23 +669,23 @@ namespace build2 // // Determine if there is a match between the regular expression and some // part of a value of an arbitrary type. Convert the value to string prior - // to searching. Return the boolean value unless return_match or - // return_subs flag is specified (see below) in which case return names - // (NULL if no match). + // to searching. Return the boolean value unless `return_match` or + // `return_subs` flag is specified (see below) in which case return names + // (`null` if no match). // // The following flags are supported: // - // icase - match ignoring case + // icase - match ignoring case // - // return_match - return names (rather than boolean), that contain a - // sub-string that matches the whole regular expression and - // NULL if no match + // return_match - return names (rather than boolean), that contain a + // sub-string that matches the whole regular expression + // and null if no match // - // return_subs - return names (rather than boolean), that contain - // sub-strings that match the marked sub-expressions and - // NULL if no match + // return_subs - return names (rather than boolean), that contain + // sub-strings that match the marked sub-expressions + // and null if no match // - // If both return_match and return_subs flags are specified then the + // If both `return_match` and `return_subs` flags are specified then the // sub-string that matches the whole regular expression comes first. // f[".search"] += [](value v, string re, optional flags) @@ -706,7 +706,7 @@ namespace build2 // // The following flags are supported: // - // icase - match ignoring case + // icase - match ignoring case // f[".find_search"] += [](names ns, string re, optional flags) { @@ -723,13 +723,13 @@ namespace build2 // $regex.filter_search(, [, ]) // $regex.filter_out_search(, [, ]) // - // Return elements of a list for which there is a match (filter) or no - // match (filter_out) between the regular expression and some part of the - // element. Convert the elements to strings prior to matching. + // Return elements of a list for which there is a match (`filter`) or no + // match (`filter_out`) between the regular expression and some part of + // the element. Convert the elements to strings prior to matching. // // The following flags are supported: // - // icase - match ignoring case + // icase - match ignoring case // f[".filter_search"] += [](names ns, string re, optional flags) { @@ -763,19 +763,17 @@ namespace build2 // string. Convert the value to string prior to matching. The result value // is always untyped, regardless of the argument type. // - // Substitution escape sequences are extended with a subset of Perl - // sequences (see libbutl/regex.hxx for details). - // // The following flags are supported: // - // icase - match ignoring case + // icase - match ignoring case // - // format_first_only - only replace the first match + // format_first_only - only replace the first match // - // format_no_copy - do not copy unmatched value parts into the result + // format_no_copy - do not copy unmatched value parts into the + // result // - // If both format_first_only and format_no_copy flags are specified then - // the result will only contain the replacement of the first match. + // If both `format_first_only` and `format_no_copy` flags are specified + // then the result will only contain the replacement of the first match. // f[".replace"] += [](value v, string re, string fmt, optional flags) { @@ -793,21 +791,21 @@ namespace build2 // $regex.replace_lines(, , [, ]) // // Convert the value to string, parse it into lines and for each line - // apply the $regex.replace() function with the specified pattern, format, - // and flags. If the format argument is NULL, omit the "all-NULL" - // replacements for the matched lines from the result. Return unmatched - // lines and line replacements as a name list unless return_lines flag is - // specified (see below), in which case return a single multi-line simple - // name value. + // apply the `$regex.replace()` function with the specified pattern, + // format, and flags. If the format argument is `null`, omit the + // "all-`null`" replacements for the matched lines from the result. Return + // unmatched lines and line replacements as a `name` list unless + // `return_lines` flag is specified (see below), in which case return a + // single multi-line simple `name` value. // - // The following flags are supported in addition to the $regex.replace() - // function flags: + // The following flags are supported in addition to the `$regex.replace()` + // function's flags: // - // return_lines - return the simple name (rather than a name list) - // containing the unmatched lines and line replacements - // separated with newlines. + // return_lines - return the simple name (rather than a name list) + // containing the unmatched lines and line replacements + // separated with newlines. // - // Note that if format_no_copy is specified, unmatched lines are not + // Note that if `format_no_copy` is specified, unmatched lines are not // copied either. // f[".replace_lines"] += [](value v, @@ -836,19 +834,17 @@ namespace build2 // // Split a value of an arbitrary type into a list of unmatched value parts // and replacements of the matched parts, omitting empty ones (unless the - // format_copy_empty flag is specified). Convert the value to string prior - // to matching. - // - // Substitution escape sequences are extended with a subset of Perl - // sequences (see libbutl/regex.hxx for details). + // `format_copy_empty` flag is specified). Convert the value to string + // prior to matching. // // The following flags are supported: // - // icase - match ignoring case + // icase - match ignoring case // - // format_no_copy - do not copy unmatched value parts into the result + // format_no_copy - do not copy unmatched value parts into the + // result // - // format_copy_empty - copy empty elements into the result + // format_copy_empty - copy empty elements into the result // f[".split"] += [](value v, string re, string fmt, optional flags) { @@ -868,24 +864,22 @@ namespace build2 // Replace matched parts in a list of elements using the regex format // string. Convert the elements to strings prior to matching. The result // value is untyped and contains concatenation of transformed non-empty - // elements (unless the format_copy_empty flag is specified) optionally + // elements (unless the `format_copy_empty` flag is specified) optionally // separated with a delimiter. // - // Substitution escape sequences are extended with a subset of Perl - // sequences (see libbutl/regex.hxx for details). - // // The following flags are supported: // - // icase - match ignoring case + // icase - match ignoring case // - // format_first_only - only replace the first match + // format_first_only - only replace the first match // - // format_no_copy - do not copy unmatched value parts into the result + // format_no_copy - do not copy unmatched value parts into the + // result // - // format_copy_empty - copy empty elements into the result + // format_copy_empty - copy empty elements into the result // - // If both format_first_only and format_no_copy flags are specified then - // the result will be a concatenation of only the first match + // If both `format_first_only` and `format_no_copy` flags are specified + // then the result will be a concatenation of only the first match // replacements. // f[".merge"] += [](names ns, @@ -923,23 +917,21 @@ namespace build2 // Replace matched parts of each element in a list using the regex format // string. Convert the elements to strings prior to matching. Return a // list of transformed elements, omitting the empty ones (unless the - // format_copy_empty flag is specified). - // - // Substitution escape sequences are extended with a subset of Perl - // sequences (see libbutl/regex.hxx for details). + // `format_copy_empty` flag is specified). // // The following flags are supported: // - // icase - match ignoring case + // icase - match ignoring case // - // format_first_only - only replace the first match + // format_first_only - only replace the first match // - // format_no_copy - do not copy unmatched value parts into the result + // format_no_copy - do not copy unmatched value parts into the + // result // - // format_copy_empty - copy empty elements into the result + // format_copy_empty - copy empty elements into the result // - // If both format_first_only and format_no_copy flags are specified then - // the result elements will only contain the replacement of the first + // If both `format_first_only` and `format_no_copy` flags are specified + // then the result elements will only contain the replacement of the first // match. // f[".apply"] += [](names ns, string re, string fmt, optional flags) -- cgit v1.1