YetAnotherStringMatcher 1.0.3

YetAnotherStringMatcher

YetAnotherStringMatcher library tries to make string matching easier, more readable while being somewhat expressive.

It tries to replace Regex to some extent, mostly when it comes to relatively basic cases.

For now it is in very early version and apart from the errors, then it may lack of "obvious things" and be kinda inconsistent in its APIs

Source Code: https://github.com/xd-loler/YetAnotherStringMatcher/tree/master/src/Core

Tests: https://github.com/xd-loler/YetAnotherStringMatcher/blob/master/src/Tests/BasicTests.cs

How to install

• .NET CLI: dotnet add package YetAnotherStringMatcher --version 1.0.3

• Package Manager: Install-Package YetAnotherStringMatcher -Version 1.0.3

• Package Reference: <PackageReference Include="YetAnotherStringMatcher" Version="1.0.3" />

• Nuget.org URL: https://www.nuget.org/packages/YetAnotherStringMatcher/

Some random examples, more in specific API description below

// Polish Postal Code
var input = "12-345";

var result = new Matcher(input)
                 .MatchDigitsOfLength(2)
                 .Then("-")
                 .ThenDigitsOfLength(3)
                 .Check();

Assert.True(result.Success);

var matcher = new Matcher("[2021-09-05] ERROR: Message1! Exception!")
                  .Match("[2021-09-05]")
                  .ThenAnything()
                  .Then("Exception!")
                  .Check();
				  
Assert.True(matcher.Success);

var input = new List<string>
{
	"[2021-09-05] ERROR: Message1",
	"[2021-09-05] WARNING: Message1",
	"[2021-09-05] INFO: Message1",
	"[2021-09-07] WARNING: Message1",
};

var pattern = new Matcher()
		  .Match("[2021-09-05] ")
		  .ThenAnyOf("WARNING:", "ERROR:");

Assert.True(pattern.Check(input[0]).Success);
Assert.True(pattern.Check(input[1]).Success);

Assert.False(pattern.Check(input[2]).Success);
Assert.False(pattern.Check(input[3]).Success);

var matcher = new Matcher("Apple Watermelon")
                  .MatchAnyOf("Apple", "Banana")
                  .Then(" ")
                  .ThenAnyOf("Giraffe", "melon", "Watermelon")
                  .Check();

Assert.True(matcher.Success);

var matcher = new Matcher("TEST")
                  .Match("test").IgnoreCase()
                  .Check();

Assert.True(matcher.Success);

// Sample Phone Number / Reusable Pattern
var input = new List<string> { "+123 345 67 89", "+1424 345 67 89" };

var pattern = new Matcher()
                  .Match("+")
                  .ThenDigitsOfLength(3)
                  .Then(" ")
                  .ThenDigitsOfLength(3)
                  .Then(" ")
                  .ThenDigitsOfLength(2)
                  .Then(" ")
                  .ThenDigitsOfLength(2);

Assert.True(pattern.Check(input[0]).Success);
Assert.False(pattern.Check(input[1]).Success);

var result = new Matcher("Apple Pineapple")
                .Match("Apple ")
                .Then("Coconut ").IsOptional()
                .Then("Pineapple")
                .Check();

Assert.True(result.Success);

var str = @"RROR: duplicate key value violates unique...
            Detail: Key (some_column)=(b01a0e23-da71-3a08-9893-11b8b2dfb069) already exists.";

var check = new Matcher(str)
                .MatchAnything()
                .Then("duplicate key value violates unique")
                .ThenAnything()
                .Then("Detail: Key ")
                .ThenExtract().ExtractAs("output")
                .Then(" already exists.")
                .Check();

Assert.True(check.Success);
Assert.Equal("(some_column)=(b01a0e23-da71-3a08-9893-11b8b2dfb069)", check.ExtractedData["output"]);

var result = new Matcher("Apple Water_Banana Watermelon")
		 .Match("Apple")
		 .ThenAnything()
		 .Then("Water")
		 .Then("melon")
		 .Check();
				 
Assert.True(result.Success);

Avaliable APIs:

Match / Then - tries to match exact string

var matcher = new Matcher("ERROR: Exception 1...")
                  .Match("ERROR: Exception ")
                  .ThenAnyOf("1", "2", "3")
                  .Check();

