Regex visualized as 3D marble run

What you want is something akin to a Raku (perl6) grammar, which was their enhancement to matching they developed to go beyond regular expressions.

    grammar IniFile {
        token key   { \w+ }
        token value { <-[\n;]>+ }
        token pair  { <key> \h* '=' \h* <value> \n+ }
        token TOP   { <pair>+ }
    }

    my $text = "user = alice\nrole = admin\n";
    my $match = IniFile.parse($text);

    if $match {
        say "Parsed successfully!";
    }

There are various libraries for other languages that try to accomplish something similar or Port the concept, so if this interests you, maybe you can find one. Or in this day and age, maybe you can have some VC (and much of society) subsidize the fairly quick creation of a library for you language of choice through AI.

If you're not looking for that, and more specifically what you have shown above, there are often ways to accomplish that in certain languages. In Perl it's easy because you can use regex cars in a regex, so you can just assign `my $digit = qr/(? :0-9)/;` and then use it in the regex as you did (and Perl already supports non matching whitespace with a flag). For that matter, Perl regexes allow you to define chunks purely within the regex to be reused in a DEFINE block, so possibly that is a feature other regex engines have as well.

In practice, including a unit test for any nontrivial regex in your application is very helpful. You can demonstrate which sorts of strings are expected to match and, maybe more importantly, which ones are not expected to match. The same goes for testing the capture group contents.

It may feel silly to have a whole unit test for a one-line regex, but that one line can be really dense. If you wrote a function to parse the string without regex, that function would be complex enough to warrant a unit test, after all.

Introducing regressions when tweaking a regex in your application is also a big risk which unit tests can help mitigate.

If you want readability you can write

    ^(?P<country_code>\+[0-9]{1,3}-?)?[0-9]{3}-[0-9]{3}-[0-9]{4}$

Most regex engines even have a verbose mode (typically the x flag) where this is a valid regex:

  ^
  (   
      \+
      [0-9]{1,3}
      -?
  )?   # optional country code
  [0-9]{3}
  -
  [0-9]{3}
  -
  [0-9]{4}
  $

I am not sure if everyone writes unreadable regex because the reputation of regex makes it seem pointless to try, or if being witty one-liners is a critical part of the value proposition of regex

Regex in xml? Now you have 2 problems. And the comments are not xml comments even.

Ultimately it is a dsl. Should equations in math also use full words and comments?

No, they should not. Maybe a nice syntax for grammars like raku is a better approach.

There are certainly alternatives, like https://pomsky-lang.org/

Most regex dialects allow whitespace and comments, so that already gets you halfway there.

wouldn't it be easier to just add a comment block in the code above the regex?

You can enable extended mode for most engines, which allows you to add white space and comments.

Personally, I like regexes, in the same way that I like shell string manipulation: it looks utterly inscrutable, and performs magic. If I write one in code meant for others, I usually use extended mode with each line commented.

I think some languages do have a library-style version of regex. But the function names aren't consistent between the different libraries. Maybe then we need to put on special goggles to make them look the same.

Autodidact here. Beyond just the five core quantifiers

  .
  |
  ?
  *
  +

regex only has capture groups

  ()

and lazy variants of the core quantifiers "?", "*" and "+", which are helpfully called:

  ??
  *?
  +?

The rest is just shorthands.

So while I think it's a worthwhile suggestion not to show people the whole thing the first time round, I doubt that the whole thing is really that complicated.

  Regexes (or NFAs, or DFAs) classify exactly the properties of strings which can be checked in constant space.

add to that

- using groups "(" .. ")" in replacement "\"i

- character ranges "[" .. "]"

- character classes "[:" .. ":]"

- multiline match

- ignore case

- beginning / end of line / word