diff --git a/Cargo.lock b/Cargo.lock index a308f5087253e..a56d657f1479b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -536,12 +536,6 @@ version = "0.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "5827cebf4670468b8772dd191856768aedcb1b0278a04f989f7766351917b9dc" -[[package]] -name = "countme" -version = "3.0.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7704b5fdd17b18ae31c4c1da5a2e0305a2bf17b5249300a9ee9ed7b72114c636" - [[package]] name = "cpufeatures" version = "0.2.5" @@ -626,7 +620,7 @@ dependencies = [ "autocfg", "cfg-if", "crossbeam-utils", - "memoffset 0.7.1", + "memoffset", "scopeguard", ] @@ -810,16 +804,6 @@ dependencies = [ "cfg-if", ] -[[package]] -name = "env_logger" -version = "0.8.4" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a19187fea3ac7e84da7dacf48de0c45d63c6a76f9490dae389aead16c243fce3" -dependencies = [ - "log", - "regex", -] - [[package]] name = "env_proxy" version = "0.4.1" @@ -1226,12 +1210,6 @@ dependencies = [ "want", ] -[[package]] -name = "iai" -version = "0.1.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "71a816c97c42258aa5834d07590b718b4c9a598944cd39a52dc25b351185d678" - [[package]] name = "iana-time-zone" version = "0.1.53" @@ -1674,15 +1652,6 @@ version = "2.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2dffe52ecf27772e601905b7522cb4ef790d2cc203488bbd0e2fe85fcb74566d" -[[package]] -name = "memoffset" -version = "0.6.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5aa361d4faea93603064a027415f07bd8e1d5c88c9fbf68bf56a285428fd79ce" -dependencies = [ - "autocfg", -] - [[package]] name = "memoffset" version = "0.7.1" @@ -2302,28 +2271,6 @@ dependencies = [ "memchr", ] -[[package]] -name = "quickcheck" -version = "1.0.3" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "588f6378e4dd99458b60ec275b4477add41ce4fa9f64dcba6f15adccb19b50d6" -dependencies = [ - "env_logger", - "log", - "rand", -] - -[[package]] -name = "quickcheck_macros" -version = "1.0.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b22a693222d716a9587786f37ac3f6b4faedb5b80c23914e7303ff5a1d8016e9" -dependencies = [ - "proc-macro2", - "quote", - "syn", -] - [[package]] name = "quote" version = "1.0.23" @@ -2620,12 +2567,9 @@ dependencies = [ name = "ruff_formatter" version = "0.0.0" dependencies = [ - "cfg-if", - "countme", "drop_bomb", - "indexmap", "insta", - "ruff_rowan", + "ruff_text_size", "rustc-hash", "schemars", "serde", @@ -2653,35 +2597,6 @@ dependencies = [ "rustc-hash", ] -[[package]] -name = "ruff_rowan" -version = "0.0.0" -dependencies = [ - "countme", - "hashbrown", - "iai", - "memoffset 0.6.5", - "quickcheck", - "quickcheck_macros", - "ruff_text_edit", - "ruff_text_size", - "rustc-hash", - "schemars", - "serde", - "serde_json", - "tracing", -] - -[[package]] -name = "ruff_text_edit" -version = "0.0.0" -dependencies = [ - "ruff_text_size", - "schemars", - "serde", - "similar", -] - [[package]] name = "ruff_text_size" version = "0.0.0" @@ -3024,10 +2939,6 @@ name = "similar" version = "2.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "420acb44afdae038210c99e69aae24109f32f15500aa708e81d46c9f29d55fcf" -dependencies = [ - "bstr 0.2.17", - "unicode-segmentation", -] [[package]] name = "siphasher" @@ -3646,12 +3557,6 @@ dependencies = [ "tinyvec", ] -[[package]] -name = "unicode-segmentation" -version = "1.10.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1dd624098567895118886609431a7c3b8f516e41d30e0643f03d94592a147e36" - [[package]] name = "unicode-width" version = "0.1.10" diff --git a/LICENSE b/LICENSE index fe0ba665900b3..00d4422bb4e1d 100644 --- a/LICENSE +++ b/LICENSE @@ -1063,33 +1063,6 @@ are: - flake8-django, licensed under the GPL license. -- rust-analyzer/rowan, licensed under the MIT license: - """ - Permission is hereby granted, free of charge, to any - person obtaining a copy of this software and associated - documentation files (the "Software"), to deal in the - Software without restriction, including without - limitation the rights to use, copy, modify, merge, - publish, distribute, sublicense, and/or sell copies of - the Software, and to permit persons to whom the Software - is furnished to do so, subject to the following - conditions: - - The above copyright notice and this permission notice - shall be included in all copies or substantial portions - of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF - ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED - TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A - PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT - SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY - CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION - OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR - IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER - DEALINGS IN THE SOFTWARE. - """ - - rust-analyzer/text-size, licensed under the MIT license: """ Permission is hereby granted, free of charge, to any @@ -1117,33 +1090,6 @@ are: DEALINGS IN THE SOFTWARE. """ -- rust-analyzer/text-edit, licensed under the MIT license: - """ - Permission is hereby granted, free of charge, to any - person obtaining a copy of this software and associated - documentation files (the "Software"), to deal in the - Software without restriction, including without - limitation the rights to use, copy, modify, merge, - publish, distribute, sublicense, and/or sell copies of - the Software, and to permit persons to whom the Software - is furnished to do so, subject to the following - conditions: - - The above copyright notice and this permission notice - shall be included in all copies or substantial portions - of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF - ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED - TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A - PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT - SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY - CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION - OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR - IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER - DEALINGS IN THE SOFTWARE. - """ - - rome/tools, licensed under the MIT license: """ MIT License diff --git a/crates/ruff_formatter/Cargo.toml b/crates/ruff_formatter/Cargo.toml index 622d4b2e9c7ad..ad9ac01ec3846 100644 --- a/crates/ruff_formatter/Cargo.toml +++ b/crates/ruff_formatter/Cargo.toml @@ -5,11 +5,8 @@ publish = false edition = "2021" [dependencies] -cfg-if = { version = "1.0.0" } -countme = { version = "3.0.1" } drop_bomb = { version = "0.1.5" } -indexmap = { version = "1.9.1" } -ruff_rowan = { path = "../ruff_rowan" } +ruff_text_size = { path = "../ruff_text_size" } rustc-hash = { workspace = true } schemars = { version = "0.8.10", optional = true } serde = { version = "1.0.136", features = ["derive"], optional = true } @@ -20,4 +17,4 @@ unicode-width = { version = "0.1.9" } insta = { version = "1.19.0" } [features] -serde = ["dep:serde", "schemars", "ruff_rowan/serde"] +serde = ["dep:serde", "schemars"] diff --git a/crates/ruff_formatter/src/builders.rs b/crates/ruff_formatter/src/builders.rs index 084b9d9ab1994..c00d54d4984d0 100644 --- a/crates/ruff_formatter/src/builders.rs +++ b/crates/ruff_formatter/src/builders.rs @@ -1,10 +1,10 @@ use crate::format_element::tag::{Condition, Tag}; use crate::prelude::tag::{DedentMode, GroupMode, LabelId}; use crate::prelude::*; -use crate::{format_element, write, Argument, Arguments, GroupId, TextRange, TextSize}; +use crate::{format_element, write, Argument, Arguments, GroupId, TextSize}; use crate::{Buffer, VecBuffer}; -use ruff_rowan::{Language, SyntaxNode, SyntaxToken, SyntaxTokenText, TextLen}; -use std::borrow::Cow; + +use ruff_text_size::TextRange; use std::cell::Cell; use std::marker::PhantomData; use std::num::NonZeroU8; @@ -332,93 +332,6 @@ impl std::fmt::Debug for StaticTextSlice { } } -/// String that is the same as in the input source text if `text` is [`Cow::Borrowed`] or -/// some replaced content if `text` is [`Cow::Owned`]. -pub fn syntax_token_cow_slice<'a, L: Language>( - text: Cow<'a, str>, - token: &'a SyntaxToken, - start: TextSize, -) -> SyntaxTokenCowSlice<'a, L> { - debug_assert_no_newlines(&text); - - SyntaxTokenCowSlice { text, token, start } -} - -pub struct SyntaxTokenCowSlice<'a, L: Language> { - text: Cow<'a, str>, - token: &'a SyntaxToken, - start: TextSize, -} - -impl Format for SyntaxTokenCowSlice<'_, L> { - fn fmt(&self, f: &mut Formatter) -> FormatResult<()> { - match &self.text { - Cow::Borrowed(text) => { - let range = TextRange::at(self.start, text.text_len()); - debug_assert_eq!( - *text, - &self.token.text()[range - self.token.text_range().start()], - "The borrowed string doesn't match the specified token substring. Does the borrowed string belong to this token and range?" - ); - - let relative_range = range - self.token.text_range().start(); - let slice = self.token.token_text().slice(relative_range); - - f.write_element(FormatElement::SyntaxTokenTextSlice { - slice, - source_position: self.start, - }) - } - Cow::Owned(text) => f.write_element(FormatElement::DynamicText { - text: text.to_string().into_boxed_str(), - source_position: self.start, - }), - } - } -} - -impl std::fmt::Debug for SyntaxTokenCowSlice<'_, L> { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - std::write!(f, "SyntaxTokenCowSlice({})", self.text) - } -} - -/// Copies a source text 1:1 into the output text. -pub fn syntax_token_text_slice( - token: &SyntaxToken, - range: TextRange, -) -> SyntaxTokenTextSlice { - let relative_range = range - token.text_range().start(); - let slice = token.token_text().slice(relative_range); - - debug_assert_no_newlines(&slice); - - SyntaxTokenTextSlice { - text: slice, - source_position: range.start(), - } -} - -pub struct SyntaxTokenTextSlice { - text: SyntaxTokenText, - source_position: TextSize, -} - -impl Format for SyntaxTokenTextSlice { - fn fmt(&self, f: &mut Formatter) -> FormatResult<()> { - f.write_element(FormatElement::SyntaxTokenTextSlice { - slice: self.text.clone(), - source_position: self.source_position, - }) - } -} - -impl std::fmt::Debug for SyntaxTokenTextSlice { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - std::write!(f, "SyntaxTokenTextSlice({})", self.text) - } -} - fn debug_assert_no_newlines(text: &str) { debug_assert!(!text.contains('\r'), "The content '{}' contains an unsupported '\\r' line terminator character but text must only use line feeds '\\n' as line separator. Use '\\n' instead of '\\r' and '\\r\\n' to insert a line break in strings.", text); } @@ -1853,7 +1766,7 @@ impl std::fmt::Debug for FormatWith { /// ``` /// use ruff_formatter::prelude::*; /// use ruff_formatter::{SimpleFormatContext, format, write}; -/// use ruff_rowan::TextSize; +/// use ruff_text_size::TextSize; /// /// struct MyFormat { /// items: Vec<&'static str>, @@ -1948,7 +1861,7 @@ where /// ```panics /// use ruff_formatter::prelude::*; /// use ruff_formatter::{SimpleFormatContext, format, write, Buffer}; -/// use ruff_rowan::TextSize; +/// use ruff_text_size::TextSize; /// /// let mut count = 0; /// @@ -2063,99 +1976,6 @@ where } } -/// Builder to join together nodes that ensures that nodes separated by empty lines continue -/// to be separated by empty lines in the formatted output. -#[must_use = "must eventually call `finish()` on Format builders"] -pub struct JoinNodesBuilder<'fmt, 'buf, Separator, Context> { - result: FormatResult<()>, - /// The separator to insert between nodes. Either a soft or hard line break - separator: Separator, - fmt: &'fmt mut Formatter<'buf, Context>, - has_elements: bool, -} - -impl<'fmt, 'buf, Separator, Context> JoinNodesBuilder<'fmt, 'buf, Separator, Context> -where - Separator: Format, -{ - pub(super) fn new(separator: Separator, fmt: &'fmt mut Formatter<'buf, Context>) -> Self { - Self { - result: Ok(()), - separator, - fmt, - has_elements: false, - } - } - - /// Adds a new node with the specified formatted content to the output, respecting any new lines - /// that appear before the node in the input source. - pub fn entry(&mut self, node: &SyntaxNode, content: &dyn Format) { - self.result = self.result.and_then(|_| { - if self.has_elements { - if get_lines_before(node) > 1 { - write!(self.fmt, [empty_line()])?; - } else { - self.separator.fmt(self.fmt)?; - } - } - - self.has_elements = true; - - write!(self.fmt, [content]) - }); - } - - /// Writes an entry without adding a separating line break or empty line. - pub fn entry_no_separator(&mut self, content: &dyn Format) { - self.result = self.result.and_then(|_| { - self.has_elements = true; - - write!(self.fmt, [content]) - }) - } - - /// Adds an iterator of entries to the output. Each entry is a `(node, content)` tuple. - pub fn entries(&mut self, entries: I) -> &mut Self - where - L: Language, - F: Format, - I: IntoIterator, F)>, - { - for (node, content) in entries { - self.entry(&node, &content) - } - - self - } - - pub fn finish(&mut self) -> FormatResult<()> { - self.result - } -} - -/// Get the number of line breaks between two consecutive SyntaxNodes in the tree -pub fn get_lines_before(next_node: &SyntaxNode) -> usize { - // Count the newlines in the leading trivia of the next node - if let Some(token) = next_node.first_token() { - get_lines_before_token(&token) - } else { - 0 - } -} - -pub fn get_lines_before_token(token: &SyntaxToken) -> usize { - token - .leading_trivia() - .pieces() - .take_while(|piece| { - // Stop at the first comment or skipped piece, the comment printer - // will handle newlines between the comment and the node - !(piece.is_comments() || piece.is_skipped()) - }) - .filter(|piece| piece.is_newline()) - .count() -} - /// Builder to fill as many elements as possible on a single line. #[must_use = "must eventually call `finish()` on Format builders"] pub struct FillBuilder<'fmt, 'buf, Context> { diff --git a/crates/ruff_formatter/src/comments.rs b/crates/ruff_formatter/src/comments.rs deleted file mode 100644 index 861b4d6b9bfd5..0000000000000 --- a/crates/ruff_formatter/src/comments.rs +++ /dev/null @@ -1,1175 +0,0 @@ -//! Types for extracting and representing comments of a syntax tree. -//! -//! Most programming languages support comments allowing programmers to document their programs. Comments are different from other syntaxes because programming languages allow comments in almost any position, giving programmers great flexibility on where they can write comments: -//! -//! ```ignore -//! /** -//! * Documentation comment -//! */ -//! async /* comment */ function Test () // line comment -//! {/*inline*/} -//! ``` -//! -//! However, this flexibility makes formatting comments challenging because: -//! * The formatter must consistently place comments so that re-formatting the output yields the same result and does not create invalid syntax (line comments). -//! * It is essential that formatters place comments close to the syntax the programmer intended to document. However, the lack of rules regarding where comments are allowed and what syntax they document requires the use of heuristics to infer the documented syntax. -//! -//! This module strikes a balance between placing comments as closely as possible to their source location and reducing the complexity of formatting comments. It does so by associating comments per node rather than a token. This greatly reduces the combinations of possible comment positions but turns out to be, in practice, sufficiently precise to keep comments close to their source location. -//! -//! ## Node comments -//! -//! Comments are associated per node but get further distinguished on their location related to that node: -//! -//! ### Leading Comments -//! -//! A comment at the start of a node -//! -//! ```ignore -//! // Leading comment of the statement -//! console.log("test"); -//! -//! [/* leading comment of identifier */ a ]; -//! ``` -//! -//! ### Dangling Comments -//! -//! A comment that is neither at the start nor the end of a node -//! -//! ```ignore -//! [/* in between the brackets */ ]; -//! async /* between keywords */ function Test () {} -//! ``` -//! -//! ### Trailing Comments -//! -//! A comment at the end of a node -//! -//! ```ignore -//! [a /* trailing comment of a */, b, c]; -//! [ -//! a // trailing comment of a -//! ] -//! ``` -//! -//! ## Limitations -//! Limiting the placement of comments to leading, dangling, or trailing node comments reduces complexity inside the formatter but means, that the formatter's possibility of where comments can be formatted depends on the AST structure. -//! -//! For example, the continue statement in JavaScript is defined as: -//! -//! ```ungram -//! JsContinueStatement = -//! 'continue' -//! (label: 'ident')? -//! ';'? -//! ``` -//! -//! but a programmer may decide to add a comment in front or after the label: -//! -//! ```ignore -//! continue /* comment 1 */ label; -//! continue label /* comment 2*/; /* trailing */ -//! ``` -//! -//! Because all children of the `continue` statement are tokens, it is only possible to make the comments leading, dangling, or trailing comments of the `continue` statement. But this results in a loss of information as the formatting code can no longer distinguish if a comment appeared before or after the label and, thus, has to format them the same way. -//! -//! This hasn't shown to be a significant limitation today but the infrastructure could be extended to support a `label` on [`SourceComment`] that allows to further categorise comments. -//! - -mod builder; -mod map; - -use self::{builder::CommentsBuilderVisitor, map::CommentsMap}; -use crate::formatter::Formatter; -use crate::{buffer::Buffer, write}; -use crate::{CstFormatContext, FormatResult, FormatRule, TextSize, TransformSourceMap}; -use ruff_rowan::syntax::SyntaxElementKey; -use ruff_rowan::{Language, SyntaxNode, SyntaxToken, SyntaxTriviaPieceComments}; -use rustc_hash::FxHashSet; -#[cfg(debug_assertions)] -use std::cell::{Cell, RefCell}; -use std::marker::PhantomData; -use std::rc::Rc; - -#[derive(Copy, Clone, Eq, PartialEq, Debug)] -pub enum CommentKind { - /// An inline comment that can appear between any two tokens and doesn't contain any line breaks. - /// - /// ## Examples - /// - /// ```ignore - /// a /* test */ - /// ``` - InlineBlock, - - /// A block comment that can appear between any two tokens and contains at least one line break. - /// - /// ## Examples - /// - /// ```javascript - /// /* first line - /// * more content on the second line - /// */ - /// ``` - Block, - - /// A line comment that appears at the end of the line. - /// - /// ## Examples - /// - /// ```ignore - /// a // test - /// ``` - Line, -} - -impl CommentKind { - pub const fn is_line(&self) -> bool { - matches!(self, CommentKind::Line) - } - - pub const fn is_block(&self) -> bool { - matches!(self, CommentKind::Block) - } - - pub const fn is_inline_block(&self) -> bool { - matches!(self, CommentKind::InlineBlock) - } - - /// Returns `true` for comments that can appear inline between any two tokens. - /// - /// ## Examples - /// - /// ```rust - /// use ruff_formatter::comments::CommentKind; - /// - /// // Block and InlineBlock comments can appear inline - /// assert!(CommentKind::Block.is_inline()); - /// assert!(CommentKind::InlineBlock.is_inline()); - /// - /// // But not line comments - /// assert!(!CommentKind::Line.is_inline()) - /// ``` - pub const fn is_inline(&self) -> bool { - matches!(self, CommentKind::InlineBlock | CommentKind::Block) - } -} - -/// A comment in the source document. -#[derive(Debug, Clone)] -pub struct SourceComment { - /// The number of lines appearing before this comment - pub(crate) lines_before: u32, - - pub(crate) lines_after: u32, - - /// The comment piece - pub(crate) piece: SyntaxTriviaPieceComments, - - /// The kind of the comment. - pub(crate) kind: CommentKind, - - /// Whether the comment has been formatted or not. - #[cfg(debug_assertions)] - pub(crate) formatted: Cell, -} - -impl SourceComment { - /// Returns the underlining comment trivia piece - pub fn piece(&self) -> &SyntaxTriviaPieceComments { - &self.piece - } - - /// The number of lines between this comment and the **previous** token or comment. - /// - /// # Examples - /// - /// ## Same line - /// - /// ```ignore - /// a // end of line - /// ``` - /// - /// Returns `0` because there's no line break between the token `a` and the comment. - /// - /// ## Own Line - /// - /// ```ignore - /// a; - /// - /// /* comment */ - /// ``` - /// - /// Returns `2` because there are two line breaks between the token `a` and the comment. - pub fn lines_before(&self) -> u32 { - self.lines_before - } - - /// The number of line breaks right after this comment. - /// - /// # Examples - /// - /// ## End of line - /// - /// ```ignore - /// a; // comment - /// - /// b; - /// ``` - /// - /// Returns `2` because there are two line breaks between the comment and the token `b`. - /// - /// ## Same line - /// - /// ```ignore - /// a; - /// /* comment */ b; - /// ``` - /// - /// Returns `0` because there are no line breaks between the comment and the token `b`. - pub fn lines_after(&self) -> u32 { - self.lines_after - } - - /// The kind of the comment - pub fn kind(&self) -> CommentKind { - self.kind - } - - #[cfg(not(debug_assertions))] - #[inline(always)] - pub fn mark_formatted(&self) {} - - /// Marks the comment as formatted - #[cfg(debug_assertions)] - pub fn mark_formatted(&self) { - self.formatted.set(true) - } -} - -/// A comment decorated with additional information about its surrounding context in the source document. -/// -/// Used by [CommentStyle::place_comment] to determine if this should become a [leading](self#leading-comments), [dangling](self#dangling-comments), or [trailing](self#trailing-comments) comment. -#[derive(Debug, Clone)] -pub struct DecoratedComment { - enclosing: SyntaxNode, - preceding: Option>, - following: Option>, - following_token: Option>, - text_position: CommentTextPosition, - lines_before: u32, - lines_after: u32, - comment: SyntaxTriviaPieceComments, - kind: CommentKind, -} - -impl DecoratedComment { - /// The closest parent node that fully encloses the comment. - /// - /// A node encloses a comment when the comment is between two of its direct children (ignoring lists). - /// - /// # Examples - /// - /// ```ignore - /// [a, /* comment */ b] - /// ``` - /// - /// The enclosing node is the array expression and not the identifier `b` because - /// `a` and `b` are children of the array expression and `comment` is a comment between the two nodes. - pub fn enclosing_node(&self) -> &SyntaxNode { - &self.enclosing - } - - /// Returns the comment piece. - pub fn piece(&self) -> &SyntaxTriviaPieceComments { - &self.comment - } - - /// Returns the node preceding the comment. - /// - /// The direct child node (ignoring lists) of the [`enclosing_node`](DecoratedComment::enclosing_node) that precedes this comment. - /// - /// Returns [None] if the [`enclosing_node`](DecoratedComment::enclosing_node) only consists of tokens or if - /// all preceding children of the [`enclosing_node`](DecoratedComment::enclosing_node) have been tokens. - /// - /// The Preceding node is guaranteed to be a sibling of [`following_node`](DecoratedComment::following_node). - /// - /// # Examples - /// - /// ## Preceding tokens only - /// - /// ```ignore - /// [/* comment */] - /// ``` - /// Returns [None] because the comment has no preceding node, only a preceding `[` token. - /// - /// ## Preceding node - /// - /// ```ignore - /// [a /* comment */, b] - /// ``` - /// - /// Returns `Some(a)` because `a` directly precedes the comment. - /// - /// ## Preceding token and node - /// - /// ```ignore - /// [a, /* comment */] - /// ``` - /// - /// Returns `Some(a)` because `a` is the preceding node of `comment`. The presence of the `,` token - /// doesn't change that. - pub fn preceding_node(&self) -> Option<&SyntaxNode> { - self.preceding.as_ref() - } - - /// Takes the [`preceding_node`](DecoratedComment::preceding_node) and replaces it with [None]. - fn take_preceding_node(&mut self) -> Option> { - self.preceding.take() - } - - /// Returns the node following the comment. - /// - /// The direct child node (ignoring lists) of the [`enclosing_node`](DecoratedComment::enclosing_node) that follows this comment. - /// - /// Returns [None] if the [`enclosing_node`](DecoratedComment::enclosing_node) only consists of tokens or if - /// all children children of the [`enclosing_node`](DecoratedComment::enclosing_node) following this comment are tokens. - /// - /// The following node is guaranteed to be a sibling of [`preceding_node`](DecoratedComment::preceding_node). - /// - /// # Examples - /// - /// ## Following tokens only - /// - /// ```ignore - /// [ /* comment */ ] - /// ``` - /// - /// Returns [None] because there's no node following the comment, only the `]` token. - /// - /// ## Following node - /// - /// ```ignore - /// [ /* comment */ a ] - /// ``` - /// - /// Returns `Some(a)` because `a` is the node directly following the comment. - /// - /// ## Following token and node - /// - /// ```ignore - /// async /* comment */ function test() {} - /// ``` - /// - /// Returns `Some(test)` because the `test` identifier is the first node following `comment`. - /// - /// ## Following parenthesized expression - /// - /// ```ignore - /// !( - /// a /* comment */ - /// ); - /// b - /// ``` - /// - /// Returns `None` because `comment` is enclosed inside the parenthesized expression and it has no children - /// following `/* comment */. - pub fn following_node(&self) -> Option<&SyntaxNode> { - self.following.as_ref() - } - - /// Takes the [`following_node`](DecoratedComment::following_node) and replaces it with [None]. - fn take_following_node(&mut self) -> Option> { - self.following.take() - } - - /// The number of line breaks between this comment and the **previous** token or comment. - /// - /// # Examples - /// - /// ## Same line - /// - /// ```ignore - /// a // end of line - /// ``` - /// - /// Returns `0` because there's no line break between the token `a` and the comment. - /// - /// ## Own Line - /// - /// ```ignore - /// a; - /// - /// /* comment */ - /// ``` - /// - /// Returns `2` because there are two line breaks between the token `a` and the comment. - pub fn lines_before(&self) -> u32 { - self.lines_before - } - - /// The number of line breaks right after this comment. - /// - /// # Examples - /// - /// ## End of line - /// - /// ```ignore - /// a; // comment - /// - /// b; - /// ``` - /// - /// Returns `2` because there are two line breaks between the comment and the token `b`. - /// - /// ## Same line - /// - /// ```ignore - /// a; - /// /* comment */ b; - /// ``` - /// - /// Returns `0` because there are no line breaks between the comment and the token `b`. - pub fn lines_after(&self) -> u32 { - self.lines_after - } - - /// Returns the [CommentKind] of the comment. - pub fn kind(&self) -> CommentKind { - self.kind - } - - /// The position of the comment in the text. - pub fn text_position(&self) -> CommentTextPosition { - self.text_position - } - - /// The next token that comes after this comment. It is possible that other comments are between this comment - /// and the token. - /// - /// ```ignore - /// a /* comment */ /* other b */ - /// ``` - /// - /// The `following_token` for both comments is `b` because it's the token coming after the comments. - pub fn following_token(&self) -> Option<&SyntaxToken> { - self.following_token.as_ref() - } -} - -impl From> for SourceComment { - fn from(decorated: DecoratedComment) -> Self { - Self { - lines_before: decorated.lines_before, - lines_after: decorated.lines_after, - piece: decorated.comment, - kind: decorated.kind, - #[cfg(debug_assertions)] - formatted: Cell::new(false), - } - } -} - -/// The position of a comment in the source text. -#[derive(Debug, Copy, Clone, Eq, PartialEq)] -pub enum CommentTextPosition { - /// A comment that is on the same line as the preceding token and is separated by at least one line break from the following token. - /// - /// # Examples - /// - /// ## End of line - /// - /// ```ignore - /// a; /* this */ // or this - /// b; - /// ``` - /// - /// Both `/* this */` and `// or this` are end of line comments because both comments are separated by - /// at least one line break from the following token `b`. - /// - /// ## Own line - /// - /// ```ignore - /// a; - /// /* comment */ - /// b; - /// ``` - /// - /// This is not an end of line comment because it isn't on the same line as the preceding token `a`. - EndOfLine, - - /// A Comment that is separated by at least one line break from the preceding token. - /// - /// # Examples - /// - /// ```ignore - /// a; - /// /* comment */ /* or this */ - /// b; - /// ``` - /// - /// Both comments are own line comments because they are separated by one line break from the preceding - /// token `a`. - OwnLine, - - /// A comment that is placed on the same line as the preceding and following token. - /// - /// # Examples - /// - /// ```ignore - /// a /* comment */ + b - /// ``` - SameLine, -} - -impl CommentTextPosition { - pub const fn is_same_line(&self) -> bool { - matches!(self, CommentTextPosition::SameLine) - } - - pub const fn is_own_line(&self) -> bool { - matches!(self, CommentTextPosition::OwnLine) - } - - pub const fn is_end_of_line(&self) -> bool { - matches!(self, CommentTextPosition::EndOfLine) - } -} - -#[derive(Debug)] -pub enum CommentPlacement { - /// Makes `comment` a [leading comment](self#leading-comments) of `node`. - Leading { - node: SyntaxNode, - comment: SourceComment, - }, - /// Makes `comment` a [trailing comment](self#trailing-comments) of `node`. - Trailing { - node: SyntaxNode, - comment: SourceComment, - }, - - /// Makes `comment` a [dangling comment](self#dangling-comments) of `node`. - Dangling { - node: SyntaxNode, - comment: SourceComment, - }, - - /// Uses the default heuristic to determine the placement of the comment. - /// - /// # Same line comments - /// - /// Makes the comment a... - /// - /// * [trailing comment] of the [`preceding_node`] if both the [`following_node`] and [`preceding_node`] are not [None] - /// and the comment and [`preceding_node`] are only separated by a space (there's no token between the comment and [`preceding_node`]). - /// * [leading comment] of the [`following_node`] if the [`following_node`] is not [None] - /// * [trailing comment] of the [`preceding_node`] if the [`preceding_node`] is not [None] - /// * [dangling comment] of the [`enclosing_node`]. - /// - /// ## Examples - /// ### Comment with preceding and following nodes - /// - /// ```ignore - /// [ - /// a, // comment - /// b - /// ] - /// ``` - /// - /// The comment becomes a [trailing comment] of the node `a`. - /// - /// ### Comment with preceding node only - /// - /// ```ignore - /// [ - /// a // comment - /// ] - /// ``` - /// - /// The comment becomes a [trailing comment] of the node `a`. - /// - /// ### Comment with following node only - /// - /// ```ignore - /// [ // comment - /// b - /// ] - /// ``` - /// - /// The comment becomes a [leading comment] of the node `b`. - /// - /// ### Dangling comment - /// - /// ```ignore - /// [ // comment - /// ] - /// ``` - /// - /// The comment becomes a [dangling comment] of the enclosing array expression because both the [`preceding_node`] and [`following_node`] are [None]. - /// - /// # Own line comments - /// - /// Makes the comment a... - /// - /// * [leading comment] of the [`following_node`] if the [`following_node`] is not [None] - /// * or a [trailing comment] of the [`preceding_node`] if the [`preceding_node`] is not [None] - /// * or a [dangling comment] of the [`enclosing_node`]. - /// - /// ## Examples - /// - /// ### Comment with leading and preceding nodes - /// - /// ```ignore - /// [ - /// a, - /// // comment - /// b - /// ] - /// ``` - /// - /// The comment becomes a [leading comment] of the node `b`. - /// - /// ### Comment with preceding node only - /// - /// ```ignore - /// [ - /// a - /// // comment - /// ] - /// ``` - /// - /// The comment becomes a [trailing comment] of the node `a`. - /// - /// ### Comment with following node only - /// - /// ```ignore - /// [ - /// // comment - /// b - /// ] - /// ``` - /// - /// The comment becomes a [leading comment] of the node `b`. - /// - /// ### Dangling comment - /// - /// ```ignore - /// [ - /// // comment - /// ] - /// ``` - /// - /// The comment becomes a [dangling comment] of the array expression because both [`preceding_node`] and [`following_node`] are [None]. - /// - /// - /// # End of line comments - /// Makes the comment a... - /// - /// * [trailing comment] of the [`preceding_node`] if the [`preceding_node`] is not [None] - /// * or a [leading comment] of the [`following_node`] if the [`following_node`] is not [None] - /// * or a [dangling comment] of the [`enclosing_node`]. - /// - /// - /// ## Examples - /// - /// ### Comment with leading and preceding nodes - /// - /// ```ignore - /// [a /* comment */, b] - /// ``` - /// - /// The comment becomes a [trailing comment] of the node `a` because there's no token between the node `a` and the `comment`. - /// - /// ```ignore - /// [a, /* comment */ b] - /// ``` - /// - /// The comment becomes a [leading comment] of the node `b` because the node `a` and the comment are separated by a `,` token. - /// - /// ### Comment with preceding node only - /// - /// ```ignore - /// [a, /* last */ ] - /// ``` - /// - /// The comment becomes a [trailing comment] of the node `a` because the [`following_node`] is [None]. - /// - /// ### Comment with following node only - /// - /// ```ignore - /// [/* comment */ b] - /// ``` - /// - /// The comment becomes a [leading comment] of the node `b` because the [`preceding_node`] is [None] - /// - /// ### Dangling comment - /// - /// ```ignore - /// [/* comment*/] - /// ``` - /// - /// The comment becomes a [dangling comment] of the array expression because both [`preceding_node`] and [`following_node`] are [None]. - /// - /// [`preceding_node`]: DecoratedComment::preceding_node - /// [`following_node`]: DecoratedComment::following_node - /// [`enclosing_node`]: DecoratedComment::enclosing_node - /// [trailing comment]: self#trailing-comments - /// [leading comment]: self#leading-comments - /// [dangling comment]: self#dangling-comments - Default(DecoratedComment), -} - -impl CommentPlacement { - /// Makes `comment` a [leading comment](self#leading-comments) of `node`. - #[inline] - pub fn leading(node: SyntaxNode, comment: impl Into>) -> Self { - Self::Leading { - node, - comment: comment.into(), - } - } - - /// Makes `comment` a [dangling comment](self::dangling-comments) of `node`. - pub fn dangling(node: SyntaxNode, comment: impl Into>) -> Self { - Self::Dangling { - node, - comment: comment.into(), - } - } - - /// Makes `comment` a [trailing comment](self::trailing-comments) of `node`. - #[inline] - pub fn trailing(node: SyntaxNode, comment: impl Into>) -> Self { - Self::Trailing { - node, - comment: comment.into(), - } - } - - /// Returns the placement if it isn't [CommentPlacement::Default], otherwise calls `f` and returns the result. - #[inline] - pub fn or_else(self, f: F) -> Self - where - F: FnOnce(DecoratedComment) -> CommentPlacement, - { - match self { - CommentPlacement::Default(comment) => f(comment), - placement => placement, - } - } -} - -/// Defines how to format comments for a specific [Language]. -pub trait CommentStyle: Default { - type Language: Language; - - /// Returns `true` if a comment with the given `text` is a `rome-ignore format:` suppression comment. - fn is_suppression(_text: &str) -> bool { - false - } - - /// Returns the (kind)[CommentKind] of the comment - fn get_comment_kind(comment: &SyntaxTriviaPieceComments) -> CommentKind; - - /// Determines the placement of `comment`. - /// - /// The default implementation returns [CommentPlacement::Default]. - fn place_comment( - &self, - comment: DecoratedComment, - ) -> CommentPlacement { - CommentPlacement::Default(comment) - } -} - -/// The comments of a syntax tree stored by node. -/// -/// Cloning `comments` is cheap as it only involves bumping a reference counter. -#[derive(Debug, Clone, Default)] -pub struct Comments { - /// The use of a [Rc] is necessary to achieve that [Comments] has a lifetime that is independent from the [crate::Formatter]. - /// Having independent lifetimes is necessary to support the use case where a (formattable object)[crate::Format] - /// iterates over all comments, and writes them into the [crate::Formatter] (mutably borrowing the [crate::Formatter] and in turn its context). - /// - /// ```block - /// for leading in f.context().comments().leading_comments(node) { - /// ^ - /// |- Borrows comments - /// write!(f, [comment(leading.piece.text())])?; - /// ^ - /// |- Mutably borrows the formatter, state, context, and comments (if comments aren't cloned) - /// } - /// ``` - /// - /// Using an `Rc` here allows to cheaply clone [Comments] for these use cases. - data: Rc>, -} - -impl Comments { - /// Extracts all the comments from `root` and its descendants nodes. - pub fn from_node