[go_router] docs: Document regex constraints on path parameters (flutter#177766)#11722
[go_router] docs: Document regex constraints on path parameters (flutter#177766)#11722NadeemIqbal wants to merge 2 commits into
Conversation
GoRoute.path supports constraining a path parameter to a regular expression via the :name(regex) syntax (parsed in path_utils.dart by _parameterRegExp and patternToRegExp), but the feature was undocumented; users found it only by trawling issues such as flutter/flutter#143070 and flutter/flutter#107240. Add a paragraph to GoRoute.path's dartdoc describing the supported syntax, explaining the matching semantics (segments that fail the pattern fall through), and noting the constraint that the regex must not introduce its own capturing groups. Fixes flutter/flutter#177766.
github-actions
Bot
added
p: go_router
triage-framework
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds documentation to GoRoute explaining how to constrain path parameters with regular expressions. Feedback suggests using raw string literals for regex examples to avoid escape sequence errors and clarifying that nested parentheses are not supported by the path parser.
| /// `:paramName(regex)`. The parameter only matches if the corresponding path | ||
| /// segment also matches the regular expression — segments that fail the | ||
| /// pattern fall through to other route candidates. For example, | ||
| /// `/users/:id(\d+)` matches `/users/42` but not `/users/alice`. The |
There was a problem hiding this comment.
The example path contains a backslash (\d). In Dart, this requires using a raw string literal or escaping the backslash to avoid an 'Invalid escape sequence' error. Using the raw string prefix r in the documentation makes the example more accurate and easier for developers to use directly.
| /// `/users/:id(\d+)` matches `/users/42` but not `/users/alice`. The | |
| /// `r'/users/:id(\d+)'` matches `/users/42` but not `/users/alice`. The |
| /// expression must not introduce its own capturing groups; everything | ||
| /// between the parentheses is interpreted as a Dart [RegExp] body. |
There was a problem hiding this comment.
The current implementation of the path parser (_parameterRegExp in path_utils.dart) does not support un-escaped nested parentheses. Additionally, the internal escaping of characters like :, =, and ! prevents the use of advanced features such as non-capturing groups ((?:...)) or lookarounds. It is more accurate to state that the expression must not contain nested parentheses.
| /// expression must not introduce its own capturing groups; everything | |
| /// between the parentheses is interpreted as a Dart [RegExp] body. | |
| /// expression must not contain nested parentheses; everything | |
| /// between the parentheses is interpreted as a Dart [RegExp] body. |
…m doc Address review feedback (flutter#11722): the parser disallows un-escaped nested parentheses (per `_parameterRegExp`'s `[^\\()]` class) and additionally escapes `:`, `=`, and `!`, which also prevents non-capturing groups and lookarounds. Saying the expression "must not contain nested parentheses" captures the actual constraint more accurately than "must not introduce its own capturing groups".
1 participant
Fixes flutter/flutter#177766.
Description
GoRoute.pathsupports constraining a path parameter to a regular expression via the:name(regex)syntax (parsed inpackages/go_router/lib/src/path_utils.dartby_parameterRegExpandpatternToRegExp), but the feature was undocumented. As the reporter noted on the issue, the feature is currently only discoverable by trawling related GitHub issues (flutter/flutter#143070, flutter/flutter#107240, flutter/flutter#117307). On the issue thread@justinmcconfirmed the addition "sounds reasonable to me".This PR adds a paragraph to
GoRoute.path's dartdoc that::paramName(regex)syntax.Documentation-only change; no API or behavior change.
List which issues are fixed by this PR.
flutter/flutter#177766
Pre-launch Checklist