Skip to main content

rustfmt_nightly/
comment.rs

1// Formatting and tools for comments.
2
3use std::{borrow::Cow, iter};
4
5use itertools::{Itertools as _, MultiPeek, multipeek};
6use rustc_span::Span;
7use tracing::{debug, trace};
8
9use crate::config::Config;
10use crate::rewrite::{RewriteContext, RewriteErrorExt, RewriteResult};
11use crate::shape::{Indent, Shape};
12use crate::string::{StringFormat, rewrite_string};
13use crate::utils::{
14    count_newlines, first_line_width, last_line_width, trim_left_preserve_layout,
15    trimmed_last_line_width, unicode_str_width,
16};
17use crate::{ErrorKind, FormattingError};
18
19fn is_custom_comment(comment: &str) -> bool {
20    if !comment.starts_with("//") {
21        false
22    } else if let Some(c) = comment.chars().nth(2) {
23        !c.is_alphanumeric() && !c.is_whitespace()
24    } else {
25        false
26    }
27}
28
29#[derive(Copy, Clone, PartialEq, Eq)]
30pub(crate) enum CommentStyle<'a> {
31    DoubleSlash,
32    TripleSlash,
33    Doc,
34    SingleBullet,
35    DoubleBullet,
36    Exclamation,
37    Custom(&'a str),
38}
39
40fn custom_opener(s: &str) -> &str {
41    s.lines().next().map_or("", |first_line| {
42        first_line
43            .find(' ')
44            .map_or(first_line, |space_index| &first_line[0..=space_index])
45    })
46}
47
48impl<'a> CommentStyle<'a> {
49    /// Returns `true` if the commenting style cannot span multiple lines.
50    pub(crate) fn is_line_comment(&self) -> bool {
51        matches!(
52            self,
53            CommentStyle::DoubleSlash
54                | CommentStyle::TripleSlash
55                | CommentStyle::Doc
56                | CommentStyle::Custom(_)
57        )
58    }
59
60    /// Returns `true` if the commenting style can span multiple lines.
61    pub(crate) fn is_block_comment(&self) -> bool {
62        matches!(
63            self,
64            CommentStyle::SingleBullet | CommentStyle::DoubleBullet | CommentStyle::Exclamation
65        )
66    }
67
68    /// Returns `true` if the commenting style is for documentation.
69    pub(crate) fn is_doc_comment(&self) -> bool {
70        matches!(*self, CommentStyle::TripleSlash | CommentStyle::Doc)
71    }
72
73    pub(crate) fn opener(&self) -> &'a str {
74        match *self {
75            CommentStyle::DoubleSlash => "// ",
76            CommentStyle::TripleSlash => "/// ",
77            CommentStyle::Doc => "//! ",
78            CommentStyle::SingleBullet => "/* ",
79            CommentStyle::DoubleBullet => "/** ",
80            CommentStyle::Exclamation => "/*! ",
81            CommentStyle::Custom(opener) => opener,
82        }
83    }
84
85    pub(crate) fn closer(&self) -> &'a str {
86        match *self {
87            CommentStyle::DoubleSlash
88            | CommentStyle::TripleSlash
89            | CommentStyle::Custom(..)
90            | CommentStyle::Doc => "",
91            CommentStyle::SingleBullet | CommentStyle::DoubleBullet | CommentStyle::Exclamation => {
92                " */"
93            }
94        }
95    }
96
97    pub(crate) fn comment_prefix(&self) -> &'a str {
98        match *self {
99            CommentStyle::DoubleSlash => "// ",
100            CommentStyle::TripleSlash => "/// ",
101            CommentStyle::Doc => "//! ",
102            CommentStyle::SingleBullet | CommentStyle::DoubleBullet | CommentStyle::Exclamation => {
103                " * "
104            }
105            CommentStyle::Custom(opener) => opener,
106        }
107    }
108
109    pub(crate) fn to_str_tuplet(&self) -> (&'a str, &'a str, &'a str) {
110        (self.opener(), self.closer(), self.comment_prefix())
111    }
112}
113
114pub(crate) fn comment_style(orig: &str, normalize_comments: bool) -> CommentStyle<'_> {
115    if !normalize_comments {
116        if orig.starts_with("/**") && !orig.starts_with("/**/") {
117            CommentStyle::DoubleBullet
118        } else if orig.starts_with("/*!") {
119            CommentStyle::Exclamation
120        } else if orig.starts_with("/*") {
121            CommentStyle::SingleBullet
122        } else if orig.starts_with("///") && orig.chars().nth(3).map_or(true, |c| c != '/') {
123            CommentStyle::TripleSlash
124        } else if orig.starts_with("//!") {
125            CommentStyle::Doc
126        } else if is_custom_comment(orig) {
127            CommentStyle::Custom(custom_opener(orig))
128        } else {
129            CommentStyle::DoubleSlash
130        }
131    } else if (orig.starts_with("///") && orig.chars().nth(3).map_or(true, |c| c != '/'))
132        || (orig.starts_with("/**") && !orig.starts_with("/**/"))
133    {
134        CommentStyle::TripleSlash
135    } else if orig.starts_with("//!") || orig.starts_with("/*!") {
136        CommentStyle::Doc
137    } else if is_custom_comment(orig) {
138        CommentStyle::Custom(custom_opener(orig))
139    } else {
140        CommentStyle::DoubleSlash
141    }
142}
143
144/// Returns true if the last line of the passed string finishes with a block-comment.
145pub(crate) fn is_last_comment_block(s: &str) -> bool {
146    s.trim_end().ends_with("*/")
147}
148
149/// Combine `prev_str` and `next_str` into a single `String`. `span` may contain
150/// comments between two strings. If there are such comments, then that will be
151/// recovered. If `allow_extend` is true and there is no comment between the two
152/// strings, then they will be put on a single line as long as doing so does not
153/// exceed max width.
154pub(crate) fn combine_strs_with_missing_comments(
155    context: &RewriteContext<'_>,
156    prev_str: &str,
157    next_str: &str,
158    span: Span,
159    shape: Shape,
160    allow_extend: bool,
161) -> RewriteResult {
162    trace!(
163        "combine_strs_with_missing_comments `{}` `{}` {:?} {:?}",
164        prev_str, next_str, span, shape
165    );
166
167    let mut result =
168        String::with_capacity(prev_str.len() + next_str.len() + shape.indent.width() + 128);
169    result.push_str(prev_str);
170    let mut allow_one_line = !prev_str.contains('\n') && !next_str.contains('\n');
171    let first_sep =
172        if prev_str.is_empty() || next_str.is_empty() || trimmed_last_line_width(prev_str) == 0 {
173            ""
174        } else {
175            " "
176        };
177    let mut one_line_width = last_line_width(prev_str, context.config.tab_spaces())
178        + first_line_width(next_str)
179        + first_sep.len();
180
181    let config = context.config;
182    let indent = shape.indent;
183    let missing_comment = rewrite_missing_comment(span, shape, context)?;
184
185    if missing_comment.is_empty() {
186        if allow_extend && one_line_width <= shape.width {
187            result.push_str(first_sep);
188        } else if !prev_str.is_empty() {
189            result.push_str(&indent.to_string_with_newline(config))
190        }
191        result.push_str(next_str);
192        return Ok(result);
193    }
194
195    // We have a missing comment between the first expression and the second expression.
196
197    // Peek the original source code and find out whether there is a newline between the first
198    // expression and the second expression or the missing comment. We will preserve the original
199    // layout whenever possible.
200    let original_snippet = context.snippet(span);
201    let prefer_same_line = if let Some(pos) = original_snippet.find('/') {
202        !original_snippet[..pos].contains('\n')
203    } else {
204        !original_snippet.contains('\n')
205    };
206
207    one_line_width -= first_sep.len();
208    let first_sep = if prev_str.is_empty() || missing_comment.is_empty() {
209        Cow::from("")
210    } else {
211        let one_line_width = last_line_width(prev_str, context.config.tab_spaces())
212            + first_line_width(&missing_comment)
213            + 1;
214        if prefer_same_line && one_line_width <= shape.width {
215            Cow::from(" ")
216        } else {
217            indent.to_string_with_newline(config)
218        }
219    };
220    result.push_str(&first_sep);
221    result.push_str(&missing_comment);
222
223    let second_sep = if missing_comment.is_empty() || next_str.is_empty() {
224        Cow::from("")
225    } else if missing_comment.starts_with("//") {
226        indent.to_string_with_newline(config)
227    } else {
228        one_line_width += missing_comment.len() + first_sep.len() + 1;
229        allow_one_line &= !missing_comment.starts_with("//") && !missing_comment.contains('\n');
230        if prefer_same_line && allow_one_line && one_line_width <= shape.width {
231            Cow::from(" ")
232        } else {
233            indent.to_string_with_newline(config)
234        }
235    };
236    result.push_str(&second_sep);
237    result.push_str(next_str);
238
239    Ok(result)
240}
241
242pub(crate) fn rewrite_doc_comment(orig: &str, shape: Shape, config: &Config) -> RewriteResult {
243    identify_comment(orig, false, shape, config, true)
244}
245
246pub(crate) fn rewrite_comment(
247    orig: &str,
248    block_style: bool,
249    shape: Shape,
250    config: &Config,
251) -> RewriteResult {
252    identify_comment(orig, block_style, shape, config, false)
253}
254
255fn identify_comment(
256    orig: &str,
257    block_style: bool,
258    shape: Shape,
259    config: &Config,
260    is_doc_comment: bool,
261) -> RewriteResult {
262    let style = comment_style(orig, false);
263
264    // Computes the byte length of line taking into account a newline if the line is part of a
265    // paragraph.
266    fn compute_len(orig: &str, line: &str) -> usize {
267        if orig.len() > line.len() {
268            if orig.as_bytes()[line.len()] == b'\r' {
269                line.len() + 2
270            } else {
271                line.len() + 1
272            }
273        } else {
274            line.len()
275        }
276    }
277
278    // Get the first group of line comments having the same commenting style.
279    //
280    // Returns a tuple with:
281    // - a boolean indicating if there is a blank line
282    // - a number indicating the size of the first group of comments
283    fn consume_same_line_comments(
284        style: CommentStyle<'_>,
285        orig: &str,
286        line_start: &str,
287    ) -> (bool, usize) {
288        let mut first_group_ending = 0;
289        let mut hbl = false;
290
291        for line in orig.lines() {
292            let trimmed_line = line.trim_start();
293            if trimmed_line.is_empty() {
294                hbl = true;
295                break;
296            } else if trimmed_line.starts_with(line_start)
297                || comment_style(trimmed_line, false) == style
298            {
299                first_group_ending += compute_len(&orig[first_group_ending..], line);
300            } else {
301                break;
302            }
303        }
304        (hbl, first_group_ending)
305    }
306
307    let (has_bare_lines, first_group_ending) = match style {
308        CommentStyle::DoubleSlash | CommentStyle::TripleSlash | CommentStyle::Doc => {
309            let line_start = style.comment_prefix().trim_start();
310            consume_same_line_comments(style, orig, line_start)
311        }
312        CommentStyle::Custom(opener) => {
313            let trimmed_opener = opener.trim_end();
314            consume_same_line_comments(style, orig, trimmed_opener)
315        }
316        // for a block comment, search for the closing symbol
317        CommentStyle::DoubleBullet | CommentStyle::SingleBullet | CommentStyle::Exclamation => {
318            let closer = style.closer().trim_start();
319            let mut count = orig.matches(closer).count();
320            let mut closing_symbol_offset = 0;
321            let mut hbl = false;
322            let mut first = true;
323            for line in orig.lines() {
324                closing_symbol_offset += compute_len(&orig[closing_symbol_offset..], line);
325                let mut trimmed_line = line.trim_start();
326                if !trimmed_line.starts_with('*')
327                    && !trimmed_line.starts_with("//")
328                    && !trimmed_line.starts_with("/*")
329                {
330                    hbl = true;
331                }
332
333                // Remove opener from consideration when searching for closer
334                if first {
335                    let opener = style.opener().trim_end();
336                    trimmed_line = &trimmed_line[opener.len()..];
337                    first = false;
338                }
339                if trimmed_line.ends_with(closer) {
340                    count -= 1;
341                    if count == 0 {
342                        break;
343                    }
344                }
345            }
346            (hbl, closing_symbol_offset)
347        }
348    };
349
350    let (first_group, rest) = orig.split_at(first_group_ending);
351    let rewritten_first_group =
352        if !config.normalize_comments() && has_bare_lines && style.is_block_comment() {
353            trim_left_preserve_layout(first_group, shape.indent, config).unknown_error()?
354        } else if !config.normalize_comments()
355            && !config.wrap_comments()
356            && !(
357                // `format_code_in_doc_comments` should only take effect on doc comments,
358                // so we only consider it when this comment block is a doc comment block.
359                is_doc_comment && config.format_code_in_doc_comments()
360            )
361        {
362            light_rewrite_comment(first_group, shape.indent, config, is_doc_comment)
363        } else {
364            rewrite_comment_inner(
365                first_group,
366                block_style,
367                style,
368                shape,
369                config,
370                is_doc_comment || style.is_doc_comment(),
371            )?
372        };
373    if rest.is_empty() {
374        Ok(rewritten_first_group)
375    } else {
376        identify_comment(
377            rest.trim_start(),
378            block_style,
379            shape,
380            config,
381            is_doc_comment,
382        )
383        .map(|rest_str| {
384            format!(
385                "{}\n{}{}{}",
386                rewritten_first_group,
387                // insert back the blank line
388                if has_bare_lines && style.is_line_comment() {
389                    "\n"
390                } else {
391                    ""
392                },
393                shape.indent.to_string(config),
394                rest_str
395            )
396        })
397    }
398}
399
400/// Enum indicating if the code block contains rust based on attributes
401enum CodeBlockAttribute {
402    Rust,
403    NotRust,
404}
405
406impl CodeBlockAttribute {
407    /// Parse comma separated attributes list. Return rust only if all
408    /// attributes are valid rust attributes
409    /// See <https://doc.rust-lang.org/rustdoc/print.html#attributes>
410    fn new(attributes: &str) -> CodeBlockAttribute {
411        for attribute in attributes.split(',') {
412            match attribute.trim() {
413                "" | "rust" | "should_panic" | "no_run" | "edition2015" | "edition2018"
414                | "edition2021" => (),
415                "ignore" | "compile_fail" | "text" => return CodeBlockAttribute::NotRust,
416                _ => return CodeBlockAttribute::NotRust,
417            }
418        }
419        CodeBlockAttribute::Rust
420    }
421}
422
423/// Block that is formatted as an item.
424///
425/// An item starts with either a star `*`, a dash `-`, a greater-than `>`, a plus '+', or a number
426/// `12.` or `34)` (with at most 2 digits). An item represents CommonMark's ["list
427/// items"](https://spec.commonmark.org/0.30/#list-items) and/or ["block
428/// quotes"](https://spec.commonmark.org/0.30/#block-quotes), but note that only a subset of
429/// CommonMark is recognized - see the doc comment of [`ItemizedBlock::get_marker_length`] for more
430/// details.
431///
432/// Different level of indentation are handled by shrinking the shape accordingly.
433struct ItemizedBlock {
434    /// the lines that are identified as part of an itemized block
435    lines: Vec<String>,
436    /// the number of characters (typically whitespaces) up to the item marker
437    indent: usize,
438    /// the string that marks the start of an item
439    opener: String,
440    /// sequence of characters (typically whitespaces) to prefix new lines that are part of the item
441    line_start: String,
442}
443
444impl ItemizedBlock {
445    /// Checks whether the `trimmed` line includes an item marker. Returns `None` if there is no
446    /// marker. Returns the length of the marker (in bytes) if one is present. Note that the length
447    /// includes the whitespace that follows the marker, for example the marker in `"* list item"`
448    /// has the length of 2.
449    ///
450    /// This function recognizes item markers that correspond to CommonMark's
451    /// ["bullet list marker"](https://spec.commonmark.org/0.30/#bullet-list-marker),
452    /// ["block quote marker"](https://spec.commonmark.org/0.30/#block-quote-marker), and/or
453    /// ["ordered list marker"](https://spec.commonmark.org/0.30/#ordered-list-marker).
454    ///
455    /// Compared to CommonMark specification, the number of digits that are allowed in an ["ordered
456    /// list marker"](https://spec.commonmark.org/0.30/#ordered-list-marker) is more limited (to at
457    /// most 2 digits). Limiting the length of the marker helps reduce the risk of recognizing
458    /// arbitrary numbers as markers. See also
459    /// <https://talk.commonmark.org/t/blank-lines-before-lists-revisited/1990> which gives the
460    /// following example where a number (i.e. "1868") doesn't signify an ordered list:
461    /// ```md
462    /// The Captain died in
463    /// 1868. He wes buried in...
464    /// ```
465    fn get_marker_length(trimmed: &str) -> Option<usize> {
466        // https://spec.commonmark.org/0.30/#bullet-list-marker or
467        // https://spec.commonmark.org/0.30/#block-quote-marker
468        let itemized_start = ["* ", "- ", "> ", "+ "];
469        if itemized_start.iter().any(|s| trimmed.starts_with(s)) {
470            return Some(2); // All items in `itemized_start` have length 2.
471        }
472
473        // https://spec.commonmark.org/0.30/#ordered-list-marker, where at most 2 digits are
474        // allowed.
475        for suffix in [". ", ") "] {
476            if let Some((prefix, _)) = trimmed.split_once(suffix) {
477                let has_leading_digits = (1..=2).contains(&prefix.len())
478                    && prefix.chars().all(|c| char::is_ascii_digit(&c));
479                if has_leading_digits {
480                    return Some(prefix.len() + suffix.len());
481                }
482            }
483        }
484
485        None // No markers found.
486    }
487
488    /// Creates a new `ItemizedBlock` described with the given `line`.
489    /// Returns `None` if `line` doesn't start an item.
490    fn new(line: &str) -> Option<ItemizedBlock> {
491        let marker_length = ItemizedBlock::get_marker_length(line.trim_start())?;
492        let space_to_marker = line.chars().take_while(|c| c.is_whitespace()).count();
493        let mut indent = space_to_marker + marker_length;
494        let mut line_start = " ".repeat(indent);
495
496        // Markdown blockquote start with a "> "
497        if line.trim_start().starts_with('>') {
498            // remove the original +2 indent because there might be multiple nested block quotes
499            // and it's easier to reason about the final indent by just taking the length
500            // of the new line_start. We update the indent because it effects the max width
501            // of each formatted line.
502            line_start = itemized_block_quote_start(line, line_start, 2);
503            indent = line_start.len();
504        }
505        Some(ItemizedBlock {
506            lines: vec![line[indent..].to_string()],
507            indent,
508            opener: line[..indent].to_string(),
509            line_start,
510        })
511    }
512
513    /// Returns a `StringFormat` used for formatting the content of an item.
514    fn create_string_format<'a>(&'a self, fmt: &'a StringFormat<'_>) -> StringFormat<'a> {
515        StringFormat {
516            opener: "",
517            closer: "",
518            line_start: "",
519            line_end: "",
520            shape: Shape::legacy(fmt.shape.width.saturating_sub(self.indent), Indent::empty()),
521            trim_end: true,
522            config: fmt.config,
523        }
524    }
525
526    /// Returns `true` if the line is part of the current itemized block.
527    /// If it is, then it is added to the internal lines list.
528    fn add_line(&mut self, line: &str) -> bool {
529        if ItemizedBlock::get_marker_length(line.trim_start()).is_none()
530            && self.indent <= line.chars().take_while(|c| c.is_whitespace()).count()
531        {
532            self.lines.push(line.to_string());
533            return true;
534        }
535        false
536    }
537
538    /// Returns the block as a string, with each line trimmed at the start.
539    fn trimmed_block_as_string(&self) -> String {
540        self.lines.iter().fold(String::new(), |mut acc, line| {
541            acc.push_str(line.trim_start());
542            acc.push(' ');
543            acc
544        })
545    }
546
547    /// Returns the block as a string under its original form.
548    fn original_block_as_string(&self) -> String {
549        self.lines.join("\n")
550    }
551}
552
553/// Determine the line_start when formatting markdown block quotes.
554/// The original line_start likely contains indentation (whitespaces), which we'd like to
555/// replace with '> ' characters.
556fn itemized_block_quote_start(line: &str, mut line_start: String, remove_indent: usize) -> String {
557    let quote_level = line
558        .chars()
559        .take_while(|c| !c.is_alphanumeric())
560        .fold(0, |acc, c| if c == '>' { acc + 1 } else { acc });
561
562    for _ in 0..remove_indent {
563        line_start.pop();
564    }
565
566    for _ in 0..quote_level {
567        line_start.push_str("> ");
568    }
569    line_start
570}
571
572struct CommentRewrite<'a> {
573    result: String,
574    code_block_buffer: String,
575    is_prev_line_multi_line: bool,
576    code_block_attr: Option<CodeBlockAttribute>,
577    item_block: Option<ItemizedBlock>,
578    comment_line_separator: String,
579    indent_str: String,
580    max_width: usize,
581    fmt_indent: Indent,
582    fmt: StringFormat<'a>,
583
584    opener: String,
585    closer: String,
586    comment_prefix: String,
587    style: CommentStyle<'a>,
588}
589
590impl<'a> CommentRewrite<'a> {
591    fn new(
592        orig: &'a str,
593        block_style: bool,
594        shape: Shape,
595        config: &'a Config,
596    ) -> CommentRewrite<'a> {
597        let ((opener, closer, line_start), style) = if block_style {
598            (
599                CommentStyle::SingleBullet.to_str_tuplet(),
600                CommentStyle::SingleBullet,
601            )
602        } else {
603            let style = comment_style(orig, config.normalize_comments());
604            (style.to_str_tuplet(), style)
605        };
606
607        let max_width = shape
608            .width
609            .checked_sub(closer.len() + opener.len())
610            .unwrap_or(1);
611        let indent_str = shape.indent.to_string_with_newline(config).to_string();
612
613        let mut cr = CommentRewrite {
614            result: String::with_capacity(orig.len() * 2),
615            code_block_buffer: String::with_capacity(128),
616            is_prev_line_multi_line: false,
617            code_block_attr: None,
618            item_block: None,
619            comment_line_separator: format!("{indent_str}{line_start}"),
620            max_width,
621            indent_str,
622            fmt_indent: shape.indent,
623
624            fmt: StringFormat {
625                opener: "",
626                closer: "",
627                line_start,
628                line_end: "",
629                shape: Shape::legacy(max_width, shape.indent),
630                trim_end: true,
631                config,
632            },
633
634            opener: opener.to_owned(),
635            closer: closer.to_owned(),
636            comment_prefix: line_start.to_owned(),
637            style,
638        };
639        cr.result.push_str(opener);
640        cr
641    }
642
643    fn join_block(s: &str, sep: &str) -> String {
644        let mut result = String::with_capacity(s.len() + 128);
645        let mut iter = s.lines().peekable();
646        while let Some(line) = iter.next() {
647            result.push_str(line);
648            result.push_str(match iter.peek() {
649                Some(&"") => sep.trim_end(),
650                Some(..) => sep,
651                None => "",
652            });
653        }
654        result
655    }
656
657    /// Check if any characters were written to the result buffer after the start of the comment.
658    /// when calling [`CommentRewrite::new()`] the result buffer is initialized with the opening
659    /// characters for the comment.
660    fn buffer_contains_comment(&self) -> bool {
661        // if self.result.len() < self.opener.len() then an empty comment is in the buffer
662        // if self.result.len() > self.opener.len() then a non empty comment is in the buffer
663        self.result.len() != self.opener.len()
664    }
665
666    fn finish(mut self) -> String {
667        if !self.code_block_buffer.is_empty() {
668            // There is a code block that is not properly enclosed by backticks.
669            // We will leave them untouched.
670            self.result.push_str(&self.comment_line_separator);
671            self.result.push_str(&Self::join_block(
672                &trim_custom_comment_prefix(&self.code_block_buffer),
673                &self.comment_line_separator,
674            ));
675        }
676
677        if let Some(ref ib) = self.item_block {
678            // the last few lines are part of an itemized block
679            self.fmt.shape = Shape::legacy(self.max_width, self.fmt_indent);
680            let item_fmt = ib.create_string_format(&self.fmt);
681
682            // only push a comment_line_separator for ItemizedBlocks if the comment is not empty
683            if self.buffer_contains_comment() {
684                self.result.push_str(&self.comment_line_separator);
685            }
686
687            self.result.push_str(&ib.opener);
688            match rewrite_string(
689                &ib.trimmed_block_as_string(),
690                &item_fmt,
691                self.max_width.saturating_sub(ib.indent),
692            ) {
693                Some(s) => self.result.push_str(&Self::join_block(
694                    &s,
695                    &format!("{}{}", self.comment_line_separator, ib.line_start),
696                )),
697                None => self.result.push_str(&Self::join_block(
698                    &ib.original_block_as_string(),
699                    &self.comment_line_separator,
700                )),
701            };
702        }
703
704        self.result.push_str(&self.closer);
705        if self.result.ends_with(&self.opener) && self.opener.ends_with(' ') {
706            // Trailing space.
707            self.result.pop();
708        }
709
710        self.result
711    }
712
713    fn handle_line(
714        &mut self,
715        orig: &'a str,
716        i: usize,
717        line: &'a str,
718        has_leading_whitespace: bool,
719        is_doc_comment: bool,
720    ) -> bool {
721        let num_newlines = count_newlines(orig);
722        let is_last = i == num_newlines;
723        let needs_new_comment_line = if self.style.is_block_comment() {
724            num_newlines > 0 || self.buffer_contains_comment()
725        } else {
726            self.buffer_contains_comment()
727        };
728
729        if let Some(ref mut ib) = self.item_block {
730            if ib.add_line(line) {
731                return false;
732            }
733            self.is_prev_line_multi_line = false;
734            self.fmt.shape = Shape::legacy(self.max_width, self.fmt_indent);
735            let item_fmt = ib.create_string_format(&self.fmt);
736
737            // only push a comment_line_separator if we need to start a new comment line
738            if needs_new_comment_line {
739                self.result.push_str(&self.comment_line_separator);
740            }
741
742            self.result.push_str(&ib.opener);
743            match rewrite_string(
744                &ib.trimmed_block_as_string(),
745                &item_fmt,
746                self.max_width.saturating_sub(ib.indent),
747            ) {
748                Some(s) => self.result.push_str(&Self::join_block(
749                    &s,
750                    &format!("{}{}", self.comment_line_separator, ib.line_start),
751                )),
752                None => self.result.push_str(&Self::join_block(
753                    &ib.original_block_as_string(),
754                    &self.comment_line_separator,
755                )),
756            };
757        } else if self.code_block_attr.is_some() {
758            if line.starts_with("```") {
759                let code_block = match self.code_block_attr.as_ref().unwrap() {
760                    CodeBlockAttribute::Rust
761                        if self.fmt.config.format_code_in_doc_comments()
762                            && !self.code_block_buffer.trim().is_empty() =>
763                    {
764                        let mut config = self.fmt.config.clone();
765                        config.set().wrap_comments(false);
766                        let comment_max_width = config
767                            .doc_comment_code_block_width()
768                            .min(config.max_width());
769                        config.set().max_width(comment_max_width);
770                        if let Some(comment_use_small_heuristics) = config
771                            .doc_comment_code_block_small_heuristics()
772                            .to_heuristics()
773                        {
774                            config
775                                .set()
776                                .use_small_heuristics(comment_use_small_heuristics);
777                        }
778                        if let Some(s) =
779                            crate::format_code_block(&self.code_block_buffer, &config, false)
780                        {
781                            trim_custom_comment_prefix(&s.snippet)
782                        } else {
783                            trim_custom_comment_prefix(&self.code_block_buffer)
784                        }
785                    }
786                    _ => trim_custom_comment_prefix(&self.code_block_buffer),
787                };
788                if !code_block.is_empty() {
789                    self.result.push_str(&self.comment_line_separator);
790                    self.result
791                        .push_str(&Self::join_block(&code_block, &self.comment_line_separator));
792                }
793                self.code_block_buffer.clear();
794                self.result.push_str(&self.comment_line_separator);
795                self.result.push_str(line);
796                self.code_block_attr = None;
797            } else {
798                self.code_block_buffer
799                    .push_str(&hide_sharp_behind_comment(line));
800                self.code_block_buffer.push('\n');
801            }
802            return false;
803        }
804
805        self.code_block_attr = None;
806        self.item_block = None;
807        if let Some(stripped) = line.strip_prefix("```") {
808            self.code_block_attr = Some(CodeBlockAttribute::new(stripped))
809        } else if self.fmt.config.wrap_comments() {
810            if let Some(ib) = ItemizedBlock::new(line) {
811                self.item_block = Some(ib);
812                return false;
813            }
814        }
815
816        if self.result == self.opener {
817            let force_leading_whitespace = &self.opener == "/* " && count_newlines(orig) == 0;
818            if !has_leading_whitespace && !force_leading_whitespace && self.result.ends_with(' ') {
819                self.result.pop();
820            }
821            if line.is_empty() {
822                return false;
823            }
824        } else if self.is_prev_line_multi_line && !line.is_empty() {
825            self.result.push(' ')
826        } else if is_last && line.is_empty() {
827            // trailing blank lines are unwanted
828            if !self.closer.is_empty() {
829                self.result.push_str(&self.indent_str);
830            }
831            return true;
832        } else {
833            self.result.push_str(&self.comment_line_separator);
834            if !has_leading_whitespace && self.result.ends_with(' ') {
835                self.result.pop();
836            }
837        }
838
839        let is_markdown_header_doc_comment = is_doc_comment && line.starts_with('#');
840
841        // We only want to wrap the comment if:
842        // 1) wrap_comments = true is configured
843        // 2) The comment is not the start of a markdown header doc comment
844        // 3) The comment width exceeds the shape's width
845        // 4) No URLS were found in the comment
846        // If this changes, the documentation in ../Configurations.md#wrap_comments
847        // should be changed accordingly.
848        let should_wrap_comment = self.fmt.config.wrap_comments()
849            && !is_markdown_header_doc_comment
850            && unicode_str_width(line) > self.fmt.shape.width
851            && !has_url(line)
852            && !is_table_item(line);
853
854        if should_wrap_comment {
855            match rewrite_string(line, &self.fmt, self.max_width) {
856                Some(ref s) => {
857                    self.is_prev_line_multi_line = s.contains('\n');
858                    self.result.push_str(s);
859                }
860                None if self.is_prev_line_multi_line => {
861                    // We failed to put the current `line` next to the previous `line`.
862                    // Remove the trailing space, then start rewrite on the next line.
863                    self.result.pop();
864                    self.result.push_str(&self.comment_line_separator);
865                    self.fmt.shape = Shape::legacy(self.max_width, self.fmt_indent);
866                    match rewrite_string(line, &self.fmt, self.max_width) {
867                        Some(ref s) => {
868                            self.is_prev_line_multi_line = s.contains('\n');
869                            self.result.push_str(s);
870                        }
871                        None => {
872                            self.is_prev_line_multi_line = false;
873                            self.result.push_str(line);
874                        }
875                    }
876                }
877                None => {
878                    self.is_prev_line_multi_line = false;
879                    self.result.push_str(line);
880                }
881            }
882
883            self.fmt.shape = if self.is_prev_line_multi_line {
884                // 1 = " "
885                let offset = 1 + last_line_width(&self.result, self.fmt.config.tab_spaces())
886                    - self.comment_prefix.len()
887                    - self.fmt_indent.width();
888                Shape {
889                    width: self.max_width.saturating_sub(offset),
890                    indent: self.fmt_indent,
891                    offset: self.fmt.shape.offset + offset,
892                }
893            } else {
894                Shape::legacy(self.max_width, self.fmt_indent)
895            };
896        } else {
897            if line.is_empty() && self.result.ends_with(' ') && !is_last {
898                // Remove space if this is an empty comment or a doc comment.
899                self.result.pop();
900            }
901            if self.code_block_attr.is_some() && self.is_prev_line_multi_line {
902                self.result.push_str(&self.comment_line_separator);
903            }
904            self.result.push_str(line);
905            self.fmt.shape = Shape::legacy(self.max_width, self.fmt_indent);
906            self.is_prev_line_multi_line = false;
907        }
908
909        false
910    }
911}
912
913fn rewrite_comment_inner(
914    orig: &str,
915    block_style: bool,
916    style: CommentStyle<'_>,
917    shape: Shape,
918    config: &Config,
919    is_doc_comment: bool,
920) -> RewriteResult {
921    let mut rewriter = CommentRewrite::new(orig, block_style, shape, config);
922
923    let line_breaks = count_newlines(orig.trim_end());
924    let lines = orig
925        .lines()
926        .enumerate()
927        .map(|(i, mut line)| {
928            line = trim_end_unless_two_whitespaces(line.trim_start(), is_doc_comment);
929            // Drop old closer.
930            if i == line_breaks && line.ends_with("*/") && !line.starts_with("//") {
931                line = line[..(line.len() - 2)].trim_end();
932            }
933
934            line
935        })
936        .map(|s| left_trim_comment_line(s, &style))
937        .map(|(line, has_leading_whitespace)| {
938            if orig.starts_with("/*") && line_breaks == 0 {
939                (
940                    line.trim_start(),
941                    has_leading_whitespace || config.normalize_comments(),
942                )
943            } else {
944                (line, has_leading_whitespace || config.normalize_comments())
945            }
946        });
947
948    for (i, (line, has_leading_whitespace)) in lines.enumerate() {
949        if rewriter.handle_line(orig, i, line, has_leading_whitespace, is_doc_comment) {
950            break;
951        }
952    }
953
954    Ok(rewriter.finish())
955}
956
957const RUSTFMT_CUSTOM_COMMENT_PREFIX: &str = "//#### ";
958
959fn hide_sharp_behind_comment(s: &str) -> Cow<'_, str> {
960    let s_trimmed = s.trim();
961    if s_trimmed.starts_with("# ") || s_trimmed == "#" {
962        Cow::from(format!("{RUSTFMT_CUSTOM_COMMENT_PREFIX}{s}"))
963    } else {
964        Cow::from(s)
965    }
966}
967
968fn trim_custom_comment_prefix(s: &str) -> String {
969    s.lines()
970        .map(|line| {
971            let left_trimmed = line.trim_start();
972            if left_trimmed.starts_with(RUSTFMT_CUSTOM_COMMENT_PREFIX) {
973                left_trimmed.trim_start_matches(RUSTFMT_CUSTOM_COMMENT_PREFIX)
974            } else {
975                line
976            }
977        })
978        .collect::<Vec<_>>()
979        .join("\n")
980}
981
982/// Returns `true` if the given string MAY include URLs or alike.
983fn has_url(s: &str) -> bool {
984    // A regex matching reference doc links.
985    //
986    // ```markdown
987    // /// An [example].
988    // ///
989    // /// [example]: this::is::a::link
990    // ```
991    let reference_link_url = static_regex!(r"^\[.+\]\s?:");
992
993    // This function may return false positive, but should get its job done in most cases.
994    s.contains("https://")
995        || s.contains("http://")
996        || s.contains("ftp://")
997        || s.contains("file://")
998        || reference_link_url.is_match(s)
999}
1000
1001/// Returns true if the given string may be part of a Markdown table.
1002fn is_table_item(mut s: &str) -> bool {
1003    // This function may return false positive, but should get its job done in most cases (i.e.
1004    // markdown tables with two column delimiters).
1005    s = s.trim_start();
1006    return s.starts_with('|')
1007        && match s.rfind('|') {
1008            Some(0) | None => false,
1009            _ => true,
1010        };
1011}
1012
1013/// Given the span, rewrite the missing comment inside it if available.
1014/// Note that the given span must only include comments (or leading/trailing whitespaces).
1015pub(crate) fn rewrite_missing_comment(
1016    span: Span,
1017    shape: Shape,
1018    context: &RewriteContext<'_>,
1019) -> RewriteResult {
1020    let missing_snippet = context.snippet(span);
1021    let trimmed_snippet = missing_snippet.trim();
1022    // check the span starts with a comment
1023    let pos = trimmed_snippet.find('/');
1024    if !trimmed_snippet.is_empty() && pos.is_some() {
1025        rewrite_comment(trimmed_snippet, false, shape, context.config)
1026    } else {
1027        Ok(String::new())
1028    }
1029}
1030
1031/// Recover the missing comments in the specified span, if available.
1032/// The layout of the comments will be preserved as long as it does not break the code
1033/// and its total width does not exceed the max width.
1034pub(crate) fn recover_missing_comment_in_span(
1035    span: Span,
1036    shape: Shape,
1037    context: &RewriteContext<'_>,
1038    used_width: usize,
1039) -> RewriteResult {
1040    let missing_comment = rewrite_missing_comment(span, shape, context)?;
1041    if missing_comment.is_empty() {
1042        Ok(String::new())
1043    } else {
1044        let missing_snippet = context.snippet(span);
1045        let pos = missing_snippet.find('/').unknown_error()?;
1046        // 1 = ` `
1047        let total_width = missing_comment.len() + used_width + 1;
1048        let force_new_line_before_comment =
1049            missing_snippet[..pos].contains('\n') || total_width > context.config.max_width();
1050        let sep = if force_new_line_before_comment {
1051            shape.indent.to_string_with_newline(context.config)
1052        } else {
1053            Cow::from(" ")
1054        };
1055        Ok(format!("{sep}{missing_comment}"))
1056    }
1057}
1058
1059/// Trim trailing whitespaces unless they consist of two or more whitespaces.
1060fn trim_end_unless_two_whitespaces(s: &str, is_doc_comment: bool) -> &str {
1061    if is_doc_comment && s.ends_with("  ") {
1062        s
1063    } else {
1064        s.trim_end()
1065    }
1066}
1067
1068/// Trims whitespace and aligns to indent, but otherwise does not change comments.
1069fn light_rewrite_comment(
1070    orig: &str,
1071    offset: Indent,
1072    config: &Config,
1073    is_doc_comment: bool,
1074) -> String {
1075    orig.lines()
1076        .map(|l| {
1077            // This is basically just l.trim(), but in the case that a line starts
1078            // with `*` we want to leave one space before it, so it aligns with the
1079            // `*` in `/*`.
1080            let first_non_whitespace = l.find(|c| !char::is_whitespace(c));
1081            let left_trimmed = if let Some(fnw) = first_non_whitespace {
1082                if l.as_bytes()[fnw] == b'*' {
1083                    Cow::Owned(format!(" {}", &l[fnw..]))
1084                } else {
1085                    Cow::Borrowed(&l[fnw..])
1086                }
1087            } else {
1088                Cow::Borrowed("")
1089            };
1090
1091            // Preserve markdown's double-space line break syntax in doc comment.
1092            match left_trimmed {
1093                Cow::Borrowed(left_trimmed) => Cow::Borrowed(trim_end_unless_two_whitespaces(
1094                    left_trimmed,
1095                    is_doc_comment,
1096                )),
1097                Cow::Owned(left_trimmed) => {
1098                    let trimmed = trim_end_unless_two_whitespaces(&left_trimmed, is_doc_comment);
1099                    Cow::Owned(trimmed.to_string())
1100                }
1101            }
1102        })
1103        .join(&format!("\n{}", offset.to_string(config)))
1104}
1105
1106/// Trims comment characters and possibly a single space from the left of a string.
1107/// Does not trim all whitespace. If a single space is trimmed from the left of the string,
1108/// this function returns true.
1109fn left_trim_comment_line<'a>(line: &'a str, style: &CommentStyle<'_>) -> (&'a str, bool) {
1110    if line.starts_with("//! ")
1111        || line.starts_with("/// ")
1112        || line.starts_with("/*! ")
1113        || line.starts_with("/** ")
1114    {
1115        (&line[4..], true)
1116    } else if let CommentStyle::Custom(opener) = *style {
1117        if let Some(stripped) = line.strip_prefix(opener) {
1118            (stripped, true)
1119        } else {
1120            (&line[opener.trim_end().len()..], false)
1121        }
1122    } else if line.starts_with("/* ")
1123        || line.starts_with("// ")
1124        || line.starts_with("//!")
1125        || line.starts_with("///")
1126        || line.starts_with("** ")
1127        || line.starts_with("/*!")
1128        || (line.starts_with("/**") && !line.starts_with("/**/"))
1129    {
1130        (&line[3..], line.chars().nth(2).unwrap() == ' ')
1131    } else if line.starts_with("/*")
1132        || line.starts_with("* ")
1133        || line.starts_with("//")
1134        || line.starts_with("**")
1135    {
1136        (&line[2..], line.chars().nth(1).unwrap() == ' ')
1137    } else if let Some(stripped) = line.strip_prefix('*') {
1138        (stripped, false)
1139    } else {
1140        (line, line.starts_with(' '))
1141    }
1142}
1143
1144pub(crate) trait FindUncommented {
1145    fn find_uncommented(&self, pat: &str) -> Option<usize>;
1146    fn find_last_uncommented(&self, pat: &str) -> Option<usize>;
1147}
1148
1149impl FindUncommented for str {
1150    fn find_uncommented(&self, pat: &str) -> Option<usize> {
1151        let mut needle_iter = pat.chars();
1152        for (kind, (i, b)) in CharClasses::new(self.char_indices()) {
1153            match needle_iter.next() {
1154                None => {
1155                    return Some(i - pat.len());
1156                }
1157                Some(c) => match kind {
1158                    FullCodeCharKind::Normal | FullCodeCharKind::InString if b == c => {}
1159                    _ => {
1160                        needle_iter = pat.chars();
1161                    }
1162                },
1163            }
1164        }
1165
1166        // Handle case where the pattern is a suffix of the search string
1167        match needle_iter.next() {
1168            Some(_) => None,
1169            None => Some(self.len() - pat.len()),
1170        }
1171    }
1172
1173    fn find_last_uncommented(&self, pat: &str) -> Option<usize> {
1174        if let Some(left) = self.find_uncommented(pat) {
1175            let mut result = left;
1176            // add 1 to use find_last_uncommented for &str after pat
1177            while let Some(next) = self[(result + 1)..].find_last_uncommented(pat) {
1178                result += next + 1;
1179            }
1180            Some(result)
1181        } else {
1182            None
1183        }
1184    }
1185}
1186
1187// Returns the first byte position after the first comment. The given string
1188// is expected to be prefixed by a comment, including delimiters.
1189// Good: `/* /* inner */ outer */ code();`
1190// Bad:  `code(); // hello\n world!`
1191pub(crate) fn find_comment_end(s: &str) -> Option<usize> {
1192    let mut iter = CharClasses::new(s.char_indices());
1193    for (kind, (i, _c)) in &mut iter {
1194        if kind == FullCodeCharKind::Normal || kind == FullCodeCharKind::InString {
1195            return Some(i);
1196        }
1197    }
1198
1199    // Handle case where the comment ends at the end of `s`.
1200    if iter.status == CharClassesStatus::Normal {
1201        Some(s.len())
1202    } else {
1203        None
1204    }
1205}
1206
1207/// Returns `true` if text contains any comment.
1208pub(crate) fn contains_comment(text: &str) -> bool {
1209    CharClasses::new(text.chars()).any(|(kind, _)| kind.is_comment())
1210}
1211
1212pub(crate) struct CharClasses<T>
1213where
1214    T: Iterator,
1215    T::Item: RichChar,
1216{
1217    base: MultiPeek<T>,
1218    status: CharClassesStatus,
1219}
1220
1221pub(crate) trait RichChar {
1222    fn get_char(&self) -> char;
1223}
1224
1225impl RichChar for char {
1226    fn get_char(&self) -> char {
1227        *self
1228    }
1229}
1230
1231impl RichChar for (usize, char) {
1232    fn get_char(&self) -> char {
1233        self.1
1234    }
1235}
1236
1237#[derive(PartialEq, Eq, Debug, Clone, Copy)]
1238enum CharClassesStatus {
1239    Normal,
1240    /// Character is within a string
1241    LitString,
1242    LitStringEscape,
1243    /// Character is within a raw string
1244    LitRawString(u32),
1245    RawStringPrefix(u32),
1246    RawStringSuffix(u32),
1247    LitChar,
1248    LitCharEscape,
1249    /// Character inside a block comment, with the integer indicating the nesting deepness of the
1250    /// comment
1251    BlockComment(u32),
1252    /// Character inside a block-commented string, with the integer indicating the nesting deepness
1253    /// of the comment
1254    StringInBlockComment(u32),
1255    /// Status when the '/' has been consumed, but not yet the '*', deepness is
1256    /// the new deepness (after the comment opening).
1257    BlockCommentOpening(u32),
1258    /// Status when the '*' has been consumed, but not yet the '/', deepness is
1259    /// the new deepness (after the comment closing).
1260    BlockCommentClosing(u32),
1261    /// Character is within a line comment
1262    LineComment,
1263}
1264
1265/// Distinguish between functional part of code and comments
1266#[derive(PartialEq, Eq, Debug, Clone, Copy)]
1267pub(crate) enum CodeCharKind {
1268    Normal,
1269    Comment,
1270}
1271
1272/// Distinguish between functional part of code and comments,
1273/// describing opening and closing of comments for ease when chunking
1274/// code from tagged characters
1275#[derive(PartialEq, Eq, Debug, Clone, Copy)]
1276pub(crate) enum FullCodeCharKind {
1277    Normal,
1278    /// The first character of a comment, there is only one for a comment (always '/')
1279    StartComment,
1280    /// Any character inside a comment including the second character of comment
1281    /// marks ("//", "/*")
1282    InComment,
1283    /// Last character of a comment, '\n' for a line comment, '/' for a block comment.
1284    EndComment,
1285    /// Start of a multiline string inside a comment
1286    StartStringCommented,
1287    /// End of a multiline string inside a comment
1288    EndStringCommented,
1289    /// Inside a commented string
1290    InStringCommented,
1291    /// Start of a multiline string
1292    StartString,
1293    /// End of a multiline string
1294    EndString,
1295    /// Inside a string.
1296    InString,
1297}
1298
1299impl FullCodeCharKind {
1300    pub(crate) fn is_comment(self) -> bool {
1301        match self {
1302            FullCodeCharKind::StartComment
1303            | FullCodeCharKind::InComment
1304            | FullCodeCharKind::EndComment
1305            | FullCodeCharKind::StartStringCommented
1306            | FullCodeCharKind::InStringCommented
1307            | FullCodeCharKind::EndStringCommented => true,
1308            _ => false,
1309        }
1310    }
1311
1312    /// Returns true if the character is inside a comment
1313    pub(crate) fn inside_comment(self) -> bool {
1314        match self {
1315            FullCodeCharKind::InComment
1316            | FullCodeCharKind::StartStringCommented
1317            | FullCodeCharKind::InStringCommented
1318            | FullCodeCharKind::EndStringCommented => true,
1319            _ => false,
1320        }
1321    }
1322
1323    pub(crate) fn is_string(self) -> bool {
1324        self == FullCodeCharKind::InString || self == FullCodeCharKind::StartString
1325    }
1326
1327    /// Returns true if the character is within a commented string
1328    pub(crate) fn is_commented_string(self) -> bool {
1329        self == FullCodeCharKind::InStringCommented
1330            || self == FullCodeCharKind::StartStringCommented
1331    }
1332
1333    fn to_codecharkind(self) -> CodeCharKind {
1334        if self.is_comment() {
1335            CodeCharKind::Comment
1336        } else {
1337            CodeCharKind::Normal
1338        }
1339    }
1340}
1341
1342impl<T> CharClasses<T>
1343where
1344    T: Iterator,
1345    T::Item: RichChar,
1346{
1347    pub(crate) fn new(base: T) -> CharClasses<T> {
1348        CharClasses {
1349            base: multipeek(base),
1350            status: CharClassesStatus::Normal,
1351        }
1352    }
1353}
1354
1355/// Returns `true` if the `r` just consumed opens a raw string literal, i.e. the run of
1356/// `#`s that follows it ends in a `"`. Peeking a single `#` is not enough to tell a raw
1357/// string apart from a raw identifier such as `r#struct`.
1358fn is_raw_string_prefix<T>(iter: &mut MultiPeek<T>) -> bool
1359where
1360    T: Iterator,
1361    T::Item: RichChar,
1362{
1363    while let Some(c) = iter.peek() {
1364        match c.get_char() {
1365            '#' => continue,
1366            '"' => return true,
1367            _ => return false,
1368        }
1369    }
1370    false
1371}
1372
1373fn is_raw_string_suffix<T>(iter: &mut MultiPeek<T>, count: u32) -> bool
1374where
1375    T: Iterator,
1376    T::Item: RichChar,
1377{
1378    for _ in 0..count {
1379        match iter.peek() {
1380            Some(c) if c.get_char() == '#' => continue,
1381            _ => return false,
1382        }
1383    }
1384    true
1385}
1386
1387impl<T> Iterator for CharClasses<T>
1388where
1389    T: Iterator,
1390    T::Item: RichChar,
1391{
1392    type Item = (FullCodeCharKind, T::Item);
1393
1394    fn next(&mut self) -> Option<(FullCodeCharKind, T::Item)> {
1395        let item = self.base.next()?;
1396        let chr = item.get_char();
1397        let mut char_kind = FullCodeCharKind::Normal;
1398        self.status = match self.status {
1399            CharClassesStatus::LitRawString(sharps) => {
1400                char_kind = FullCodeCharKind::InString;
1401                match chr {
1402                    '"' => {
1403                        if sharps == 0 {
1404                            char_kind = FullCodeCharKind::Normal;
1405                            CharClassesStatus::Normal
1406                        } else if is_raw_string_suffix(&mut self.base, sharps) {
1407                            CharClassesStatus::RawStringSuffix(sharps)
1408                        } else {
1409                            CharClassesStatus::LitRawString(sharps)
1410                        }
1411                    }
1412                    _ => CharClassesStatus::LitRawString(sharps),
1413                }
1414            }
1415            CharClassesStatus::RawStringPrefix(sharps) => {
1416                char_kind = FullCodeCharKind::InString;
1417                match chr {
1418                    '#' => CharClassesStatus::RawStringPrefix(sharps + 1),
1419                    '"' => CharClassesStatus::LitRawString(sharps),
1420                    _ => CharClassesStatus::Normal, // Unreachable.
1421                }
1422            }
1423            CharClassesStatus::RawStringSuffix(sharps) => {
1424                match chr {
1425                    '#' => {
1426                        if sharps == 1 {
1427                            CharClassesStatus::Normal
1428                        } else {
1429                            char_kind = FullCodeCharKind::InString;
1430                            CharClassesStatus::RawStringSuffix(sharps - 1)
1431                        }
1432                    }
1433                    _ => CharClassesStatus::Normal, // Unreachable
1434                }
1435            }
1436            CharClassesStatus::LitString => {
1437                char_kind = FullCodeCharKind::InString;
1438                match chr {
1439                    '"' => CharClassesStatus::Normal,
1440                    '\\' => CharClassesStatus::LitStringEscape,
1441                    _ => CharClassesStatus::LitString,
1442                }
1443            }
1444            CharClassesStatus::LitStringEscape => {
1445                char_kind = FullCodeCharKind::InString;
1446                CharClassesStatus::LitString
1447            }
1448            CharClassesStatus::LitChar => match chr {
1449                '\\' => CharClassesStatus::LitCharEscape,
1450                '\'' => CharClassesStatus::Normal,
1451                _ => CharClassesStatus::LitChar,
1452            },
1453            CharClassesStatus::LitCharEscape => CharClassesStatus::LitChar,
1454            CharClassesStatus::Normal => match chr {
1455                'r' => match self.base.peek().map(RichChar::get_char) {
1456                    Some('"') => {
1457                        char_kind = FullCodeCharKind::InString;
1458                        CharClassesStatus::RawStringPrefix(0)
1459                    }
1460                    // `r#` opens a raw string only if the `#`s end in a `"`; otherwise
1461                    // this is a raw identifier like `r#struct` and stays normal code.
1462                    Some('#') if is_raw_string_prefix(&mut self.base) => {
1463                        char_kind = FullCodeCharKind::InString;
1464                        CharClassesStatus::RawStringPrefix(0)
1465                    }
1466                    _ => CharClassesStatus::Normal,
1467                },
1468                '"' => {
1469                    char_kind = FullCodeCharKind::InString;
1470                    CharClassesStatus::LitString
1471                }
1472                '\'' => {
1473                    // HACK: Work around mut borrow.
1474                    match self.base.peek() {
1475                        Some(next) if next.get_char() == '\\' => {
1476                            self.status = CharClassesStatus::LitChar;
1477                            return Some((char_kind, item));
1478                        }
1479                        _ => (),
1480                    }
1481
1482                    match self.base.peek() {
1483                        Some(next) if next.get_char() == '\'' => CharClassesStatus::LitChar,
1484                        _ => CharClassesStatus::Normal,
1485                    }
1486                }
1487                '/' => match self.base.peek() {
1488                    Some(next) if next.get_char() == '*' => {
1489                        self.status = CharClassesStatus::BlockCommentOpening(1);
1490                        return Some((FullCodeCharKind::StartComment, item));
1491                    }
1492                    Some(next) if next.get_char() == '/' => {
1493                        self.status = CharClassesStatus::LineComment;
1494                        return Some((FullCodeCharKind::StartComment, item));
1495                    }
1496                    _ => CharClassesStatus::Normal,
1497                },
1498                _ => CharClassesStatus::Normal,
1499            },
1500            CharClassesStatus::StringInBlockComment(deepness) => {
1501                char_kind = FullCodeCharKind::InStringCommented;
1502                if chr == '"' {
1503                    CharClassesStatus::BlockComment(deepness)
1504                } else if chr == '*' && self.base.peek().map(RichChar::get_char) == Some('/') {
1505                    char_kind = FullCodeCharKind::InComment;
1506                    CharClassesStatus::BlockCommentClosing(deepness - 1)
1507                } else {
1508                    CharClassesStatus::StringInBlockComment(deepness)
1509                }
1510            }
1511            CharClassesStatus::BlockComment(deepness) => {
1512                assert_ne!(deepness, 0);
1513                char_kind = FullCodeCharKind::InComment;
1514                match self.base.peek() {
1515                    Some(next) if next.get_char() == '/' && chr == '*' => {
1516                        CharClassesStatus::BlockCommentClosing(deepness - 1)
1517                    }
1518                    Some(next) if next.get_char() == '*' && chr == '/' => {
1519                        CharClassesStatus::BlockCommentOpening(deepness + 1)
1520                    }
1521                    _ if chr == '"' => CharClassesStatus::StringInBlockComment(deepness),
1522                    _ => self.status,
1523                }
1524            }
1525            CharClassesStatus::BlockCommentOpening(deepness) => {
1526                assert_eq!(chr, '*');
1527                self.status = CharClassesStatus::BlockComment(deepness);
1528                return Some((FullCodeCharKind::InComment, item));
1529            }
1530            CharClassesStatus::BlockCommentClosing(deepness) => {
1531                assert_eq!(chr, '/');
1532                if deepness == 0 {
1533                    self.status = CharClassesStatus::Normal;
1534                    return Some((FullCodeCharKind::EndComment, item));
1535                } else {
1536                    self.status = CharClassesStatus::BlockComment(deepness);
1537                    return Some((FullCodeCharKind::InComment, item));
1538                }
1539            }
1540            CharClassesStatus::LineComment => match chr {
1541                '\n' => {
1542                    self.status = CharClassesStatus::Normal;
1543                    return Some((FullCodeCharKind::EndComment, item));
1544                }
1545                _ => {
1546                    self.status = CharClassesStatus::LineComment;
1547                    return Some((FullCodeCharKind::InComment, item));
1548                }
1549            },
1550        };
1551        Some((char_kind, item))
1552    }
1553}
1554
1555/// An iterator over the lines of a string, paired with the char kind at the
1556/// end of the line.
1557pub(crate) struct LineClasses<'a> {
1558    base: iter::Peekable<CharClasses<std::str::Chars<'a>>>,
1559    kind: FullCodeCharKind,
1560}
1561
1562impl<'a> LineClasses<'a> {
1563    pub(crate) fn new(s: &'a str) -> Self {
1564        LineClasses {
1565            base: CharClasses::new(s.chars()).peekable(),
1566            kind: FullCodeCharKind::Normal,
1567        }
1568    }
1569}
1570
1571impl<'a> Iterator for LineClasses<'a> {
1572    type Item = (FullCodeCharKind, String);
1573
1574    fn next(&mut self) -> Option<Self::Item> {
1575        self.base.peek()?;
1576
1577        let mut line = String::new();
1578
1579        let start_kind = match self.base.peek() {
1580            Some((kind, _)) => *kind,
1581            None => unreachable!(),
1582        };
1583
1584        for (kind, c) in self.base.by_ref() {
1585            // needed to set the kind of the ending character on the last line
1586            self.kind = kind;
1587            if c == '\n' {
1588                self.kind = match (start_kind, kind) {
1589                    (FullCodeCharKind::Normal, FullCodeCharKind::InString) => {
1590                        FullCodeCharKind::StartString
1591                    }
1592                    (FullCodeCharKind::InString, FullCodeCharKind::Normal) => {
1593                        FullCodeCharKind::EndString
1594                    }
1595                    (FullCodeCharKind::InComment, FullCodeCharKind::InStringCommented) => {
1596                        FullCodeCharKind::StartStringCommented
1597                    }
1598                    (FullCodeCharKind::InStringCommented, FullCodeCharKind::InComment) => {
1599                        FullCodeCharKind::EndStringCommented
1600                    }
1601                    _ => kind,
1602                };
1603                break;
1604            }
1605            line.push(c);
1606        }
1607
1608        // Workaround for CRLF newline.
1609        if line.ends_with('\r') {
1610            line.pop();
1611        }
1612
1613        Some((self.kind, line))
1614    }
1615}
1616
1617/// Iterator over functional and commented parts of a string. Any part of a string is either
1618/// functional code, either *one* block comment, either *one* line comment. Whitespace between
1619/// comments is functional code. Line comments contain their ending newlines.
1620struct UngroupedCommentCodeSlices<'a> {
1621    slice: &'a str,
1622    iter: iter::Peekable<CharClasses<std::str::CharIndices<'a>>>,
1623}
1624
1625impl<'a> UngroupedCommentCodeSlices<'a> {
1626    fn new(code: &'a str) -> UngroupedCommentCodeSlices<'a> {
1627        UngroupedCommentCodeSlices {
1628            slice: code,
1629            iter: CharClasses::new(code.char_indices()).peekable(),
1630        }
1631    }
1632}
1633
1634impl<'a> Iterator for UngroupedCommentCodeSlices<'a> {
1635    type Item = (CodeCharKind, usize, &'a str);
1636
1637    fn next(&mut self) -> Option<Self::Item> {
1638        let (kind, (start_idx, _)) = self.iter.next()?;
1639        match kind {
1640            FullCodeCharKind::Normal | FullCodeCharKind::InString => {
1641                // Consume all the Normal code
1642                while let Some(&(char_kind, _)) = self.iter.peek() {
1643                    if char_kind.is_comment() {
1644                        break;
1645                    }
1646                    let _ = self.iter.next();
1647                }
1648            }
1649            FullCodeCharKind::StartComment => {
1650                // Consume the whole comment
1651                loop {
1652                    match self.iter.next() {
1653                        Some((kind, ..)) if kind.inside_comment() => continue,
1654                        _ => break,
1655                    }
1656                }
1657            }
1658            _ => panic!(),
1659        }
1660        let slice = match self.iter.peek() {
1661            Some(&(_, (end_idx, _))) => &self.slice[start_idx..end_idx],
1662            None => &self.slice[start_idx..],
1663        };
1664        Some((
1665            if kind.is_comment() {
1666                CodeCharKind::Comment
1667            } else {
1668                CodeCharKind::Normal
1669            },
1670            start_idx,
1671            slice,
1672        ))
1673    }
1674}
1675
1676/// Iterator over an alternating sequence of functional and commented parts of
1677/// a string. The first item is always a, possibly zero length, subslice of
1678/// functional text. Line style comments contain their ending newlines.
1679pub(crate) struct CommentCodeSlices<'a> {
1680    slice: &'a str,
1681    last_slice_kind: CodeCharKind,
1682    last_slice_end: usize,
1683}
1684
1685impl<'a> CommentCodeSlices<'a> {
1686    pub(crate) fn new(slice: &'a str) -> CommentCodeSlices<'a> {
1687        CommentCodeSlices {
1688            slice,
1689            last_slice_kind: CodeCharKind::Comment,
1690            last_slice_end: 0,
1691        }
1692    }
1693}
1694
1695impl<'a> Iterator for CommentCodeSlices<'a> {
1696    type Item = (CodeCharKind, usize, &'a str);
1697
1698    fn next(&mut self) -> Option<Self::Item> {
1699        if self.last_slice_end == self.slice.len() {
1700            return None;
1701        }
1702
1703        let mut sub_slice_end = self.last_slice_end;
1704        let mut first_whitespace = None;
1705        let subslice = &self.slice[self.last_slice_end..];
1706        let mut iter = CharClasses::new(subslice.char_indices());
1707
1708        for (kind, (i, c)) in &mut iter {
1709            let is_comment_connector = self.last_slice_kind == CodeCharKind::Normal
1710                && &subslice[..2] == "//"
1711                && [' ', '\t'].contains(&c);
1712
1713            if is_comment_connector && first_whitespace.is_none() {
1714                first_whitespace = Some(i);
1715            }
1716
1717            if kind.to_codecharkind() == self.last_slice_kind && !is_comment_connector {
1718                let last_index = match first_whitespace {
1719                    Some(j) => j,
1720                    None => i,
1721                };
1722                sub_slice_end = self.last_slice_end + last_index;
1723                break;
1724            }
1725
1726            if !is_comment_connector {
1727                first_whitespace = None;
1728            }
1729        }
1730
1731        if let (None, true) = (iter.next(), sub_slice_end == self.last_slice_end) {
1732            // This was the last subslice.
1733            sub_slice_end = match first_whitespace {
1734                Some(i) => self.last_slice_end + i,
1735                None => self.slice.len(),
1736            };
1737        }
1738
1739        let kind = match self.last_slice_kind {
1740            CodeCharKind::Comment => CodeCharKind::Normal,
1741            CodeCharKind::Normal => CodeCharKind::Comment,
1742        };
1743        let res = (
1744            kind,
1745            self.last_slice_end,
1746            &self.slice[self.last_slice_end..sub_slice_end],
1747        );
1748        self.last_slice_end = sub_slice_end;
1749        self.last_slice_kind = kind;
1750
1751        Some(res)
1752    }
1753}
1754
1755/// Checks is `new` didn't miss any comment from `span`, if it removed any, return previous text
1756pub(crate) fn recover_comment_removed(
1757    new: String,
1758    span: Span,
1759    context: &RewriteContext<'_>,
1760) -> String {
1761    let snippet = context.snippet(span);
1762    if snippet != new && changed_comment_content(snippet, &new) {
1763        // We missed some comments. Warn and keep the original text.
1764        if context.config.error_on_unformatted() {
1765            context.report.append(
1766                context.psess.span_to_filename(span),
1767                vec![FormattingError::from_span(
1768                    span,
1769                    context.psess,
1770                    ErrorKind::LostComment,
1771                )],
1772            );
1773        }
1774        snippet.to_owned()
1775    } else {
1776        new
1777    }
1778}
1779
1780pub(crate) fn filter_normal_code(code: &str) -> String {
1781    let mut buffer = String::with_capacity(code.len());
1782    LineClasses::new(code).for_each(|(kind, line)| match kind {
1783        FullCodeCharKind::Normal
1784        | FullCodeCharKind::StartString
1785        | FullCodeCharKind::InString
1786        | FullCodeCharKind::EndString => {
1787            buffer.push_str(&line);
1788            buffer.push('\n');
1789        }
1790        _ => (),
1791    });
1792    if !code.ends_with('\n') && buffer.ends_with('\n') {
1793        buffer.pop();
1794    }
1795    buffer
1796}
1797
1798/// Returns `true` if the two strings of code have the same payload of comments.
1799/// The payload of comments is everything in the string except:
1800/// - actual code (not comments),
1801/// - comment start/end marks,
1802/// - whitespace,
1803/// - '*' at the beginning of lines in block comments.
1804fn changed_comment_content(orig: &str, new: &str) -> bool {
1805    // Cannot write this as a fn since we cannot return types containing closures.
1806    let code_comment_content = |code| {
1807        let slices = UngroupedCommentCodeSlices::new(code);
1808        slices
1809            .filter(|(kind, _, _)| *kind == CodeCharKind::Comment)
1810            .flat_map(|(_, _, s)| CommentReducer::new(s))
1811    };
1812    let res = code_comment_content(orig).ne(code_comment_content(new));
1813    debug!(
1814        "comment::changed_comment_content: {}\norig: '{}'\nnew: '{}'\nraw_old: {}\nraw_new: {}",
1815        res,
1816        orig,
1817        new,
1818        code_comment_content(orig).collect::<String>(),
1819        code_comment_content(new).collect::<String>()
1820    );
1821    res
1822}
1823
1824/// Iterator over the 'payload' characters of a comment.
1825/// It skips whitespace, comment start/end marks, and '*' at the beginning of lines.
1826/// The comment must be one comment, ie not more than one start mark (no multiple line comments,
1827/// for example).
1828struct CommentReducer<'a> {
1829    is_block: bool,
1830    at_start_line: bool,
1831    iter: std::str::Chars<'a>,
1832}
1833
1834impl<'a> CommentReducer<'a> {
1835    fn new(comment: &'a str) -> CommentReducer<'a> {
1836        let is_block = comment.starts_with("/*");
1837        let comment = remove_comment_header(comment);
1838        CommentReducer {
1839            is_block,
1840            // There are no supplementary '*' on the first line.
1841            at_start_line: false,
1842            iter: comment.chars(),
1843        }
1844    }
1845}
1846
1847impl<'a> Iterator for CommentReducer<'a> {
1848    type Item = char;
1849
1850    fn next(&mut self) -> Option<Self::Item> {
1851        loop {
1852            let mut c = self.iter.next()?;
1853            if self.is_block && self.at_start_line {
1854                while c.is_whitespace() {
1855                    c = self.iter.next()?;
1856                }
1857                // Ignore leading '*'.
1858                if c == '*' {
1859                    c = self.iter.next()?;
1860                }
1861            } else if c == '\n' {
1862                self.at_start_line = true;
1863            }
1864            if !c.is_whitespace() {
1865                return Some(c);
1866            }
1867        }
1868    }
1869}
1870
1871fn remove_comment_header(comment: &str) -> &str {
1872    if comment.starts_with("///") || comment.starts_with("//!") {
1873        &comment[3..]
1874    } else if let Some(stripped) = comment.strip_prefix("//") {
1875        stripped
1876    } else if (comment.starts_with("/**") && !comment.starts_with("/**/"))
1877        || comment.starts_with("/*!")
1878    {
1879        &comment[3..comment.len() - 2]
1880    } else {
1881        assert!(
1882            comment.starts_with("/*"),
1883            "string '{comment}' is not a comment"
1884        );
1885        &comment[2..comment.len() - 2]
1886    }
1887}
1888
1889#[cfg(test)]
1890mod test {
1891    use super::*;
1892
1893    #[test]
1894    fn char_classes() {
1895        let mut iter = CharClasses::new("//\n\n".chars());
1896
1897        assert_eq!((FullCodeCharKind::StartComment, '/'), iter.next().unwrap());
1898        assert_eq!((FullCodeCharKind::InComment, '/'), iter.next().unwrap());
1899        assert_eq!((FullCodeCharKind::EndComment, '\n'), iter.next().unwrap());
1900        assert_eq!((FullCodeCharKind::Normal, '\n'), iter.next().unwrap());
1901        assert_eq!(None, iter.next());
1902    }
1903
1904    #[test]
1905    fn comment_code_slices() {
1906        let input = "code(); /* test */ 1 + 1";
1907        let mut iter = CommentCodeSlices::new(input);
1908
1909        assert_eq!((CodeCharKind::Normal, 0, "code(); "), iter.next().unwrap());
1910        assert_eq!(
1911            (CodeCharKind::Comment, 8, "/* test */"),
1912            iter.next().unwrap()
1913        );
1914        assert_eq!((CodeCharKind::Normal, 18, " 1 + 1"), iter.next().unwrap());
1915        assert_eq!(None, iter.next());
1916    }
1917
1918    #[test]
1919    fn comment_code_slices_two() {
1920        let input = "// comment\n    test();";
1921        let mut iter = CommentCodeSlices::new(input);
1922
1923        assert_eq!((CodeCharKind::Normal, 0, ""), iter.next().unwrap());
1924        assert_eq!(
1925            (CodeCharKind::Comment, 0, "// comment\n"),
1926            iter.next().unwrap()
1927        );
1928        assert_eq!(
1929            (CodeCharKind::Normal, 11, "    test();"),
1930            iter.next().unwrap()
1931        );
1932        assert_eq!(None, iter.next());
1933    }
1934
1935    #[test]
1936    fn comment_code_slices_three() {
1937        let input = "1 // comment\n    // comment2\n\n";
1938        let mut iter = CommentCodeSlices::new(input);
1939
1940        assert_eq!((CodeCharKind::Normal, 0, "1 "), iter.next().unwrap());
1941        assert_eq!(
1942            (CodeCharKind::Comment, 2, "// comment\n    // comment2\n"),
1943            iter.next().unwrap()
1944        );
1945        assert_eq!((CodeCharKind::Normal, 29, "\n"), iter.next().unwrap());
1946        assert_eq!(None, iter.next());
1947    }
1948
1949    #[test]
1950    #[rustfmt::skip]
1951    fn format_doc_comments() {
1952        let mut wrap_normalize_config: crate::config::Config = Default::default();
1953        wrap_normalize_config.set().wrap_comments(true);
1954        wrap_normalize_config.set().normalize_comments(true);
1955
1956        let mut wrap_config: crate::config::Config = Default::default();
1957        wrap_config.set().wrap_comments(true);
1958
1959        let comment = rewrite_comment(" //test",
1960                                      true,
1961                                      Shape::legacy(100, Indent::new(0, 100)),
1962                                      &wrap_normalize_config).unwrap();
1963        assert_eq!("/* test */", comment);
1964
1965        let comment = rewrite_comment("// comment on a",
1966                                      false,
1967                                      Shape::legacy(10, Indent::empty()),
1968                                      &wrap_normalize_config).unwrap();
1969        assert_eq!("// comment\n// on a", comment);
1970
1971        let comment = rewrite_comment("//  A multi line comment\n             // between args.",
1972                                      false,
1973                                      Shape::legacy(60, Indent::new(0, 12)),
1974                                      &wrap_normalize_config).unwrap();
1975        assert_eq!("//  A multi line comment\n            // between args.", comment);
1976
1977        let input = "// comment";
1978        let expected =
1979            "/* comment */";
1980        let comment = rewrite_comment(input,
1981                                      true,
1982                                      Shape::legacy(9, Indent::new(0, 69)),
1983                                      &wrap_normalize_config).unwrap();
1984        assert_eq!(expected, comment);
1985
1986        let comment = rewrite_comment("/*   trimmed    */",
1987                                      true,
1988                                      Shape::legacy(100, Indent::new(0, 100)),
1989                                      &wrap_normalize_config).unwrap();
1990        assert_eq!("/* trimmed */", comment);
1991
1992        // Check that different comment style are properly recognised.
1993        let comment = rewrite_comment(r#"/// test1
1994                                         /// test2
1995                                         /*
1996                                          * test3
1997                                          */"#,
1998                                      false,
1999                                      Shape::legacy(100, Indent::new(0, 0)),
2000                                      &wrap_normalize_config).unwrap();
2001        assert_eq!("/// test1\n/// test2\n// test3", comment);
2002
2003        // Check that the blank line marks the end of a commented paragraph.
2004        let comment = rewrite_comment(r#"// test1
2005
2006                                         // test2"#,
2007                                      false,
2008                                      Shape::legacy(100, Indent::new(0, 0)),
2009                                      &wrap_normalize_config).unwrap();
2010        assert_eq!("// test1\n\n// test2", comment);
2011
2012        // Check that the blank line marks the end of a custom-commented paragraph.
2013        let comment = rewrite_comment(r#"//@ test1
2014
2015                                         //@ test2"#,
2016                                      false,
2017                                      Shape::legacy(100, Indent::new(0, 0)),
2018                                      &wrap_normalize_config).unwrap();
2019        assert_eq!("//@ test1\n\n//@ test2", comment);
2020
2021        // Check that bare lines are just indented but otherwise left unchanged.
2022        let comment = rewrite_comment(r#"// test1
2023                                         /*
2024                                           a bare line!
2025
2026                                                another bare line!
2027                                          */"#,
2028                                      false,
2029                                      Shape::legacy(100, Indent::new(0, 0)),
2030                                      &wrap_config).unwrap();
2031        assert_eq!("// test1\n/*\n a bare line!\n\n      another bare line!\n*/", comment);
2032    }
2033
2034    // This is probably intended to be a non-test fn, but it is not used.
2035    // We should keep this around unless it helps us test stuff to remove it.
2036    fn uncommented(text: &str) -> String {
2037        CharClasses::new(text.chars())
2038            .filter_map(|(s, c)| match s {
2039                FullCodeCharKind::Normal | FullCodeCharKind::InString => Some(c),
2040                _ => None,
2041            })
2042            .collect()
2043    }
2044
2045    #[test]
2046    fn test_uncommented() {
2047        assert_eq!(&uncommented("abc/*...*/"), "abc");
2048        assert_eq!(
2049            &uncommented("// .... /* \n../* /* *** / */ */a/* // */c\n"),
2050            "..ac\n"
2051        );
2052        assert_eq!(&uncommented("abc \" /* */\" qsdf"), "abc \" /* */\" qsdf");
2053    }
2054
2055    #[test]
2056    fn test_contains_comment() {
2057        assert_eq!(contains_comment("abc"), false);
2058        assert_eq!(contains_comment("abc // qsdf"), true);
2059        assert_eq!(contains_comment("abc /* kqsdf"), true);
2060        assert_eq!(contains_comment("abc \" /* */\" qsdf"), false);
2061    }
2062
2063    #[test]
2064    fn test_find_uncommented() {
2065        fn check(haystack: &str, needle: &str, expected: Option<usize>) {
2066            assert_eq!(expected, haystack.find_uncommented(needle));
2067        }
2068
2069        check("/*/ */test", "test", Some(6));
2070        check("//test\ntest", "test", Some(7));
2071        check("/* comment only */", "whatever", None);
2072        check(
2073            "/* comment */ some text /* more commentary */ result",
2074            "result",
2075            Some(46),
2076        );
2077        check("sup // sup", "p", Some(2));
2078        check("sup", "x", None);
2079        check(r#"π? /**/ π is nice!"#, r#"π is nice"#, Some(9));
2080        check("/*sup yo? \n sup*/ sup", "p", Some(20));
2081        check("hel/*lohello*/lo", "hello", None);
2082        check("acb", "ab", None);
2083        check(",/*A*/ ", ",", Some(0));
2084        check("abc", "abc", Some(0));
2085        check("/* abc */", "abc", None);
2086        check("/**/abc/* */", "abc", Some(4));
2087        check("\"/* abc */\"", "abc", Some(4));
2088        check("\"/* abc", "abc", Some(4));
2089    }
2090
2091    #[test]
2092    fn test_filter_normal_code() {
2093        let s = r#"
2094fn main() {
2095    println!("hello, world");
2096}
2097"#;
2098        assert_eq!(s, filter_normal_code(s));
2099        let s_with_comment = r#"
2100fn main() {
2101    // hello, world
2102    println!("hello, world");
2103}
2104"#;
2105        assert_eq!(s, filter_normal_code(s_with_comment));
2106    }
2107
2108    #[test]
2109    fn test_itemized_block_first_line_handling() {
2110        fn run_test(
2111            test_input: &str,
2112            expected_line: &str,
2113            expected_indent: usize,
2114            expected_opener: &str,
2115            expected_line_start: &str,
2116        ) {
2117            let block = ItemizedBlock::new(test_input).unwrap();
2118            assert_eq!(1, block.lines.len(), "test_input: {test_input:?}");
2119            assert_eq!(expected_line, &block.lines[0], "test_input: {test_input:?}");
2120            assert_eq!(expected_indent, block.indent, "test_input: {test_input:?}");
2121            assert_eq!(expected_opener, &block.opener, "test_input: {test_input:?}");
2122            assert_eq!(
2123                expected_line_start, &block.line_start,
2124                "test_input: {test_input:?}"
2125            );
2126        }
2127
2128        run_test("- foo", "foo", 2, "- ", "  ");
2129        run_test("* foo", "foo", 2, "* ", "  ");
2130        run_test("> foo", "foo", 2, "> ", "> ");
2131
2132        run_test("1. foo", "foo", 3, "1. ", "   ");
2133        run_test("12. foo", "foo", 4, "12. ", "    ");
2134        run_test("1) foo", "foo", 3, "1) ", "   ");
2135        run_test("12) foo", "foo", 4, "12) ", "    ");
2136
2137        run_test("    - foo", "foo", 6, "    - ", "      ");
2138
2139        // https://spec.commonmark.org/0.30 says: "A start number may begin with 0s":
2140        run_test("0. foo", "foo", 3, "0. ", "   ");
2141        run_test("01. foo", "foo", 4, "01. ", "    ");
2142    }
2143
2144    #[test]
2145    fn test_itemized_block_nonobvious_markers_are_rejected() {
2146        let test_inputs = vec![
2147            // Non-numeric item markers (e.g. `a.` or `iv.`) are not allowed by
2148            // https://spec.commonmark.org/0.30/#ordered-list-marker. We also note that allowing
2149            // them would risk misidentifying regular words as item markers. See also the
2150            // discussion in https://talk.commonmark.org/t/blank-lines-before-lists-revisited/1990
2151            "word.  rest of the paragraph.",
2152            "a.  maybe this is a list item?  maybe not?",
2153            "iv.  maybe this is a list item?  maybe not?",
2154            // Numbers with 3 or more digits are not recognized as item markers, to avoid
2155            // formatting the following example as a list:
2156            //
2157            // ```
2158            // The Captain died in
2159            // 1868. He was buried in...
2160            // ```
2161            "123.  only 2-digit numbers are recognized as item markers.",
2162            // Parens:
2163            "123)  giving some coverage to parens as well.",
2164            "a)  giving some coverage to parens as well.",
2165            // https://spec.commonmark.org/0.30 says that "at least one space or tab is needed
2166            // between the list marker and any following content":
2167            "1.Not a list item.",
2168            "1.2.3. Not a list item.",
2169            "1)Not a list item.",
2170            "-Not a list item.",
2171            "+Not a list item.",
2172            "+1 not a list item.",
2173            // https://spec.commonmark.org/0.30 says: "A start number may not be negative":
2174            "-1. Not a list item.",
2175            "-1 Not a list item.",
2176            // Marker without prefix are not recognized as item markers:
2177            ".   Not a list item.",
2178            ")   Not a list item.",
2179        ];
2180        for line in test_inputs.iter() {
2181            let maybe_block = ItemizedBlock::new(line);
2182            assert!(
2183                maybe_block.is_none(),
2184                "The following line shouldn't be classified as a list item: {line}"
2185            );
2186        }
2187    }
2188}