uCalc API Version: 2.1.3-preview.2 Released: 6/16/2026

Warning

uCalc API Preview Release Notice:The documentation describes the intended behavior of the API. The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.

Rule = [Rule]

Property

Product: 

Transformer Library

Class: 

Match

Retrieves the Rule object that generated this specific match, enabling runtime introspection of the pattern and its properties.

Remarks

🕵️‍♀️ Introspection: Linking a Match to its Origin

The Rule property is a powerful introspection tool that returns the specific Rule object responsible for generating an individual match. This creates a direct link from a result (Match) back to its origin (the pattern definition), which is crucial for debugging and building context-aware logic.

When you iterate through a Matches collection, you can call this property on each Match to access the full metadata of the rule that found it.

🎯 What Can You Do with the Rule Object?

Once you retrieve the Rule object, you can query its properties to understand why the match occurred:

  • Description(): Get the human-readable description you assigned to the rule.
  • Name(): Get the rule's internal name (often derived from its pattern).
  • Pattern(): Get the original pattern string.
  • Tag(): Retrieve a custom integer tag for programmatic identification.
  • Behavioral Properties: Check flags like CaseSensitive(), WhitespaceSensitive(), etc.

💡 Comparative Analysis

This feature provides a significant advantage over traditional regular expression engines.

  • vs. .NET Regex.Match: In .NET, a Match object provides access to captured groups by name or index. However, it offers no direct link back to the Regex object that created it, let alone a specific sub-expression within a complex pattern. To achieve similar logic, you would need to use named capture groups and manually map those names back to your application's internal rule definitions. uCalc's Match.Rule property provides this link automatically and transparently. This makes building tools like syntax highlighters or debug visualizers significantly simpler, as you can directly query the source Rule for metadata like a Tag or Description to decide how to render the match.

Examples

Finds a single match and retrieves the name of the rule that generated it.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var ruleA = t.FromTo("apple", "fruit");
t.Text = "an apple a day";
t.Find();

var firstMatch = t.Matches[0];
var generatingRule = firstMatch.Rule;

Console.Write("Match text: '"); Console.Write(firstMatch.Text); Console.Write("' was found by rule: '"); Console.Write(generatingRule.Name); Console.Write("'");
				
			
Match text: 'apple' was found by rule: 'apple'
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   auto ruleA = t.FromTo("apple", "fruit");
   t.Text("an apple a day");
   t.Find();

   auto firstMatch = t.Matches()[0];
   auto generatingRule = firstMatch.Rule();

   cout << "Match text: '" << firstMatch.Text() << "' was found by rule: '" << generatingRule.Name() << "'";
}
				
			
Match text: 'apple' was found by rule: 'apple'
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim ruleA = t.FromTo("apple", "fruit")
      t.Text = "an apple a day"
      t.Find()
      
      Dim firstMatch = t.Matches(0)
      Dim generatingRule = firstMatch.Rule
      
      Console.Write("Match text: '")
      Console.Write(firstMatch.Text)
      Console.Write("' was found by rule: '")
      Console.Write(generatingRule.Name)
      Console.Write("'")
   End Sub
End Module
				
			
Match text: 'apple' was found by rule: 'apple'
Assigns descriptive text to multiple rules and uses the `Rule` property to identify which rule generated each match.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "<h3>Title</h3><b>Bold statement</b><h3>Title B</h3><b>Other text</b><p>My paragraph</p>";

var AnyOtherTag = t.Pattern("<{tag}>{text}</{tag}>").SetDescription("other kind of tag");
var BoldTag = t.Pattern("<b>{text}</b>").SetDescription("bold tag");
var H3Tag = t.Pattern("<h3>{text}</h3>").SetDescription("h3 tag");
t.Find();

foreach(var match in t.Matches) {
   Console.WriteLine(match.Text + "   Description: " + match.Rule.Description);
}
				
			
<h3>Title</h3>   Description: h3 tag
<b>Bold statement</b>   Description: bold tag
<h3>Title B</h3>   Description: h3 tag
<b>Other text</b>   Description: bold tag
<p>My paragraph</p>   Description: other kind of tag
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("<h3>Title</h3><b>Bold statement</b><h3>Title B</h3><b>Other text</b><p>My paragraph</p>");

   auto AnyOtherTag = t.Pattern("<{tag}>{text}</{tag}>").SetDescription("other kind of tag");
   auto BoldTag = t.Pattern("<b>{text}</b>").SetDescription("bold tag");
   auto H3Tag = t.Pattern("<h3>{text}</h3>").SetDescription("h3 tag");
   t.Find();

   for(auto match : t.Matches()) {
      cout << match.Text() + "   Description: " + match.Rule().Description() << endl;
   }
}
				
			
<h3>Title</h3>   Description: h3 tag
<b>Bold statement</b>   Description: bold tag
<h3>Title B</h3>   Description: h3 tag
<b>Other text</b>   Description: bold tag
<p>My paragraph</p>   Description: other kind of tag
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "<h3>Title</h3><b>Bold statement</b><h3>Title B</h3><b>Other text</b><p>My paragraph</p>"
      
      Dim AnyOtherTag = t.Pattern("<{tag}>{text}</{tag}>").SetDescription("other kind of tag")
      Dim BoldTag = t.Pattern("<b>{text}</b>").SetDescription("bold tag")
      Dim H3Tag = t.Pattern("<h3>{text}</h3>").SetDescription("h3 tag")
      t.Find()
      
      For Each match In t.Matches
         Console.WriteLine(match.Text + "   Description: " + match.Rule.Description)
      Next
   End Sub
