uCalc API Version: 2.1.3-preview.2 Released: 6/17/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.

GlobalRuleSet = [Rule]

Property

Product:

Transformer Library

Class:

Transformer

Gets a special Rule object used to define global, cumulative properties that apply across all rules in a transformation pass.

Remarks

Note: This feature is currently in the design phase and is not yet implemented in the production engine.

⚙️ Global Transformation Control: GlobalRuleSet

The GlobalRuleSet property provides access to a special Rule object that is not used for matching text itself. Instead, it acts as a central control panel for setting properties that have a cumulative effect on the entire Transformer operation. This is a powerful feature for establishing global constraints and validation logic.

Global vs. Default vs. Per-Rule Settings

It is crucial to understand the different scopes of rule configuration:

Configuration Method	Scope & Purpose
Per-Rule (`myRule.@StopAfter(5)`)	Individual. Affects only `myRule`. Each rule has its own independent counter and settings.
DefaultRuleSet	Template. Sets the initial property values for all new rules created in the transformer. Each rule still behaves independently.
`GlobalRuleSet` (This Property)	Global/Cumulative. Sets a shared, single limit for the entire transformer pass. The counter is shared across all rules.

Key Cumulative Properties

When set on the GlobalRuleSet, these properties have a cumulative effect:

@StopAfter(n): The entire transformation pass stops after a combined total of n matches have been found across all active rules.
@StartAfter(n): The transformation will skip the first n total matches found across all rules before it begins keeping results.
@Maximum(n): The entire transformation pass is invalidated (returning zero matches) if the combined total of matches from all rules exceeds n.
@Minimum(n): The entire transformation pass is invalidated if the combined total of matches from all rules is less than n.

⚠️ Performance & Memory Considerations

To enable the "all or nothing" validation behavior of global Minimum and Maximum properties, the Transformer may need to store a backup of the original string. If a global constraint is not met, the engine discards all results. This can consume more memory than a standard transformation.

💡 Why uCalc? (Comparative Analysis)

In a standard Regex-based workflow, enforcing a global match count is a manual, multi-step process:

Run searches for all patterns to get all possible matches.
Combine the match collections.
Write an if statement in your host language (C#, C++, etc.) to check if the total count meets your constraints.
If it doesn't, manually discard all results.

This is imperative, verbose, and inefficient. uCalc's GlobalRuleSet is declarative. You state your constraints directly on the Transformer, and the engine handles the complex validation and counting logic internally. This leads to cleaner, more expressive, and less error-prone code by keeping the validation logic tightly coupled with the transformation it governs.