Aller au contenu principal

@babel/parser

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

The Babel parser (previously Babylon) is a JavaScript parser used in Babel.

  • La dernière version d'ECMAScript activée par défaut (ES2020).

  • Attachement des commentaires.

  • Prise en charge de JSX, Flow et TypeScript.

  • Prise en charge des propositions de langage expérimentales (acceptation de PR pour toute proposition au moins au stage-0).

Crédits​

Fortement basé sur acorn et acorn-jsx, grâce au travail remarquable de @RReverser et @marijnh.

API​

babelParser.parse(code, [options])​

babelParser.parseExpression(code, [options])​

parse() analyse le code fourni comme un programme ECMAScript complet, tandis que parseExpression() tente d'analyser une seule Expression en privilégiant la performance. En cas de doute, utilisez .parse().

Options​

History
VersionChanges
v7.28.0Added sourceType: "commonjs"
v7.27.0Added allowYieldOutsideFunction
v7.26.0Added startIndex
v7.23.0Added createImportExpressions
v7.21.0Added allowNewTargetOutsideFunction and annexB
v7.16.0Added startColumn
v7.15.0Added attachComment
v7.7.0Added errorRecovery
v7.5.0Added allowUndeclaredExports
v7.2.0Added createParenthesizedExpressions

  • allowImportExportEverywhere: Par défaut, les déclarations import et export ne peuvent apparaître qu'au niveau supérieur d'un programme. Définir cette option à true les autorise partout où une instruction est permise.

  • allowAwaitOutsideFunction: Par défaut, l'utilisation de await n'est autorisée qu'à l'intérieur d'une fonction asynchrone ou, lorsque le plugin topLevelAwait est activé, dans la portée de niveau supérieur des modules. Définissez cette option à true pour l'accepter également dans la portée de niveau supérieur des scripts. Cette option est déconseillée au profit du plugin topLevelAwait.

  • allowYieldOutsideFunction: Par défaut, l'utilisation de yield n'est autorisée qu'à l'intérieur d'une fonction génératrice. Définissez cette option à true pour l'accepter également au niveau supérieur.

  • allowNewTargetOutsideFunction: Par défaut, l'utilisation de new.target n'est pas autorisée en dehors d'une fonction ou d'une classe. Définissez cette option à true pour accepter ce type de code.

  • allowReturnOutsideFunction: Par défaut, une instruction return au niveau supérieur lève une erreur. Définissez cette option à true pour accepter ce type de code.

  • allowSuperOutsideMethod: Par défaut, l'utilisation de super n'est pas autorisée en dehors des méthodes de classe et d'objet. Définissez cette option à true pour accepter ce type de code.

  • allowUndeclaredExports: Par défaut, exporter un identifiant non déclaré dans la portée du module actuel lèvera une erreur. Bien que ce comportement soit requis par la spécification des modules ECMAScript, le parseur de Babel ne peut anticiper les transformations ultérieures dans le pipeline de plugins qui pourraient insérer les déclarations appropriées. Il est donc parfois important de définir cette option à true pour empêcher le parseur de signaler prématurément des exportations non déclarées qui seront ajoutées ultérieurement.

  • attachComment: Par défaut, Babel attache les commentaires aux nœuds AST adjacents. Lorsque cette option est définie à false, les commentaires ne sont pas attachés. Cela peut améliorer les performances jusqu'à 30% lorsque le code d'entrée contient beaucoup de commentaires. @babel/eslint-parser le définira automatiquement. Il n'est pas recommandé d'utiliser attachComment: false avec la transformation Babel, car cela supprime tous les commentaires dans le code de sortie et rend les annotations comme /* istanbul ignore next */ non fonctionnelles.

  • annexB: Par défaut, Babel analyse JavaScript selon la syntaxe de l'annexe B d'ECMAScript "Additional ECMAScript Features for Web Browsers". Lorsque cette option est définie à false, Babel analysera la syntaxe sans les extensions spécifiques à l'annexe B.

  • createImportExpressions: Par défaut, l'analyseur syntaxique traite l'import dynamique import() comme des nœuds d'expression d'appel. Lorsque cette option est définie sur true, des nœuds AST ImportExpression sont créés à la place. Cette option sera activée par défaut (true) dans Babel 8.

  • createParenthesizedExpressions: Par défaut, l'analyseur définit extra.parenthesized sur les nœuds d'expression. Lorsque cette option est définie sur true, des nœuds AST ParenthesizedExpression sont créés à la place.

  • errorRecovery: Par défaut, Babel lève systématiquement une erreur lorsqu'il rencontre du code non valide. Lorsque cette option est définie sur true, il stocke l'erreur d'analyse et tente de poursuivre l'analyse du fichier non valide. L'AST résultant contiendra une propriété errors représentant un tableau de toutes les erreurs d'analyse. Notez que même avec cette option activée, @babel/parser peut lever des exceptions pour des erreurs irrécupérables.

  • plugins: Tableau contenant les plugins à activer.

  • sourceType: Indique le mode d'analyse du code. Peut être "script", "commonjs", "module" ou "unambiguous". Valeur par défaut : "script". "unambiguous" fait que @babel/parser tente de déduire le mode en fonction de la présence d'instructions ES6 import ou export. Les fichiers contenant des import ou export ES6 sont considérés comme "module", sinon "script".

    Le mode "commonjs" indique que le code s'exécute dans un environnement CommonJS comme Node.js. Il est largement compatible avec le mode "script", sauf que les déclarations return, new.target et using/await using sont autorisées au niveau supérieur.

  • sourceFilename: Met en corrélation les nœuds AST de sortie avec leur nom de fichier source. Utile lors de la génération de code et de source maps à partir d'AST de plusieurs fichiers.

  • startColumn: Par défaut, le code analysé est traité comme commençant à la ligne 1, colonne 0. Vous pouvez spécifier un numéro de colonne alternatif pour le début. Utile pour l'intégration avec d'autres outils de manipulation de code source.

  • startLine: Par défaut, le code analysé est traité comme commençant à la ligne 1, colonne 0. Vous pouvez spécifier un numéro de ligne alternatif pour le début. Utile pour l'intégration avec d'autres outils de manipulation de code source.

  • startIndex: Par défaut, tous les index source commencent à 0. Cette option permet de définir un index de départ alternatif. Pour garantir des index source AST précis, cette option doit toujours être spécifiée lorsque startLine est supérieur à 1. Utile pour l'intégration avec d'autres outils de manipulation de code source.

  • strictMode: Par défaut, le code ECMAScript est analysé en mode strict uniquement en présence d'une directive "use strict"; ou si le fichier est un module ECMAScript. Définissez cette option sur true pour toujours analyser les fichiers en mode strict.

  • ranges: Ajoute une propriété range à chaque nœud : [node.start, node.end]

  • tokens: Ajoute tous les jetons analysés à une propriété tokens du nœud File

