Skip to content

docs(ast): document TryStatement and related nodes #5970

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
graphite-app merged 1 commit into from
Sep 22, 2024
Merged

docs(ast): document TryStatement and related nodes #5970

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions crates/oxc_ast/src/ast/js.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1511,6 +1511,12 @@ pub struct LabeledStatement<'a> {
}

/// Throw Statement
///
/// # Example
/// ```ts
/// throw new Error('something went wrong!');
/// // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ argument
/// ```
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ContentHash)]
Expand All @@ -1519,10 +1525,25 @@ pub struct LabeledStatement<'a> {
pub struct ThrowStatement<'a> {
#[serde(flatten)]
pub span: Span,
/// The expression being thrown, e.g. `err` in `throw err;`
pub argument: Expression<'a>,
}

/// Try Statement
///
/// # Example
/// ```ts
/// var x;
/// let didRun = false;
///
/// try { // block
/// x = 1;
/// } catch (e) { // handler
/// console.error(e);
/// } finally { // finalizer
/// didRun = true;
/// }
/// ```
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ContentHash)]
Expand All @@ -1531,12 +1552,27 @@ pub struct ThrowStatement<'a> {
pub struct TryStatement<'a> {
#[serde(flatten)]
pub span: Span,
/// Statements in the `try` block
pub block: Box<'a, BlockStatement<'a>>,
/// The `catch` clause, including the parameter and the block statement
pub handler: Option<Box<'a, CatchClause<'a>>>,
/// The `finally` clause
#[visit(as(FinallyClause))]
pub finalizer: Option<Box<'a, BlockStatement<'a>>>,
}

/// Catch Clause in a [`try/catch` statement](TryStatement).
///
/// This node creates a new scope inside its `body`.
///
/// # Example
/// ```ts
/// try {
/// throw new Error('foo');
/// } catch (e) { // `param` is `e`
/// console.error(e); // `body`
/// }
/// ```
#[ast(visit)]
#[scope(flags(ScopeFlags::CatchClause))]
#[derive(Debug)]
Expand All @@ -1546,13 +1582,28 @@ pub struct TryStatement<'a> {
pub struct CatchClause<'a> {
#[serde(flatten)]
pub span: Span,
/// The caught error parameter, e.g. `e` in `catch (e) {}`
pub param: Option<CatchParameter<'a>>,
/// The statements run when an error is caught
pub body: Box<'a, BlockStatement<'a>>,
#[serde(skip)]
#[clone_in(default)]
pub scope_id: Cell<Option<ScopeId>>,
}

/// A caught error parameter in a [catch clause](CatchClause).
///
/// # Examples
///
/// ```ts
/// try {} catch (err) {}
/// // ^^^ pattern
/// ```
///
/// ```ts
/// try {} catch ({ err }) {}
/// // ^^^^^^^ pattern
/// ```
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ContentHash)]
Expand All @@ -1561,10 +1612,17 @@ pub struct CatchClause<'a> {
pub struct CatchParameter<'a> {
#[serde(flatten)]
pub span: Span,
/// The bound error
pub pattern: BindingPattern<'a>,
}

/// Debugger Statement
///
/// # Example
/// ```ts
/// let x = 1;
/// debugger; // <--
/// ```
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ContentHash)]
Expand Down
36 changes: 18 additions & 18 deletions crates/oxc_ast/src/generated/ast_builder.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3925,7 +3925,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - argument
/// - argument: The expression being thrown, e.g. `err` in `throw err;`
#[inline]
pub fn statement_throw(self, span: Span, argument: Expression<'a>) -> Statement<'a> {
Statement::ThrowStatement(self.alloc(self.throw_statement(span, argument)))
Expand All @@ -3946,9 +3946,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - block
/// - handler
/// - finalizer
/// - block: Statements in the `try` block
/// - handler: The `catch` clause, including the parameter and the block statement
/// - finalizer: The `finally` clause
#[inline]
pub fn statement_try<T1, T2, T3>(
self,
Expand Down Expand Up @@ -5183,7 +5183,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - argument
/// - argument: The expression being thrown, e.g. `err` in `throw err;`
#[inline]
pub fn throw_statement(self, span: Span, argument: Expression<'a>) -> ThrowStatement<'a> {
ThrowStatement { span, argument }
Expand All @@ -5195,7 +5195,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - argument
/// - argument: The expression being thrown, e.g. `err` in `throw err;`
#[inline]
pub fn alloc_throw_statement(
self,
Expand All @@ -5211,9 +5211,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - block
/// - handler
/// - finalizer
/// - block: Statements in the `try` block
/// - handler: The `catch` clause, including the parameter and the block statement
/// - finalizer: The `finally` clause
#[inline]
pub fn try_statement<T1, T2, T3>(
self,
Expand Down Expand Up @@ -5241,9 +5241,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - block
/// - handler
/// - finalizer
/// - block: Statements in the `try` block
/// - handler: The `catch` clause, including the parameter and the block statement
/// - finalizer: The `finally` clause
#[inline]
pub fn alloc_try_statement<T1, T2, T3>(
self,
Expand All @@ -5266,8 +5266,8 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - param
/// - body
/// - param: The caught error parameter, e.g. `e` in `catch (e) {}`
/// - body: The statements run when an error is caught
#[inline]
pub fn catch_clause<T1>(
self,
Expand All @@ -5292,8 +5292,8 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - param
/// - body
/// - param: The caught error parameter, e.g. `e` in `catch (e) {}`
/// - body: The statements run when an error is caught
#[inline]
pub fn alloc_catch_clause<T1>(
self,
Expand All @@ -5313,7 +5313,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - pattern
/// - pattern: The bound error
#[inline]
pub fn catch_parameter(self, span: Span, pattern: BindingPattern<'a>) -> CatchParameter<'a> {
CatchParameter { span, pattern }
Expand All @@ -5325,7 +5325,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - pattern
/// - pattern: The bound error
#[inline]
pub fn alloc_catch_parameter(
self,
Expand Down