Add ToRegex method to WildcardPattern class

[yotsuda]

PR Summary

Add public ToRegex() method to WildcardPattern class for converting PowerShell wildcard patterns to regular expressions.

PR Context

Resolves #19992

PowerShell users often need to convert wildcard patterns to regular expressions for use in programs that accept regex. While the internal implementation already exists, it was not accessible through a public API.

This PR exposes the conversion functionality by adding a public ToRegex() method to the WildcardPattern class.

Usage Example

$pattern = [System.Management.Automation.WildcardPattern]::new("*.txt")
$regex = $pattern.ToRegex()
$regexObj = [regex]::new($regex)
$regexObj.IsMatch("file.txt")  # True

Conversion Rules

• * (asterisk) converts to .* in regex (matches zero or more characters)
• ? (question mark) converts to . (matches exactly one character)
• [abc], [a-z] (bracket expressions) preserve their regex meaning (character sets and ranges)
• Literal characters are escaped as needed (e.g., . → \.)
• For backward compatibility, some optimizations are applied (e.g., standalone * returns empty string)

PR Checklist

• [x] PR has a meaningful title
• [x] Summarized changes
• [x] Make sure all .h, .cpp, .cs, .ps1 and .psm1 files have the correct copyright header
• [x] This PR is ready to merge and is not Work in Progress
• Breaking changes
  • [x] None
• User-facing changes
  • [x] Documentation needed
    • [ ] Issue filed:
• Testing - New and feature
  • [x] Make sure you've added a new test if existing tests do not effectively test the code changed
• [x] New and old tests pass locally

Description

Implementation

Added a public ToRegex() method to the WildcardPattern class that:

• Leverages the existing internal PatternConvertedToRegex property
• Returns a string (not Regex object) for maximum flexibility
• Respects all WildcardOptions (IgnoreCase, CultureInvariant, Compiled)
• Includes comprehensive XML documentation with examples

Files Changed

• src/System.Management.Automation/engine/regex.cs - Added public ToRegex() method
• test/powershell/engine/WildcardPattern.Tests.ps1 - Added comprehensive test coverage (13 tests)

Testing

Added Pester tests covering:

• Basic wildcard conversions (*, ?, [])
• WildcardOptions handling (IgnoreCase, CultureInvariant)
• Consistency with WildcardPattern.IsMatch() behavior
• Edge cases (empty pattern, escaped characters, standalone *)
• Complex patterns (multiple wildcards, character ranges)

All 13 tests pass locally.

Additional Notes

• Pure addition - no breaking changes
• Uses existing optimized conversion logic
• Enables interoperability between PowerShell wildcards and regex-based tools

[iSazonov]

@daxian-dbw @SeeminglyScience Looking as the new method could be used should it return Regex type instead of string? I'd expect users want exactly get and use Regex and they will be forced to convert the string back to Regex. They can always call ToString() method themselves if necessary, for example, for debugging.

[iSazonov]

@yotsuda I think the method should return Regex. Could you please make the change? Already added tests are good in the case too.

[yotsuda]

@iSazonov @MatejKafka Thanks for the feedback!

I've updated ToRegex() to return Regex instead of string. The implementation now caches the Regex instance for subsequent calls.

Changes (ce1dcf368):

• ToRegex() returns Regex directly
• Added _regex field to cache the instance
• Removed the internal PatternConvertedToRegex property (was only used by ToRegex())
• Added a test to verify that calling ToRegex() multiple times returns the same instance