dotnet / dotnet/docs

RegEx docs need improvements

Open
#23,335 0 comments 1 reaction 0 assignees View on GitHub
discussion
Dominant language
No language data
Stars
4.8k
Forks
6.1k
Avg merge
19h 10m
Merged PRs (30d)
268

Description

This issue is to track and discuss improvements we can make to the regex language overview pages.

TOC starts at https://docs.microsoft.com/dotnet/standard/base-types/regular-expression-language-quick-reference

To get the conversation started, here are some items we could potentially address.

------
### Placeholders

The placeholders use the older MSDN style where syntax was styled differently from placeholders.

Code
```markdown
`(` *subexpression* `)`
```

Result\
`(` *subexpression* `)`

#### Pros

1. The benefit of this is that the placeholder *subexpression* can be translated.

#### Cons

1. The downside to this is that it may be visually unappealing and hard to read, especially on bigger constructs:

`(?<` *name1* `-` *name2* `>` *subexpression* `)`

2. There are whitespaces introduced around the placeholder which may be confusing when looking at syntax.

#### Suggestion

The syntax could be adjusted to inline `code`. This is easier to maintain, but has the drawback of non translatable placeholders.

Code
```markdown
(subexpression)
```

Result\
`(subexpression)`

A bigger construct would look like this: `(?subexpression)`

------
### Multiline examples

Brought up in [22866](https://github.com/dotnet/docs/issues/22866#issuecomment-781633611) by @daveyostcom

The examples that use multiple code lines to break up bigger regular expressions are a bit hard to read. For example, in [grouping constructs](https://docs.microsoft.com/en-us/dotnet/standard/base-types/grouping-constructs-in-regular-expressions):

```csharp
string pattern = "^[^<>]*" +
"(" +
"((?'Open'<)[^<>]*)+" +
"((?'Close-Open'>)[^<>]*)+" +
")*" +
"(?(Open)(?!))$";
```

This example does use multiple string lines to demonstrate the different groups. Once the string is constructed, it's translated into `^[^<>]*(((?'Open'<)[^<>]*)+((?'Close-Open'>)[^<>]*)+)*(?(Open)(?!))$`.

#### Pros

1. Demonstrates grouping in an easier to read format.

#### Cons

1. You have to manage strings and multiple lines.

#### Suggestion

The code could enable the `RegexOptions.IgnorePatternWhitespace` regex option and then provide the string with white space.

```csharp
string pattern = @"
^
[^<>]*
(
( (?'Open' < ) [^<>]* )+
( (?'Close-Open' > ) [^<>]* )+
)*
(?(Open) (?!) )
$
";
```

This does provide a cleaner look to the regex code and removes the string syntax out of the way. The downsides are

1. The code has to be changed. The code examples used in these articles are still pointing to the legacy `/samples/snippets/` locations. This means moving them to the relative `snippets/markdown-file-name/` folder and potentially breaking code up into multiple projects.
2. Requires the use of a specific regex option. We do have this [option documented](https://docs.microsoft.com/dotnet/standard/base-types/regular-expression-options#ignore-white-space) though

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.