Assert.True(matcher.Success);

MatchAnyOf / ThenAnyOf - tries to match longest possible element of list handed as parameter.

var matcher = new Matcher("Apple Watermelon")
                  .MatchAnyOf("Apple", "Banana")
                  .Then(" ")
                  .ThenAnyOf("Giraffe", "melon", "Watermelon")
                  .Check();

Assert.True(matcher.Success);

MatchAnything / ThenAnything - matches anything non empty

var matcher = new Matcher("[2021-09-05] ERROR: Message1! Exception!")
                  .Match("[2021-09-05]")
                  .ThenAnything()
                  .Then("Exception!")
                  .Check();
				  
Assert.True(matcher.Success);

This one will FAIL:

var matcher = new Matcher("12")
                  .Match("1")
                  .ThenAnything()
                  .Then("2")
                  .Check();
				  
Assert.False(matcher.Success);

ThenExtract().ExtractAs(...) - next symbols will be extracted and returned as element of dictionary with under key provided by ExtractAs

var str = @"RROR: duplicate key value violates unique...
            Detail: Key (some_column)=(b01a0e23-da71-3a08-9893-11b8b2dfb069) already exists.";

var check = new Matcher(str)
                .MatchAnything()
                .Then("duplicate key value violates unique")
                .ThenAnything()
                .Then("Detail: Key ")
                .ThenExtract().ExtractAs("output")
                .Then(" already exists.")
                .Check();

Assert.True(check.Success);
Assert.Equal("(some_column)=(b01a0e23-da71-3a08-9893-11b8b2dfb069)", check.ExtractedData["output"]);

MatchAnythingOfLength / ThenAnythingOfLength - matches anything that has expected length

var matcher = new Matcher("01-000 London")
                  .Match("01")
                  .ThenAnythingOfLength(5)
                  .Then("London")
                  .Check();
				  
Assert.True(matcher.Success);

MatchDigitsOfLength / ThenDigitsOfLength - matches digits of expected length

var matcher = new Matcher("01-000 London")
                  .MatchDigitsOfLength(2)
                  .Then("-")
                  .MatchDigitsOfLength(3)
                  .Check();
				  
Assert.True(matcher.Success);

This one will FAIL:

var matcher = new Matcher("aa-000 London")
                  .MatchDigitsOfLength(2)
                  .Then("-")
                  .MatchDigitsOfLength(3)
                  .Check();

Assert.False(matcher.Success);

MatchDigitsWithLengthBetween / ThenDigitsWithLengthBetween - matches digits with length between [A...B]

var input = new List<string> { "12-000 London", "2-00 Zurich" };

var pattern = new Matcher()
                  .MatchDigitsWithLengthBetween(1, 2)
                  .Then("-")
                  .MatchDigitsWithLengthBetween(1, 3);

Assert.True(pattern.Check(input[0]).Success);
Assert.True(pattern.Check(input[1]).Success);

This one will FAIL:

var input = new List<string> { "121-000 London", "44-0011 Zurich" };

var pattern = new Matcher()
                  .MatchDigitsWithLengthBetween(1, 2)
                  .Then("-") // because it isn't on 3rd position
                  .MatchDigitsWithLengthBetween(1, 3);

Assert.False(pattern.Check(input[0]).Success);

MatchSymbolsOfLength / ThenSymbolsOfLength - matches symbols that are provided

var input = new List<string> { "+-123" };

var pattern = new Matcher()
                  .MatchSymbolsOfLength(new[] { '+','-'}, 2)
                  .MatchDigitsWithLengthBetween(1, 3)
                  .NoMore();

Assert.True(pattern.Check(input[0]).Success);

This one will FAIL:

var input = new List<string> { "+-123" };

var pattern = new Matcher()
                  .MatchSymbolsOfLength(new[] { '!','@'}, 2)
                  .MatchDigitsWithLengthBetween(1, 3)
                  .NoMore();

Assert.False(pattern.Check(input[0]).Success);

MatchCustomOfLength / ThenCustomOfLength - matches symbols that satisfy given predicate

Func<char, CheckOptions, bool> func = (char c, CheckOptions _) => char.IsUpper(c);

