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, Debug, 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.trim_start(), 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        // 5) No inline links were found (the pattern is `](...)`)
847        // 6) The comment is not a table item
848        // If this changes, the documentation in ../Configurations.md#wrap_comments
849        // should be changed accordingly.
850        let should_wrap_comment = self.fmt.config.wrap_comments()
851            && !is_markdown_header_doc_comment
852            && unicode_str_width(line) > self.fmt.shape.width
853            && !has_url(line)
854            && !is_inline_link(line)
855            && !is_table_item(line);
856
857        if should_wrap_comment {
858            match rewrite_string(line, &self.fmt, self.max_width) {
859                Some(ref s) => {
860                    self.is_prev_line_multi_line = s.contains('\n');
861                    self.result.push_str(s);
862                }
863                None if self.is_prev_line_multi_line => {
864                    // We failed to put the current `line` next to the previous `line`.
865                    // Remove the trailing space, then start rewrite on the next line.
866                    self.result.pop();
867                    self.result.push_str(&self.comment_line_separator);
868                    self.fmt.shape = Shape::legacy(self.max_width, self.fmt_indent);
869                    match rewrite_string(line, &self.fmt, self.max_width) {
870                        Some(ref s) => {
871                            self.is_prev_line_multi_line = s.contains('\n');
872                            self.result.push_str(s);
873                        }
874                        None => {
875                            self.is_prev_line_multi_line = false;
876                            self.result.push_str(line);
877                        }
878                    }
879                }
880                None => {
881                    self.is_prev_line_multi_line = false;
882                    self.result.push_str(line);
883                }
884            }
885
886            self.fmt.shape = if self.is_prev_line_multi_line {
887                // 1 = " "
888                let offset = 1 + last_line_width(&self.result, self.fmt.config.tab_spaces())
889                    - self.comment_prefix.len()
890                    - self.fmt_indent.width();
891                Shape {
892                    width: self.max_width.saturating_sub(offset),
893                    indent: self.fmt_indent,
894                    offset: self.fmt.shape.offset + offset,
895                }
896            } else {
897                Shape::legacy(self.max_width, self.fmt_indent)
898            };
899        } else {
900            if line.is_empty() && self.result.ends_with(' ') && !is_last {
901                // Remove space if this is an empty comment or a doc comment.
902                self.result.pop();
903            }
904            if self.code_block_attr.is_some() && self.is_prev_line_multi_line {
905                self.result.push_str(&self.comment_line_separator);
906            }
907            self.result.push_str(line);
908            self.fmt.shape = Shape::legacy(self.max_width, self.fmt_indent);
909            self.is_prev_line_multi_line = false;
910        }
911
912        false
913    }
914}
915
916fn rewrite_comment_inner(
917    orig: &str,
918    block_style: bool,
919    style: CommentStyle<'_>,
920    shape: Shape,
921    config: &Config,
922    is_doc_comment: bool,
923) -> RewriteResult {
924    let mut rewriter = CommentRewrite::new(orig, block_style, shape, config);
925
926    let line_breaks = count_newlines(orig.trim_end());
927    let lines = orig
928        .lines()
929        .enumerate()
930        .map(|(i, mut line)| {
931            line = trim_end_unless_two_whitespaces(line.trim_start(), is_doc_comment);
932            // Drop old closer.
933            if i == line_breaks && line.ends_with("*/") && !line.starts_with("//") {
934                line = line[..(line.len() - 2)].trim_end();
935            }
936
937            line
938        })
939        .map(|s| left_trim_comment_line(s, &style))
940        .map(|(line, has_leading_whitespace)| {
941            if orig.starts_with("/*") && line_breaks == 0 {
942                (
943                    line.trim_start(),
944                    has_leading_whitespace || config.normalize_comments(),
945                )
946            } else {
947                (line, has_leading_whitespace || config.normalize_comments())
948            }
949        });
950
951    for (i, (line, has_leading_whitespace)) in lines.enumerate() {
952        if rewriter.handle_line(orig, i, line, has_leading_whitespace, is_doc_comment) {
953            break;
954        }
955    }
956
957    Ok(rewriter.finish())
958}
959
960const RUSTFMT_CUSTOM_COMMENT_PREFIX: &str = "//#### ";
961
962fn hide_sharp_behind_comment(s: &str) -> Cow<'_, str> {
963    let s_trimmed = s.trim();
964    if s_trimmed.starts_with("# ") || s_trimmed == "#" {
965        Cow::from(format!("{RUSTFMT_CUSTOM_COMMENT_PREFIX}{s}"))
966    } else {
967        Cow::from(s)
968    }
969}
970
971fn trim_custom_comment_prefix(s: &str) -> String {
972    s.lines()
973        .map(|line| {
974            let left_trimmed = line.trim_start();
975            if left_trimmed.starts_with(RUSTFMT_CUSTOM_COMMENT_PREFIX) {
976                left_trimmed.trim_start_matches(RUSTFMT_CUSTOM_COMMENT_PREFIX)
977            } else {
978                line
979            }
980        })
981        .collect::<Vec<_>>()
982        .join("\n")
983}
984
985/// Returns `true` if the given string includes link-like fragments.
986/// The pattern is `](...)`
987fn is_inline_link(s: &str) -> bool {
988    if let Some(start) = s.find("](") {
989        let after = &s[start + 2..];
990        return after.contains(')');
991    }
992    false
993}
994
995/// Returns `true` if the given string MAY include URLs or alike.
996fn has_url(s: &str) -> bool {
997    // A regex matching reference doc links.
998    //
999    // ```markdown
1000    // /// An [example].
1001    // ///
1002    // /// [example]: this::is::a::link
1003    // ```
1004    let reference_link_url = static_regex!(r"^\[.+\]\s?:");
1005
1006    // This function may return false positive, but should get its job done in most cases.
1007    s.contains("https://")
1008        || s.contains("http://")
1009        || s.contains("ftp://")
1010        || s.contains("file://")
1011        || reference_link_url.is_match(s)
1012}
1013
1014/// Returns true if the given string may be part of a Markdown table.
1015fn is_table_item(mut s: &str) -> bool {
1016    // This function may return false positive, but should get its job done in most cases (i.e.
1017    // markdown tables with two column delimiters).
1018    s = s.trim_start();
1019    return s.starts_with('|')
1020        && match s.rfind('|') {
1021            Some(0) | None => false,
1022            _ => true,
1023        };
1024}
1025
1026/// Given the span, rewrite the missing comment inside it if available.
1027/// Note that the given span must only include comments (or leading/trailing whitespaces).
1028pub(crate) fn rewrite_missing_comment(
1029    span: Span,
1030    shape: Shape,
1031    context: &RewriteContext<'_>,
1032) -> RewriteResult {
1033    let missing_snippet = context.snippet(span);
1034    let trimmed_snippet = missing_snippet.trim();
1035    // check the span starts with a comment
1036    let pos = trimmed_snippet.find('/');
1037    if !trimmed_snippet.is_empty() && pos.is_some() {
1038        rewrite_comment(trimmed_snippet, false, shape, context.config)
1039    } else {
1040        Ok(String::new())
1041    }
1042}
1043
1044/// Recover the missing comments in the specified span, if available.
1045/// The layout of the comments will be preserved as long as it does not break the code
1046/// and its total width does not exceed the max width.
1047pub(crate) fn recover_missing_comment_in_span(
1048    span: Span,
1049    shape: Shape,
1050    context: &RewriteContext<'_>,
1051    used_width: usize,
1052) -> RewriteResult {
1053    let missing_comment = rewrite_missing_comment(span, shape, context)?;
1054    if missing_comment.is_empty() {
1055        Ok(String::new())
1056    } else {
1057        let missing_snippet = context.snippet(span);
1058        let pos = missing_snippet.find('/').unknown_error()?;
1059        // 1 = ` `
1060        let total_width = missing_comment.len() + used_width + 1;
1061        let force_new_line_before_comment =
1062            missing_snippet[..pos].contains('\n') || total_width > context.config.max_width();
1063        let sep = if force_new_line_before_comment {
1064            shape.indent.to_string_with_newline(context.config)
1065        } else {
1066            Cow::from(" ")
1067        };
1068        Ok(format!("{sep}{missing_comment}"))
1069    }
1070}
1071
1072/// Trim trailing whitespaces unless they consist of two or more whitespaces.
1073fn trim_end_unless_two_whitespaces(s: &str, is_doc_comment: bool) -> &str {
1074    if is_doc_comment && s.ends_with("  ") {
1075        s
1076    } else {
1077        s.trim_end()
1078    }
1079}
1080
1081/// Trims whitespace and aligns to indent, but otherwise does not change comments.
1082fn light_rewrite_comment(
1083    orig: &str,
1084    offset: Indent,
1085    config: &Config,
1086    is_doc_comment: bool,
1087) -> String {
1088    orig.lines()
1089        .map(|l| {
1090            // This is basically just l.trim(), but in the case that a line starts
1091            // with `*` we want to leave one space before it, so it aligns with the
1092            // `*` in `/*`.
1093            let first_non_whitespace = l.find(|c| !char::is_whitespace(c));
1094            let left_trimmed = if let Some(fnw) = first_non_whitespace {
1095                if l.as_bytes()[fnw] == b'*' {
1096                    Cow::Owned(format!(" {}", &l[fnw..]))
1097                } else {
1098                    Cow::Borrowed(&l[fnw..])
1099                }
1100            } else {
1101                Cow::Borrowed("")
1102            };
1103
1104            // Preserve markdown's double-space line break syntax in doc comment.
1105            match left_trimmed {
1106                Cow::Borrowed(left_trimmed) => Cow::Borrowed(trim_end_unless_two_whitespaces(
1107                    left_trimmed,
1108                    is_doc_comment,
1109                )),
1110                Cow::Owned(left_trimmed) => {
1111                    let trimmed = trim_end_unless_two_whitespaces(&left_trimmed, is_doc_comment);
1112                    Cow::Owned(trimmed.to_string())
1113                }
1114            }
1115        })
1116        .join(&format!("\n{}", offset.to_string(config)))
1117}
1118
1119/// Trims comment characters and possibly a single space from the left of a string.
1120/// Does not trim all whitespace. If a single space is trimmed from the left of the string,
1121/// this function returns true.
1122fn left_trim_comment_line<'a>(line: &'a str, style: &CommentStyle<'_>) -> (&'a str, bool) {
1123    if line.starts_with("//! ")
1124        || line.starts_with("/// ")
1125        || line.starts_with("/*! ")
1126        || line.starts_with("/** ")
1127    {
1128        (&line[4..], true)
1129    } else if let CommentStyle::Custom(opener) = *style {
1130        if let Some(stripped) = line.strip_prefix(opener) {
1131            (stripped, true)
1132        } else {
1133            (&line[opener.trim_end().len()..], false)
1134        }
1135    } else if line.starts_with("/* ")
1136        || line.starts_with("// ")
1137        || line.starts_with("//!")
1138        || line.starts_with("///")
1139        || line.starts_with("** ")
1140        || line.starts_with("/*!")
1141        || (line.starts_with("/**") && !line.starts_with("/**/"))
1142    {
1143        (&line[3..], line.chars().nth(2).unwrap() == ' ')
1144    } else if line.starts_with("/*")
1145        || line.starts_with("* ")
1146        || line.starts_with("//")
1147        || line.starts_with("**")
1148    {
1149        (&line[2..], line.chars().nth(1).unwrap() == ' ')
1150    } else if let Some(stripped) = line.strip_prefix('*') {
1151        (stripped, false)
1152    } else {
1153        (line, line.starts_with(' '))
1154    }
1155}
1156
1157pub(crate) trait FindUncommented {
1158    fn find_uncommented(&self, pat: &str) -> Option<usize>;
1159    fn find_last_uncommented(&self, pat: &str) -> Option<usize>;
1160}
1161
1162impl FindUncommented for str {
1163    fn find_uncommented(&self, pat: &str) -> Option<usize> {
1164        let mut needle_iter = pat.chars();
1165        for (kind, (i, b)) in CharClasses::new(self.char_indices()) {
1166            match needle_iter.next() {
1167                None => {
1168                    return Some(i - pat.len());
1169                }
1170                Some(c) => match kind {
1171                    FullCodeCharKind::Normal | FullCodeCharKind::InString if b == c => {}
1172                    _ => {
1173                        needle_iter = pat.chars();
1174                    }
1175                },
1176            }
1177        }
1178
1179        // Handle case where the pattern is a suffix of the search string
1180        match needle_iter.next() {
1181            Some(_) => None,
1182            None => Some(self.len() - pat.len()),
1183        }
1184    }
1185
1186    fn find_last_uncommented(&self, pat: &str) -> Option<usize> {
1187        if let Some(left) = self.find_uncommented(pat) {
1188            let mut result = left;
1189            // add 1 to use find_last_uncommented for &str after pat
1190            while let Some(next) = self[(result + 1)..].find_last_uncommented(pat) {
1191                result += next + 1;
1192            }
1193            Some(result)
1194        } else {
1195            None
1196        }
1197    }
1198}
1199
1200// Returns the first byte position after the first comment. The given string
1201// is expected to be prefixed by a comment, including delimiters.
1202// Good: `/* /* inner */ outer */ code();`
1203// Bad:  `code(); // hello\n world!`
1204pub(crate) fn find_comment_end(s: &str) -> Option<usize> {
1205    let mut iter = CharClasses::new(s.char_indices());
1206    for (kind, (i, _c)) in &mut iter {
1207        if kind == FullCodeCharKind::Normal || kind == FullCodeCharKind::InString {
1208            return Some(i);
1209        }
1210    }
1211
1212    // Handle case where the comment ends at the end of `s`.
1213    if iter.status == CharClassesStatus::Normal {
1214        Some(s.len())
1215    } else {
1216        None
1217    }
1218}
1219
1220/// Returns `true` if text contains any comment.
1221pub(crate) fn contains_comment(text: &str) -> bool {
1222    CharClasses::new(text.chars()).any(|(kind, _)| kind.is_comment())
1223}
1224
1225pub(crate) struct CharClasses<T>
1226where
1227    T: Iterator,
1228    T::Item: RichChar,
1229{
1230    base: MultiPeek<T>,
1231    status: CharClassesStatus,
1232}
1233
1234pub(crate) trait RichChar {
1235    fn get_char(&self) -> char;
1236}
1237
1238impl RichChar for char {
1239    fn get_char(&self) -> char {
1240        *self
1241    }
1242}
1243
1244impl RichChar for (usize, char) {
1245    fn get_char(&self) -> char {
1246        self.1
1247    }
1248}
1249
1250#[derive(PartialEq, Eq, Debug, Clone, Copy)]
1251enum CharClassesStatus {
1252    Normal,
1253    /// Character is within a string
1254    LitString,
1255    LitStringEscape,
1256    /// Character is within a raw string
1257    LitRawString(u32),
1258    RawStringPrefix(u32),
1259    RawStringSuffix(u32),
1260    LitChar,
1261    LitCharEscape,
1262    /// Character inside a block comment, with the integer indicating the nesting deepness of the
1263    /// comment
1264    BlockComment(u32),
1265    /// Character inside a block-commented string, with the integer indicating the nesting deepness
1266    /// of the comment
1267    StringInBlockComment(u32),
1268    /// Status when the '/' has been consumed, but not yet the '*', deepness is
1269    /// the new deepness (after the comment opening).
1270    BlockCommentOpening(u32),
1271    /// Status when the '*' has been consumed, but not yet the '/', deepness is
1272    /// the new deepness (after the comment closing).
1273    BlockCommentClosing(u32),
1274    /// Character is within a line comment
1275    LineComment,
1276}
1277
1278/// Distinguish between functional part of code and comments
1279#[derive(PartialEq, Eq, Debug, Clone, Copy)]
1280pub(crate) enum CodeCharKind {
1281    Normal,
1282    Comment,
1283}
1284
1285/// Distinguish between functional part of code and comments,
1286/// describing opening and closing of comments for ease when chunking
1287/// code from tagged characters
1288#[derive(PartialEq, Eq, Debug, Clone, Copy)]
1289pub(crate) enum FullCodeCharKind {
1290    Normal,
1291    /// The first character of a comment, there is only one for a comment (always '/')
1292    StartComment,
1293    /// Any character inside a comment including the second character of comment
1294    /// marks ("//", "/*")
1295    InComment,
1296    /// Last character of a comment, '\n' for a line comment, '/' for a block comment.
1297    EndComment,
1298    /// Start of a multiline string inside a comment
1299    StartStringCommented,
1300    /// End of a multiline string inside a comment
1301    EndStringCommented,
1302    /// Inside a commented string
1303    InStringCommented,
1304    /// Start of a multiline string
1305    StartString,
1306    /// End of a multiline string
1307    EndString,
1308    /// Inside a string.
1309    InString,
1310}
1311
1312impl FullCodeCharKind {
1313    pub(crate) fn is_comment(self) -> bool {
1314        match self {
1315            FullCodeCharKind::StartComment
1316            | FullCodeCharKind::InComment
1317            | FullCodeCharKind::EndComment
1318            | FullCodeCharKind::StartStringCommented
1319            | FullCodeCharKind::InStringCommented
1320            | FullCodeCharKind::EndStringCommented => true,
1321            _ => false,
1322        }
1323    }
1324
1325    /// Returns true if the character is inside a comment
1326    pub(crate) fn inside_comment(self) -> bool {
1327        match self {
1328            FullCodeCharKind::InComment
1329            | FullCodeCharKind::StartStringCommented
1330            | FullCodeCharKind::InStringCommented
1331            | FullCodeCharKind::EndStringCommented => true,
1332            _ => false,
1333        }
1334    }
1335
1336    pub(crate) fn is_string(self) -> bool {
1337        self == FullCodeCharKind::InString || self == FullCodeCharKind::StartString
1338    }
1339
1340    /// Returns true if the character is within a commented string
1341    pub(crate) fn is_commented_string(self) -> bool {
1342        self == FullCodeCharKind::InStringCommented
1343            || self == FullCodeCharKind::StartStringCommented
1344    }
1345
1346    fn to_codecharkind(self) -> CodeCharKind {
1347        if self.is_comment() {
1348            CodeCharKind::Comment
1349        } else {
1350            CodeCharKind::Normal
1351        }
1352    }
1353}
1354
1355impl<T> CharClasses<T>
1356where
1357    T: Iterator,
1358    T::Item: RichChar,
1359{
1360    pub(crate) fn new(base: T) -> CharClasses<T> {
1361        CharClasses {
1362            base: multipeek(base),
1363            status: CharClassesStatus::Normal,
1364        }
1365    }
1366}
1367
1368/// Returns `true` if the `r` just consumed opens a raw string literal, i.e. the run of
1369/// `#`s that follows it ends in a `"`. Peeking a single `#` is not enough to tell a raw
1370/// string apart from a raw identifier such as `r#struct`.
1371fn is_raw_string_prefix<T>(iter: &mut MultiPeek<T>) -> bool
1372where
1373    T: Iterator,
1374    T::Item: RichChar,
1375{
1376    while let Some(c) = iter.peek() {
1377        match c.get_char() {
1378            '#' => continue,
1379            '"' => return true,
1380            _ => return false,
1381        }
1382    }
1383    false
1384}
1385
1386fn is_raw_string_suffix<T>(iter: &mut MultiPeek<T>, count: u32) -> bool
1387where
1388    T: Iterator,
1389    T::Item: RichChar,
1390{
1391    for _ in 0..count {
1392        match iter.peek() {
1393            Some(c) if c.get_char() == '#' => continue,
1394            _ => return false,
1395        }
1396    }
1397    true
1398}
1399
1400impl<T> Iterator for CharClasses<T>
1401where
1402    T: Iterator,
1403    T::Item: RichChar,
1404{
1405    type Item = (FullCodeCharKind, T::Item);
1406
1407    fn next(&mut self) -> Option<(FullCodeCharKind, T::Item)> {
1408        let item = self.base.next()?;
1409        let chr = item.get_char();
1410        let mut char_kind = FullCodeCharKind::Normal;
1411        self.status = match self.status {
1412            CharClassesStatus::LitRawString(sharps) => {
1413                char_kind = FullCodeCharKind::InString;
1414                match chr {
1415                    '"' => {
1416                        if sharps == 0 {
1417                            CharClassesStatus::Normal
1418                        } else if is_raw_string_suffix(&mut self.base, sharps) {
1419                            CharClassesStatus::RawStringSuffix(sharps)
1420                        } else {
1421                            CharClassesStatus::LitRawString(sharps)
1422                        }
1423                    }
1424                    _ => CharClassesStatus::LitRawString(sharps),
1425                }
1426            }
1427            CharClassesStatus::RawStringPrefix(sharps) => {
1428                char_kind = FullCodeCharKind::InString;
1429                match chr {
1430                    '#' => CharClassesStatus::RawStringPrefix(sharps + 1),
1431                    '"' => CharClassesStatus::LitRawString(sharps),
1432                    _ => CharClassesStatus::Normal, // Unreachable.
1433                }
1434            }
1435            CharClassesStatus::RawStringSuffix(sharps) => {
1436                match chr {
1437                    '#' => {
1438                        if sharps == 1 {
1439                            CharClassesStatus::Normal
1440                        } else {
1441                            char_kind = FullCodeCharKind::InString;
1442                            CharClassesStatus::RawStringSuffix(sharps - 1)
1443                        }
1444                    }
1445                    _ => CharClassesStatus::Normal, // Unreachable
1446                }
1447            }
1448            CharClassesStatus::LitString => {
1449                char_kind = FullCodeCharKind::InString;
1450                match chr {
1451                    '"' => CharClassesStatus::Normal,
1452                    '\\' => CharClassesStatus::LitStringEscape,
1453                    _ => CharClassesStatus::LitString,
1454                }
1455            }
1456            CharClassesStatus::LitStringEscape => {
1457                char_kind = FullCodeCharKind::InString;
1458                CharClassesStatus::LitString
1459            }
1460            CharClassesStatus::LitChar => match chr {
1461                '\\' => CharClassesStatus::LitCharEscape,
1462                '\'' => CharClassesStatus::Normal,
1463                _ => CharClassesStatus::LitChar,
1464            },
1465            CharClassesStatus::LitCharEscape => CharClassesStatus::LitChar,
1466            CharClassesStatus::Normal => match chr {
1467                'r' => match self.base.peek().map(RichChar::get_char) {
1468                    Some('"') => {
1469                        char_kind = FullCodeCharKind::InString;
1470                        CharClassesStatus::RawStringPrefix(0)
1471                    }
1472                    // `r#` opens a raw string only if the `#`s end in a `"`; otherwise
1473                    // this is a raw identifier like `r#struct` and stays normal code.
1474                    Some('#') if is_raw_string_prefix(&mut self.base) => {
1475                        char_kind = FullCodeCharKind::InString;
1476                        CharClassesStatus::RawStringPrefix(0)
1477                    }
1478                    _ => CharClassesStatus::Normal,
1479                },
1480                '"' => {
1481                    char_kind = FullCodeCharKind::InString;
1482                    CharClassesStatus::LitString
1483                }
1484                '\'' => {
1485                    // HACK: Work around mut borrow.
1486                    match self.base.peek() {
1487                        Some(next) if next.get_char() == '\\' => {
1488                            self.status = CharClassesStatus::LitChar;
1489                            return Some((char_kind, item));
1490                        }
1491                        _ => (),
1492                    }
1493
1494                    match self.base.peek() {
1495                        Some(next) if next.get_char() == '\'' => CharClassesStatus::LitChar,
1496                        _ => CharClassesStatus::Normal,
1497                    }
1498                }
1499                '/' => match self.base.peek() {
1500                    Some(next) if next.get_char() == '*' => {
1501                        self.status = CharClassesStatus::BlockCommentOpening(1);
1502                        return Some((FullCodeCharKind::StartComment, item));
1503                    }
1504                    Some(next) if next.get_char() == '/' => {
1505                        self.status = CharClassesStatus::LineComment;
1506                        return Some((FullCodeCharKind::StartComment, item));
1507                    }
1508                    _ => CharClassesStatus::Normal,
1509                },
1510                _ => CharClassesStatus::Normal,
1511            },
1512            CharClassesStatus::StringInBlockComment(deepness) => {
1513                char_kind = FullCodeCharKind::InStringCommented;
1514                if chr == '"' {
1515                    CharClassesStatus::BlockComment(deepness)
1516                } else if chr == '*' && self.base.peek().map(RichChar::get_char) == Some('/') {
1517                    char_kind = FullCodeCharKind::InComment;
1518                    CharClassesStatus::BlockCommentClosing(deepness - 1)
1519                } else {
1520                    CharClassesStatus::StringInBlockComment(deepness)
1521                }
1522            }
1523            CharClassesStatus::BlockComment(deepness) => {
1524                assert_ne!(deepness, 0);
1525                char_kind = FullCodeCharKind::InComment;
1526                match self.base.peek() {
1527                    Some(next) if next.get_char() == '/' && chr == '*' => {
1528                        CharClassesStatus::BlockCommentClosing(deepness - 1)
1529                    }
1530                    Some(next) if next.get_char() == '*' && chr == '/' => {
1531                        CharClassesStatus::BlockCommentOpening(deepness + 1)
1532                    }
1533                    _ if chr == '"' => CharClassesStatus::StringInBlockComment(deepness),
1534                    _ => self.status,
1535                }
1536            }
1537            CharClassesStatus::BlockCommentOpening(deepness) => {
1538                assert_eq!(chr, '*');
1539                self.status = CharClassesStatus::BlockComment(deepness);
1540                return Some((FullCodeCharKind::InComment, item));
1541            }
1542            CharClassesStatus::BlockCommentClosing(deepness) => {
1543                assert_eq!(chr, '/');
1544                if deepness == 0 {
1545                    self.status = CharClassesStatus::Normal;
1546                    return Some((FullCodeCharKind::EndComment, item));
1547                } else {
1548                    self.status = CharClassesStatus::BlockComment(deepness);
1549                    return Some((FullCodeCharKind::InComment, item));
1550                }
1551            }
1552            CharClassesStatus::LineComment => match chr {
1553                '\n' => {
1554                    self.status = CharClassesStatus::Normal;
1555                    return Some((FullCodeCharKind::EndComment, item));
1556                }
1557                _ => {
1558                    self.status = CharClassesStatus::LineComment;
1559                    return Some((FullCodeCharKind::InComment, item));
1560                }
1561            },
1562        };
1563        Some((char_kind, item))
1564    }
1565}
1566
1567/// An iterator over the lines of a string, paired with the char kind at the
1568/// end of the line.
1569pub(crate) struct LineClasses<'a> {
1570    base: iter::Peekable<CharClasses<std::str::Chars<'a>>>,
1571    kind: FullCodeCharKind,
1572}
1573
1574impl<'a> LineClasses<'a> {
1575    pub(crate) fn new(s: &'a str) -> Self {
1576        LineClasses {
1577            base: CharClasses::new(s.chars()).peekable(),
1578            kind: FullCodeCharKind::Normal,
1579        }
1580    }
1581}
1582
1583impl<'a> Iterator for LineClasses<'a> {
1584    type Item = (FullCodeCharKind, String);
1585
1586    fn next(&mut self) -> Option<Self::Item> {
1587        self.base.peek()?;
1588
1589        let mut line = String::new();
1590
1591        let start_kind = match self.base.peek() {
1592            Some((kind, _)) => *kind,
1593            None => unreachable!(),
1594        };
1595
1596        for (kind, c) in self.base.by_ref() {
1597            // needed to set the kind of the ending character on the last line
1598            self.kind = kind;
1599            if c == '\n' {
1600                self.kind = match (start_kind, kind) {
1601                    (FullCodeCharKind::Normal, FullCodeCharKind::InString) => {
1602                        FullCodeCharKind::StartString
1603                    }
1604                    (FullCodeCharKind::InString, FullCodeCharKind::Normal) => {
1605                        FullCodeCharKind::EndString
1606                    }
1607                    (FullCodeCharKind::InComment, FullCodeCharKind::InStringCommented) => {
1608                        FullCodeCharKind::StartStringCommented
1609                    }
1610                    (FullCodeCharKind::InStringCommented, FullCodeCharKind::InComment) => {
1611                        FullCodeCharKind::EndStringCommented
1612                    }
1613                    _ => kind,
1614                };
1615                break;
1616            }
1617            line.push(c);
1618        }
1619
1620        // Workaround for CRLF newline.
1621        if line.ends_with('\r') {
1622            line.pop();
1623        }
1624
1625        Some((self.kind, line))
1626    }
1627}
1628
1629/// Iterator over functional and commented parts of a string. Any part of a string is either
1630/// functional code, either *one* block comment, either *one* line comment. Whitespace between
1631/// comments is functional code. Line comments contain their ending newlines.
1632struct UngroupedCommentCodeSlices<'a> {
1633    slice: &'a str,
1634    iter: iter::Peekable<CharClasses<std::str::CharIndices<'a>>>,
1635}
1636
1637impl<'a> UngroupedCommentCodeSlices<'a> {
1638    fn new(code: &'a str) -> UngroupedCommentCodeSlices<'a> {
1639        UngroupedCommentCodeSlices {
1640            slice: code,
1641            iter: CharClasses::new(code.char_indices()).peekable(),
1642        }
1643    }
1644}
1645
1646impl<'a> Iterator for UngroupedCommentCodeSlices<'a> {
1647    type Item = (CodeCharKind, usize, &'a str);
1648
1649    fn next(&mut self) -> Option<Self::Item> {
1650        let (kind, (start_idx, _)) = self.iter.next()?;
1651        match kind {
1652            FullCodeCharKind::Normal | FullCodeCharKind::InString => {
1653                // Consume all the Normal code
1654                while let Some(&(char_kind, _)) = self.iter.peek() {
1655                    if char_kind.is_comment() {
1656                        break;
1657                    }
1658                    let _ = self.iter.next();
1659                }
1660            }
1661            FullCodeCharKind::StartComment => {
1662                // Consume the whole comment
1663                loop {
1664                    match self.iter.next() {
1665                        Some((kind, ..)) if kind.inside_comment() => continue,
1666                        _ => break,
1667                    }
1668                }
1669            }
1670            _ => panic!(),
1671        }
1672        let slice = match self.iter.peek() {
1673            Some(&(_, (end_idx, _))) => &self.slice[start_idx..end_idx],
1674            None => &self.slice[start_idx..],
1675        };
1676        Some((
1677            if kind.is_comment() {
1678                CodeCharKind::Comment
1679            } else {
1680                CodeCharKind::Normal
1681            },
1682            start_idx,
1683            slice,
1684        ))
1685    }
1686}
1687
1688/// Iterator over an alternating sequence of functional and commented parts of
1689/// a string. The first item is always a, possibly zero length, subslice of
1690/// functional text. Line style comments contain their ending newlines.
1691pub(crate) struct CommentCodeSlices<'a> {
1692    slice: &'a str,
1693    last_slice_kind: CodeCharKind,
1694    last_slice_end: usize,
1695}
1696
1697impl<'a> CommentCodeSlices<'a> {
1698    pub(crate) fn new(slice: &'a str) -> CommentCodeSlices<'a> {
1699        CommentCodeSlices {
1700            slice,
1701            last_slice_kind: CodeCharKind::Comment,
1702            last_slice_end: 0,
1703        }
1704    }
1705}
1706
1707impl<'a> Iterator for CommentCodeSlices<'a> {
1708    type Item = (CodeCharKind, usize, &'a str);
1709
1710    fn next(&mut self) -> Option<Self::Item> {
1711        if self.last_slice_end == self.slice.len() {
1712            return None;
1713        }
1714
1715        let mut sub_slice_end = self.last_slice_end;
1716        let mut first_whitespace = None;
1717        let subslice = &self.slice[self.last_slice_end..];
1718        let mut iter = CharClasses::new(subslice.char_indices());
1719
1720        for (kind, (i, c)) in &mut iter {
1721            let is_comment_connector = self.last_slice_kind == CodeCharKind::Normal
1722                && &subslice[..2] == "//"
1723                && [' ', '\t'].contains(&c);
1724
1725            if is_comment_connector && first_whitespace.is_none() {
1726                first_whitespace = Some(i);
1727            }
1728
1729            if kind.to_codecharkind() == self.last_slice_kind && !is_comment_connector {
1730                let last_index = match first_whitespace {
1731                    Some(j) => j,
1732                    None => i,
1733                };
1734                sub_slice_end = self.last_slice_end + last_index;
1735                break;
1736            }
1737
1738            if !is_comment_connector {
1739                first_whitespace = None;
1740            }
1741        }
1742
1743        if let (None, true) = (iter.next(), sub_slice_end == self.last_slice_end) {
1744            // This was the last subslice.
1745            sub_slice_end = match first_whitespace {
1746                Some(i) => self.last_slice_end + i,
1747                None => self.slice.len(),
1748            };
1749        }
1750
1751        let kind = match self.last_slice_kind {
1752            CodeCharKind::Comment => CodeCharKind::Normal,
1753            CodeCharKind::Normal => CodeCharKind::Comment,
1754        };
1755        let res = (
1756            kind,
1757            self.last_slice_end,
1758            &self.slice[self.last_slice_end..sub_slice_end],
1759        );
1760        self.last_slice_end = sub_slice_end;
1761        self.last_slice_kind = kind;
1762
1763        Some(res)
1764    }
1765}
1766
1767/// Checks is `new` didn't miss any comment from `span`, if it removed any, return previous text
1768pub(crate) fn recover_comment_removed(
1769    new: String,
1770    span: Span,
1771    context: &RewriteContext<'_>,
1772) -> String {
1773    let snippet = context.snippet(span);
1774    if snippet != new && changed_comment_content(snippet, &new) {
1775        // We missed some comments. Warn and keep the original text.
1776        if context.config.error_on_unformatted() {
1777            context.report.append(
1778                context.psess.span_to_filename(span),
1779                vec![FormattingError::from_span(
1780                    span,
1781                    context.psess,
1782                    ErrorKind::LostComment,
1783                )],
1784            );
1785        }
1786        snippet.to_owned()
1787    } else {
1788        new
1789    }
1790}
1791
1792pub(crate) fn filter_normal_code(code: &str) -> String {
1793    let mut buffer = String::with_capacity(code.len());
1794    LineClasses::new(code).for_each(|(kind, line)| match kind {
1795        FullCodeCharKind::Normal
1796        | FullCodeCharKind::StartString
1797        | FullCodeCharKind::InString
1798        | FullCodeCharKind::EndString => {
1799            buffer.push_str(&line);
1800            buffer.push('\n');
1801        }
1802        _ => (),
1803    });
1804    if !code.ends_with('\n') && buffer.ends_with('\n') {
1805        buffer.pop();
1806    }
1807    buffer
1808}
1809
1810/// Returns `true` if the two strings of code have the same payload of comments.
1811/// The payload of comments is everything in the string except:
1812/// - actual code (not comments),
1813/// - comment start/end marks,
1814/// - whitespace,
1815/// - '*' at the beginning of lines in block comments.
1816fn changed_comment_content(orig: &str, new: &str) -> bool {
1817    // Cannot write this as a fn since we cannot return types containing closures.
1818    let code_comment_content = |code| {
1819        let slices = UngroupedCommentCodeSlices::new(code);
1820        slices
1821            .filter(|(kind, _, _)| *kind == CodeCharKind::Comment)
1822            .flat_map(|(_, _, s)| CommentReducer::new(s))
1823    };
1824    let res = code_comment_content(orig).ne(code_comment_content(new));
1825    debug!(
1826        "comment::changed_comment_content: {}\norig: '{}'\nnew: '{}'\nraw_old: {}\nraw_new: {}",
1827        res,
1828        orig,
1829        new,
1830        code_comment_content(orig).collect::<String>(),
1831        code_comment_content(new).collect::<String>()
1832    );
1833    res
1834}
1835
1836/// Iterator over the 'payload' characters of a comment.
1837/// It skips whitespace, comment start/end marks, and '*' at the beginning of lines.
1838/// The comment must be one comment, ie not more than one start mark (no multiple line comments,
1839/// for example).
1840struct CommentReducer<'a> {
1841    is_block: bool,
1842    at_start_line: bool,
1843    iter: std::str::Chars<'a>,
1844}
1845
1846impl<'a> CommentReducer<'a> {
1847    fn new(comment: &'a str) -> CommentReducer<'a> {
1848        let is_block = comment.starts_with("/*");
1849        let comment = remove_comment_header(comment);
1850        CommentReducer {
1851            is_block,
1852            // There are no supplementary '*' on the first line.
1853            at_start_line: false,
1854            iter: comment.chars(),
1855        }
1856    }
1857}
1858
1859impl<'a> Iterator for CommentReducer<'a> {
1860    type Item = char;
1861
1862    fn next(&mut self) -> Option<Self::Item> {
1863        loop {
1864            let mut c = self.iter.next()?;
1865            if self.is_block && self.at_start_line {
1866                while c.is_whitespace() {
1867                    c = self.iter.next()?;
1868                }
1869                // Ignore leading '*'.
1870                if c == '*' {
1871                    c = self.iter.next()?;
1872                }
1873            } else if c == '\n' {
1874                self.at_start_line = true;
1875            }
1876            if !c.is_whitespace() {
1877                return Some(c);
1878            }
1879        }
1880    }
1881}
1882
1883fn remove_comment_header(comment: &str) -> &str {
1884    if comment.starts_with("///") || comment.starts_with("//!") {
1885        &comment[3..]
1886    } else if let Some(stripped) = comment.strip_prefix("//") {
1887        stripped
1888    } else if (comment.starts_with("/**") && !comment.starts_with("/**/"))
1889        || comment.starts_with("/*!")
1890    {
1891        &comment[3..comment.len() - 2]
1892    } else {
1893        assert!(
1894            comment.starts_with("/*"),
1895            "string '{comment}' is not a comment"
1896        );
1897        &comment[2..comment.len() - 2]
1898    }
1899}
1900
1901#[cfg(test)]
1902mod test {
1903    use super::*;
1904
1905    #[test]
1906    fn char_classes() {
1907        let mut iter = CharClasses::new("//\n\n".chars());
1908
1909        assert_eq!((FullCodeCharKind::StartComment, '/'), iter.next().unwrap());
1910        assert_eq!((FullCodeCharKind::InComment, '/'), iter.next().unwrap());
1911        assert_eq!((FullCodeCharKind::EndComment, '\n'), iter.next().unwrap());
1912        assert_eq!((FullCodeCharKind::Normal, '\n'), iter.next().unwrap());
1913        assert_eq!(None, iter.next());
1914    }
1915
1916    #[test]
1917    fn char_classes_hashless_raw_string() {
1918        let mut iter = CharClasses::new("r\"a\nb\",".chars());
1919
1920        assert_eq!((FullCodeCharKind::InString, 'r'), iter.next().unwrap());
1921        assert_eq!((FullCodeCharKind::InString, '"'), iter.next().unwrap());
1922        assert_eq!((FullCodeCharKind::InString, 'a'), iter.next().unwrap());
1923        assert_eq!((FullCodeCharKind::InString, '\n'), iter.next().unwrap());
1924        assert_eq!((FullCodeCharKind::InString, 'b'), iter.next().unwrap());
1925        assert_eq!((FullCodeCharKind::InString, '"'), iter.next().unwrap());
1926        assert_eq!((FullCodeCharKind::Normal, ','), iter.next().unwrap());
1927        assert_eq!(None, iter.next());
1928    }
1929
1930    #[test]
1931    fn comment_code_slices() {
1932        let input = "code(); /* test */ 1 + 1";
1933        let mut iter = CommentCodeSlices::new(input);
1934
1935        assert_eq!((CodeCharKind::Normal, 0, "code(); "), iter.next().unwrap());
1936        assert_eq!(
1937            (CodeCharKind::Comment, 8, "/* test */"),
1938            iter.next().unwrap()
1939        );
1940        assert_eq!((CodeCharKind::Normal, 18, " 1 + 1"), iter.next().unwrap());
1941        assert_eq!(None, iter.next());
1942    }
1943
1944    #[test]
1945    fn comment_code_slices_two() {
1946        let input = "// comment\n    test();";
1947        let mut iter = CommentCodeSlices::new(input);
1948
1949        assert_eq!((CodeCharKind::Normal, 0, ""), iter.next().unwrap());
1950        assert_eq!(
1951            (CodeCharKind::Comment, 0, "// comment\n"),
1952            iter.next().unwrap()
1953        );
1954        assert_eq!(
1955            (CodeCharKind::Normal, 11, "    test();"),
1956            iter.next().unwrap()
1957        );
1958        assert_eq!(None, iter.next());
1959    }
1960
1961    #[test]
1962    fn comment_code_slices_three() {
1963        let input = "1 // comment\n    // comment2\n\n";
1964        let mut iter = CommentCodeSlices::new(input);
1965
1966        assert_eq!((CodeCharKind::Normal, 0, "1 "), iter.next().unwrap());
1967        assert_eq!(
1968            (CodeCharKind::Comment, 2, "// comment\n    // comment2\n"),
1969            iter.next().unwrap()
1970        );
1971        assert_eq!((CodeCharKind::Normal, 29, "\n"), iter.next().unwrap());
1972        assert_eq!(None, iter.next());
1973    }
1974
1975    #[test]
1976    #[rustfmt::skip]
1977    fn format_doc_comments() {
1978        let mut wrap_normalize_config: crate::config::Config = Default::default();
1979        wrap_normalize_config.set().wrap_comments(true);
1980        wrap_normalize_config.set().normalize_comments(true);
1981
1982        let mut wrap_config: crate::config::Config = Default::default();
1983        wrap_config.set().wrap_comments(true);
1984
1985        let comment = rewrite_comment(" //test",
1986                                      true,
1987                                      Shape::legacy(100, Indent::new(0, 100)),
1988                                      &wrap_normalize_config).unwrap();
1989        assert_eq!("/* test */", comment);
1990
1991        let comment = rewrite_comment("// comment on a",
1992                                      false,
1993                                      Shape::legacy(10, Indent::empty()),
1994                                      &wrap_normalize_config).unwrap();
1995        assert_eq!("// comment\n// on a", comment);
1996
1997        let comment = rewrite_comment("//  A multi line comment\n             // between args.",
1998                                      false,
1999                                      Shape::legacy(60, Indent::new(0, 12)),
2000                                      &wrap_normalize_config).unwrap();
2001        assert_eq!("//  A multi line comment\n            // between args.", comment);
2002
2003        let input = "// comment";
2004        let expected =
2005            "/* comment */";
2006        let comment = rewrite_comment(input,
2007                                      true,
2008                                      Shape::legacy(9, Indent::new(0, 69)),
2009                                      &wrap_normalize_config).unwrap();
2010        assert_eq!(expected, comment);
2011
2012        let comment = rewrite_comment("/*   trimmed    */",
2013                                      true,
2014                                      Shape::legacy(100, Indent::new(0, 100)),
2015                                      &wrap_normalize_config).unwrap();
2016        assert_eq!("/* trimmed */", comment);
2017
2018        // Check that different comment style are properly recognised.
2019        let comment = rewrite_comment(r#"/// test1
2020                                         /// test2
2021                                         /*
2022                                          * test3
2023                                          */"#,
2024                                      false,
2025                                      Shape::legacy(100, Indent::new(0, 0)),
2026                                      &wrap_normalize_config).unwrap();
2027        assert_eq!("/// test1\n/// test2\n// test3", comment);
2028
2029        // Check that the blank line marks the end of a commented paragraph.
2030        let comment = rewrite_comment(r#"// test1
2031
2032                                         // test2"#,
2033                                      false,
2034                                      Shape::legacy(100, Indent::new(0, 0)),
2035                                      &wrap_normalize_config).unwrap();
2036        assert_eq!("// test1\n\n// test2", comment);
2037
2038        // Check that the blank line marks the end of a custom-commented paragraph.
2039        let comment = rewrite_comment(r#"//@ test1
2040
2041                                         //@ test2"#,
2042                                      false,
2043                                      Shape::legacy(100, Indent::new(0, 0)),
2044                                      &wrap_normalize_config).unwrap();
2045        assert_eq!("//@ test1\n\n//@ test2", comment);
2046
2047        // Check that bare lines are just indented but otherwise left unchanged.
2048        let comment = rewrite_comment(r#"// test1
2049                                         /*
2050                                           a bare line!
2051
2052                                                another bare line!
2053                                          */"#,
2054                                      false,
2055                                      Shape::legacy(100, Indent::new(0, 0)),
2056                                      &wrap_config).unwrap();
2057        assert_eq!("// test1\n/*\n a bare line!\n\n      another bare line!\n*/", comment);
2058    }
2059
2060    // This is probably intended to be a non-test fn, but it is not used.
2061    // We should keep this around unless it helps us test stuff to remove it.
2062    fn uncommented(text: &str) -> String {
2063        CharClasses::new(text.chars())
2064            .filter_map(|(s, c)| match s {
2065                FullCodeCharKind::Normal | FullCodeCharKind::InString => Some(c),
2066                _ => None,
2067            })
2068            .collect()
2069    }
2070
2071    #[test]
2072    fn test_uncommented() {
2073        assert_eq!(&uncommented("abc/*...*/"), "abc");
2074        assert_eq!(
2075            &uncommented("// .... /* \n../* /* *** / */ */a/* // */c\n"),
2076            "..ac\n"
2077        );
2078        assert_eq!(&uncommented("abc \" /* */\" qsdf"), "abc \" /* */\" qsdf");
2079    }
2080
2081    #[test]
2082    fn test_contains_comment() {
2083        assert_eq!(contains_comment("abc"), false);
2084        assert_eq!(contains_comment("abc // qsdf"), true);
2085        assert_eq!(contains_comment("abc /* kqsdf"), true);
2086        assert_eq!(contains_comment("abc \" /* */\" qsdf"), false);
2087    }
2088
2089    #[test]
2090    fn test_find_uncommented() {
2091        fn check(haystack: &str, needle: &str, expected: Option<usize>) {
2092            assert_eq!(expected, haystack.find_uncommented(needle));
2093        }
2094
2095        check("/*/ */test", "test", Some(6));
2096        check("//test\ntest", "test", Some(7));
2097        check("/* comment only */", "whatever", None);
2098        check(
2099            "/* comment */ some text /* more commentary */ result",
2100            "result",
2101            Some(46),
2102        );
2103        check("sup // sup", "p", Some(2));
2104        check("sup", "x", None);
2105        check(r#"π? /**/ π is nice!"#, r#"π is nice"#, Some(9));
2106        check("/*sup yo? \n sup*/ sup", "p", Some(20));
2107        check("hel/*lohello*/lo", "hello", None);
2108        check("acb", "ab", None);
2109        check(",/*A*/ ", ",", Some(0));
2110        check("abc", "abc", Some(0));
2111        check("/* abc */", "abc", None);
2112        check("/**/abc/* */", "abc", Some(4));
2113        check("\"/* abc */\"", "abc", Some(4));
2114        check("\"/* abc", "abc", Some(4));
2115    }
2116
2117    #[test]
2118    fn test_filter_normal_code() {
2119        let s = r#"
2120fn main() {
2121    println!("hello, world");
2122}
2123"#;
2124        assert_eq!(s, filter_normal_code(s));
2125        let s_with_comment = r#"
2126fn main() {
2127    // hello, world
2128    println!("hello, world");
2129}
2130"#;
2131        assert_eq!(s, filter_normal_code(s_with_comment));
2132    }
2133
2134    #[test]
2135    fn test_itemized_block_first_line_handling() {
2136        fn run_test(
2137            test_input: &str,
2138            expected_line: &str,
2139            expected_indent: usize,
2140            expected_opener: &str,
2141            expected_line_start: &str,
2142        ) {
2143            let block = ItemizedBlock::new(test_input).unwrap();
2144            assert_eq!(1, block.lines.len(), "test_input: {test_input:?}");
2145            assert_eq!(expected_line, &block.lines[0], "test_input: {test_input:?}");
2146            assert_eq!(expected_indent, block.indent, "test_input: {test_input:?}");
2147            assert_eq!(expected_opener, &block.opener, "test_input: {test_input:?}");
2148            assert_eq!(
2149                expected_line_start, &block.line_start,
2150                "test_input: {test_input:?}"
2151            );
2152        }
2153
2154        run_test("- foo", "foo", 2, "- ", "  ");
2155        run_test("* foo", "foo", 2, "* ", "  ");
2156        run_test("> foo", "foo", 2, "> ", "> ");
2157
2158        run_test("1. foo", "foo", 3, "1. ", "   ");
2159        run_test("12. foo", "foo", 4, "12. ", "    ");
2160        run_test("1) foo", "foo", 3, "1) ", "   ");
2161        run_test("12) foo", "foo", 4, "12) ", "    ");
2162
2163        run_test("    - foo", "foo", 6, "    - ", "      ");
2164
2165        // https://spec.commonmark.org/0.30 says: "A start number may begin with 0s":
2166        run_test("0. foo", "foo", 3, "0. ", "   ");
2167        run_test("01. foo", "foo", 4, "01. ", "    ");
2168    }
2169
2170    #[test]
2171    fn test_itemized_block_nonobvious_markers_are_rejected() {
2172        let test_inputs = vec![
2173            // Non-numeric item markers (e.g. `a.` or `iv.`) are not allowed by
2174            // https://spec.commonmark.org/0.30/#ordered-list-marker. We also note that allowing
2175            // them would risk misidentifying regular words as item markers. See also the
2176            // discussion in https://talk.commonmark.org/t/blank-lines-before-lists-revisited/1990
2177            "word.  rest of the paragraph.",
2178            "a.  maybe this is a list item?  maybe not?",
2179            "iv.  maybe this is a list item?  maybe not?",
2180            // Numbers with 3 or more digits are not recognized as item markers, to avoid
2181            // formatting the following example as a list:
2182            //
2183            // ```
2184            // The Captain died in
2185            // 1868. He was buried in...
2186            // ```
2187            "123.  only 2-digit numbers are recognized as item markers.",
2188            // Parens:
2189            "123)  giving some coverage to parens as well.",
2190            "a)  giving some coverage to parens as well.",
2191            // https://spec.commonmark.org/0.30 says that "at least one space or tab is needed
2192            // between the list marker and any following content":
2193            "1.Not a list item.",
2194            "1.2.3. Not a list item.",
2195            "1)Not a list item.",
2196            "-Not a list item.",
2197            "+Not a list item.",
2198            "+1 not a list item.",
2199            // https://spec.commonmark.org/0.30 says: "A start number may not be negative":
2200            "-1. Not a list item.",
2201            "-1 Not a list item.",
2202            // Marker without prefix are not recognized as item markers:
2203            ".   Not a list item.",
2204            ")   Not a list item.",
2205        ];
2206        for line in test_inputs.iter() {
2207            let maybe_block = ItemizedBlock::new(line);
2208            assert!(
2209                maybe_block.is_none(),
2210                "The following line shouldn't be classified as a list item: {line}"
2211            );
2212        }
2213    }
2214}