Groupe capturant nommé : (?<name>...)

Syntaxe

(?<name>pattern)

Paramètres

pattern

Un motif constitué de tout ce que vous pouvez utiliser dans un littéral d'expression rationnelle, y compris une disjonction.

name

Le nom du groupe. Doit être un identifiant valide.

Description

Les groupes capturant nommés peuvent être utilisés de la même manière que les groupes capturant — ils ont également leur index de correspondance dans le tableau de résultats, et ils peuvent être référencés par \1, \2, etc. La seule différence est qu'ils peuvent être en plus référencés par leur nom. Les informations sur la correspondance du groupe capturant peuvent être accessibles avec :

• La propriété groups de la valeur retournée par RegExp.prototype.exec(), String.prototype.match() et String.prototype.matchAll()
• Le paramètre groups de la fonction de rappel replacement des méthodes String.prototype.replace() et String.prototype.replaceAll()
• Les rétro-références nommées dans le même motif

Tous les noms doivent être uniques dans un même motif. Plusieurs groupes capturant nommés portant le même nom provoquent une erreur de syntaxe.

/(?<name>)(?<name>)/; // SyntaxError: Invalid regular expression: Duplicate capture group name

Cette restriction est assouplie si les groupes capturant nommés en double ne figurent pas dans la même alternative de disjonction, de sorte qu'un seul groupe capturant nommé puisse correspondre pour une même chaîne de caractères en entrée. Cette fonctionnalité est récente ; vérifiez la compatibilité des navigateurs avant de l'utiliser.

/(?<year>\d{4})-\d{2}|\d{2}-(?<year>\d{4})/;
// Fonctionne ; "year" peut apparaître avant ou après le trait d'union

Tous les groupes capturant nommés figurent dans le résultat. Si un groupe capturant nommé ne correspond pas (par exemple, s'il appartient à une alternative non correspondante dans une disjonction), la propriété correspondante de l'objet groups vaut undefined.

/(?<ab>ab)|(?<cd>cd)/.exec("cd").groups; // [Object: null prototype] { ab: undefined, cd: 'cd' }

Vous pouvez obtenir les indices de début et de fin de chaque groupe capturant nommé dans la chaîne de caractères d'entrée à l'aide de l'indicateur d. Vous pouvez les consulter dans la propriété indices du tableau retourné par exec(), ainsi que par leurs noms dans indices.groups.

Par rapport aux groupes capturant non nommés, les groupes capturant nommés présentent les avantages suivants :

• Ils vous permettent de donner un nom descriptif au résultat de chaque sous-correspondance.
• Ils vous permettent d'accéder aux résultats des sous-correspondances sans devoir mémoriser leur ordre dans le motif.
• Lors de la re-factorisation du code, vous pouvez modifier l'ordre des groupes de capture sans risquer de casser d'autres références.

Exemples

Utiliser les groupes capturant nommés

L'exemple suivant extrait un horodatage et le nom d'un auteur·ice d'une entrée de journal Git (produite avec git log --format=%ct,%an -- filename) :

function analyserJournaux(entree) {
  const { auteur, chronologie } = /^(?<chronologie>\d+),(?<auteur>.+)$/.exec(
    entree,
  ).groups;
  return `${auteur} committed on ${new Date(
    parseInt(chronologie, 10) * 1000,
  ).toLocaleString()}`;
}

analyserJournaux("1560979912,Caroline"); // "Caroline committed on 6/19/2019, 5:31:52 PM"

Spécifications

Compatibilité des navigateurs

Voir aussi

• La prothèse d'émulation des groupes capturant nommés dans core-js ^(angl.)
• Le guide des groupes et rétro-références
• Expressions rationnelles
• Groupe capturant : (...)
• Groupe non capturant : (?:...)
• Rétro-référence nommée : \k<name>
• Règle d'ESLint : prefer-named-capture-group ^(angl.)