diff --git a/boa/src/syntax/ast/keyword.rs b/boa/src/syntax/ast/keyword.rs index 80122af028..4530c11d2b 100644 --- a/boa/src/syntax/ast/keyword.rs +++ b/boa/src/syntax/ast/keyword.rs @@ -1,4 +1,4 @@ -//! This module implements the `Keyword` structure, which represents reserved words of The JavaScript language. +//! This module implements the `Keyword` structure, which represents reserved words of the JavaScript language. use std::{ error, @@ -21,35 +21,16 @@ use serde::{Deserialize, Serialize}; #[cfg_attr(feature = "serde-ast", derive(Serialize, Deserialize))] #[derive(Clone, Copy, PartialEq, Debug)] pub enum Keyword { - /// The `await` operator is used to wait for a [`Promise`][promise]. It can only be used inside an [async function][async-function]. - /// - /// Syntax: `[rv] = await x;` - /// - /// The await expression causes async function execution to pause until a Promise is settled (that is, fulfilled or rejected), - /// and to resume execution of the async function after fulfillment. When resumed, the value of the await expression is that of - /// the fulfilled Promise. - /// - /// If the Promise is rejected, the await expression throws the rejected value. + /// The `await` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-AwaitExpression) /// - [MDN documentation][mdn] /// /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await - /// [promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise - /// [async-function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function Await, - /// The break statement terminates the current loop, switch, or label statement and transfers program control to the statement following the terminated statement. - /// - /// Syntax: `break [label];` - /// - /// `label`(optional): - /// > Identifier associated with the label of the statement. If the statement is not a loop or switch, this is required. - /// - /// The break statement includes an optional label that allows the program to break out of a labeled statement. - /// The break statement needs to be nested within the referenced label. The labeled statement can be any block statement; - /// it does not have to be preceded by a loop statement. + /// The `break` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-BreakStatement) @@ -58,12 +39,7 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/break Break, - /// The `case` keyword is used to match against an expression in a switch statement. - /// - /// Syntax: `case x:` - /// - /// If the expression matches, the statements inside the case clause are executed until either the end of the - /// switch statement or a break. + /// The `case` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-CaseClause) @@ -72,16 +48,8 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch Case, - /// The `catch` keyword is use in `catch`-block contains statements that specify what to do if an exception is thrown in the try-block. - /// - /// Syntax: `try { ... } catch(x) { ... }` - /// - /// `x`: - /// > An identifier to hold an exception object for the associated `catch`-block. - /// - /// If any statement within the try-block (or in a function called from within the try-block) throws an exception, - /// control is immediately shifted to the catch-block. If no exception is thrown in the try-block, the catch-block is skipped. - /// + /// The `catch` keyword. + /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-Catch) /// - [MDN documentation][mdn] @@ -89,39 +57,17 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch Catch, - /// The `class` keyword is used to creates a new class with a given name using prototype-based inheritance. - /// - /// Syntax: `class [name [extends otherName]] { /* `[`class body`][class-body]` */ }` - /// - /// `name`: - /// > The name of the class. - /// - /// `otherName`: - /// > The inherited class name. + /// The `class` keyword. /// - /// You can also define a class using a class expression. But unlike a class expression, - /// a class declaration doesn't allow an existing class to be declared again and will throw a `SyntaxError` if attempted. - /// - /// The class body of a class declaration is executed in strict mode. The constructor method is optional. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ClassDeclaration) /// - [MDN documentation][mdn] /// /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/class - /// [class-body]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#Class_body_and_method_definitions Class, - /// The continue statement terminates execution of the statements in the current iteration of the current or labeled loop, - /// and continues execution of the loop with the next iteration. - /// - /// Syntax: `continue [label];` - /// - /// `label`(optional): - /// > Identifier associated with the label of the statement. - /// - /// The continue statement can include an optional label that allows the program to jump to the next iteration of a labeled - /// loop statement instead of the current loop. In this case, the continue statement needs to be nested within this labeled statement. + /// The continue keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ContinueStatement) @@ -130,18 +76,7 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/continue Continue, - /// Constants are block-scoped, much like variables defined using the let keyword. - /// - /// Syntax: `const name1 = value1 [, name2 = value2 [, ... [, nameN = valueN]]];` - /// - /// The const declaration creates a read-only reference to a value. - /// It does not mean the value it holds is immutable—just that the variable identifier cannot be reassigned. - /// - /// This constant declaration whose scope can be either global or local to the block in which it is declared. - /// Global constants do not become properties of the window object, unlike var variables. - /// - /// An initializer for a constant is required. You must specify its value in the same statement in which it's declared. - /// (This makes sense, given that it can't be changed later.) + /// The `const` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-let-and-const-declarations) @@ -150,11 +85,7 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const Const, - /// The `debugger` statement invokes any available debugging functionality, such as setting a breakpoint. - /// - /// Syntax: `debugger;` - /// - /// If no debugging functionality is available, this statement has no effect. + /// The `debugger` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-debugger-statement) @@ -163,25 +94,7 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger Debugger, - /// The `default` keyword can be used within a switch statement, or with an export statement. - /// - /// Syntax **in switch statement**: - /// ```text - /// switch (expression) { - /// case value1: - /// //Statements executed when the result of expression matches value1 - /// [break;] - /// default: - /// //Statements executed when none of the values match the value of the expression - /// [break;] - /// } - /// ``` - /// - /// The default keyword will help in any other case and executes the associated statement. - /// - /// Syntax **in export statement**: `export default name;` - /// - /// If you want to export a single value or need a fallback value for a module, a default export can be used. + /// The `default` keyword. /// /// More information: /// - [ECMAScript reference default clause](https://tc39.es/ecma262/#prod-DefaultClause) @@ -191,15 +104,7 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/default Default, - /// The JavaScript `delete` operator removes a property from an object. - /// - /// Syntax: `delete x` - /// - /// Unlike what common belief suggests, the `delete` operator has **nothing** to do with directly freeing memory. - /// Memory management is done indirectly via breaking references. - /// - /// The delete operator removes a given property from an object. On successful deletion, - /// it will return `true`, else `false` will be returned. + /// The `delete` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-delete-operator) @@ -208,24 +113,7 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/delete Delete, - /// The `do` keyword is used in `do...while` statement creates a loop that executes a specified statement - /// until the test condition evaluates to `false`. - /// - /// Syntax: - /// ```text - /// do - /// statement - /// while (condition); - /// ``` - /// - /// `statement` - /// > A statement that is executed at least once and is re-executed each time the condition evaluates to `true`. - /// - /// `condition` - /// > An expression evaluated after each pass through the loop. If condition evaluates to true, - /// the statement is re-executed. When condition evaluates to `false`, control passes to the statement following the `do...while`. - /// - /// The `do...while` loop iterates at least once and reiterates until the given condition return `false`. + /// The `do` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-do-while-statement) @@ -242,41 +130,7 @@ pub enum Keyword { /// Future reserved keywords. Enum, - /// The export statement is used when creating JavaScript modules to export functions, objects, or primitive values from the module. - /// - /// Syntax: - /// ```text - /// // Exporting individual features - /// export let name1, name2, …, nameN; // also var, const - /// export let name1 = …, name2 = …, …, nameN; // also var, const - /// export function functionName(){...} - /// export class ClassName {...} - /// - /// // Export list - /// export { name1, name2, …, nameN }; - /// - /// // Renaming exports - /// export { variable1 as name1, variable2 as name2, …, nameN }; - /// - /// // Exporting destructured assignments with renaming - /// export const { name1, name2: bar } = o; - /// - /// // Default exports - /// export default expression; - /// export default function (…) { … } // also class, function* - /// export default function name1(…) { … } // also class, function* - /// export { name1 as default, … }; - /// - /// // Aggregating modules - /// export * from …; // does not set the default export - /// export * as name1 from …; - /// export { name1, name2, …, nameN } from …; - /// export { import1 as name1, import2 as name2, …, nameN } from …; - /// export { default } from …; - ///``` - /// - /// There are two different types of export, named and default. You can have multiple named exports - /// per module but only one default export. + /// The `export` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-exports) @@ -285,13 +139,7 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export Export, - /// The extends keyword is used in class declarations or class expressions to create a class which is a child of another class. - /// - /// Syntax: `class ChildClass extends ParentClass { ... }` - /// - /// The extends keyword can be used to subclass custom classes as well as built-in objects. - /// - /// The .prototype of the extension must be an Object or null. + /// The `extends` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ClassHeritage) @@ -300,11 +148,7 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/extends Extends, - /// The finally statement lets you execute code, after try and catch, regardless of the result. - /// - /// Syntax: `try { ... } [catch( ... ) { ... }] [finally { ... }]` - /// - /// The catch and finally statements are both optional, but you need to use one of them (if not both) while using the try statement. + /// The `finally` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-Finally) @@ -313,26 +157,7 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch Finally, - /// The **`for` statement** creates a loop that consists of three optional expressions. - /// - /// Syntax: - /// ```text - /// for ([initialization]; [condition]; [final-expression]) - /// statement - /// - /// ``` - /// `initialization`: - /// > An expression (including assignment expressions) or variable declaration evaluated once before the loop begins. - /// - /// `condition`: - /// > An expression to be evaluated before each loop iteration. If this expression evaluates to true, statement is executed. - /// - /// `final-expression`: - /// > An expression to be evaluated at the end of each loop iteration. This occurs before the next evaluation of condition. - /// - /// `statement`: - /// > A statement that is executed as long as the condition evaluates to true. To execute multiple statements within the loop, - /// > use a block statement (`{ ... }`) to group those statements. + /// The `for` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ForDeclaration) @@ -341,29 +166,7 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for For, - /// The **`function` declaration** (function statement) defines a function with the specified parameters. - /// - /// Syntax: - /// ```text - /// function name([param[, param,[..., param]]]) { - /// [statements] - /// } - /// ``` - /// - /// `name`: - /// > The function name. - /// - /// `param`(optional): - /// > The name of an argument to be passed to the function. Maximum number of arguments varies in different engines. - /// - /// `statements`(optional): - /// > The statements which comprise the body of the function. - /// - /// A function created with a function declaration is a `Function` object and has all the properties, methods and behavior of `Function`. - /// - /// A function can also be created using an expression (see function expression). - /// - /// By default, functions return undefined. To return any other value, the function must have a return statement that specifies the value to return. + /// The `function` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-terms-and-definitions-function) @@ -372,52 +175,16 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function Function, - /// The **`if` statement** executes a statement if a specified condition is [`truthy`][truthy]. If the condition is [`falsy`][falsy], another statement can be executed. - /// - /// Syntax: - /// ```text - /// if (condition) - /// statement1 - /// [else - /// statement2] - /// ``` - /// - /// `condition`: - /// > An [expression][expression] that is considered to be either [`truthy`][truthy] or [`falsy`][falsy]. - /// - /// `statement1`: - /// > Statement that is executed if condition is truthy. Can be any statement, including further nested if statements. - /// - /// `statement2`: - /// > Statement that is executed if condition is [`falsy`][falsy] and the else clause exists. Can be any statement, including block statements and further nested if statements. - /// - /// Multiple `if...else` statements can be nested to create an else if clause. - /// - /// **Note** that there is no elseif (in one word) keyword in JavaScript. + /// The `if` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-IfStatement) /// - [MDN documentation][mdn] /// /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/if...else - /// [truthy]: https://developer.mozilla.org/en-US/docs/Glossary/truthy - /// [falsy]: https://developer.mozilla.org/en-US/docs/Glossary/falsy - /// [expression]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators#Expressions If, - /// The **`in` operator** returns `true` if the specified property is in the specified object or its prototype chain. - /// - /// Syntax: `prop in object` - /// - /// `prop`: - /// > A string or symbol representing a property name or array index (non-symbols will be coerced to strings). - /// - /// `object`: - /// > Object to check if it (or its prototype chain) contains the property with specified name (`prop`). - /// - /// If you delete a property with the `delete` operator, the `in` operator returns `false` for that property. - /// - /// If you set a property to `undefined` but do not delete it, the `in` operator returns true for that property. + /// The `in` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-RelationalExpression) @@ -426,20 +193,7 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/in In, - /// The **`instanceof` operator** tests whether the `prototype` property of a constructor appears anywhere in the `prototype` chain of an object. - /// - /// Syntax: `object instanceof constructor` - /// - /// `object`: - /// > The object to test. - /// - /// `constructor`: - /// > Function to test against. - /// - /// The **`instanceof` operator** tests the presence of `constructor.prototype` in object's `prototype` chain. - /// - /// Note that the value of an `instanceof` test can change based on changes to the `prototype` property of constructors. - /// It can also be changed by changing an object's prototype using `Object.setPrototypeOf`. It is also possible using the non-standard `__proto__` pseudo-property. + /// The `instanceof` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-instanceofoperator) @@ -448,41 +202,7 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof InstanceOf, - /// The static **`import` statement** is used to import bindings which are exported by another module. - /// - /// Syntax: - /// ```text - /// import defaultExport from "module-name"; - /// import * as name from "module-name"; - /// import { export1 } from "module-name"; - /// import { export1 as alias1 } from "module-name"; - /// import { export1 , export2 } from "module-name"; - /// import { foo , bar } from "module-name/path/to/specific/un-exported/file"; - /// import { export1 , export2 as alias2 , [...] } from "module-name"; - /// import defaultExport, { export1 [ , [...] ] } from "module-name"; - /// import defaultExport, * as name from "module-name"; - /// import "module-name"; - /// var promise = import("module-name"); - /// ``` - /// - /// `defaultExport`: - /// > Name that will refer to the default export from the module. - /// - /// `module-name`: - /// > The module to import from. This is often a relative or absolute path name to the .js file containing the module. - /// > Certain bundlers may permit or require the use of the extension; check your environment. Only single quoted and double quoted Strings are allowed. - /// - /// `name`: - /// > Name of the module object that will be used as a kind of namespace when referring to the imports. - /// - /// `exportN`: - /// > Name of the exports to be imported. - /// - /// `aliasN`: - /// > Names that will refer to the named imports. - /// - /// The `name` parameter is the name of the "module object" which will be used as a kind of namespace to refer to the exports. - /// The `export` parameters specify individual named exports, while the `import * as name` syntax imports all of them. + /// The`import` keyword. /// /// More information: /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-imports) @@ -491,33 +211,130 @@ pub enum Keyword { /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import Import, - /// The `let` keyword + /// The `let` keyword. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-let-and-const-declarations) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let Let, - /// The `new` keyword + + /// The `new` keyword. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-NewExpression) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/new New, + /// The `return` keyword + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ReturnStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/return Return, + /// The `super` keyword + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-super-keyword) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/super Super, - /// The `switch` keyword + + /// The `switch` keyword. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-SwitchStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch Switch, - /// The `this` keyword + + /// The `this` keyword. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-this-keyword) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this This, - /// The `throw` keyword + + /// The `throw` keyword. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ArrowFunction) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions Throw, - /// The `try` keyword + + /// The `try` keyword. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-TryStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch Try, - /// The `typeof` keyword + + /// The `typeof` keyword. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-typeof-operator) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof TypeOf, - /// The `var` keyword + + /// The `var` keyword. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-VariableStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/var Var, - /// The `void` keyword + + /// The `void` keyword. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-void-operator) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/void Void, - /// The `while` keyword + + /// The `while` keyword. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-grammar-notation-WhileStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/while While, - /// The `with` keyword + + /// The `with` keyword. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-WithStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with With, - /// The 'yield' keyword + + /// The 'yield' keyword. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-YieldExpression) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/yield Yield, } diff --git a/boa/src/syntax/ast/node.rs b/boa/src/syntax/ast/node.rs index 5fd0007431..236175c837 100644 --- a/boa/src/syntax/ast/node.rs +++ b/boa/src/syntax/ast/node.rs @@ -12,85 +12,409 @@ use serde::{Deserialize, Serialize}; #[cfg_attr(feature = "serde-ast", derive(Serialize, Deserialize))] #[derive(Clone, Debug, Trace, Finalize, PartialEq)] pub enum Node { - /// Create an array with items inside. + /// An array is an ordered collection of data (either primitive or object depending upon the language). + /// + /// Arrays are used to store multiple values in a single variable. + /// This is compared to a variable that can store only one value. + /// + /// Each item in an array has a number attached to it, called a numeric index, that allows you to access it. + /// In JavaScript, arrays start at index zero and can be manipulated with various methods. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ArrayLiteral) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array ArrayDecl(Vec), - /// Create an arrow function with the given arguments and internal AST node. + + /// An arrow function expression is a syntactically compact alternative to a regular function expression. + /// + /// Arrow function expressions are ill suited as methods, and they cannot be used as constructors. + /// Arrow functions cannot be used as constructors and will throw an error when used with new. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ArrowFunction) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions ArrowFunctionDecl(Vec, Box), - /// Assign an AST node result to an AST node. + + /// An assignment operator assigns a value to its left operand based on the value of its right operand. + /// + /// Assignment operator (`=`), assigns the value of its right operand to its left operand. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-AssignmentExpression) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Assignment_Operators Assign(Box, Box), - /// Run an operation between 2 AST nodes. + + /// Binary operators requires two operands, one before the operator and one after the operator. + /// + /// More information: + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators#Operators BinOp(BinOp, Box, Box), - /// Run several AST nodes from top-to-bottom. + + /// A **`block` statement** (or compound statement in other languages) is used to group zero or more statements. + /// + /// The block statement is often called compound statement in other languages. + /// It allows you to use multiple statements where JavaScript expects only one statement. + /// Combining statements into blocks is a common practice in JavaScript. The opposite behavior is possible using an empty statement, + /// where you provide no statement, although one is required. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-BlockStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/block Block(Vec), - /// Break statement with an optional label. + + /// The **`break` statement** terminates the current loop, switch, or label statement and transfers program control to the statement following the terminated statement. + /// + /// The break statement includes an optional label that allows the program to break out of a labeled statement. + /// The break statement needs to be nested within the referenced label. The labeled statement can be any block statement; + /// it does not have to be preceded by a loop statement. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-BreakStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/break Break(Option), - /// Call a function with some values. + + /// Calling the function actually performs the specified actions with the indicated parameters. + /// + /// Defining a function does not execute it. Defining it simply names the function and specifies what to do when the function is called. + /// Functions must be in scope when they are called, but the function declaration can be hoisted + /// The scope of a function is the function in which it is declared (or the entire program, if it is declared at the top level). + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-CallExpression) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Functions#Calling_functions Call(Box, Vec), - /// Conditional Operator (`{condition} ? {if true} : {if false}`). + + /// The `conditional` (ternary) operator is the only JavaScript operator that takes three operands. + /// + /// This operator is the only JavaScript operator that takes three operands: a condition followed by a question mark (`?`), + /// then an expression to execute `if` the condition is truthy followed by a colon (`:`), and finally the expression to execute if the condition is `falsy`. + /// This operator is frequently used as a shortcut for the `if` statement. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ConditionalExpression) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Literals ConditionalOp(Box, Box, Box), - /// Make a constant value. + + /// Literals represent values in JavaScript. + /// + /// These are fixed values **not variables** that you literally provide in your script. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-primary-expression-literals) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_types Const(Const), - /// Const declaration. + + /// The **`const` statements** are block-scoped, much like variables defined using the `let` keyword. + /// + /// This declaration creates a constant whose scope can be either global or local to the block in which it is declared. + /// Global constants do not become properties of the window object, unlike var variables. + /// + /// An initializer for a constant is required. You must specify its value in the same statement in which it's declared. + /// (This makes sense, given that it can't be changed later.) + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-let-and-const-declarations) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const + /// [identifier]: https://developer.mozilla.org/en-US/docs/Glossary/identifier + /// [expression]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators#Expressions ConstDecl(Vec<(String, Node)>), - /// Continue with an optional label. + + /// The **`continue` statement** terminates execution of the statements in the current iteration of the current or labeled loop, + /// and continues execution of the loop with the next iteration. + /// + /// The continue statement can include an optional label that allows the program to jump to the next iteration of a labeled + /// loop statement instead of the current loop. In this case, the continue statement needs to be nested within this labeled statement. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ContinueStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/continue Continue(Option), + /// do [body] while [cond] DoWhileLoop(Box, Box), - /// Create a function with the given name, arguments, and internal AST node. + + /// The **`function` declaration** (function statement) defines a function with the specified parameters. + /// + /// A function created with a function declaration is a `Function` object and has all the properties, methods and behavior of `Function`. + /// + /// A function can also be created using an expression (see function expression). + /// + /// By default, functions return undefined. To return any other value, the function must have a return statement that specifies the value to return. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-terms-and-definitions-function) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function FunctionDecl(Option, Vec, Box), + /// Gets the constant field of a value. GetConstField(Box, String), + /// Gets the [field] of a value. GetField(Box, Box), - /// [init], [cond], [step], body + + /// The **`for` statement** creates a loop that consists of three optional expressions. + /// + /// A `for` loop repeats until a specified condition evaluates to `false`. + /// The JavaScript for loop is similar to the Java and C for loop. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ForDeclaration) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for ForLoop( Option>, Option>, Option>, Box, ), - /// Check if a conditional expression is true and run an expression if it is and another expression if it isn't + + /// The **`if` statement** executes a statement if a specified condition is [`truthy`][truthy]. If the condition is [`falsy`][falsy], another statement can be executed. + /// + /// Multiple `if...else` statements can be nested to create an else if clause. + /// + /// **Note** that there is no elseif (in one word) keyword in JavaScript. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-IfStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/if...else + /// [truthy]: https://developer.mozilla.org/en-US/docs/Glossary/truthy + /// [falsy]: https://developer.mozilla.org/en-US/docs/Glossary/falsy + /// [expression]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators#Expressions If(Box, Box, Option>), - /// Let declaraton + + /// The **`let` statement** declares a block scope local variable, optionally initializing it to a value. + /// + /// + /// `let` allows you to declare variables that are limited to a scope of a block statement, or expression on which + /// it is used, unlike the `var` keyword, which defines a variable globally, or locally to an entire function regardless of block scope. + /// + /// Just like const the `let` does not create properties of the window object when declared globally (in the top-most scope). + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-let-and-const-declarations) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let LetDecl(Vec<(String, Option)>), - /// Load a reference to a value, or a function argument + + /// An `identifier` is a sequence of characters in the code that identifies a variable, function, or property. + /// + /// In JavaScript, identifiers are case-sensitive and can contain Unicode letters, $, _, and digits (0-9), but may not start with a digit. + /// + /// An identifier differs from a string in that a string is data, while an identifier is part of the code. In JavaScript, there is no way + /// to convert identifiers to strings, but sometimes it is possible to parse strings into identifiers. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-Identifier) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Glossary/Identifier Local(String), - /// New + + /// The **`new` operator** lets developers create an instance of a user-defined object type or of one of the built-in object types that has a constructor function. + /// + /// The new keyword does the following things: + /// - Creates a blank, plain JavaScript object; + /// - Links (sets the constructor of) this object to another object; + /// - Passes the newly created object from Step 1 as the this context; + /// - Returns this if the function doesn't return its own object. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-NewExpression) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/new New(Box), - /// Object Declaration + + /// Objects in JavaScript may be defined as an unordered collection of related data, of primitive or reference types, in the form of “key: value” pairs. + /// + /// Objects can be initialized using `new Object()`, `Object.create()`, or using the literal notation. + /// + /// An object initializer is an expression that describes the initialization of an [`Object`][object]. + /// Objects consist of properties, which are used to describe an object. Values of object properties can either + /// contain [`primitive`][primitive] data types or other objects. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ObjectLiteral) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer + /// [object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object + /// [primitive]: https://developer.mozilla.org/en-US/docs/Glossary/primitive Object(Vec), - /// Return the expression from a function + + /// The **`return` statement** ends function execution and specifies a value to be returned to the function caller. + /// + /// Syntax: `return [expression];` + /// + /// `expression`: + /// > The expression whose value is to be returned. If omitted, `undefined` is returned instead. + /// + /// When a `return` statement is used in a function body, the execution of the function is stopped. + /// If specified, a given value is returned to the function caller. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ReturnStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/return Return(Option>), - /// Run blocks whose cases match the expression + + /// The **`switch` statement evaluates** an expression, matching the expression's value to a case clause, + /// and executes statements associated with that case, as well as statements in cases that follow the matching case. + /// + /// A `switch` statement first evaluates its expression. It then looks for the first case clause whose expression evaluates + /// to the same value as the result of the input expression (using the strict comparison, `===`) and transfers control to that clause, + /// executing the associated statements. (If multiple cases match the provided value, the first case that matches is selected, even if + /// the cases are not equal to each other.) + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-SwitchStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch Switch(Box, Vec<(Node, Vec)>, Option>), - /// `...a` - spread an iterable value + + /// The **`spread` operator** allows an iterable such as an array expression or string to be expanded. + /// + /// Syntax: `...x` + /// + /// It expands array expressions or strings in places where zero or more arguments (for function calls) or elements (for array literals) + /// are expected, or an object expression to be expanded in places where zero or more key-value pairs (for object literals) are expected. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-SpreadElement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax Spread(Box), - // Similar to Block but without the braces + + /// Similar to `Node::Block` but without the braces + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-StatementList) StatementList(Vec), - /// Throw a value + + /// The **`throw` statement** throws a user-defined exception. + /// + /// Syntax: `throw expression;` + /// + /// Execution of the current function will stop (the statements after throw won't be executed), + /// and control will be passed to the first catch block in the call stack. If no catch block exists among + /// caller functions, the program will terminate. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-ThrowStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/throw Throw(Box), - /// Return a string representing the type of the given expression + + /// The **`typeof` operator** returns a string indicating the type of the unevaluated operand. + /// + /// Syntax: `typeof operand` + /// + /// Returns a string indicating the type of the unevaluated operand. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-typeof-operator) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof TypeOf(Box), - /// Try / Catch + + /// The **`try...catch` statement** marks a block of statements to try and specifies a response should an exception be thrown. + /// + /// The `try` statement consists of a `try`-block, which contains one or more statements. `{}` must always be used, + /// even for single statements. At least one `catch`-block, or a `finally`-block, must be present. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-TryStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch Try( Box, Option>, Option>, Option>, ), + /// The JavaScript `this` keyword refers to the object it belongs to. /// /// A property of an execution context (global, function or eval) that, /// in non–strict mode, is always a reference to an object and in strict /// mode can be any value. /// - /// For more information, please check: + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#sec-this-keyword) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this This, - /// Run an operation on a value + + /// A unary operation is an operation with only one operand. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-UnaryExpression) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators#Unary_operators UnaryOp(UnaryOp, Box), - /// A variable declaration + + /// The **`var` statement** declares a variable, optionally initializing it to a value. + /// + /// var declarations, wherever they occur, are processed before any code is executed. This is called hoisting, and is discussed further below. + /// + /// The scope of a variable declared with var is its current execution context, which is either the enclosing function or, + /// for variables declared outside any function, global. If you re-declare a JavaScript variable, it will not lose its value. + /// + /// Assigning a value to an undeclared variable implicitly creates it as a global variable + /// (it becomes a property of the global object) when the assignment is executed. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-VariableStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/var VarDecl(Vec<(String, Option)>), - /// Repeatedly run an expression while the conditional expression resolves to true + + /// The **`while` statement** creates a loop that executes a specified statement as long as the test condition evaluates to `true`. + /// + /// The condition is evaluated before executing the statement. + /// + /// More information: + /// - [ECMAScript reference](https://tc39.es/ecma262/#prod-grammar-notation-WhileStatement) + /// - [MDN documentation][mdn] + /// + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/while WhileLoop(Box, Box), }