Rename Suggested: Write-RegEx should be New-RegEx

[HerbM]

** PREFACE: I love this. Thx.**

The documentation (readme and help) for Write-Regex states that:

Write-Regex -CharacterClass Digit -Repeat # This writes the Regex (\d+)

However, this only "writes" 3 blanks lines.

To Reproduce
Write-Regex -CharacterClass Digit -Repeat # This writes the Regex (\d+)

Expected behavior
Expect the pattern '\d+' to appear as the comment indicates.

Actual behavior
3 blank lines.
What is actually being "written" is the Regex object itself, since apparently there is a default formatter for regexes that produce this output.

Additional context
The following will show all of the object properties (as will | Format-Table *)

Write-Regex -CharacterClass Digit -Repeat | Select-Object *

The pattern can also be seen by accessing the "Pattern" property or using the ToString() method of the regex object.

This is not a bug in Irregular's cmdlets (IMO) but rather a serious issue in the documentation and help.

Write-* cmdlets (practically) all produce (some) screen output in the default case -- due to the formatters.

Those who don't understand GetType(), Get-Member, or using Format explicitly or Select-Object will have a hard time understanding what Write-Regex is actually doing.

I can't decide if this is truly non-standard behavior for a Write-* cmdlets or simply surprising because the result is so different (and the text is hidden).

However, it did cost me a few minutes, first thinking that maybe my 7.2 RC PowerShell was buggy, then trying it in 5.1, and finally investigating deeper.

I suspect many people will give up and walk away from it, and maybe even from this excellent module.

STRONGLY recommend

1. Adding (much) more to the Description area of the Write-Regex Help
2. Adding explanations in the existing examples
3. Adding explicit examples to show how to display the fields.**

[StartAutomating]

@HerbM there's a lot of rationale behind this, and it could be better explained in the documentation.

Thus I won't close the issue until I've added some more documentation to Write-RegEx, despite this behaving "as intended".

The short answer of the rationale is that, if the regex is valid, Write-RegEx should return that as a [RegEx].

This enables:

• Ad-hoc use of generated Regular expressions (e.g. $digits = Write-Regex -CharacterClass Digits -Repeat; $digits.Match("abc123"))
• Determination if a regex is valid until a given point (if the Regex is invalid, it will return a property bag instead)
• Piping the Regex into Use-RegEx

It also works with one of my general philosophies of Cmdlet Development: return the most useful type of object.

If Write-RegEx returned strings, it wouldn't be very helpful. If it returned an object that would only work well with Irregular's other commands, it wouldn't be as helpful. Returning a Regex can be helpful to anyone.

Please let me know if this makes sense to you, and how you'd like this reflected in documentation.

Thx

[HerbM]

@StartAutomating Absolutely correct, and I'd hope that was clear in my submission.
This is mainly a doc deficiency due to the behavior of the default formatted of an emitted regex.
You don't control that formatter and cannot reasonably correct or change that.
And of course I agree you do well to return the most useful object, i.e. dotnet Regex.
Fixing the read me and bleeding up the Help should be sufficient.

FYI: I would probabably have chosen to use New-Regex rather than Write-Regex which more strongly implies not just returning one but also displaying it if it's not captured.

Get could also have been used, but I believe you use that for another purpose & and since the function is creating a Regex, New would be a better choice.

[StartAutomating]

This is mainly a doc deficiency due to the behavior of the default formatted of an emitted regex.

Actually, Irregular defines a formatter for [Regex].

The default formatting behavior for a Regex doesn't display a Regex, it shows the three properties a [Regex] has: Options, MatchTimeOut, and RightToLeft

Irregular adds a colorizer (with a little help from another module, EZOut to write the formatter)

Fixing the read me and bleeding up the Help should be sufficient.

Fixing it how / updating what?

FYI: I would probably have chosen to use New-Regex rather than Write-Regex which more strongly implies not just returning one but also displaying it if it's not captured.

Upon reflection, I think you're correct here. New-RegEx seems the more appropriate command name. Would you be opposed to renaming it to New-Regex? What about aliasing Write-Regex to New-Regex for the next several versions?

@HerbM what do you think?

[HerbM]

Alias is a good solution.

Do you think my PowerShell 7.2 or something is causing formatter to not work?

Fixing that would still be useful.

[StartAutomating]

@HerbM I'll rename the cmdlet and alias Write-Regex. I'll leave this issue open until the change is made.

As far as the formatter goes, I believe it's working as intended. Under normal circumstances, I want a Regex to render as it's pattern, and colorize as much of it as the host will allow.

The PowerShell formatting engine is the likely culprit of the leading/trailing line.

[HerbM]

I like your solutions, @StartAutomating

On 7.2 Release Write-Regex is not showing the pattern. It's not showing anything but 3 blank lines.

"[";write-regex 'abc|efg';"]"
[


]

If I embed it in string evalute it it turns into the pattern string:

"[$(write-regex 'abc|efg')]"      # Square brackets are just my way to see blanks etc
[abc|efg]

If I just capture or output it showing all fields it looks like this:

write-regex 'abc|efg'
GroupNames   : 0
Pattern      : abc|efg
IsValid      : True
Options      : IgnoreCase, IgnorePatternWhitespace
RightToLeft  : False
MatchTimeout : 00:00:05

My guess it's some problem with 7.2 picking up the formatter.

I'll try to investigate later.

[StartAutomating]

@HerbM what you're observing is a general known behavior of the formatting engine in PowerShell I like to call the "Heterogenous Output Bug"

Basically:

A series of objects are formatted according to their first object shape.
Thus objects of different shapes cannot be formatted together without side-effects.
This most commonly will exhibit itself as a row with all blank properties in a table formatter.
You're seeing it because you're trying to emit a pipeline of [string], [regex], [string].

Hope this helps

[HerbM]

The phenomenon you describe is real, for collections containing different object and incompatible types.

(Get-ChildItem works fine for dir & file objects, and the best example of WHEN to break the 1-rule. )

However, that's not what I was doing.

I was merely calling for one regex & emitting it, and it's showing up as blank lines.

All the other efforts were merely to try to discover what it was really doing.

Presumably you have it working in other versions.

Or maybe it's something odd about my machine itself.

I'll take a closer look.