fix #157: split function accounting for quotes

[mikyll]

Added Util.splitCSVLine() function that splits a CSV-formatted string into an array of tokens, accounting for quotes (single and double) and escape characters.

[casbin-bot]

@Edmond-J-A @rushitote please review

[CLAassistant]

All committers have signed the CLA.

[hsluoyz]

@mikyll fix CI errors:

[mikyll]

@leeqvip I made some fixes to Util functions and added unit tests (also added an example use case and the related unit test about #157)

[mikyll]

Summary

Differences

Old Util.split(str, delimiter, x) function

This function was used for simply splitting a CSV-formatted line, into an array of fields, separated by delimiter (up to x number of fields). Fields were also trimmed to remove leading/trailing whitespaces.

New Util.splitEnhanced(str, delimiter, trimFields) function

This function does the same as Util.split(), but it adds the following features:

1. quoted fields - fields can be wrapped in double quotes (") to escape comma characters that are part of the field (useful for example in regexMatch, to handle {N,M} pattern quantifiers);

2. double quotes in quoted fields - quoted fields can contain double quotes, which are escaped through another double quotes character ("").

   This complies with what is stated in the documentation (Policy Storage | Casbin):

   Show/Hide

   NOTE
   If your file contains commas, you should wrap them in double quotes. For example:

   p, alice, "data1,data2", read    --correct
   p, alice, data1,data2, read        --incorrect (the whole phrase "data1,data2" should be wrapped in double quotes)
   

   If your file contains commas and double quotes, you should enclose the field in double quotes and double any embedded double quotes.

   p, alice, data, "r.act in (""get"", ""post"")"        --correct
   p, alice, data, "r.act in ("get", "post")"            --incorrect (you should use "" to escape "")
   

   Related issue: casbin#886

3. policy syntax errors:
   • if a quoted field presents extra trailing chracters, after the closing double quotes, the function throws the error Quoted fields cannot have extra characters outside double quotes.
   • if there are unmatched quotes, the function throws the error Unmatched quotes.

New Example

• file examples/basic_model_with_regex.conf - implements a simple ACL model with regex for each field of the policy rules;
• file examples/basic_policy_with_regex.csv - shows a simple usage of this model with a rule that includes the pattern quantifier {N,M} (it includes a comma escaped through the quoted field, so it's a way to show the correct behaviour of the Util.splitEnhanced() function).

Tests

util_spec

• test isOnlyWhitespaces - verifies the correct behaviour of Util.isOnlyWhitespaces();
• test splitEnhanced - verifies the correct behaviour of Util.splitEnhanced(). In particular, the usage of quotedFields, escaped double quotes and errors;

enforcer_spec

• test regexMatch - verifies the regexMatch behaviour of the new example, which exploits the new "quoted fields" feature.

[github-actions]

🎉 This PR is included in version 1.41.9 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