mod commands;
use crate::{
grammar::ParseResult,
kind::CppSyntaxKind,
lexer::{DocToken, DocTokenKind, is_block_comment, is_documentation_comment, lex_comment},
parser::{CppParser, MarkerEventContainer},
parser_error::CppParseError,
text::SourceRange,
};
pub use commands::{
DocCommandArgs, DocCommandKind, DocCommandSpec, END_CODE_COMMAND, UNKNOWN_COMMAND_ARGS,
every_command, lookup,
};
pub fn command_kind(name: &str) -> Option<DocCommandKind> {
lookup(name).map(|spec| spec.kind)
}
pub fn command_args(name: &str) -> DocCommandArgs {
lookup(name).map_or(UNKNOWN_COMMAND_ARGS, |spec| spec.args)
}
#[derive(Debug, Clone, Copy)]
pub struct CommentSource {
pub range: SourceRange,
pub separator: [Option<SourceRange>; MAX_SEPARATOR_TOKENS],
pub separator_len: usize,
}
pub const MAX_SEPARATOR_TOKENS: usize = 4;
impl CommentSource {
pub fn first(range: SourceRange) -> Self {
CommentSource {
range,
separator: [None; MAX_SEPARATOR_TOKENS],
separator_len: 0,
}
}
pub fn separator_tokens(&self) -> impl Iterator<Item = SourceRange> + '_ {
self.separator[..self.separator_len]
.iter()
.filter_map(|range| *range)
}
pub fn end(&self) -> usize {
self.range.end_offset()
}
}
pub fn parse_comment_group(p: &mut CppParser<'_>, comments: &[CommentSource]) -> ParseResult {
let m = p.mark(CppSyntaxKind::DocComment);
let file = p.origin_text();
let mut code_block_depth = 0usize;
let mut open_code_block: Option<crate::parser::Marker> = None;
let body = p.mark(CppSyntaxKind::DocCommentBody);
for comment in comments {
for range in comment.separator_tokens() {
let kind = if file[range.start_offset..range.end_offset()].contains('\n') {
crate::kind::CppTokenKind::Newline
} else {
crate::kind::CppTokenKind::Whitespace
};
p.push_doc_token(kind, range);
}
let text = &file[comment.range.start_offset..comment.range.end_offset()];
let tokens = lex_comment(text, comment.range.start_offset);
let documentation = is_documentation_comment(text);
let is_block = is_block_comment(text);
let mut parser = DocParser::new(
p,
tokens,
file,
is_block,
comment.end(),
code_block_depth,
open_code_block,
);
if documentation {
parser.parse_document();
} else {
parser.parse_plain();
}
code_block_depth = parser.code_block_depth;
open_code_block = parser.open_code_block;
}
body.complete(p);
if let Some(block) = open_code_block {
block.complete(p);
}
Ok(m.complete(p))
}
struct DocParser<'a, 'p> {
p: &'a mut CppParser<'p>,
tokens: Vec<DocToken>,
text: &'a str,
index: usize,
code_block_depth: usize,
is_block: bool,
end_offset: usize,
open_code_block: Option<crate::parser::Marker>,
}
impl<'a, 'p> DocParser<'a, 'p> {
#[allow(clippy::too_many_arguments)]
fn new(
p: &'a mut CppParser<'p>,
tokens: Vec<DocToken>,
text: &'a str,
is_block: bool,
end_offset: usize,
code_block_depth: usize,
open_code_block: Option<crate::parser::Marker>,
) -> Self {
DocParser {
p,
tokens,
text,
index: 0,
code_block_depth,
is_block,
end_offset,
open_code_block,
}
}
fn past_comment_end(&self) -> bool {
self.current_range().start_offset >= self.end_offset
}
fn current(&self) -> DocTokenKind {
self.tokens
.get(self.index)
.map_or(DocTokenKind::Eof, |token| token.kind)
}
fn current_range(&self) -> SourceRange {
self.tokens
.get(self.index)
.map_or(SourceRange::EMPTY, |token| token.range)
}
fn current_text(&self) -> &'a str {
match self.tokens.get(self.index) {
Some(token) => &self.text[token.range.start_offset..token.range.end_offset()],
None => "",
}
}
fn at_end(&self) -> bool {
self.index >= self.tokens.len()
}
fn bump(&mut self) {
if let Some(token) = self.tokens.get(self.index) {
self.p.push_token_event(token);
}
self.index += 1;
}
fn skip_layout(&mut self) {
while self.current().is_trivia() {
self.bump();
}
}
fn bump_to_end_of_line(&mut self) {
while !self.at_end() && !self.past_comment_end() {
let ends_line = self.current().ends_a_line();
self.bump();
if ends_line {
break;
}
}
}
fn parse_document(&mut self) {
while !self.at_end() {
if self.code_block_depth > 0 {
self.parse_code_block();
continue;
}
self.skip_layout();
if self.at_end() {
break;
}
match self.current() {
DocTokenKind::DocCommandName => self.parse_command(),
DocTokenKind::DocText => self.parse_free_description(),
_ => self.bump(),
}
}
}
fn parse_plain(&mut self) {
while !self.at_end() {
self.bump();
}
}
fn parse_free_description(&mut self) {
let m = self.p.mark(CppSyntaxKind::DocCommandBody);
while !self.at_end() && !self.starts_a_command_here() && !self.body_ends_here() {
self.bump();
}
m.complete(self.p);
}
fn parse_command(&mut self) {
let m = self.p.mark(CppSyntaxKind::DocCommand);
let name = self.current_text().to_string();
let spec = commands::lookup(&name);
self.bump();
if self.code_block_depth > 0 {
self.bump_to_end_of_line();
m.complete(self.p);
return;
}
let args = spec.map_or(UNKNOWN_COMMAND_ARGS, |spec| spec.args);
match args {
DocCommandArgs::None => {
self.bump_to_end_of_line();
}
DocCommandArgs::Body => {
self.parse_body();
}
DocCommandArgs::NameAndBody => {
self.skip_layout();
self.parse_name_argument();
self.parse_body();
}
DocCommandArgs::DirectionalNameAndBody => {
self.skip_layout();
self.parse_direction_argument();
self.skip_layout();
self.parse_name_argument();
self.parse_body();
}
DocCommandArgs::ReferenceAndBody => {
self.skip_layout();
self.parse_reference_argument();
self.parse_body();
}
DocCommandArgs::SectionTitle => {
self.skip_layout();
self.parse_name_argument();
self.parse_body();
}
DocCommandArgs::CodeBlock => {
self.code_block_depth += 1;
}
}
m.complete(self.p);
}
fn parse_body(&mut self) {
self.skip_layout();
self.split_leading_layout();
let m = self.p.mark(CppSyntaxKind::DocCommandBody);
while !self.at_end() && !self.past_comment_end() {
match self.current() {
DocTokenKind::DocIntroducer | DocTokenKind::DocCommandName
if self.starts_a_command_here() =>
{
break;
}
DocTokenKind::BlockCommentEnd => break,
DocTokenKind::DocNewline => {
self.bump();
if !self.block_comment_continues() {
break;
}
}
_ if self.body_ends_here() => break,
_ => self.bump(),
}
}
m.complete(self.p);
}
fn split_leading_layout(&mut self) {
let Some(token) = self.tokens.get(self.index) else {
return;
};
if token.kind != DocTokenKind::DocText {
return;
}
let range = token.range;
let Some(slice) = self.text.get(range.start_offset..range.end_offset()) else {
return;
};
let layout = slice.len() - slice.trim_start_matches([' ', '\t']).len();
if layout == 0 || layout == slice.len() {
return;
}
self.tokens[self.index].range =
SourceRange::new(range.start_offset + layout, range.length - layout);
self.tokens.insert(
self.index,
DocToken::new(
DocTokenKind::DocWhitespace,
SourceRange::new(range.start_offset, layout),
),
);
self.skip_layout();
}
fn body_ends_here(&self) -> bool {
let next = self.tokens[self.index..]
.iter()
.position(|token| !token.kind.is_trivia())
.map(|offset| self.index + offset);
match next {
Some(index) => {
self.tokens[index].kind == DocTokenKind::BlockCommentEnd
|| self.command_starts_at(index)
}
None => true,
}
}
fn starts_a_command_here(&self) -> bool {
match self.current() {
DocTokenKind::DocCommandName => true,
DocTokenKind::DocIntroducer => self.tokens.get(self.index + 1).is_some_and(|token| {
matches!(
token.kind,
DocTokenKind::DocCommandName | DocTokenKind::DocWhitespace
)
}),
_ => false,
}
}
fn command_starts_at(&self, index: usize) -> bool {
match self.tokens.get(index).map(|token| token.kind) {
Some(DocTokenKind::DocCommandName) => true,
Some(DocTokenKind::DocIntroducer) => {
let rest = &self.tokens[index + 1..];
let spaces = rest
.iter()
.take_while(|token| token.kind == DocTokenKind::DocWhitespace)
.count();
spaces <= 1
&& rest[spaces..]
.first()
.is_some_and(|token| token.kind == DocTokenKind::DocCommandName)
}
_ => false,
}
}
fn block_comment_continues(&self) -> bool {
!self.at_end() && !self.past_comment_end() && self.is_block
}
fn parse_code_block(&mut self) {
while !self.at_end() && !self.past_comment_end() {
if self.open_code_block.is_none() {
self.open_code_block = Some(self.p.mark(CppSyntaxKind::DocCodeBlock));
}
if self.ends_the_code_block() {
if self.current() == DocTokenKind::DocIntroducer {
self.bump();
}
self.bump(); self.bump_to_end_of_line();
self.code_block_depth -= 1;
if let Some(block) = self.open_code_block.take() {
block.complete(self.p);
}
return;
}
self.bump();
}
}
fn ends_the_code_block(&self) -> bool {
match self.current() {
DocTokenKind::DocCommandName => {
self.current_text().eq_ignore_ascii_case(END_CODE_COMMAND)
}
DocTokenKind::DocIntroducer => self.tokens.get(self.index + 1).is_some_and(|token| {
token.kind == DocTokenKind::DocCommandName
&& self.text[token.range.start_offset..token.range.end_offset()]
.eq_ignore_ascii_case(END_CODE_COMMAND)
}),
_ => false,
}
}
fn parse_name_argument(&mut self) {
if !self.starts_an_argument() {
return;
}
let m = self.p.mark(CppSyntaxKind::DocCommandArg);
self.emit_argument();
m.complete(self.p);
}
fn parse_direction_argument(&mut self) {
if self.current() != DocTokenKind::DocLeftBracket {
return;
}
let m = self.p.mark(CppSyntaxKind::DocCommandArg);
self.bump();
while !self.at_end()
&& !matches!(
self.current(),
DocTokenKind::DocRightBracket | DocTokenKind::DocNewline
)
{
self.bump();
}
if self.current() == DocTokenKind::DocRightBracket {
self.bump();
}
m.complete(self.p);
}
fn parse_reference_argument(&mut self) {
if !self.starts_an_argument() {
return;
}
let m = self.p.mark(CppSyntaxKind::DocCommandArg);
self.emit_argument();
m.complete(self.p);
}
fn starts_an_argument(&self) -> bool {
matches!(
self.current(),
DocTokenKind::DocText
| DocTokenKind::DocScope
| DocTokenKind::DocDot
| DocTokenKind::DocColon
| DocTokenKind::DocLess
| DocTokenKind::DocGreater
| DocTokenKind::DocEquals
)
}
fn emit_argument(&mut self) {
if !self.starts_an_argument() {
return;
}
let Some(token) = self.tokens.get(self.index) else {
return;
};
let range = token.range;
if token.kind == DocTokenKind::DocText
&& let Some(space) = self.text[range.start_offset..range.end_offset()].find(' ')
&& space > 0
&& space + 1 < range.length
{
let split = range.start_offset + space;
self.tokens[self.index].range.length = space;
self.bump();
self.tokens.insert(
self.index,
DocToken::new(DocTokenKind::DocWhitespace, SourceRange::new(split, 1)),
);
self.bump();
let remainder = DocToken::new(
DocTokenKind::DocText,
SourceRange::new(split + 1, range.end_offset() - split - 1),
);
self.tokens.insert(self.index, remainder);
return;
}
while let Some(token) = self.tokens.get(self.index) {
match token.kind {
DocTokenKind::DocWhitespace
| DocTokenKind::DocNewline
| DocTokenKind::DocCommandName
| DocTokenKind::Eof => break,
_ => {
self.bump();
if matches!(
self.current(),
DocTokenKind::DocText | DocTokenKind::DocWhitespace
) {
break;
}
}
}
}
}
}
impl CppParser<'_> {
pub(crate) fn push_token_event(&mut self, token: &DocToken) {
self.push_doc_token(token.kind.to_cpp_token(), token.range);
}
}
#[allow(dead_code)]
pub(crate) fn report(p: &mut CppParser<'_>, message: &str, range: SourceRange) {
p.push_error(CppParseError::syntax_error_from(message, range));
}