End Module
				
			
<h3>Title</h3>   Description: h3 tag
<b>Bold statement</b>   Description: bold tag
<h3>Title B</h3>   Description: h3 tag
<b>Other text</b>   Description: bold tag
<p>My paragraph</p>   Description: other kind of tag
Internal Test: Uses integer tags to programmatically categorize matches and process them differently in a loop.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
t.Text = "Log: INFO message. Log: ERROR alert. Log: INFO another message.";

var infoRule = t.Pattern("Log: INFO {msg}.").SetTag(1); // Tag 1 for INFO
var errorRule = t.Pattern("Log: ERROR {msg}.").SetTag(99); // Tag 99 for ERROR

t.Find();

foreach(var match in t.Matches) {
   var ruleTag = match.Rule.Tag;
   if (ruleTag == 1) {
      Console.WriteLine($"Found informational log: {match.Text}");
   }
   if (ruleTag == 99) {
      Console.WriteLine($"!!! Found CRITICAL error: {match.Text} !!!");
   }
}
				
			
Found informational log: Log: INFO message.
!!! Found CRITICAL error: Log: ERROR alert. !!!
Found informational log: Log: INFO another message.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   t.Text("Log: INFO message. Log: ERROR alert. Log: INFO another message.");

   auto infoRule = t.Pattern("Log: INFO {msg}.").SetTag(1); // Tag 1 for INFO
   auto errorRule = t.Pattern("Log: ERROR {msg}.").SetTag(99); // Tag 99 for ERROR

   t.Find();

   for(auto match : t.Matches()) {
      auto ruleTag = match.Rule().Tag();
      if (ruleTag == 1) {
         cout << "Found informational log: " << match.Text() << endl;
      }
      if (ruleTag == 99) {
         cout << "!!! Found CRITICAL error: " << match.Text() << " !!!" << endl;
      }
   }
}
				
			
Found informational log: Log: INFO message.
!!! Found CRITICAL error: Log: ERROR alert. !!!
Found informational log: Log: INFO another message.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      t.Text = "Log: INFO message. Log: ERROR alert. Log: INFO another message."
      
      Dim infoRule = t.Pattern("Log: INFO {msg}.").SetTag(1) '// Tag 1 for INFO
      Dim errorRule = t.Pattern("Log: ERROR {msg}.").SetTag(99) '// Tag 99 for ERROR
      
      t.Find()
      
      For Each match In t.Matches
         Dim ruleTag = match.Rule.Tag
         If ruleTag = 1 Then
            Console.WriteLine($"Found informational log: {match.Text}")
         End If
         If ruleTag = 99 Then
            Console.WriteLine($"!!! Found CRITICAL error: {match.Text} !!!")
         End If
      Next
   End Sub
End Module
				
			
Found informational log: Log: INFO message.
!!! Found CRITICAL error: Log: ERROR alert. !!!
Found informational log: Log: INFO another message.
How to assign and retrieve descriptions for specific transformation patterns using SetDescription().
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Str("<h3>Title</h3><b>Bold statement</b><h3>Title B</h3><b>Other text</b><p>My paragraph</p>");

var AnyOtherTag = t.Pattern("<{tag}>{text}</{tag}>").SetDescription("other kind of tag");
var BoldTag = t.Pattern("<b>{text}</b>").SetDescription("bold tag");
var H3Tag = t.Pattern("<h3>{text}</h3>").SetDescription("h3 tag");
t.Find();

foreach(var match in t.Matches) {
   Console.WriteLine(match.Text + "   Description: " + match.Rule.Description);
}
				
			
<h3>Title</h3>   Description: h3 tag
<b>Bold statement</b>   Description: bold tag
<h3>Title B</h3>   Description: h3 tag
<b>Other text</b>   Description: bold tag
<p>My paragraph</p>   Description: other kind of tag
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Str("<h3>Title</h3><b>Bold statement</b><h3>Title B</h3><b>Other text</b><p>My paragraph</p>");

   auto AnyOtherTag = t.Pattern("<{tag}>{text}</{tag}>").SetDescription("other kind of tag");
   auto BoldTag = t.Pattern("<b>{text}</b>").SetDescription("bold tag");
   auto H3Tag = t.Pattern("<h3>{text}</h3>").SetDescription("h3 tag");
   t.Find();

   for(auto match : t.Matches()) {
      cout << match.Text() + "   Description: " + match.Rule().Description() << endl;
   }
}
				
			
<h3>Title</h3>   Description: h3 tag
<b>Bold statement</b>   Description: bold tag
<h3>Title B</h3>   Description: h3 tag
<b>Other text</b>   Description: bold tag
<p>My paragraph</p>   Description: other kind of tag
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Str("<h3>Title</h3><b>Bold statement</b><h3>Title B</h3><b>Other text</b><p>My paragraph</p>")
      
      Dim AnyOtherTag = t.Pattern("<{tag}>{text}</{tag}>").SetDescription("other kind of tag")
      Dim BoldTag = t.Pattern("<b>{text}</b>").SetDescription("bold tag")
      Dim H3Tag = t.Pattern("<h3>{text}</h3>").SetDescription("h3 tag")
      t.Find()
      
      For Each match In t.Matches
         Console.WriteLine(match.Text + "   Description: " + match.Rule.Description)
      Next
   End Sub
End Module
				
			
<h3>Title</h3>   Description: h3 tag
<b>Bold statement</b>   Description: bold tag
<h3>Title B</h3>   Description: h3 tag
<b>Other text</b>   Description: bold tag
<p>My paragraph</p>   Description: other kind of tag
Previous
Next