Résultat​

L'analyseur syntaxique de Babel génère un AST conforme au [format AST de Babel]. Il est basé sur la [spécification ESTree] avec les écarts suivants :

note

Le plugin estree peut annuler ces écarts. Utilisez-le uniquement si vous passez l'AST de Babel à d'autres outils compatibles ESTree.

L'AST pour le code JSX est basé sur Facebook JSX AST.

Semver​

Le parseur Babel respecte semver dans la plupart des cas. La seule particularité à noter est que certaines corrections de bugs liées à la conformité aux spécifications peuvent être publiées sous forme de versions correctives (patch).

Par exemple : Nous publions une correction pour détecter plus tôt des erreurs comme #107 - plusieurs exportations par défaut dans un même fichier. Cela serait considéré comme une correction de bug même si cela entraîne l'échec d'une compilation.

Exemple​

JavaScript
require("@babel/parser").parse("code", {
  // parse in strict mode and allow module declarations
  sourceType: "module",

  plugins: [
    // enable jsx and flow syntax
    "jsx",
    "flow",
  ],
});

Plugins​

Divers​

NameCode Example
estree (repo)n/a

Extensions de langage​

History
VersionChanges
v7.6.0Added v8intrinsic
NameCode Example
flow (repo)var a: string = "";
flowComments (docs)/*:: type Foo = {...}; */
jsx (repo)<a attr="b">{s}</a>
typescript (repo)var a: string = "";
v8intrinsic%DebugPrint(foo);

Propositions ECMAScript​