var matcher = new Matcher("ABC")
                  .MatchCustomOfLength(func, 3)
                  .Check();

Assert.True(matcher.Success);

This one will FAIL:

Func<char, CheckOptions, bool> func = (char c, CheckOptions _) => char.IsUpper(c);

var matcher = new Matcher("abc")
                  .MatchCustomOfLength(func, 3)
                  .Check();

Assert.False(matcher.Success);

NoMore - string must end here

var matcher = new Matcher("TEST123")
                  .Match("TEST")
                  .NoMore()
                  .Check();

Assert.False(matcher.Success);

IsOptional - matching will not fail if this particular element is not present

var result = new Matcher("Apple Pineapple")
                .Match("Apple ")
                .Then("Coconut ").IsOptional()
                .Then("Pineapple")
                .Check();

Assert.True(result.Success);

IgnoreCase - Ignores Case

var matcher = new Matcher("TEST")
                  .Match("test").IgnoreCase()
                  .Check();

Assert.True(matcher.Success);

IgnoreCaseForAllExisting - Ignores Case for all previous requirements

var matcher = new Matcher("TEST_ABC")
                  .Match("test_")
                  .Match("abc")
                  .IgnoreCaseForAllExisting()
                  .Check();

Assert.True(matcher.Success);

ExtractAs - read description of ThenExtract()

ThenCustom - You can provide your own implementation of IRequirement interface.

FAQ

• Should I use this on prod? Probably not (yet)

• Why does it use old C#? I wanted it to work even on old .NET

To Do List

• Improve error handling / add some additional information why given step failed

• Support more complex operations like ThenAnyOf(IRequirement, IRequirement, IRequirement...)

• Perform Benchmarks between this and Regex (System.Text.RegularExpressions)

• Complete Regex Generation https://github.com/xd-loler/YetAnotherStringMatcher/tree/master/src/RegexCodeGeneration

Experimental Features

It is possible to generate pure Regex from Matcher itself, but it will probably not support all kind of requirements because SomethingOfLenghtRequirement receives Func<char, CheckOptions, bool> which would be pretty diffcult to convert into Regex.

var text = "APPLE1";

var matcher = new Matcher()
                    .MatchAnyOf("Apple", "Watermelon").IgnoreCase();

var generator = new RegexGenerator(matcher.GetRequirements.ToList());

var result = generator.Emit();

Assert.True(result.Success);
Assert.False(string.IsNullOrWhiteSpace(result.Code));

// ("Apple", "Watermelon") are ordered by length.
Assert.Equal("(?i)(Watermelon|Apple)", result.Code);

var regex = new Regex(result.Code);

Assert.True(matcher.Check(text).Success);
Assert.Matches(regex, text);

var matcher = new Matcher()
                .Match("[2021-09-05] ")
                .ThenAnyOf("WARNING:", "ERROR:");

var generator = new RegexGenerator(matcher.GetRequirements.ToList());
var result = generator.Emit();
Console.WriteLine(result.Code); // ([2021-09-05] )(WARNING:|ERROR:)

var matcher = new Matcher()
                .MatchAnyOf("Apple", "Banana")
                .Then(" ")
                .ThenAnyOf("Giraffe", "melon", "Watermelon");

var generator = new RegexGenerator(matcher.GetRequirements.ToList());
var result = generator.Emit();
Console.WriteLine(result.Code); // (Banana|Apple)( )(Watermelon|Giraffe|melon)

Source code: https://github.com/xd-loler/YetAnotherStringMatcher/tree/master/src/RegexCodeGeneration

Tests: https://github.com/xd-loler/YetAnotherStringMatcher/blob/master/src/Tests/RegexCodeGenTests.cs

Some Naive Benchmarks

Source Code: https://github.com/xd-loler/YetAnotherStringMatcher/tree/master/src/Benchmarking

Results

.NET SDK=6.0.100-preview.5.21302.13
  [Host]     : .NET 5.0.9 (5.0.921.35908), X64 RyuJIT
  DefaultJob : .NET 5.0.9 (5.0.921.35908), X64 RyuJIT

Compiled:

Not Compiled:

Benchmark FAQ

• How to run Benchmark on my own computer?

Run this command inside \Benchmarking folder

dotnet run -c Release