blob: e3b895bca3da6d59bc2c9c66e88d14a6e9ad8ae7 [file] [log] [blame]
// Part of the Crubit project, under the Apache License v2.0 with LLVM
// Exceptions. See /LICENSE for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
use anyhow::{anyhow, ensure, Result};
use itertools::Itertools;
use once_cell::sync::Lazy;
use proc_macro2::{Ident, TokenStream};
use quote::{format_ident, quote, ToTokens};
use std::collections::{BTreeSet, HashSet};
use std::rc::Rc;
/// Formats a C++ identifier. Returns an error when `ident` is a C++ reserved
/// keyword or is an invalid identifier.
pub fn format_cc_ident(ident: &str) -> Result<TokenStream> {
ensure!(!ident.is_empty(), "Empty string is not a valid C++ identifier");
// C++ doesn't have an equivalent of
// https://doc.rust-lang.org/rust-by-example/compatibility/raw_identifiers.html and therefore
// an error is returned when `ident` is a C++ reserved keyword.
ensure!(
!RESERVED_CC_KEYWORDS.contains(ident),
"`{}` is a C++ reserved keyword and can't be used as a C++ identifier",
ident
);
ident.parse().map_err(
// Explicitly mapping the error via `anyhow!`, because `LexError` is not `Sync`
// (required for `anyhow::Error` to implement `From<LexError>`) and
// therefore we can't just use `?`.
|lex_error| anyhow!("Can't format `{ident}` as a C++ identifier: {lex_error}"),
)
}
/// Makes an 'Ident' to be used in the Rust source code. Escapes Rust keywords.
/// Panics if `ident` is empty or is otherwise an invalid identifier.
pub fn make_rs_ident(ident: &str) -> Ident {
// TODO(https://github.com/dtolnay/syn/pull/1098): Remove the hardcoded list once syn recognizes
// 2018 and 2021 keywords.
if ["async", "await", "try", "dyn"].contains(&ident) {
return format_ident!("r#{}", ident);
}
match syn::parse_str::<syn::Ident>(ident) {
Ok(_) => format_ident!("{}", ident),
Err(_) => format_ident!("r#{}", ident),
}
}
/// Representation of `foo::bar::baz` where each component is either the name
/// of a C++ namespace, or the name of a Rust module.
#[derive(Debug, PartialEq, Eq, Clone, Hash, PartialOrd, Ord)]
pub struct NamespaceQualifier(Vec<Rc<str>>);
impl NamespaceQualifier {
/// Constructs a new `NamespaceQualifier` from a sequence of names.
pub fn new<T: Into<Rc<str>>>(iter: impl IntoIterator<Item = T>) -> Self {
// TODO(b/258265044): Catch most (all if possible) error conditions early. For
// example:
// - Panic early if any strings are empty, or are not Rust identifiers
// - Report an error early if any strings are C++ reserved keywords
// This may make `format_for_cc`, `format_with_cc_body`, and
// `format_namespace_bound_cc_tokens` infallible.
Self(iter.into_iter().map(Into::into).collect())
}
/// Returns `foo::bar::baz::` (escaping Rust keywords as needed).
pub fn format_for_rs(&self) -> TokenStream {
let namespace_rs_idents = self.0.iter().map(|ns| make_rs_ident(ns));
quote! { #(#namespace_rs_idents::)* }
}
/// Returns `foo::bar::baz::` (reporting errors for C++ keywords).
pub fn format_for_cc(&self) -> Result<TokenStream> {
let namespace_cc_idents = self.cc_idents()?;
Ok(quote! { #(#namespace_cc_idents::)* })
}
fn format_with_cc_body(&self, body: TokenStream) -> Result<TokenStream> {
if self.0.is_empty() {
Ok(body)
} else {
let namespace_cc_idents = self.cc_idents()?;
Ok(quote! {
namespace #(#namespace_cc_idents)::* {
#body
}
})
}
}
fn cc_idents(&self) -> Result<Vec<TokenStream>> {
self.0.iter().map(|ns| format_cc_ident(ns)).collect()
}
}
/// `format_namespace_bound_cc_tokens` formats a sequence of namespace-bound
/// snippets. For example, `[(ns, tokens)]` will be formatted as:
///
/// ```
/// namespace ns {
/// #tokens
/// }
/// ```
///
/// `format_namespace_bound_cc_tokens` tries to give a nice-looking output - for
/// example it combines consecutive items that belong to the same namespace,
/// when given `[(ns, tokens1), (ns, tokens2)]` as input:
///
/// ```
/// namespace ns {
/// #tokens1
/// #tokens2
/// }
/// ```
///
/// `format_namespace_bound_cc_tokens` also knows that top-level items (e.g.
/// ones where `NamespaceQualifier` doesn't contain any namespace names) should
/// be emitted at the top-level (not nesting them under a `namespace` keyword).
/// For example, `[(toplevel_ns, tokens)]` will be formatted as just:
///
/// ```
/// #tokens
/// ```
pub fn format_namespace_bound_cc_tokens(
iter: impl IntoIterator<Item = (NamespaceQualifier, TokenStream)>,
) -> TokenStream {
let iter = iter
.into_iter()
.coalesce(|(ns1, mut tokens1), (ns2, tokens2)| {
// Coallesce tokens if subsequent items belong to the same namespace.
if ns1 == ns2 {
tokens1.extend(tokens2);
Ok((ns1, tokens1))
} else {
Err(((ns1, tokens1), (ns2, tokens2)))
}
})
.map(|(ns, tokens)| {
ns.format_with_cc_body(tokens).unwrap_or_else(|err| {
let name = ns.0.iter().join("::");
let err = format!("Failed to format namespace name `{name}`: {err}");
quote! { __COMMENT__ #err }
})
});
// Using fully-qualified syntax to avoid the warning that `intersperse`
// may be added to the standard library in the future.
//
// TODO(https://github.com/rust-lang/rust/issues/79524): Use `.intersperse(...)` syntax once
// 1) this stdlib feature gets stabilized and
// 2) the method with conflicting name gets removed from `itertools`.
let iter = itertools::Itertools::intersperse(iter, quote! { __NEWLINE__ __NEWLINE__ });
iter.collect()
}
/// `CcInclude` represents a single `#include ...` directive in C++.
#[derive(Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub enum CcInclude {
SystemHeader(&'static str),
UserHeader(Rc<str>),
}
impl CcInclude {
/// Creates a `CcInclude` that represents `#include <cstddef>` and provides
/// C++ types like `std::size_t` or `std::ptrdiff_t`. See also
/// https://en.cppreference.com/w/cpp/header/cstddef
pub fn cstddef() -> Self {
Self::SystemHeader("cstddef")
}
/// Creates a `CcInclude` that represents `#include <cstdint>` and provides
/// C++ types like `std::int16_t` or `std::uint32_t`. See also
/// https://en.cppreference.com/w/cpp/header/cstdint
pub fn cstdint() -> Self {
Self::SystemHeader("cstdint")
}
/// Creates a `CcInclude` that represents `#include <memory>`.
/// See also https://en.cppreference.com/w/cpp/header/memory
pub fn memory() -> Self {
Self::SystemHeader("memory")
}
/// Creates a `CcInclude` that represents `#include <utility>` and provides
/// C++ functions like `std::move` and C++ types like `std::tuple`.
/// See also https://en.cppreference.com/w/cpp/header/utility
pub fn utility() -> Self {
Self::SystemHeader("utility")
}
/// Creates a user include: `#include "some/path/to/header.h"`.
pub fn user_header(path: Rc<str>) -> Self {
Self::UserHeader(path)
}
}
impl ToTokens for CcInclude {
fn to_tokens(&self, tokens: &mut TokenStream) {
match self {
Self::SystemHeader(path) => {
let path: TokenStream = path
.parse()
.expect("`pub` API of `CcInclude` guarantees validity of system includes");
quote! { __HASH_TOKEN__ include < #path > __NEWLINE__ }.to_tokens(tokens)
}
Self::UserHeader(path) => {
quote! { __HASH_TOKEN__ include #path __NEWLINE__ }.to_tokens(tokens)
}
}
}
}
/// Formats a set of `CcInclude`s, trying to follow the guidance from
/// [the Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes).
pub fn format_cc_includes(set_of_includes: &BTreeSet<CcInclude>) -> TokenStream {
let mut tokens = TokenStream::default();
let mut iter = set_of_includes.iter().peekable();
while let Some(include) = iter.next() {
include.to_tokens(&mut tokens);
// Add an empty line between system headers and user headers.
if let (CcInclude::SystemHeader(_), Some(CcInclude::UserHeader(_))) = (include, iter.peek())
{
quote! { __NEWLINE__ }.to_tokens(&mut tokens)
}
}
tokens
}
static RESERVED_CC_KEYWORDS: Lazy<HashSet<&'static str>> = Lazy::new(|| {
// `RESERVED_CC_KEYWORDS` are based on https://en.cppreference.com/w/cpp/keyword
[
"alignas",
"alignof",
"and",
"and_eq",
"asm",
"atomic_cancel",
"atomic_commit",
"atomic_noexcept",
"auto",
"bitand",
"bitor",
"bool",
"break",
"case",
"catch",
"char",
"char8_t",
"char16_t",
"char32_t",
"class",
"compl",
"concept",
"const",
"consteval",
"constexpr",
"constinit",
"const_cast",
"continue",
"co_await",
"co_return",
"co_yield",
"decltype",
"default",
"delete",
"do",
"double",
"dynamic_cast",
"else",
"enum",
"explicit",
"export",
"extern",
"false",
"float",
"for",
"friend",
"goto",
"if",
"inline",
"int",
"long",
"mutable",
"namespace",
"new",
"noexcept",
"not",
"not_eq",
"nullptr",
"operator",
"or",
"or_eq",
"private",
"protected",
"public",
"reflexpr",
"register",
"reinterpret_cast",
"requires",
"return",
"short",
"signed",
"sizeof",
"static",
"static_assert",
"static_cast",
"struct",
"switch",
"synchronized",
"template",
"this",
"thread_local",
"throw",
"true",
"try",
"typedef",
"typeid",
"typename",
"union",
"unsigned",
"using",
"virtual",
"void",
"volatile",
"wchar_t",
"while",
"xor",
"xor_eq",
]
.into_iter()
.collect()
});
#[cfg(test)]
pub mod tests {
use super::*;
use quote::quote;
use token_stream_matchers::{assert_cc_matches, assert_rs_matches};
use token_stream_printer::cc_tokens_to_formatted_string_for_tests;
#[test]
fn test_format_cc_ident_basic() {
assert_cc_matches!(
format_cc_ident("foo").unwrap(),
quote! { foo }
);
}
#[test]
fn test_format_cc_ident_reserved_rust_keyword() {
assert_cc_matches!(
format_cc_ident("impl").unwrap(),
quote! { impl }
);
}
#[test]
fn test_format_cc_ident_reserved_cc_keyword() {
let err = format_cc_ident("reinterpret_cast").unwrap_err();
let msg = err.to_string();
assert!(msg.contains("`reinterpret_cast`"));
assert!(msg.contains("C++ reserved keyword"));
}
#[test]
fn test_format_cc_ident_unfinished_group() {
let err = format_cc_ident("(foo") // No closing `)`.
.unwrap_err();
let msg = err.to_string();
assert!(msg.contains("Can't format `(foo` as a C++ identifier"));
assert!(msg.contains("cannot parse"));
}
#[test]
fn test_format_cc_ident_unqualified_identifiers() {
// https://en.cppreference.com/w/cpp/language/identifiers#Unqualified_identifiers
// These may appear in `IR::Func::name`.
assert_cc_matches!(
format_cc_ident("operator==").unwrap(),
quote! { operator== }
);
assert_cc_matches!(
format_cc_ident("operator new").unwrap(),
quote! { operator new }
);
// This may appear in `IR::Record::cc_name` (although in practice these will
// be namespace-qualified most of the time).
assert_cc_matches!(
format_cc_ident("MyTemplate<int>").unwrap(),
quote! { MyTemplate<int> }
);
// These forms of unqualified identifiers are not used by Crubit in practice,
assert_cc_matches!(
format_cc_ident("~MyClass").unwrap(),
quote! { ~MyClass }
);
assert_cc_matches!(
format_cc_ident(r#" operator "" _km "#).unwrap(),
quote! { operator "" _km }
);
}
#[test]
fn test_format_cc_ident_empty() {
let err = format_cc_ident("").unwrap_err();
let msg = err.to_string();
assert_eq!(msg, "Empty string is not a valid C++ identifier");
}
#[test]
fn test_format_cc_ident_qualified_identifiers() {
// https://en.cppreference.com/w/cpp/language/identifiers#Qualified_identifiers
// This may appear in `IR::Record::cc_name`.
assert_cc_matches!(
format_cc_ident("std::vector<int>").unwrap(),
quote! { std::vector<int> }
);
}
#[test]
fn test_make_rs_ident_basic() {
let id = make_rs_ident("foo");
assert_rs_matches!(quote! { #id }, quote! { foo });
}
#[test]
fn test_make_rs_ident_reserved_cc_keyword() {
let id = make_rs_ident("reinterpret_cast");
assert_rs_matches!(quote! { #id }, quote! { reinterpret_cast });
}
#[test]
fn test_make_rs_ident_reserved_rust_keyword() {
let id = make_rs_ident("impl");
assert_rs_matches!(quote! { #id }, quote! { r#impl });
}
#[test]
#[should_panic]
fn test_make_rs_ident_unfinished_group() {
make_rs_ident("(foo"); // No closing `)`.
}
#[test]
#[should_panic]
fn test_make_rs_ident_empty() {
make_rs_ident("");
}
#[test]
fn test_cc_include_to_tokens_for_system_header() {
let include = CcInclude::cstddef();
assert_cc_matches!(
quote! { #include },
quote! {
__HASH_TOKEN__ include <cstddef>
}
);
}
#[test]
fn test_cc_include_to_tokens_for_user_header() {
let include = CcInclude::user_header("some/path/to/header.h".into());
assert_cc_matches!(
quote! { #include },
quote! {
__HASH_TOKEN__ include "some/path/to/header.h"
}
);
}
#[test]
fn test_cc_include_ord() {
let cstddef = CcInclude::cstddef();
let memory = CcInclude::memory();
let a = CcInclude::user_header("a.h".into());
let b = CcInclude::user_header("b.h".into());
assert!(cstddef < memory);
assert!(cstddef < a);
assert!(cstddef < b);
assert!(memory < a);
assert!(memory < b);
assert!(a < b);
}
#[test]
fn test_format_cc_includes() {
let includes = [
CcInclude::cstddef(),
CcInclude::memory(),
CcInclude::user_header("a.h".into()),
CcInclude::user_header("b.h".into()),
]
.into_iter()
.collect::<BTreeSet<_>>();
let tokens = format_cc_includes(&includes);
let actual =
cc_tokens_to_formatted_string_for_tests(quote! { __NEWLINE__ #tokens }).unwrap();
assert_eq!(
actual,
r#"
#include <cstddef>
#include <memory>
#include "a.h"
#include "b.h"
"#
);
}
#[test]
fn test_namespace_qualifier_empty() {
let ns = NamespaceQualifier::new::<&str>([]);
let actual_rs = ns.format_for_rs();
assert!(actual_rs.is_empty());
let actual_cc = ns.format_for_cc().unwrap();
assert!(actual_cc.is_empty());
}
#[test]
fn test_namespace_qualifier_basic() {
let ns = NamespaceQualifier::new(["foo", "bar"]);
let actual_rs = ns.format_for_rs();
assert_rs_matches!(actual_rs, quote! { foo::bar:: });
let actual_cc = ns.format_for_cc().unwrap();
assert_cc_matches!(actual_cc, quote! { foo::bar:: });
}
#[test]
fn test_namespace_qualifier_reserved_cc_keyword() {
let ns = NamespaceQualifier::new(["foo", "impl", "bar"]);
let actual_rs = ns.format_for_rs();
assert_rs_matches!(actual_rs, quote! { foo :: r#impl :: bar :: });
let actual_cc = ns.format_for_cc().unwrap();
assert_cc_matches!(actual_cc, quote! { foo::impl::bar:: });
}
#[test]
fn test_namespace_qualifier_reserved_rust_keyword() {
let ns = NamespaceQualifier::new(["foo", "reinterpret_cast", "bar"]);
let actual_rs = ns.format_for_rs();
assert_rs_matches!(actual_rs, quote! { foo :: reinterpret_cast :: bar :: });
let cc_error = ns.format_for_cc().unwrap_err();
let msg = cc_error.to_string();
assert!(msg.contains("`reinterpret_cast`"));
assert!(msg.contains("C++ reserved keyword"));
}
#[test]
fn test_namespace_qualifier_format_with_cc_body_top_level_namespace() {
let ns = NamespaceQualifier::new::<&str>([]);
assert_cc_matches!(
ns.format_with_cc_body(quote! { cc body goes here }).unwrap(),
quote! { cc body goes here },
);
}
#[test]
fn test_namespace_qualifier_format_with_cc_body_nested_namespace() {
let ns = NamespaceQualifier::new(["foo", "bar", "baz"]);
assert_cc_matches!(
ns.format_with_cc_body(quote! { cc body goes here }).unwrap(),
quote! {
namespace foo::bar::baz {
cc body goes here
} // namespace foo::bar::baz
},
);
}
#[test]
fn test_format_namespace_bound_cc_tokens() {
let top_level = NamespaceQualifier::new::<&str>([]);
let m1 = NamespaceQualifier::new(["m1"]);
let m2 = NamespaceQualifier::new(["m2"]);
let input = [
(top_level.clone(), quote! { void f0a(); }),
(m1.clone(), quote! { void f1a(); }),
(m1.clone(), quote! { void f1b(); }),
(top_level.clone(), quote! { void f0b(); }),
(top_level.clone(), quote! { void f0c(); }),
(m2.clone(), quote! { void f2a(); }),
(m1.clone(), quote! { void f1c(); }),
(m1.clone(), quote! { void f1d(); }),
];
assert_cc_matches!(
format_namespace_bound_cc_tokens(input),
quote! {
void f0a();
namespace m1 {
void f1a();
void f1b();
} // namespace m1
void f0b();
void f0c();
namespace m2 {
void f2a();
}
namespace m1 {
void f1c();
void f1d();
} // namespace m1
},
);
}
#[test]
fn test_format_namespace_bound_cc_tokens_with_reserved_cpp_keywords() {
let working_module = NamespaceQualifier::new(["foo", "working_module", "bar"]);
let broken_module = NamespaceQualifier::new(["foo", "reinterpret_cast", "bar"]);
let input = vec![
(broken_module.clone(), quote! { void broken_module_f1(); }),
(broken_module.clone(), quote! { void broken_module_f2(); }),
(working_module.clone(), quote! { void working_module_f3(); }),
(working_module.clone(), quote! { void working_module_f4(); }),
(broken_module.clone(), quote! { void broken_module_f5(); }),
(broken_module.clone(), quote! { void broken_module_f6(); }),
(working_module.clone(), quote! { void working_module_f7(); }),
(working_module.clone(), quote! { void working_module_f8(); }),
];
let broken_module_msg = "Failed to format namespace name `foo::reinterpret_cast::bar`: \
`reinterpret_cast` is a C++ reserved keyword \
and can't be used as a C++ identifier";
assert_cc_matches!(
format_namespace_bound_cc_tokens(input),
quote! {
__COMMENT__ #broken_module_msg
namespace foo::working_module::bar {
void working_module_f3();
void working_module_f4();
} // namespace foo::working_module::bar
// TODO(lukasza): Repeating the error message below seems somewhat undesirable.
// OTOH fixing this seems low priority, given that errors when formatting namespace
// names should be fairly rare. And fixing this requires extra work and effort,
// especially if we want to:
// 1) coallesce the 2 chunks of the `working_module`
// 2) avoid reordering where the `broken_module` error comment appears.
__COMMENT__ #broken_module_msg
namespace foo::working_module::bar {
void working_module_f7();
void working_module_f8();
} // namespace foo::working_module::bar
},
);
}
}