History
VersionChanges
v7.23.0Added sourcePhaseImports, deferredImportEvaluation, optionalChainingAssign
v7.22.0Enabled regexpUnicodeSets by default, added importAttributes
v7.20.0Added explicitResourceManagement, importReflection
v7.17.0Added regexpUnicodeSets, destructuringPrivate, decoratorAutoAccessors
v7.15.0Added hack to the proposal option of pipelineOperator. Moved topLevelAwait, privateIn to Latest ECMAScript features
v7.14.0Added asyncDoExpressions. Moved classProperties, classPrivateProperties, classPrivateMethods, moduleStringNames to Latest ECMAScript features
v7.13.0Added moduleBlocks
v7.12.0Added classStaticBlock, moduleStringNames
v7.11.0Added decimal
v7.10.0Added privateIn
v7.9.0Added recordAndTuple
v7.7.0Added topLevelAwait
v7.4.0Added partialApplication
v7.2.0Added classPrivateMethods
NameCode Example
asyncDoExpressions (proposal)async do { await requestAPI().json() }
decimal (proposal)0.3m
decorators (proposal)
decorators-legacy		@a class A {}
decoratorAutoAccessors (proposal)class Example { @reactive accessor myBool = false; }
deferredImportEvaluation (proposal)import defer * as ns from "dep";
deprecatedImportAssert (⚠️ deprecated, legacy syntax of import attributes)
importAssertions (⚠️ deprecated)		import json from "./foo.json" assert { type: "json" };
destructuringPrivate (proposal)class Example { #x = 1; method() { const { #x: x } = this; } }
doExpressions (proposal)var a = do { if (true) { 'hi'; } };
explicitResourceManagement (proposal)using reader = getReader()
exportDefaultFrom (proposal)export v from "mod"
functionBind (proposal)a::b, ::console.log
functionSent (proposal)function.sent
importReflection (proposal)import module foo from "./foo.wasm";
moduleBlocks (proposal)let m = module { export let y = 1; };
optionalChainingAssign (proposal)x?.prop = 2
partialApplication (proposal)f(?, a)
pipelineOperator (proposal)a |> b
recordAndTuple (proposal)#{x: 1}, #[1, 2]
sourcePhaseImports (proposal)import source x from "./x"
throwExpressions (proposal)() => throw new Error("")

Latest ECMAScript features​

The following features are already enabled on the latest version of @babel/parser, and cannot be disabled because they are part of the language. You should enable these features only if you are using an older version.

NameCode Example
asyncGenerators (proposal)async function*() {}, for await (let a of b) {}
bigInt (proposal)100n
classProperties (proposal)class A { b = 1; }
classPrivateProperties (proposal)class A { #b = 1; }
classPrivateMethods (proposal)class A { #c() {} }
classStaticBlock (proposal)class A { static {} }
dynamicImport (proposal)import('./guy').then(a)
exportNamespaceFrom (proposal)export * as ns from "mod"
logicalAssignment (proposal)a &&= b
moduleStringNames (proposal)import { "😄" as smile } from "emoji";
nullishCoalescingOperator (proposal)a ?? b
numericSeparator (proposal)1_000_000
objectRestSpread (proposal)var a = { b, ...c };
optionalCatchBinding (proposal)try {throw 0;} catch{do();}
optionalChaining (proposal)a?.b
privateIn (proposal)#p in obj
regexpUnicodeSets (proposal)/[\p{Decimal_Number}--[0-9]]/v;
topLevelAwait (proposal)await promise in modules
importAttributes (proposal)import json from "./foo.json" with { type: "json" };

Options des plugins​

History
VersionChanges
7.21.0The default behavior of the decorators' decoratorsBeforeExport option is to allow decorators either before or after the export keyword.
7.19.0The syntaxType option of the recordAndTuple plugin defaults to hash; added allowCallParenthesized option for the decorators plugin.
7.17.0Added @@ and ^^ to the topicToken option of the hack pipeline operator
7.16.0Added disallowAmbiguousJSXLike for typescript plugin. Added ^ to the topicToken option of the hack pipeline operators
7.14.0Added dts for typescript plugin
note

Lorsqu'un plugin est spécifié plusieurs fois, seules les premières options sont prises en compte.

  • decorators:

    • allowCallParenthesized (boolean, par défaut true)

      Lorsque false, interdit les décorateurs sous la forme @(...)() au profit de @(...()). La proposition de décorateurs stage 3 utilise allowCallParenthesized: false.

    • decoratorsBeforeExport (boolean)

      Par défaut, les décorateurs sur les classes exportées peuvent être placés avant ou après le mot-clé export. Lorsque cette option est définie, les décorateurs ne seront autorisés qu'à la position spécifiée.

      JavaScript
      // decoratorsBeforeExport: true
      @dec
      export class C {}

      // decoratorsBeforeExport: false
      export @dec class C {}
      attention

      Cette option est dépréciée et sera supprimée dans une future version. Le code valide lorsque cette option est explicitement définie à true ou false reste valide sans cette option.

  • optionalChainingAssign:

    • version (requise, valeurs acceptées : 2023-07) Cette proposition est toujours au Stage 1, et sera donc probablement sujette à des changements cassants. Vous devez spécifier la version de la proposition utilisée pour garantir que Babel continuera d'analyser votre code de manière compatible.

  • pipelineOperator:

    • proposal (requis, valeurs acceptées : fsharp, hack, minimal, smart (obsolètes)) Il existe plusieurs propositions différentes pour l'opérateur pipeline. Cette option permet de choisir quelle proposition utiliser. Consultez plugin-proposal-pipeline-operator pour plus d'informations, notamment un tableau comparant leur comportement.
    • topicToken (requis lorsque proposal est hack, valeurs acceptées : %, #, ^, @@, ^^) La proposition hack utilise un espace réservé « topic » dans son pipeline. Il existe deux choix différents pour cet espace réservé. Cette option permet de choisir quel jeton utiliser pour faire référence au topic.

  • recordAndTuple:

    • syntaxType (hash ou bar, par défaut hash) Il existe deux variantes syntaxiques pour recordAndTuple. Elles partagent exactement la même sémantique à l'exécution.
      SyntaxTypeRecord ExampleTuple Example
      "hash"#{ a: 1 }#[1, 2]
      "bar"{| a: 1 |}[|1, 2|]
      Voir Ergonomics of #{}/#[] pour plus d'informations.

  • flow:

    • all (boolean, par défaut : false) Certains codes ont des significations différentes en Flow et en JavaScript standard. Par exemple, foo<T>(x) est analysé comme une expression d'appel avec un argument de type en Flow, mais comme une comparaison (foo < T > x) selon la spécification ECMAScript. Par défaut, babel-parser analyse ces constructions ambiguës comme des types Flow uniquement si le fichier commence par un pragma // @flow. Définissez cette option à true pour toujours analyser les fichiers comme si // @flow était spécifié.

  • typescript

    • dts (boolean, par défaut false) Cette option activera l'analyse dans un contexte ambiant TypeScript, où certaines syntaxes ont des règles différentes (comme les fichiers .d.ts et dans les blocs declare module). Voir https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html et https://basarat.gitbook.io/typescript/type-system/intro pour plus d'informations sur les contextes ambiants.
    • disallowAmbiguousJSXLike (boolean, par défaut false) Même lorsque le plugin jsx n'est pas activé, cette option interdit d'utiliser une syntaxe qui serait ambiguë avec JSX (assertions de type <X> y et arguments de type <X>() => {}). Cela correspond au comportement de tsc lors de l'analyse des fichiers .mts et .mjs.

  • importAttributes:

    • deprecatedAssertSyntax (boolean, par défaut : false)

      Lorsque true, permet d'analyser une ancienne version des attributs d'importation, qui utilisait le mot-clé assert au lieu de with.

      Cela correspond à la syntaxe initialement prise en charge par le plugin d'analyse importAssertions.

Codes d'erreur​

History
VersionChanges
v7.14.0Added error codes

Les codes d'erreur sont utiles pour gérer les erreurs levées par @babel/parser.

Il existe deux codes d'erreur : code et reasonCode.

  • code

    • Classification générale des erreurs (ex. BABEL_PARSER_SYNTAX_ERROR, BABEL_PARSER_SOURCETYPE_MODULE_REQUIRED).

  • reasonCode

    • Classification détaillée des erreurs (ex. MissingSemicolon, VarRedeclaration).

Exemple d'utilisation des codes d'erreur avec errorRecovery :

JavaScript
const { parse } = require("@babel/parser");

const ast = parse(`a b`, { errorRecovery: true });

console.log(ast.errors[0].code); // BABEL_PARSER_SYNTAX_ERROR
console.log(ast.errors[0].reasonCode); // MissingSemicolon

FAQ​

Le parser Babel prendra-t-il en charge un système de plugins ?​

Problèmes précédents : #1351, #6694.

Nous ne souhaitons pas actuellement nous engager à maintenir une API pour les plugins ou l'écosystème résultant (le maintien du propre système de plugins de Babel représente déjà un travail suffisant). Il n'est pas clair comment rendre cette API efficace, et cela limiterait notre capacité à refondre et optimiser la base de code.

Notre recommandation actuelle pour ceux qui souhaitent créer leur propre syntaxe personnalisée est que les utilisateurs créent un fork du parser.

Pour utiliser votre parser personnalisé, vous pouvez ajouter un plugin dans vos options pour appeler le parser via son nom de package npm ou le require si vous utilisez JavaScript.

JavaScript
const parse = require("custom-fork-of-babel-parser-on-npm-here");

module.exports = {
  plugins: [
    {
      parserOverride(code, opts) {
        return parse(code, opts);
      },
    },
  ],
};