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.

Active = [bool]

Property

Product: 

Transformer Library

Class: 

Rule

Gets or sets a value indicating whether the rule is active and will be considered during pattern matching operations.

Remarks

The Active property provides a way to enable or disable a Rule at runtime without permanently deleting it. When a rule is inactive (false), the Transformer will completely ignore it during a Find(), Filter(), or Transform() operation.

This is a powerful feature for dynamically changing the behavior of a parser or for managing different sets of rules for different modes of operation.

⚙️ Getter and Setter Behavior

This property functions as both a getter and a setter:

  • Getter: var isActive = myRule.Active;Returns true if the rule is active (the default), and false if it has been disabled.

  • Setter: myRule.Active = false;Sets the active state of the rule. This (SetActive() method in VB and C#, or Active() in C++) returns the Rule object itself, allowing for a fluent, chainable syntax.

⚠️ Re-evaluation is Required

It is crucial to understand that changing a rule's Active state does not immediately affect the results of a previous transformation. You must call Find(), Filter(), or Transform() again to re-evaluate the input text with the updated rule set.

Active vs. Release() vs. Focusable()

Choose the right tool for managing a rule's lifecycle:

MethodPurposeStateReversibility
@Active(false)Temporarily disable a rule.The rule's definition is preserved in memory.Fully reversible by calling @Active(true).
Release()Permanently delete a rule.The rule is removed from memory and its resources are freed.Irreversible. The rule must be redefined.
@Focusable(false)Visually filter a rule's matches from the result list.The rule remains active and participates in matching, but its results can be hidden.Fully reversible. Does not require a re-scan.

💡 Why uCalc? (Comparative Analysis)

In most regex-based systems, "disabling" a pattern is not a built-in feature. A developer would typically have to:

  1. Store regex patterns as strings.
  2. Programmatically build a final "master" regex string by concatenating only the active patterns.
  3. Recompile the entire master regex object whenever the active set changes.

This is verbose, inefficient, and error-prone, especially when dealing with complex patterns.

uCalc's Active property provides a declarative, high-performance alternative. You define all your rules once, and then simply toggle their state with a boolean flag. The engine handles the complexity of ignoring inactive rules efficiently, leading to cleaner, more maintainable, and more dynamic code.

Examples

Succinct: Demonstrates the basic toggle functionality of the Active property.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
string UserText = "The cat saw another cat.";
t.Text = UserText;

// Define a rule and hold its handle
var catRule = t.FromTo("cat", "dog");

Console.Write("1. Rule Active (Default): ");
Console.WriteLine(t.Transform());

// Deactivate the rule
catRule.Active = false;

// Re-run the transform to see the change
Console.Write("2. Rule Inactive: ");
t.Text = UserText;
Console.WriteLine(t.Transform());

// Reactivate the rule
catRule.Active = true;
Console.Write("3. Rule Reactivated: ");
Console.WriteLine(t.Transform());
				
			
1. Rule Active (Default): The dog saw another dog.
2. Rule Inactive: The cat saw another cat.
3. Rule Reactivated: The dog saw another dog.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   string UserText = "The cat saw another cat.";
   t.Text(UserText);

   // Define a rule and hold its handle
   auto catRule = t.FromTo("cat", "dog");

   cout << "1. Rule Active (Default): ";
   cout << t.Transform() << endl;

   // Deactivate the rule
   catRule.Active(false);

   // Re-run the transform to see the change
   cout << "2. Rule Inactive: ";
   t.Text(UserText);
   cout << t.Transform() << endl;

   // Reactivate the rule
   catRule.Active(true);
   cout << "3. Rule Reactivated: ";
   cout << t.Transform() << endl;
}
				
			
1. Rule Active (Default): The dog saw another dog.
2. Rule Inactive: The cat saw another cat.
3. Rule Reactivated: The dog saw another dog.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim UserText As String = "The cat saw another cat."
      t.Text = UserText
      
      '// Define a rule and hold its handle
      Dim catRule = t.FromTo("cat", "dog")
      
      Console.Write("1. Rule Active (Default): ")
      Console.WriteLine(t.Transform())
      
      '// Deactivate the rule
      catRule.Active = false
      
      '// Re-run the transform to see the change
      Console.Write("2. Rule Inactive: ")
      t.Text = UserText
      Console.WriteLine(t.Transform())
      
      '// Reactivate the rule
      catRule.Active = true
      Console.Write("3. Rule Reactivated: ")
      Console.WriteLine(t.Transform())
   End Sub
End Module
				
			
1. Rule Active (Default): The dog saw another dog.
2. Rule Inactive: The cat saw another cat.
3. Rule Reactivated: The dog saw another dog.
How to dynamically enable or disable transformation rules using the Active property.
				
					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>");

var BoldTag = t.Pattern("<b>{text}</b>");
var H3Tag = t.Pattern("<h3>{text}</h3>");
t.Find();


Console.WriteLine(t.Matches.Text);
Console.WriteLine("");

BoldTag.Active = false;
Console.WriteLine($"BoldTag.Active(): {BoldTag.Active}");
Console.WriteLine("-----------------------");
t.Find();
Console.WriteLine(t.Matches.Text);
Console.WriteLine("");

BoldTag.Active = true;
Console.WriteLine($"BoldTag.Active(): {BoldTag.Active}");
Console.WriteLine("----------------------");

t.Find();
Console.WriteLine(t.Matches.Text);
Console.WriteLine("");

				
			
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>

BoldTag.Active(): False
-----------------------
<h3>Title</h3>
<h3>Title B</h3>

BoldTag.Active(): True
----------------------
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

#define tf(IsTrue) ((IsTrue) ? "True" : "False")

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>");

   auto BoldTag = t.Pattern("<b>{text}</b>");
   auto H3Tag = t.Pattern("<h3>{text}</h3>");
   t.Find();


   cout << t.Matches().Text() << endl;
   cout << "" << endl;

   BoldTag.Active(false);
   cout << "BoldTag.Active(): " << tf(BoldTag.Active()) << endl;
   cout << "-----------------------" << endl;
   t.Find();
   cout << t.Matches().Text() << endl;
   cout << "" << endl;

   BoldTag.Active(true);
   cout << "BoldTag.Active(): " << tf(BoldTag.Active()) << endl;
   cout << "----------------------" << endl;

   t.Find();
   cout << t.Matches().Text() << endl;
   cout << "" << endl;

}
				
			
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>

BoldTag.Active(): False
-----------------------
<h3>Title</h3>
<h3>Title B</h3>

BoldTag.Active(): True
----------------------
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>
				
					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>")
      
      Dim BoldTag = t.Pattern("<b>{text}</b>")
      Dim H3Tag = t.Pattern("<h3>{text}</h3>")
      t.Find()
      
      
      Console.WriteLine(t.Matches.Text)
      Console.WriteLine("")
      
      BoldTag.Active = false
      Console.WriteLine($"BoldTag.Active(): {BoldTag.Active}")
      Console.WriteLine("-----------------------")
      t.Find()
      Console.WriteLine(t.Matches.Text)
      Console.WriteLine("")
      
      BoldTag.Active = true
      Console.WriteLine($"BoldTag.Active(): {BoldTag.Active}")
      Console.WriteLine("----------------------")
      
      t.Find()
      Console.WriteLine(t.Matches.Text)
      Console.WriteLine("")
      
   End Sub
End Module
				
			
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>

BoldTag.Active(): False
-----------------------
<h3>Title</h3>
<h3>Title B</h3>

BoldTag.Active(): True
----------------------
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>
Toggling a rule on and off.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var r = t.FromTo("Hello", "Hi");

// Disable
r.Active = false;
Console.WriteLine(t.Transform("Hello").Text); // Output: Hello (No change)

// Enable
r.Active = true;
Console.WriteLine(t.Transform("Hello").Text); // Output: Hi
				
			
Hello
Hi
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   auto r = t.FromTo("Hello", "Hi");

   // Disable
   r.Active(false);
   cout << t.Transform("Hello").Text() << endl; // Output: Hello (No change)

   // Enable
   r.Active(true);
   cout << t.Transform("Hello").Text() << endl; // Output: Hi
}
				
			
Hello
Hi
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim r = t.FromTo("Hello", "Hi")
      
      '// Disable
      r.Active = false
      Console.WriteLine(t.Transform("Hello").Text) '// Output: Hello (No change)
      
      '// Enable
      r.Active = true
      Console.WriteLine(t.Transform("Hello").Text) '// Output: Hi
   End Sub
End Module
				
			
Hello
Hi
Previous
Next