1//! A higher level Clang API built on top of the generated bindings in the
2//! `clang_sys` module.
3
4#![allow(non_upper_case_globals, dead_code)]
5#![deny(clippy::missing_docs_in_private_items)]
6
7use crate::ir::context::BindgenContext;
8use clang_sys::*;
9use std::cmp;
10
11use std::ffi::{CStr, CString};
12use std::fmt;
13use std::fs::OpenOptions;
14use std::hash::Hash;
15use std::hash::Hasher;
16use std::os::raw::{c_char, c_int, c_longlong, c_uint, c_ulong, c_ulonglong};
17use std::sync::OnceLock;
18use std::{mem, ptr, slice};
19
20/// Type representing a clang attribute.
21///
22/// Values of this type can be used to check for different attributes using the `has_attrs`
23/// function.
24pub(crate) struct Attribute {
25 name: &'static [u8],
26 kind: Option<CXCursorKind>,
27 token_kind: CXTokenKind,
28}
29
30impl Attribute {
31 /// A `warn_unused_result` attribute.
32 pub(crate) const MUST_USE: Self = Self {
33 name: b"warn_unused_result",
34 // FIXME(emilio): clang-sys doesn't expose `CXCursor_WarnUnusedResultAttr` (from clang 9).
35 kind: Some(440),
36 token_kind: CXToken_Identifier,
37 };
38
39 /// A `_Noreturn` attribute.
40 pub(crate) const NO_RETURN: Self = Self {
41 name: b"_Noreturn",
42 kind: None,
43 token_kind: CXToken_Keyword,
44 };
45
46 /// A `[[noreturn]]` attribute.
47 pub(crate) const NO_RETURN_CPP: Self = Self {
48 name: b"noreturn",
49 kind: None,
50 token_kind: CXToken_Identifier,
51 };
52}
53
54/// A cursor into the Clang AST, pointing to an AST node.
55///
56/// We call the AST node pointed to by the cursor the cursor's "referent".
57#[derive(Copy, Clone)]
58pub(crate) struct Cursor {
59 x: CXCursor,
60}
61
62impl fmt::Debug for Cursor {
63 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
64 write!(
65 fmt,
66 "Cursor({} kind: {}, loc: {}, usr: {:?})",
67 self.spelling(),
68 kind_to_str(self.kind()),
69 self.location(),
70 self.usr()
71 )
72 }
73}
74
75impl Cursor {
76 /// Get the Unified Symbol Resolution for this cursor's referent, if
77 /// available.
78 ///
79 /// The USR can be used to compare entities across translation units.
80 pub(crate) fn usr(&self) -> Option<String> {
81 let s = unsafe { cxstring_into_string(clang_getCursorUSR(self.x)) };
82 if s.is_empty() {
83 None
84 } else {
85 Some(s)
86 }
87 }
88
89 /// Is this cursor's referent a declaration?
90 pub(crate) fn is_declaration(&self) -> bool {
91 unsafe { clang_isDeclaration(self.kind()) != 0 }
92 }
93
94 /// Is this cursor's referent an anonymous record or so?
95 pub(crate) fn is_anonymous(&self) -> bool {
96 unsafe { clang_Cursor_isAnonymous(self.x) != 0 }
97 }
98
99 /// Get this cursor's referent's spelling.
100 pub(crate) fn spelling(&self) -> String {
101 unsafe { cxstring_into_string(clang_getCursorSpelling(self.x)) }
102 }
103
104 /// Get this cursor's referent's display name.
105 ///
106 /// This is not necessarily a valid identifier. It includes extra
107 /// information, such as parameters for a function, etc.
108 pub(crate) fn display_name(&self) -> String {
109 unsafe { cxstring_into_string(clang_getCursorDisplayName(self.x)) }
110 }
111
112 /// Get the mangled name of this cursor's referent.
113 pub(crate) fn mangling(&self) -> String {
114 unsafe { cxstring_into_string(clang_Cursor_getMangling(self.x)) }
115 }
116
117 /// Gets the C++ manglings for this cursor, or an error if the manglings
118 /// are not available.
119 pub(crate) fn cxx_manglings(&self) -> Result<Vec<String>, ()> {
120 use clang_sys::*;
121 unsafe {
122 let manglings = clang_Cursor_getCXXManglings(self.x);
123 if manglings.is_null() {
124 return Err(());
125 }
126 let count = (*manglings).Count as usize;
127
128 let mut result = Vec::with_capacity(count);
129 for i in 0..count {
130 let string_ptr = (*manglings).Strings.add(i);
131 result.push(cxstring_to_string_leaky(*string_ptr));
132 }
133 clang_disposeStringSet(manglings);
134 Ok(result)
135 }
136 }
137
138 /// Returns whether the cursor refers to a built-in definition.
139 pub(crate) fn is_builtin(&self) -> bool {
140 let (file, _, _, _) = self.location().location();
141 file.name().is_none()
142 }
143
144 /// Get the `Cursor` for this cursor's referent's lexical parent.
145 ///
146 /// The lexical parent is the parent of the definition. The semantic parent
147 /// is the parent of the declaration. Generally, the lexical parent doesn't
148 /// have any effect on semantics, while the semantic parent does.
149 ///
150 /// In the following snippet, the `Foo` class would be the semantic parent
151 /// of the out-of-line `method` definition, while the lexical parent is the
152 /// translation unit.
153 ///
154 /// ```c++
155 /// class Foo {
156 /// void method();
157 /// };
158 ///
159 /// void Foo::method() { /* ... */ }
160 /// ```
161 pub(crate) fn lexical_parent(&self) -> Cursor {
162 unsafe {
163 Cursor {
164 x: clang_getCursorLexicalParent(self.x),
165 }
166 }
167 }
168
169 /// Get the referent's semantic parent, if one is available.
170 ///
171 /// See documentation for `lexical_parent` for details on semantic vs
172 /// lexical parents.
173 pub(crate) fn fallible_semantic_parent(&self) -> Option<Cursor> {
174 let sp = unsafe {
175 Cursor {
176 x: clang_getCursorSemanticParent(self.x),
177 }
178 };
179 if sp == *self || !sp.is_valid() {
180 return None;
181 }
182 Some(sp)
183 }
184
185 /// Get the referent's semantic parent.
186 ///
187 /// See documentation for `lexical_parent` for details on semantic vs
188 /// lexical parents.
189 pub(crate) fn semantic_parent(&self) -> Cursor {
190 self.fallible_semantic_parent().unwrap()
191 }
192
193 /// Return the number of template arguments used by this cursor's referent,
194 /// if the referent is either a template instantiation. Returns `None`
195 /// otherwise.
196 ///
197 /// NOTE: This may not return `Some` for partial template specializations,
198 /// see #193 and #194.
199 pub(crate) fn num_template_args(&self) -> Option<u32> {
200 // XXX: `clang_Type_getNumTemplateArguments` is sort of reliable, while
201 // `clang_Cursor_getNumTemplateArguments` is totally unreliable.
202 // Therefore, try former first, and only fallback to the latter if we
203 // have to.
204 self.cur_type()
205 .num_template_args()
206 .or_else(|| {
207 let n: c_int =
208 unsafe { clang_Cursor_getNumTemplateArguments(self.x) };
209
210 if n >= 0 {
211 Some(n as u32)
212 } else {
213 debug_assert_eq!(n, -1);
214 None
215 }
216 })
217 .or_else(|| {
218 let canonical = self.canonical();
219 if canonical == *self {
220 None
221 } else {
222 canonical.num_template_args()
223 }
224 })
225 }
226
227 /// Get a cursor pointing to this referent's containing translation unit.
228 ///
229 /// Note that we shouldn't create a `TranslationUnit` struct here, because
230 /// bindgen assumes there will only be one of them alive at a time, and
231 /// disposes it on drop. That can change if this would be required, but I
232 /// think we can survive fine without it.
233 pub(crate) fn translation_unit(&self) -> Cursor {
234 assert!(self.is_valid());
235 unsafe {
236 let tu = clang_Cursor_getTranslationUnit(self.x);
237 let cursor = Cursor {
238 x: clang_getTranslationUnitCursor(tu),
239 };
240 assert!(cursor.is_valid());
241 cursor
242 }
243 }
244
245 /// Is the referent a top level construct?
246 pub(crate) fn is_toplevel(&self) -> bool {
247 let mut semantic_parent = self.fallible_semantic_parent();
248
249 while semantic_parent.is_some() &&
250 (semantic_parent.unwrap().kind() == CXCursor_Namespace ||
251 semantic_parent.unwrap().kind() ==
252 CXCursor_NamespaceAlias ||
253 semantic_parent.unwrap().kind() == CXCursor_NamespaceRef)
254 {
255 semantic_parent =
256 semantic_parent.unwrap().fallible_semantic_parent();
257 }
258
259 let tu = self.translation_unit();
260 // Yes, this can happen with, e.g., macro definitions.
261 semantic_parent == tu.fallible_semantic_parent()
262 }
263
264 /// There are a few kinds of types that we need to treat specially, mainly
265 /// not tracking the type declaration but the location of the cursor, given
266 /// clang doesn't expose a proper declaration for these types.
267 pub(crate) fn is_template_like(&self) -> bool {
268 matches!(
269 self.kind(),
270 CXCursor_ClassTemplate |
271 CXCursor_ClassTemplatePartialSpecialization |
272 CXCursor_TypeAliasTemplateDecl
273 )
274 }
275
276 /// Is this Cursor pointing to a function-like macro definition?
277 pub(crate) fn is_macro_function_like(&self) -> bool {
278 unsafe { clang_Cursor_isMacroFunctionLike(self.x) != 0 }
279 }
280
281 /// Get the kind of referent this cursor is pointing to.
282 pub(crate) fn kind(&self) -> CXCursorKind {
283 self.x.kind
284 }
285
286 /// Returns true if the cursor is a definition
287 pub(crate) fn is_definition(&self) -> bool {
288 unsafe { clang_isCursorDefinition(self.x) != 0 }
289 }
290
291 /// Is the referent a template specialization?
292 pub(crate) fn is_template_specialization(&self) -> bool {
293 self.specialized().is_some()
294 }
295
296 /// Is the referent a fully specialized template specialization without any
297 /// remaining free template arguments?
298 pub(crate) fn is_fully_specialized_template(&self) -> bool {
299 self.is_template_specialization() &&
300 self.kind() != CXCursor_ClassTemplatePartialSpecialization &&
301 self.num_template_args().unwrap_or(0) > 0
302 }
303
304 /// Is the referent a template specialization that still has remaining free
305 /// template arguments?
306 pub(crate) fn is_in_non_fully_specialized_template(&self) -> bool {
307 if self.is_toplevel() {
308 return false;
309 }
310
311 let parent = self.semantic_parent();
312 if parent.is_fully_specialized_template() {
313 return false;
314 }
315
316 if !parent.is_template_like() {
317 return parent.is_in_non_fully_specialized_template();
318 }
319
320 true
321 }
322
323 /// Is the referent any kind of template parameter?
324 pub(crate) fn is_template_parameter(&self) -> bool {
325 matches!(
326 self.kind(),
327 CXCursor_TemplateTemplateParameter |
328 CXCursor_TemplateTypeParameter |
329 CXCursor_NonTypeTemplateParameter
330 )
331 }
332
333 /// Does the referent's type or value depend on a template parameter?
334 pub(crate) fn is_dependent_on_template_parameter(&self) -> bool {
335 fn visitor(
336 found_template_parameter: &mut bool,
337 cur: Cursor,
338 ) -> CXChildVisitResult {
339 // If we found a template parameter, it is dependent.
340 if cur.is_template_parameter() {
341 *found_template_parameter = true;
342 return CXChildVisit_Break;
343 }
344
345 // Get the referent and traverse it as well.
346 if let Some(referenced) = cur.referenced() {
347 if referenced.is_template_parameter() {
348 *found_template_parameter = true;
349 return CXChildVisit_Break;
350 }
351
352 referenced
353 .visit(|next| visitor(found_template_parameter, next));
354 if *found_template_parameter {
355 return CXChildVisit_Break;
356 }
357 }
358
359 // Continue traversing the AST at the original cursor.
360 CXChildVisit_Recurse
361 }
362
363 if self.is_template_parameter() {
364 return true;
365 }
366
367 let mut found_template_parameter = false;
368 self.visit(|next| visitor(&mut found_template_parameter, next));
369
370 found_template_parameter
371 }
372
373 /// Is this cursor pointing a valid referent?
374 pub(crate) fn is_valid(&self) -> bool {
375 unsafe { clang_isInvalid(self.kind()) == 0 }
376 }
377
378 /// Get the source location for the referent.
379 pub(crate) fn location(&self) -> SourceLocation {
380 unsafe {
381 SourceLocation {
382 x: clang_getCursorLocation(self.x),
383 }
384 }
385 }
386
387 /// Get the source location range for the referent.
388 pub(crate) fn extent(&self) -> CXSourceRange {
389 unsafe { clang_getCursorExtent(self.x) }
390 }
391
392 /// Get the raw declaration comment for this referent, if one exists.
393 pub(crate) fn raw_comment(&self) -> Option<String> {
394 let s = unsafe {
395 cxstring_into_string(clang_Cursor_getRawCommentText(self.x))
396 };
397 if s.is_empty() {
398 None
399 } else {
400 Some(s)
401 }
402 }
403
404 /// Get the referent's parsed comment.
405 pub(crate) fn comment(&self) -> Comment {
406 unsafe {
407 Comment {
408 x: clang_Cursor_getParsedComment(self.x),
409 }
410 }
411 }
412
413 /// Get the referent's type.
414 pub(crate) fn cur_type(&self) -> Type {
415 unsafe {
416 Type {
417 x: clang_getCursorType(self.x),
418 }
419 }
420 }
421
422 /// Given that this cursor's referent is a reference to another type, or is
423 /// a declaration, get the cursor pointing to the referenced type or type of
424 /// the declared thing.
425 pub(crate) fn definition(&self) -> Option<Cursor> {
426 unsafe {
427 let ret = Cursor {
428 x: clang_getCursorDefinition(self.x),
429 };
430
431 if ret.is_valid() && ret.kind() != CXCursor_NoDeclFound {
432 Some(ret)
433 } else {
434 None
435 }
436 }
437 }
438
439 /// Given that this cursor's referent is reference type, get the cursor
440 /// pointing to the referenced type.
441 pub(crate) fn referenced(&self) -> Option<Cursor> {
442 unsafe {
443 let ret = Cursor {
444 x: clang_getCursorReferenced(self.x),
445 };
446
447 if ret.is_valid() {
448 Some(ret)
449 } else {
450 None
451 }
452 }
453 }
454
455 /// Get the canonical cursor for this referent.
456 ///
457 /// Many types can be declared multiple times before finally being properly
458 /// defined. This method allows us to get the canonical cursor for the
459 /// referent type.
460 pub(crate) fn canonical(&self) -> Cursor {
461 unsafe {
462 Cursor {
463 x: clang_getCanonicalCursor(self.x),
464 }
465 }
466 }
467
468 /// Given that this cursor points to either a template specialization or a
469 /// template instantiation, get a cursor pointing to the template definition
470 /// that is being specialized.
471 pub(crate) fn specialized(&self) -> Option<Cursor> {
472 unsafe {
473 let ret = Cursor {
474 x: clang_getSpecializedCursorTemplate(self.x),
475 };
476 if ret.is_valid() {
477 Some(ret)
478 } else {
479 None
480 }
481 }
482 }
483
484 /// Assuming that this cursor's referent is a template declaration, get the
485 /// kind of cursor that would be generated for its specializations.
486 pub(crate) fn template_kind(&self) -> CXCursorKind {
487 unsafe { clang_getTemplateCursorKind(self.x) }
488 }
489
490 /// Traverse this cursor's referent and its children.
491 ///
492 /// Call the given function on each AST node traversed.
493 pub(crate) fn visit<Visitor>(&self, mut visitor: Visitor)
494 where
495 Visitor: FnMut(Cursor) -> CXChildVisitResult,
496 {
497 let data = &mut visitor as *mut Visitor;
498 unsafe {
499 clang_visitChildren(self.x, visit_children::<Visitor>, data.cast());
500 }
501 }
502
503 /// Traverse all of this cursor's children, sorted by where they appear in source code.
504 ///
505 /// Call the given function on each AST node traversed.
506 pub(crate) fn visit_sorted<Visitor>(
507 &self,
508 ctx: &mut BindgenContext,
509 mut visitor: Visitor,
510 ) where
511 Visitor: FnMut(&mut BindgenContext, Cursor),
512 {
513 // FIXME(#2556): The current source order stuff doesn't account well for different levels
514 // of includes, or includes that show up at the same byte offset because they are passed in
515 // via CLI.
516 const SOURCE_ORDER_ENABLED: bool = false;
517 if !SOURCE_ORDER_ENABLED {
518 return self.visit(|c| {
519 visitor(ctx, c);
520 CXChildVisit_Continue
521 });
522 }
523
524 let mut children = self.collect_children();
525 for child in &children {
526 if child.kind() == CXCursor_InclusionDirective {
527 if let Some(included_file) = child.get_included_file_name() {
528 let location = child.location();
529 let (source_file, _, _, offset) = location.location();
530
531 if let Some(source_file) = source_file.name() {
532 ctx.add_include(source_file, included_file, offset);
533 }
534 }
535 }
536 }
537 children
538 .sort_by(|child1, child2| child1.cmp_by_source_order(child2, ctx));
539 for child in children {
540 visitor(ctx, child);
541 }
542 }
543
544 /// Compare source order of two cursors, considering `#include` directives.
545 ///
546 /// Built-in items provided by the compiler (which don't have a source file),
547 /// are sorted first. Remaining files are sorted by their position in the source file.
548 /// If the items' source files differ, they are sorted by the position of the first
549 /// `#include` for their source file. If no source files are included, `None` is returned.
550 fn cmp_by_source_order(
551 &self,
552 other: &Self,
553 ctx: &BindgenContext,
554 ) -> cmp::Ordering {
555 let (file, _, _, offset) = self.location().location();
556 let (other_file, _, _, other_offset) = other.location().location();
557
558 let (file, other_file) = match (file.name(), other_file.name()) {
559 (Some(file), Some(other_file)) => (file, other_file),
560 // Built-in definitions should come first.
561 (Some(_), None) => return cmp::Ordering::Greater,
562 (None, Some(_)) => return cmp::Ordering::Less,
563 (None, None) => return cmp::Ordering::Equal,
564 };
565
566 if file == other_file {
567 // Both items are in the same source file, compare by byte offset.
568 return offset.cmp(&other_offset);
569 }
570
571 let include_location = ctx.included_file_location(&file);
572 let other_include_location = ctx.included_file_location(&other_file);
573 match (include_location, other_include_location) {
574 (Some((file2, offset2)), _) if file2 == other_file => {
575 offset2.cmp(&other_offset)
576 }
577 (Some(_), None) => cmp::Ordering::Greater,
578 (_, Some((other_file2, other_offset2))) if file == other_file2 => {
579 offset.cmp(&other_offset2)
580 }
581 (None, Some(_)) => cmp::Ordering::Less,
582 (Some((file2, offset2)), Some((other_file2, other_offset2))) => {
583 if file2 == other_file2 {
584 offset2.cmp(&other_offset2)
585 } else {
586 cmp::Ordering::Equal
587 }
588 }
589 (None, None) => cmp::Ordering::Equal,
590 }
591 }
592
593 /// Collect all of this cursor's children into a vec and return them.
594 pub(crate) fn collect_children(&self) -> Vec<Cursor> {
595 let mut children = vec![];
596 self.visit(|c| {
597 children.push(c);
598 CXChildVisit_Continue
599 });
600 children
601 }
602
603 /// Does this cursor have any children?
604 pub(crate) fn has_children(&self) -> bool {
605 let mut has_children = false;
606 self.visit(|_| {
607 has_children = true;
608 CXChildVisit_Break
609 });
610 has_children
611 }
612
613 /// Does this cursor have at least `n` children?
614 pub(crate) fn has_at_least_num_children(&self, n: usize) -> bool {
615 assert!(n > 0);
616 let mut num_left = n;
617 self.visit(|_| {
618 num_left -= 1;
619 if num_left == 0 {
620 CXChildVisit_Break
621 } else {
622 CXChildVisit_Continue
623 }
624 });
625 num_left == 0
626 }
627
628 /// Returns whether the given location contains a cursor with the given
629 /// kind in the first level of nesting underneath (doesn't look
630 /// recursively).
631 pub(crate) fn contains_cursor(&self, kind: CXCursorKind) -> bool {
632 let mut found = false;
633
634 self.visit(|c| {
635 if c.kind() == kind {
636 found = true;
637 CXChildVisit_Break
638 } else {
639 CXChildVisit_Continue
640 }
641 });
642
643 found
644 }
645
646 /// Is the referent an inlined function?
647 pub(crate) fn is_inlined_function(&self) -> bool {
648 unsafe { clang_Cursor_isFunctionInlined(self.x) != 0 }
649 }
650
651 /// Is the referent a defaulted function?
652 pub(crate) fn is_defaulted_function(&self) -> bool {
653 unsafe { clang_CXXMethod_isDefaulted(self.x) != 0 }
654 }
655
656 /// Is the referent a deleted function?
657 pub(crate) fn is_deleted_function(&self) -> bool {
658 // Unfortunately, libclang doesn't yet have an API for checking if a
659 // member function is deleted, but the following should be a good
660 // enough approximation.
661 // Deleted functions are implicitly inline according to paragraph 4 of
662 // [dcl.fct.def.delete] in the C++ standard. Normal inline functions
663 // have a definition in the same translation unit, so if this is an
664 // inline function without a definition, and it's not a defaulted
665 // function, we can reasonably safely conclude that it's a deleted
666 // function.
667 self.is_inlined_function() &&
668 self.definition().is_none() &&
669 !self.is_defaulted_function()
670 }
671
672 /// Is the referent a bit field declaration?
673 pub(crate) fn is_bit_field(&self) -> bool {
674 unsafe { clang_Cursor_isBitField(self.x) != 0 }
675 }
676
677 /// Get a cursor to the bit field's width expression, or `None` if it's not
678 /// a bit field.
679 pub(crate) fn bit_width_expr(&self) -> Option<Cursor> {
680 if !self.is_bit_field() {
681 return None;
682 }
683
684 let mut result = None;
685 self.visit(|cur| {
686 // The first child may or may not be a TypeRef, depending on whether
687 // the field's type is builtin. Skip it.
688 if cur.kind() == CXCursor_TypeRef {
689 return CXChildVisit_Continue;
690 }
691
692 // The next expression or literal is the bit width.
693 result = Some(cur);
694
695 CXChildVisit_Break
696 });
697
698 result
699 }
700
701 /// Get the width of this cursor's referent bit field, or `None` if the
702 /// referent is not a bit field or if the width could not be evaluated.
703 pub(crate) fn bit_width(&self) -> Option<u32> {
704 // It is not safe to check the bit width without ensuring it doesn't
705 // depend on a template parameter. See
706 // https://github.com/rust-lang/rust-bindgen/issues/2239
707 if self.bit_width_expr()?.is_dependent_on_template_parameter() {
708 return None;
709 }
710
711 unsafe {
712 let w = clang_getFieldDeclBitWidth(self.x);
713 if w == -1 {
714 None
715 } else {
716 Some(w as u32)
717 }
718 }
719 }
720
721 /// Get the integer representation type used to hold this cursor's referent
722 /// enum type.
723 pub(crate) fn enum_type(&self) -> Option<Type> {
724 unsafe {
725 let t = Type {
726 x: clang_getEnumDeclIntegerType(self.x),
727 };
728 if t.is_valid() {
729 Some(t)
730 } else {
731 None
732 }
733 }
734 }
735
736 /// Get the boolean constant value for this cursor's enum variant referent.
737 ///
738 /// Returns None if the cursor's referent is not an enum variant.
739 pub(crate) fn enum_val_boolean(&self) -> Option<bool> {
740 unsafe {
741 if self.kind() == CXCursor_EnumConstantDecl {
742 Some(clang_getEnumConstantDeclValue(self.x) != 0)
743 } else {
744 None
745 }
746 }
747 }
748
749 /// Get the signed constant value for this cursor's enum variant referent.
750 ///
751 /// Returns None if the cursor's referent is not an enum variant.
752 pub(crate) fn enum_val_signed(&self) -> Option<i64> {
753 unsafe {
754 if self.kind() == CXCursor_EnumConstantDecl {
755 #[allow(clippy::unnecessary_cast)]
756 Some(clang_getEnumConstantDeclValue(self.x) as i64)
757 } else {
758 None
759 }
760 }
761 }
762
763 /// Get the unsigned constant value for this cursor's enum variant referent.
764 ///
765 /// Returns None if the cursor's referent is not an enum variant.
766 pub(crate) fn enum_val_unsigned(&self) -> Option<u64> {
767 unsafe {
768 if self.kind() == CXCursor_EnumConstantDecl {
769 #[allow(clippy::unnecessary_cast)]
770 Some(clang_getEnumConstantDeclUnsignedValue(self.x) as u64)
771 } else {
772 None
773 }
774 }
775 }
776
777 /// Does this cursor have the given attributes?
778 pub(crate) fn has_attrs<const N: usize>(
779 &self,
780 attrs: &[Attribute; N],
781 ) -> [bool; N] {
782 let mut found_attrs = [false; N];
783 let mut found_count = 0;
784
785 self.visit(|cur| {
786 let kind = cur.kind();
787 for (idx, attr) in attrs.iter().enumerate() {
788 let found_attr = &mut found_attrs[idx];
789 if !*found_attr {
790 // `attr.name` and` attr.token_kind` are checked against unexposed attributes only.
791 if attr.kind == Some(kind) ||
792 (kind == CXCursor_UnexposedAttr &&
793 cur.tokens().iter().any(|t| {
794 t.kind == attr.token_kind &&
795 t.spelling() == attr.name
796 }))
797 {
798 *found_attr = true;
799 found_count += 1;
800
801 if found_count == N {
802 return CXChildVisit_Break;
803 }
804 }
805 }
806 }
807
808 CXChildVisit_Continue
809 });
810
811 found_attrs
812 }
813
814 /// Given that this cursor's referent is a `typedef`, get the `Type` that is
815 /// being aliased.
816 pub(crate) fn typedef_type(&self) -> Option<Type> {
817 let inner = Type {
818 x: unsafe { clang_getTypedefDeclUnderlyingType(self.x) },
819 };
820
821 if inner.is_valid() {
822 Some(inner)
823 } else {
824 None
825 }
826 }
827
828 /// Get the linkage kind for this cursor's referent.
829 ///
830 /// This only applies to functions and variables.
831 pub(crate) fn linkage(&self) -> CXLinkageKind {
832 unsafe { clang_getCursorLinkage(self.x) }
833 }
834
835 /// Get the visibility of this cursor's referent.
836 pub(crate) fn visibility(&self) -> CXVisibilityKind {
837 unsafe { clang_getCursorVisibility(self.x) }
838 }
839
840 /// Given that this cursor's referent is a function, return cursors to its
841 /// parameters.
842 ///
843 /// Returns None if the cursor's referent is not a function/method call or
844 /// declaration.
845 pub(crate) fn args(&self) -> Option<Vec<Cursor>> {
846 // match self.kind() {
847 // CXCursor_FunctionDecl |
848 // CXCursor_CXXMethod => {
849 self.num_args().ok().map(|num| {
850 (0..num)
851 .map(|i| Cursor {
852 x: unsafe { clang_Cursor_getArgument(self.x, i as c_uint) },
853 })
854 .collect()
855 })
856 }
857
858 /// Given that this cursor's referent is a function/method call or
859 /// declaration, return the number of arguments it takes.
860 ///
861 /// Returns Err if the cursor's referent is not a function/method call or
862 /// declaration.
863 pub(crate) fn num_args(&self) -> Result<u32, ()> {
864 unsafe {
865 let w = clang_Cursor_getNumArguments(self.x);
866 if w == -1 {
867 Err(())
868 } else {
869 Ok(w as u32)
870 }
871 }
872 }
873
874 /// Get the access specifier for this cursor's referent.
875 pub(crate) fn access_specifier(&self) -> CX_CXXAccessSpecifier {
876 unsafe { clang_getCXXAccessSpecifier(self.x) }
877 }
878
879 /// Is the cursor's referent publicly accessible in C++?
880 ///
881 /// Returns true if `self.access_specifier()` is `CX_CXXPublic` or
882 /// `CX_CXXInvalidAccessSpecifier`.
883 pub(crate) fn public_accessible(&self) -> bool {
884 let access = self.access_specifier();
885 access == CX_CXXPublic || access == CX_CXXInvalidAccessSpecifier
886 }
887
888 /// Is this cursor's referent a field declaration that is marked as
889 /// `mutable`?
890 pub(crate) fn is_mutable_field(&self) -> bool {
891 unsafe { clang_CXXField_isMutable(self.x) != 0 }
892 }
893
894 /// Get the offset of the field represented by the Cursor.
895 pub(crate) fn offset_of_field(&self) -> Result<usize, LayoutError> {
896 let offset = unsafe { clang_Cursor_getOffsetOfField(self.x) };
897
898 if offset < 0 {
899 Err(LayoutError::from(offset as i32))
900 } else {
901 Ok(offset as usize)
902 }
903 }
904
905 /// Is this cursor's referent a member function that is declared `static`?
906 pub(crate) fn method_is_static(&self) -> bool {
907 unsafe { clang_CXXMethod_isStatic(self.x) != 0 }
908 }
909
910 /// Is this cursor's referent a member function that is declared `const`?
911 pub(crate) fn method_is_const(&self) -> bool {
912 unsafe { clang_CXXMethod_isConst(self.x) != 0 }
913 }
914
915 /// Is this cursor's referent a member function that is virtual?
916 pub(crate) fn method_is_virtual(&self) -> bool {
917 unsafe { clang_CXXMethod_isVirtual(self.x) != 0 }
918 }
919
920 /// Is this cursor's referent a member function that is pure virtual?
921 pub(crate) fn method_is_pure_virtual(&self) -> bool {
922 unsafe { clang_CXXMethod_isPureVirtual(self.x) != 0 }
923 }
924
925 /// Is this cursor's referent a struct or class with virtual members?
926 pub(crate) fn is_virtual_base(&self) -> bool {
927 unsafe { clang_isVirtualBase(self.x) != 0 }
928 }
929
930 /// Try to evaluate this cursor.
931 pub(crate) fn evaluate(&self) -> Option<EvalResult> {
932 EvalResult::new(*self)
933 }
934
935 /// Return the result type for this cursor
936 pub(crate) fn ret_type(&self) -> Option<Type> {
937 let rt = Type {
938 x: unsafe { clang_getCursorResultType(self.x) },
939 };
940 if rt.is_valid() {
941 Some(rt)
942 } else {
943 None
944 }
945 }
946
947 /// Gets the tokens that correspond to that cursor.
948 pub(crate) fn tokens(&self) -> RawTokens {
949 RawTokens::new(self)
950 }
951
952 /// Gets the tokens that correspond to that cursor as `cexpr` tokens.
953 pub(crate) fn cexpr_tokens(self) -> Vec<cexpr::token::Token> {
954 self.tokens()
955 .iter()
956 .filter_map(|token| token.as_cexpr_token())
957 .collect()
958 }
959
960 /// Obtain the real path name of a cursor of `InclusionDirective` kind.
961 ///
962 /// Returns None if the cursor does not include a file, otherwise the file's full name
963 pub(crate) fn get_included_file_name(&self) -> Option<String> {
964 let file = unsafe { clang_getIncludedFile(self.x) };
965 if file.is_null() {
966 None
967 } else {
968 Some(unsafe { cxstring_into_string(clang_getFileName(file)) })
969 }
970 }
971
972 /// Is this cursor's referent a namespace that is inline?
973 pub(crate) fn is_inline_namespace(&self) -> bool {
974 unsafe { clang_Cursor_isInlineNamespace(self.x) != 0 }
975 }
976}
977
978/// A struct that owns the tokenizer result from a given cursor.
979pub(crate) struct RawTokens<'a> {
980 cursor: &'a Cursor,
981 tu: CXTranslationUnit,
982 tokens: *mut CXToken,
983 token_count: c_uint,
984}
985
986impl<'a> RawTokens<'a> {
987 fn new(cursor: &'a Cursor) -> Self {
988 let mut tokens = ptr::null_mut();
989 let mut token_count = 0;
990 let range = cursor.extent();
991 let tu = unsafe { clang_Cursor_getTranslationUnit(cursor.x) };
992 unsafe { clang_tokenize(tu, range, &mut tokens, &mut token_count) };
993 Self {
994 cursor,
995 tu,
996 tokens,
997 token_count,
998 }
999 }
1000
1001 fn as_slice(&self) -> &[CXToken] {
1002 if self.tokens.is_null() {
1003 return &[];
1004 }
1005 unsafe { slice::from_raw_parts(self.tokens, self.token_count as usize) }
1006 }
1007
1008 /// Get an iterator over these tokens.
1009 pub(crate) fn iter(&self) -> ClangTokenIterator {
1010 ClangTokenIterator {
1011 tu: self.tu,
1012 raw: self.as_slice().iter(),
1013 }
1014 }
1015}
1016
1017impl Drop for RawTokens<'_> {
1018 fn drop(&mut self) {
1019 if !self.tokens.is_null() {
1020 unsafe {
1021 clang_disposeTokens(
1022 self.tu,
1023 self.tokens,
1024 self.token_count as c_uint,
1025 );
1026 }
1027 }
1028 }
1029}
1030
1031/// A raw clang token, that exposes only kind, spelling, and extent. This is a
1032/// slightly more convenient version of `CXToken` which owns the spelling
1033/// string and extent.
1034#[derive(Debug)]
1035pub(crate) struct ClangToken {
1036 spelling: CXString,
1037 /// The extent of the token. This is the same as the relevant member from
1038 /// `CXToken`.
1039 pub(crate) extent: CXSourceRange,
1040 /// The kind of the token. This is the same as the relevant member from
1041 /// `CXToken`.
1042 pub(crate) kind: CXTokenKind,
1043}
1044
1045impl ClangToken {
1046 /// Get the token spelling, without being converted to utf-8.
1047 pub(crate) fn spelling(&self) -> &[u8] {
1048 let c_str = unsafe {
1049 CStr::from_ptr(clang_getCString(self.spelling) as *const _)
1050 };
1051 c_str.to_bytes()
1052 }
1053
1054 /// Converts a `ClangToken` to a `cexpr` token if possible.
1055 pub(crate) fn as_cexpr_token(&self) -> Option<cexpr::token::Token> {
1056 use cexpr::token;
1057
1058 let kind = match self.kind {
1059 CXToken_Punctuation => token::Kind::Punctuation,
1060 CXToken_Literal => token::Kind::Literal,
1061 CXToken_Identifier => token::Kind::Identifier,
1062 CXToken_Keyword => token::Kind::Keyword,
1063 // NB: cexpr is not too happy about comments inside
1064 // expressions, so we strip them down here.
1065 CXToken_Comment => return None,
1066 _ => {
1067 warn!("Found unexpected token kind: {self:?}");
1068 return None;
1069 }
1070 };
1071
1072 Some(token::Token {
1073 kind,
1074 raw: self.spelling().to_vec().into_boxed_slice(),
1075 })
1076 }
1077}
1078
1079impl Drop for ClangToken {
1080 fn drop(&mut self) {
1081 unsafe { clang_disposeString(self.spelling) }
1082 }
1083}
1084
1085/// An iterator over a set of Tokens.
1086pub(crate) struct ClangTokenIterator<'a> {
1087 tu: CXTranslationUnit,
1088 raw: slice::Iter<'a, CXToken>,
1089}
1090
1091impl Iterator for ClangTokenIterator<'_> {
1092 type Item = ClangToken;
1093
1094 fn next(&mut self) -> Option<Self::Item> {
1095 let raw: &CXToken = self.raw.next()?;
1096 unsafe {
1097 let kind: i32 = clang_getTokenKind(*raw);
1098 let spelling: CXString = clang_getTokenSpelling(self.tu, *raw);
1099 let extent: CXSourceRange = clang_getTokenExtent(self.tu, *raw);
1100 Some(ClangToken {
1101 kind,
1102 extent,
1103 spelling,
1104 })
1105 }
1106 }
1107}
1108
1109/// Checks whether the name looks like an identifier, i.e. is alphanumeric
1110/// (including '_') and does not start with a digit.
1111pub(crate) fn is_valid_identifier(name: &str) -> bool {
1112 let mut chars: Chars<'_> = name.chars();
1113 let first_valid: bool =
1114 chars.next().is_some_and(|c: char| c.is_alphabetic() || c == '_');
1115
1116 first_valid && chars.all(|c: char| c.is_alphanumeric() || c == '_')
1117}
1118
1119extern "C" fn visit_children<Visitor>(
1120 cur: CXCursor,
1121 _parent: CXCursor,
1122 data: CXClientData,
1123) -> CXChildVisitResult
1124where
1125 Visitor: FnMut(Cursor) -> CXChildVisitResult,
1126{
1127 let func: &mut Visitor = unsafe { &mut *(data as *mut Visitor) };
1128 let child: Cursor = Cursor { x: cur };
1129
1130 (*func)(child)
1131}
1132
1133impl PartialEq for Cursor {
1134 fn eq(&self, other: &Cursor) -> bool {
1135 unsafe { clang_equalCursors(self.x, right:other.x) == 1 }
1136 }
1137}
1138
1139impl Eq for Cursor {}
1140
1141impl Hash for Cursor {
1142 fn hash<H: Hasher>(&self, state: &mut H) {
1143 unsafe { clang_hashCursor(self.x) }.hash(state);
1144 }
1145}
1146
1147/// The type of a node in clang's AST.
1148#[derive(Clone, Copy)]
1149pub(crate) struct Type {
1150 x: CXType,
1151}
1152
1153impl PartialEq for Type {
1154 fn eq(&self, other: &Self) -> bool {
1155 unsafe { clang_equalTypes(self.x, right:other.x) != 0 }
1156 }
1157}
1158
1159impl Eq for Type {}
1160
1161impl fmt::Debug for Type {
1162 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1163 write!(
1164 fmt,
1165 "Type({}, kind: {}, cconv: {}, decl: {:?}, canon: {:?})",
1166 self.spelling(),
1167 type_to_str(self.kind()),
1168 self.call_conv(),
1169 self.declaration(),
1170 self.declaration().canonical()
1171 )
1172 }
1173}
1174
1175/// An error about the layout of a struct, class, or type.
1176#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
1177pub(crate) enum LayoutError {
1178 /// Asked for the layout of an invalid type.
1179 Invalid,
1180 /// Asked for the layout of an incomplete type.
1181 Incomplete,
1182 /// Asked for the layout of a dependent type.
1183 Dependent,
1184 /// Asked for the layout of a type that does not have constant size.
1185 NotConstantSize,
1186 /// Asked for the layout of a field in a type that does not have such a
1187 /// field.
1188 InvalidFieldName,
1189 /// An unknown layout error.
1190 Unknown,
1191}
1192
1193impl ::std::convert::From<i32> for LayoutError {
1194 fn from(val: i32) -> Self {
1195 use self::LayoutError::*;
1196
1197 match val {
1198 CXTypeLayoutError_Invalid => Invalid,
1199 CXTypeLayoutError_Incomplete => Incomplete,
1200 CXTypeLayoutError_Dependent => Dependent,
1201 CXTypeLayoutError_NotConstantSize => NotConstantSize,
1202 CXTypeLayoutError_InvalidFieldName => InvalidFieldName,
1203 _ => Unknown,
1204 }
1205 }
1206}
1207
1208impl Type {
1209 /// Get this type's kind.
1210 pub(crate) fn kind(&self) -> CXTypeKind {
1211 self.x.kind
1212 }
1213
1214 /// Get a cursor pointing to this type's declaration.
1215 pub(crate) fn declaration(&self) -> Cursor {
1216 unsafe {
1217 Cursor {
1218 x: clang_getTypeDeclaration(self.x),
1219 }
1220 }
1221 }
1222
1223 /// Get the canonical declaration of this type, if it is available.
1224 pub(crate) fn canonical_declaration(
1225 &self,
1226 location: Option<&Cursor>,
1227 ) -> Option<CanonicalTypeDeclaration> {
1228 let mut declaration = self.declaration();
1229 if !declaration.is_valid() {
1230 if let Some(location) = location {
1231 let mut location = *location;
1232 if let Some(referenced) = location.referenced() {
1233 location = referenced;
1234 }
1235 if location.is_template_like() {
1236 declaration = location;
1237 }
1238 }
1239 }
1240
1241 let canonical = declaration.canonical();
1242 if canonical.is_valid() && canonical.kind() != CXCursor_NoDeclFound {
1243 Some(CanonicalTypeDeclaration(*self, canonical))
1244 } else {
1245 None
1246 }
1247 }
1248
1249 /// Get a raw display name for this type.
1250 pub(crate) fn spelling(&self) -> String {
1251 let s = unsafe { cxstring_into_string(clang_getTypeSpelling(self.x)) };
1252 // Clang 5.0 introduced changes in the spelling API so it returned the
1253 // full qualified name. Let's undo that here.
1254 if s.split("::").all(is_valid_identifier) {
1255 if let Some(s) = s.split("::").last() {
1256 return s.to_owned();
1257 }
1258 }
1259
1260 s
1261 }
1262
1263 /// Is this type const qualified?
1264 pub(crate) fn is_const(&self) -> bool {
1265 unsafe { clang_isConstQualifiedType(self.x) != 0 }
1266 }
1267
1268 #[inline]
1269 fn is_non_deductible_auto_type(&self) -> bool {
1270 debug_assert_eq!(self.kind(), CXType_Auto);
1271 self.canonical_type() == *self
1272 }
1273
1274 #[inline]
1275 fn clang_size_of(&self, ctx: &BindgenContext) -> c_longlong {
1276 match self.kind() {
1277 // Work-around https://bugs.llvm.org/show_bug.cgi?id=40975
1278 CXType_RValueReference | CXType_LValueReference => {
1279 ctx.target_pointer_size() as c_longlong
1280 }
1281 // Work-around https://bugs.llvm.org/show_bug.cgi?id=40813
1282 CXType_Auto if self.is_non_deductible_auto_type() => -6,
1283 _ => unsafe { clang_Type_getSizeOf(self.x) },
1284 }
1285 }
1286
1287 #[inline]
1288 fn clang_align_of(&self, ctx: &BindgenContext) -> c_longlong {
1289 match self.kind() {
1290 // Work-around https://bugs.llvm.org/show_bug.cgi?id=40975
1291 CXType_RValueReference | CXType_LValueReference => {
1292 ctx.target_pointer_size() as c_longlong
1293 }
1294 // Work-around https://bugs.llvm.org/show_bug.cgi?id=40813
1295 CXType_Auto if self.is_non_deductible_auto_type() => -6,
1296 _ => unsafe { clang_Type_getAlignOf(self.x) },
1297 }
1298 }
1299
1300 /// What is the size of this type? Paper over invalid types by returning `0`
1301 /// for them.
1302 pub(crate) fn size(&self, ctx: &BindgenContext) -> usize {
1303 let val = self.clang_size_of(ctx);
1304 if val < 0 {
1305 0
1306 } else {
1307 val as usize
1308 }
1309 }
1310
1311 /// What is the size of this type?
1312 pub(crate) fn fallible_size(
1313 &self,
1314 ctx: &BindgenContext,
1315 ) -> Result<usize, LayoutError> {
1316 let val = self.clang_size_of(ctx);
1317 if val < 0 {
1318 Err(LayoutError::from(val as i32))
1319 } else {
1320 Ok(val as usize)
1321 }
1322 }
1323
1324 /// What is the alignment of this type? Paper over invalid types by
1325 /// returning `0`.
1326 pub(crate) fn align(&self, ctx: &BindgenContext) -> usize {
1327 let val = self.clang_align_of(ctx);
1328 if val < 0 {
1329 0
1330 } else {
1331 val as usize
1332 }
1333 }
1334
1335 /// What is the alignment of this type?
1336 pub(crate) fn fallible_align(
1337 &self,
1338 ctx: &BindgenContext,
1339 ) -> Result<usize, LayoutError> {
1340 let val = self.clang_align_of(ctx);
1341 if val < 0 {
1342 Err(LayoutError::from(val as i32))
1343 } else {
1344 Ok(val as usize)
1345 }
1346 }
1347
1348 /// Get the layout for this type, or an error describing why it does not
1349 /// have a valid layout.
1350 pub(crate) fn fallible_layout(
1351 &self,
1352 ctx: &BindgenContext,
1353 ) -> Result<crate::ir::layout::Layout, LayoutError> {
1354 use crate::ir::layout::Layout;
1355 let size = self.fallible_size(ctx)?;
1356 let align = self.fallible_align(ctx)?;
1357 Ok(Layout::new(size, align))
1358 }
1359
1360 /// Get the number of template arguments this type has, or `None` if it is
1361 /// not some kind of template.
1362 pub(crate) fn num_template_args(&self) -> Option<u32> {
1363 let n = unsafe { clang_Type_getNumTemplateArguments(self.x) };
1364 if n >= 0 {
1365 Some(n as u32)
1366 } else {
1367 debug_assert_eq!(n, -1);
1368 None
1369 }
1370 }
1371
1372 /// If this type is a class template specialization, return its
1373 /// template arguments. Otherwise, return None.
1374 pub(crate) fn template_args(&self) -> Option<TypeTemplateArgIterator> {
1375 self.num_template_args().map(|n| TypeTemplateArgIterator {
1376 x: self.x,
1377 length: n,
1378 index: 0,
1379 })
1380 }
1381
1382 /// Given that this type is a function prototype, return the types of its parameters.
1383 ///
1384 /// Returns None if the type is not a function prototype.
1385 pub(crate) fn args(&self) -> Option<Vec<Type>> {
1386 self.num_args().ok().map(|num| {
1387 (0..num)
1388 .map(|i| Type {
1389 x: unsafe { clang_getArgType(self.x, i as c_uint) },
1390 })
1391 .collect()
1392 })
1393 }
1394
1395 /// Given that this type is a function prototype, return the number of arguments it takes.
1396 ///
1397 /// Returns Err if the type is not a function prototype.
1398 pub(crate) fn num_args(&self) -> Result<u32, ()> {
1399 unsafe {
1400 let w = clang_getNumArgTypes(self.x);
1401 if w == -1 {
1402 Err(())
1403 } else {
1404 Ok(w as u32)
1405 }
1406 }
1407 }
1408
1409 /// Given that this type is a pointer type, return the type that it points
1410 /// to.
1411 pub(crate) fn pointee_type(&self) -> Option<Type> {
1412 match self.kind() {
1413 CXType_Pointer |
1414 CXType_RValueReference |
1415 CXType_LValueReference |
1416 CXType_MemberPointer |
1417 CXType_BlockPointer |
1418 CXType_ObjCObjectPointer => {
1419 let ret = Type {
1420 x: unsafe { clang_getPointeeType(self.x) },
1421 };
1422 debug_assert!(ret.is_valid());
1423 Some(ret)
1424 }
1425 _ => None,
1426 }
1427 }
1428
1429 /// Given that this type is an array, vector, or complex type, return the
1430 /// type of its elements.
1431 pub(crate) fn elem_type(&self) -> Option<Type> {
1432 let current_type = Type {
1433 x: unsafe { clang_getElementType(self.x) },
1434 };
1435 if current_type.is_valid() {
1436 Some(current_type)
1437 } else {
1438 None
1439 }
1440 }
1441
1442 /// Given that this type is an array or vector type, return its number of
1443 /// elements.
1444 pub(crate) fn num_elements(&self) -> Option<usize> {
1445 let num_elements_returned = unsafe { clang_getNumElements(self.x) };
1446 if num_elements_returned == -1 {
1447 None
1448 } else {
1449 Some(num_elements_returned as usize)
1450 }
1451 }
1452
1453 /// Get the canonical version of this type. This sees through `typedef`s and
1454 /// aliases to get the underlying, canonical type.
1455 pub(crate) fn canonical_type(&self) -> Type {
1456 unsafe {
1457 Type {
1458 x: clang_getCanonicalType(self.x),
1459 }
1460 }
1461 }
1462
1463 /// Is this type a variadic function type?
1464 pub(crate) fn is_variadic(&self) -> bool {
1465 unsafe { clang_isFunctionTypeVariadic(self.x) != 0 }
1466 }
1467
1468 /// Given that this type is a function type, get the type of its return
1469 /// value.
1470 pub(crate) fn ret_type(&self) -> Option<Type> {
1471 let rt = Type {
1472 x: unsafe { clang_getResultType(self.x) },
1473 };
1474 if rt.is_valid() {
1475 Some(rt)
1476 } else {
1477 None
1478 }
1479 }
1480
1481 /// Given that this type is a function type, get its calling convention. If
1482 /// this is not a function type, `CXCallingConv_Invalid` is returned.
1483 pub(crate) fn call_conv(&self) -> CXCallingConv {
1484 unsafe { clang_getFunctionTypeCallingConv(self.x) }
1485 }
1486
1487 /// For elaborated types (types which use `class`, `struct`, or `union` to
1488 /// disambiguate types from local bindings), get the underlying type.
1489 pub(crate) fn named(&self) -> Type {
1490 unsafe {
1491 Type {
1492 x: clang_Type_getNamedType(self.x),
1493 }
1494 }
1495 }
1496
1497 /// For atomic types, get the underlying type.
1498 pub(crate) fn atomic_value_type(&self) -> Type {
1499 unsafe {
1500 Type {
1501 x: clang_Type_getValueType(self.x),
1502 }
1503 }
1504 }
1505
1506 /// Is this a valid type?
1507 pub(crate) fn is_valid(&self) -> bool {
1508 self.kind() != CXType_Invalid
1509 }
1510
1511 /// Is this a valid and exposed type?
1512 pub(crate) fn is_valid_and_exposed(&self) -> bool {
1513 self.is_valid() && self.kind() != CXType_Unexposed
1514 }
1515
1516 /// Is this type a fully instantiated template?
1517 pub(crate) fn is_fully_instantiated_template(&self) -> bool {
1518 // Yep, the spelling of this containing type-parameter is extremely
1519 // nasty... But can happen in <type_traits>. Unfortunately I couldn't
1520 // reduce it enough :(
1521 self.template_args().is_some_and(|args| args.len() > 0) &&
1522 !matches!(
1523 self.declaration().kind(),
1524 CXCursor_ClassTemplatePartialSpecialization |
1525 CXCursor_TypeAliasTemplateDecl |
1526 CXCursor_TemplateTemplateParameter
1527 )
1528 }
1529
1530 /// Is this type an associated template type? Eg `T::Associated` in
1531 /// this example:
1532 ///
1533 /// ```c++
1534 /// template <typename T>
1535 /// class Foo {
1536 /// typename T::Associated member;
1537 /// };
1538 /// ```
1539 pub(crate) fn is_associated_type(&self) -> bool {
1540 // This is terrible :(
1541 fn hacky_parse_associated_type<S: AsRef<str>>(spelling: S) -> bool {
1542 static ASSOC_TYPE_RE: OnceLock<regex::Regex> = OnceLock::new();
1543 ASSOC_TYPE_RE
1544 .get_or_init(|| {
1545 regex::Regex::new(r"typename type\-parameter\-\d+\-\d+::.+")
1546 .unwrap()
1547 })
1548 .is_match(spelling.as_ref())
1549 }
1550
1551 self.kind() == CXType_Unexposed &&
1552 (hacky_parse_associated_type(self.spelling()) ||
1553 hacky_parse_associated_type(
1554 self.canonical_type().spelling(),
1555 ))
1556 }
1557}
1558
1559/// The `CanonicalTypeDeclaration` type exists as proof-by-construction that its
1560/// cursor is the canonical declaration for its type. If you have a
1561/// `CanonicalTypeDeclaration` instance, you know for sure that the type and
1562/// cursor match up in a canonical declaration relationship, and it simply
1563/// cannot be otherwise.
1564#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1565pub(crate) struct CanonicalTypeDeclaration(Type, Cursor);
1566
1567impl CanonicalTypeDeclaration {
1568 /// Get the type.
1569 pub(crate) fn ty(&self) -> &Type {
1570 &self.0
1571 }
1572
1573 /// Get the type's canonical declaration cursor.
1574 pub(crate) fn cursor(&self) -> &Cursor {
1575 &self.1
1576 }
1577}
1578
1579/// An iterator for a type's template arguments.
1580pub(crate) struct TypeTemplateArgIterator {
1581 x: CXType,
1582 length: u32,
1583 index: u32,
1584}
1585
1586impl Iterator for TypeTemplateArgIterator {
1587 type Item = Type;
1588 fn next(&mut self) -> Option<Type> {
1589 if self.index < self.length {
1590 let idx: u32 = self.index as c_uint;
1591 self.index += 1;
1592 Some(Type {
1593 x: unsafe { clang_Type_getTemplateArgumentAsType(self.x, index:idx) },
1594 })
1595 } else {
1596 None
1597 }
1598 }
1599}
1600
1601impl ExactSizeIterator for TypeTemplateArgIterator {
1602 fn len(&self) -> usize {
1603 assert!(self.index <= self.length);
1604 (self.length - self.index) as usize
1605 }
1606}
1607
1608/// A `SourceLocation` is a file, line, column, and byte offset location for
1609/// some source text.
1610pub(crate) struct SourceLocation {
1611 x: CXSourceLocation,
1612}
1613
1614impl SourceLocation {
1615 /// Get the (file, line, column, byte offset) tuple for this source
1616 /// location.
1617 pub(crate) fn location(&self) -> (File, usize, usize, usize) {
1618 unsafe {
1619 let mut file: *mut c_void = mem::zeroed();
1620 let mut line: u32 = 0;
1621 let mut col: u32 = 0;
1622 let mut off: u32 = 0;
1623 clang_getFileLocation(
1624 self.x, &mut file, &mut line, &mut col, &mut off,
1625 );
1626 (File { x: file }, line as usize, col as usize, off as usize)
1627 }
1628 }
1629}
1630
1631impl fmt::Display for SourceLocation {
1632 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1633 let (file: File, line: usize, col: usize, _) = self.location();
1634 if let Some(name: String) = file.name() {
1635 write!(f, "{name}:{line}:{col}")
1636 } else {
1637 "builtin definitions".fmt(f)
1638 }
1639 }
1640}
1641
1642impl fmt::Debug for SourceLocation {
1643 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1644 write!(f, "{self}")
1645 }
1646}
1647
1648/// A comment in the source text.
1649///
1650/// Comments are sort of parsed by Clang, and have a tree structure.
1651pub(crate) struct Comment {
1652 x: CXComment,
1653}
1654
1655impl Comment {
1656 /// What kind of comment is this?
1657 pub(crate) fn kind(&self) -> CXCommentKind {
1658 unsafe { clang_Comment_getKind(self.x) }
1659 }
1660
1661 /// Get this comment's children comment
1662 pub(crate) fn get_children(&self) -> CommentChildrenIterator {
1663 CommentChildrenIterator {
1664 parent: self.x,
1665 length: unsafe { clang_Comment_getNumChildren(self.x) },
1666 index: 0,
1667 }
1668 }
1669
1670 /// Given that this comment is the start or end of an HTML tag, get its tag
1671 /// name.
1672 pub(crate) fn get_tag_name(&self) -> String {
1673 unsafe { cxstring_into_string(clang_HTMLTagComment_getTagName(self.x)) }
1674 }
1675
1676 /// Given that this comment is an HTML start tag, get its attributes.
1677 pub(crate) fn get_tag_attrs(&self) -> CommentAttributesIterator {
1678 CommentAttributesIterator {
1679 x: self.x,
1680 length: unsafe { clang_HTMLStartTag_getNumAttrs(self.x) },
1681 index: 0,
1682 }
1683 }
1684}
1685
1686/// An iterator for a comment's children
1687pub(crate) struct CommentChildrenIterator {
1688 parent: CXComment,
1689 length: c_uint,
1690 index: c_uint,
1691}
1692
1693impl Iterator for CommentChildrenIterator {
1694 type Item = Comment;
1695 fn next(&mut self) -> Option<Comment> {
1696 if self.index < self.length {
1697 let idx: u32 = self.index;
1698 self.index += 1;
1699 Some(Comment {
1700 x: unsafe { clang_Comment_getChild(self.parent, index:idx) },
1701 })
1702 } else {
1703 None
1704 }
1705 }
1706}
1707
1708/// An HTML start tag comment attribute
1709pub(crate) struct CommentAttribute {
1710 /// HTML start tag attribute name
1711 pub(crate) name: String,
1712 /// HTML start tag attribute value
1713 pub(crate) value: String,
1714}
1715
1716/// An iterator for a comment's attributes
1717pub(crate) struct CommentAttributesIterator {
1718 x: CXComment,
1719 length: c_uint,
1720 index: c_uint,
1721}
1722
1723impl Iterator for CommentAttributesIterator {
1724 type Item = CommentAttribute;
1725 fn next(&mut self) -> Option<CommentAttribute> {
1726 if self.index < self.length {
1727 let idx: u32 = self.index;
1728 self.index += 1;
1729 Some(CommentAttribute {
1730 name: unsafe {
1731 cxstring_into_string(clang_HTMLStartTag_getAttrName(
1732 self.x, index:idx,
1733 ))
1734 },
1735 value: unsafe {
1736 cxstring_into_string(clang_HTMLStartTag_getAttrValue(
1737 self.x, index:idx,
1738 ))
1739 },
1740 })
1741 } else {
1742 None
1743 }
1744 }
1745}
1746
1747/// A source file.
1748pub(crate) struct File {
1749 x: CXFile,
1750}
1751
1752impl File {
1753 /// Get the name of this source file.
1754 pub(crate) fn name(&self) -> Option<String> {
1755 if self.x.is_null() {
1756 return None;
1757 }
1758 Some(unsafe { cxstring_into_string(clang_getFileName(self.x)) })
1759 }
1760}
1761
1762fn cxstring_to_string_leaky(s: CXString) -> String {
1763 if s.data.is_null() {
1764 return "".to_owned();
1765 }
1766 let c_str: &CStr = unsafe { CStr::from_ptr(clang_getCString(string:s) as *const _) };
1767 c_str.to_string_lossy().into_owned()
1768}
1769
1770fn cxstring_into_string(s: CXString) -> String {
1771 let ret: String = cxstring_to_string_leaky(s);
1772 unsafe { clang_disposeString(string:s) };
1773 ret
1774}
1775
1776/// An `Index` is an environment for a set of translation units that will
1777/// typically end up linked together in one final binary.
1778pub(crate) struct Index {
1779 x: CXIndex,
1780}
1781
1782impl Index {
1783 /// Construct a new `Index`.
1784 ///
1785 /// The `pch` parameter controls whether declarations in pre-compiled
1786 /// headers are included when enumerating a translation unit's "locals".
1787 ///
1788 /// The `diag` parameter controls whether debugging diagnostics are enabled.
1789 pub(crate) fn new(pch: bool, diag: bool) -> Index {
1790 unsafe {
1791 Index {
1792 x: clang_createIndex(exclude:c_int::from(pch), display:c_int::from(diag)),
1793 }
1794 }
1795 }
1796}
1797
1798impl fmt::Debug for Index {
1799 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1800 write!(fmt, "Index {{ }}")
1801 }
1802}
1803
1804impl Drop for Index {
1805 fn drop(&mut self) {
1806 unsafe {
1807 clang_disposeIndex(self.x);
1808 }
1809 }
1810}
1811
1812/// A translation unit (or "compilation unit").
1813pub(crate) struct TranslationUnit {
1814 x: CXTranslationUnit,
1815}
1816
1817impl fmt::Debug for TranslationUnit {
1818 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1819 write!(fmt, "TranslationUnit {{ }}")
1820 }
1821}
1822
1823impl TranslationUnit {
1824 /// Parse a source file into a translation unit.
1825 pub(crate) fn parse(
1826 ix: &Index,
1827 file: &str,
1828 cmd_args: &[Box<str>],
1829 unsaved: &[UnsavedFile],
1830 opts: CXTranslationUnit_Flags,
1831 ) -> Option<TranslationUnit> {
1832 let fname = CString::new(file).unwrap();
1833 let _c_args: Vec<CString> = cmd_args
1834 .iter()
1835 .map(|s| CString::new(s.as_bytes()).unwrap())
1836 .collect();
1837 let c_args: Vec<*const c_char> =
1838 _c_args.iter().map(|s| s.as_ptr()).collect();
1839 let mut c_unsaved: Vec<CXUnsavedFile> =
1840 unsaved.iter().map(|f| f.x).collect();
1841 let tu = unsafe {
1842 clang_parseTranslationUnit(
1843 ix.x,
1844 fname.as_ptr(),
1845 c_args.as_ptr(),
1846 c_args.len() as c_int,
1847 c_unsaved.as_mut_ptr(),
1848 c_unsaved.len() as c_uint,
1849 opts,
1850 )
1851 };
1852 if tu.is_null() {
1853 None
1854 } else {
1855 Some(TranslationUnit { x: tu })
1856 }
1857 }
1858
1859 /// Get the Clang diagnostic information associated with this translation
1860 /// unit.
1861 pub(crate) fn diags(&self) -> Vec<Diagnostic> {
1862 unsafe {
1863 let num = clang_getNumDiagnostics(self.x) as usize;
1864 let mut diags = vec![];
1865 for i in 0..num {
1866 diags.push(Diagnostic {
1867 x: clang_getDiagnostic(self.x, i as c_uint),
1868 });
1869 }
1870 diags
1871 }
1872 }
1873
1874 /// Get a cursor pointing to the root of this translation unit's AST.
1875 pub(crate) fn cursor(&self) -> Cursor {
1876 unsafe {
1877 Cursor {
1878 x: clang_getTranslationUnitCursor(self.x),
1879 }
1880 }
1881 }
1882
1883 /// Save a translation unit to the given file.
1884 pub(crate) fn save(&mut self, file: &str) -> Result<(), CXSaveError> {
1885 let Ok(file) = CString::new(file) else {
1886 return Err(CXSaveError_Unknown);
1887 };
1888 let ret = unsafe {
1889 clang_saveTranslationUnit(
1890 self.x,
1891 file.as_ptr(),
1892 clang_defaultSaveOptions(self.x),
1893 )
1894 };
1895 if ret != 0 {
1896 Err(ret)
1897 } else {
1898 Ok(())
1899 }
1900 }
1901
1902 /// Is this the null translation unit?
1903 pub(crate) fn is_null(&self) -> bool {
1904 self.x.is_null()
1905 }
1906}
1907
1908impl Drop for TranslationUnit {
1909 fn drop(&mut self) {
1910 unsafe {
1911 clang_disposeTranslationUnit(self.x);
1912 }
1913 }
1914}
1915
1916/// Translation unit used for macro fallback parsing
1917pub(crate) struct FallbackTranslationUnit {
1918 file_path: String,
1919 header_path: String,
1920 pch_path: String,
1921 idx: Box<Index>,
1922 tu: TranslationUnit,
1923}
1924
1925impl fmt::Debug for FallbackTranslationUnit {
1926 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1927 write!(fmt, "FallbackTranslationUnit {{ }}")
1928 }
1929}
1930
1931impl FallbackTranslationUnit {
1932 /// Create a new fallback translation unit
1933 pub(crate) fn new(
1934 file: String,
1935 header_path: String,
1936 pch_path: String,
1937 c_args: &[Box<str>],
1938 ) -> Option<Self> {
1939 // Create empty file
1940 OpenOptions::new()
1941 .write(true)
1942 .create(true)
1943 .truncate(true)
1944 .open(&file)
1945 .ok()?;
1946
1947 let f_index = Box::new(Index::new(true, false));
1948 let f_translation_unit = TranslationUnit::parse(
1949 &f_index,
1950 &file,
1951 c_args,
1952 &[],
1953 CXTranslationUnit_None,
1954 )?;
1955 Some(FallbackTranslationUnit {
1956 file_path: file,
1957 header_path,
1958 pch_path,
1959 tu: f_translation_unit,
1960 idx: f_index,
1961 })
1962 }
1963
1964 /// Get reference to underlying translation unit.
1965 pub(crate) fn translation_unit(&self) -> &TranslationUnit {
1966 &self.tu
1967 }
1968
1969 /// Reparse a translation unit.
1970 pub(crate) fn reparse(
1971 &mut self,
1972 unsaved_contents: &str,
1973 ) -> Result<(), CXErrorCode> {
1974 let unsaved = &[UnsavedFile::new(&self.file_path, unsaved_contents)];
1975 let mut c_unsaved: Vec<CXUnsavedFile> =
1976 unsaved.iter().map(|f| f.x).collect();
1977 let ret = unsafe {
1978 clang_reparseTranslationUnit(
1979 self.tu.x,
1980 unsaved.len() as c_uint,
1981 c_unsaved.as_mut_ptr(),
1982 clang_defaultReparseOptions(self.tu.x),
1983 )
1984 };
1985 if ret != 0 {
1986 Err(ret)
1987 } else {
1988 Ok(())
1989 }
1990 }
1991}
1992
1993impl Drop for FallbackTranslationUnit {
1994 fn drop(&mut self) {
1995 let _ = std::fs::remove_file(&self.file_path);
1996 let _ = std::fs::remove_file(&self.header_path);
1997 let _ = std::fs::remove_file(&self.pch_path);
1998 }
1999}
2000
2001/// A diagnostic message generated while parsing a translation unit.
2002pub(crate) struct Diagnostic {
2003 x: CXDiagnostic,
2004}
2005
2006impl Diagnostic {
2007 /// Format this diagnostic message as a string, using the given option bit
2008 /// flags.
2009 pub(crate) fn format(&self) -> String {
2010 unsafe {
2011 let opts: i32 = clang_defaultDiagnosticDisplayOptions();
2012 cxstring_into_string(clang_formatDiagnostic(self.x, flags:opts))
2013 }
2014 }
2015
2016 /// What is the severity of this diagnostic message?
2017 pub(crate) fn severity(&self) -> CXDiagnosticSeverity {
2018 unsafe { clang_getDiagnosticSeverity(self.x) }
2019 }
2020}
2021
2022impl Drop for Diagnostic {
2023 /// Destroy this diagnostic message.
2024 fn drop(&mut self) {
2025 unsafe {
2026 clang_disposeDiagnostic(self.x);
2027 }
2028 }
2029}
2030
2031/// A file which has not been saved to disk.
2032pub(crate) struct UnsavedFile {
2033 x: CXUnsavedFile,
2034 /// The name of the unsaved file. Kept here to avoid leaving dangling pointers in
2035 /// `CXUnsavedFile`.
2036 pub(crate) name: CString,
2037 contents: CString,
2038}
2039
2040impl UnsavedFile {
2041 /// Construct a new unsaved file with the given `name` and `contents`.
2042 pub(crate) fn new(name: &str, contents: &str) -> UnsavedFile {
2043 let name: CString = CString::new(name.as_bytes()).unwrap();
2044 let contents: CString = CString::new(contents.as_bytes()).unwrap();
2045 let x: CXUnsavedFile = CXUnsavedFile {
2046 Filename: name.as_ptr(),
2047 Contents: contents.as_ptr(),
2048 Length: contents.as_bytes().len() as c_ulong,
2049 };
2050 UnsavedFile { x, name, contents }
2051 }
2052}
2053
2054impl fmt::Debug for UnsavedFile {
2055 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
2056 write!(
2057 fmt,
2058 "UnsavedFile(name: {:?}, contents: {:?})",
2059 self.name, self.contents
2060 )
2061 }
2062}
2063
2064/// Convert a cursor kind into a static string.
2065pub(crate) fn kind_to_str(x: CXCursorKind) -> String {
2066 unsafe { cxstring_into_string(clang_getCursorKindSpelling(kind:x)) }
2067}
2068
2069/// Convert a type kind to a static string.
2070pub(crate) fn type_to_str(x: CXTypeKind) -> String {
2071 unsafe { cxstring_into_string(clang_getTypeKindSpelling(type_:x)) }
2072}
2073
2074/// Dump the Clang AST to stdout for debugging purposes.
2075pub(crate) fn ast_dump(c: &Cursor, depth: isize) -> CXChildVisitResult {
2076 fn print_indent<S: AsRef<str>>(depth: isize, s: S) {
2077 for _ in 0..depth {
2078 print!(" ");
2079 }
2080 println!("{}", s.as_ref());
2081 }
2082
2083 fn print_cursor<S: AsRef<str>>(depth: isize, prefix: S, c: &Cursor) {
2084 let prefix = prefix.as_ref();
2085 print_indent(
2086 depth,
2087 format!(" {prefix}kind = {}", kind_to_str(c.kind())),
2088 );
2089 print_indent(
2090 depth,
2091 format!(" {prefix}spelling = \"{}\"", c.spelling()),
2092 );
2093 print_indent(depth, format!(" {prefix}location = {}", c.location()));
2094 print_indent(
2095 depth,
2096 format!(" {prefix}is-definition? {}", c.is_definition()),
2097 );
2098 print_indent(
2099 depth,
2100 format!(" {prefix}is-declaration? {}", c.is_declaration()),
2101 );
2102 print_indent(
2103 depth,
2104 format!(
2105 " {prefix}is-inlined-function? {}",
2106 c.is_inlined_function()
2107 ),
2108 );
2109
2110 let templ_kind = c.template_kind();
2111 if templ_kind != CXCursor_NoDeclFound {
2112 print_indent(
2113 depth,
2114 format!(" {prefix}template-kind = {}", kind_to_str(templ_kind)),
2115 );
2116 }
2117 if let Some(usr) = c.usr() {
2118 print_indent(depth, format!(" {prefix}usr = \"{usr}\""));
2119 }
2120 if let Ok(num) = c.num_args() {
2121 print_indent(depth, format!(" {prefix}number-of-args = {num}"));
2122 }
2123 if let Some(num) = c.num_template_args() {
2124 print_indent(
2125 depth,
2126 format!(" {prefix}number-of-template-args = {num}"),
2127 );
2128 }
2129
2130 if c.is_bit_field() {
2131 let width = match c.bit_width() {
2132 Some(w) => w.to_string(),
2133 None => "<unevaluable>".to_string(),
2134 };
2135 print_indent(depth, format!(" {prefix}bit-width = {width}"));
2136 }
2137
2138 if let Some(ty) = c.enum_type() {
2139 print_indent(
2140 depth,
2141 format!(" {prefix}enum-type = {}", type_to_str(ty.kind())),
2142 );
2143 }
2144 if let Some(val) = c.enum_val_signed() {
2145 print_indent(depth, format!(" {prefix}enum-val = {val}"));
2146 }
2147 if let Some(ty) = c.typedef_type() {
2148 print_indent(
2149 depth,
2150 format!(" {prefix}typedef-type = {}", type_to_str(ty.kind())),
2151 );
2152 }
2153 if let Some(ty) = c.ret_type() {
2154 print_indent(
2155 depth,
2156 format!(" {prefix}ret-type = {}", type_to_str(ty.kind())),
2157 );
2158 }
2159
2160 if let Some(refd) = c.referenced() {
2161 if refd != *c {
2162 println!();
2163 print_cursor(
2164 depth,
2165 String::from(prefix) + "referenced.",
2166 &refd,
2167 );
2168 }
2169 }
2170
2171 let canonical = c.canonical();
2172 if canonical != *c {
2173 println!();
2174 print_cursor(
2175 depth,
2176 String::from(prefix) + "canonical.",
2177 &canonical,
2178 );
2179 }
2180
2181 if let Some(specialized) = c.specialized() {
2182 if specialized != *c {
2183 println!();
2184 print_cursor(
2185 depth,
2186 String::from(prefix) + "specialized.",
2187 &specialized,
2188 );
2189 }
2190 }
2191
2192 if let Some(parent) = c.fallible_semantic_parent() {
2193 println!();
2194 print_cursor(
2195 depth,
2196 String::from(prefix) + "semantic-parent.",
2197 &parent,
2198 );
2199 }
2200 }
2201
2202 fn print_type<S: AsRef<str>>(depth: isize, prefix: S, ty: &Type) {
2203 let prefix = prefix.as_ref();
2204
2205 let kind = ty.kind();
2206 print_indent(depth, format!(" {prefix}kind = {}", type_to_str(kind)));
2207 if kind == CXType_Invalid {
2208 return;
2209 }
2210
2211 print_indent(depth, format!(" {prefix}cconv = {}", ty.call_conv()));
2212
2213 print_indent(
2214 depth,
2215 format!(" {prefix}spelling = \"{}\"", ty.spelling()),
2216 );
2217 let num_template_args =
2218 unsafe { clang_Type_getNumTemplateArguments(ty.x) };
2219 if num_template_args >= 0 {
2220 print_indent(
2221 depth,
2222 format!(
2223 " {prefix}number-of-template-args = {num_template_args}"
2224 ),
2225 );
2226 }
2227 if let Some(num) = ty.num_elements() {
2228 print_indent(depth, format!(" {prefix}number-of-elements = {num}"));
2229 }
2230 print_indent(
2231 depth,
2232 format!(" {prefix}is-variadic? {}", ty.is_variadic()),
2233 );
2234
2235 let canonical = ty.canonical_type();
2236 if canonical != *ty {
2237 println!();
2238 print_type(depth, String::from(prefix) + "canonical.", &canonical);
2239 }
2240
2241 if let Some(pointee) = ty.pointee_type() {
2242 if pointee != *ty {
2243 println!();
2244 print_type(depth, String::from(prefix) + "pointee.", &pointee);
2245 }
2246 }
2247
2248 if let Some(elem) = ty.elem_type() {
2249 if elem != *ty {
2250 println!();
2251 print_type(depth, String::from(prefix) + "elements.", &elem);
2252 }
2253 }
2254
2255 if let Some(ret) = ty.ret_type() {
2256 if ret != *ty {
2257 println!();
2258 print_type(depth, String::from(prefix) + "return.", &ret);
2259 }
2260 }
2261
2262 let named = ty.named();
2263 if named != *ty && named.is_valid() {
2264 println!();
2265 print_type(depth, String::from(prefix) + "named.", &named);
2266 }
2267 }
2268
2269 print_indent(depth, "(");
2270 print_cursor(depth, "", c);
2271
2272 println!();
2273 let ty = c.cur_type();
2274 print_type(depth, "type.", &ty);
2275
2276 let declaration = ty.declaration();
2277 if declaration != *c && declaration.kind() != CXCursor_NoDeclFound {
2278 println!();
2279 print_cursor(depth, "type.declaration.", &declaration);
2280 }
2281
2282 // Recurse.
2283 let mut found_children = false;
2284 c.visit(|s| {
2285 if !found_children {
2286 println!();
2287 found_children = true;
2288 }
2289 ast_dump(&s, depth + 1)
2290 });
2291
2292 print_indent(depth, ")");
2293
2294 CXChildVisit_Continue
2295}
2296
2297/// Try to extract the clang version to a string
2298pub(crate) fn extract_clang_version() -> String {
2299 unsafe { cxstring_into_string(clang_getClangVersion()) }
2300}
2301
2302/// A wrapper for the result of evaluating an expression.
2303#[derive(Debug)]
2304pub(crate) struct EvalResult {
2305 x: CXEvalResult,
2306 ty: Type,
2307}
2308
2309impl EvalResult {
2310 /// Evaluate `cursor` and return the result.
2311 pub(crate) fn new(cursor: Cursor) -> Option<Self> {
2312 // Work around https://bugs.llvm.org/show_bug.cgi?id=42532, see:
2313 // * https://github.com/rust-lang/rust-bindgen/issues/283
2314 // * https://github.com/rust-lang/rust-bindgen/issues/1590
2315 {
2316 let mut found_cant_eval = false;
2317 cursor.visit(|c| {
2318 if c.kind() == CXCursor_TypeRef &&
2319 c.cur_type().canonical_type().kind() == CXType_Unexposed
2320 {
2321 found_cant_eval = true;
2322 return CXChildVisit_Break;
2323 }
2324
2325 CXChildVisit_Recurse
2326 });
2327
2328 if found_cant_eval {
2329 return None;
2330 }
2331 }
2332 Some(EvalResult {
2333 x: unsafe { clang_Cursor_Evaluate(cursor.x) },
2334 ty: cursor.cur_type().canonical_type(),
2335 })
2336 }
2337
2338 fn kind(&self) -> CXEvalResultKind {
2339 unsafe { clang_EvalResult_getKind(self.x) }
2340 }
2341
2342 /// Try to get back the result as a double.
2343 pub(crate) fn as_double(&self) -> Option<f64> {
2344 match self.kind() {
2345 CXEval_Float => {
2346 Some(unsafe { clang_EvalResult_getAsDouble(self.x) })
2347 }
2348 _ => None,
2349 }
2350 }
2351
2352 /// Try to get back the result as an integer.
2353 pub(crate) fn as_int(&self) -> Option<i64> {
2354 if self.kind() != CXEval_Int {
2355 return None;
2356 }
2357
2358 if unsafe { clang_EvalResult_isUnsignedInt(self.x) } != 0 {
2359 let value = unsafe { clang_EvalResult_getAsUnsigned(self.x) };
2360 if value > i64::MAX as c_ulonglong {
2361 return None;
2362 }
2363
2364 return Some(value as i64);
2365 }
2366
2367 let value = unsafe { clang_EvalResult_getAsLongLong(self.x) };
2368 if value > i64::MAX as c_longlong {
2369 return None;
2370 }
2371 if value < i64::MIN as c_longlong {
2372 return None;
2373 }
2374 #[allow(clippy::unnecessary_cast)]
2375 Some(value as i64)
2376 }
2377
2378 /// Evaluates the expression as a literal string, that may or may not be
2379 /// valid utf-8.
2380 pub(crate) fn as_literal_string(&self) -> Option<Vec<u8>> {
2381 if self.kind() != CXEval_StrLiteral {
2382 return None;
2383 }
2384
2385 let char_ty = self.ty.pointee_type().or_else(|| self.ty.elem_type())?;
2386 match char_ty.kind() {
2387 CXType_Char_S | CXType_SChar | CXType_Char_U | CXType_UChar => {
2388 let ret = unsafe {
2389 CStr::from_ptr(clang_EvalResult_getAsStr(self.x))
2390 };
2391 Some(ret.to_bytes().to_vec())
2392 }
2393 // FIXME: Support generating these.
2394 CXType_Char16 => None,
2395 CXType_Char32 => None,
2396 CXType_WChar => None,
2397 _ => None,
2398 }
2399 }
2400}
2401
2402impl Drop for EvalResult {
2403 fn drop(&mut self) {
2404 unsafe { clang_EvalResult_dispose(self.x) };
2405 }
2406}
2407/// ABI kinds as defined in
2408/// <https://github.com/llvm/llvm-project/blob/ddf1de20a3f7db3bca1ef6ba7e6cbb90aac5fd2d/clang/include/clang/Basic/TargetCXXABI.def>
2409#[derive(Debug, Eq, PartialEq, Copy, Clone)]
2410pub(crate) enum ABIKind {
2411 /// All the regular targets like Linux, Mac, WASM, etc. implement the Itanium ABI
2412 GenericItanium,
2413 /// The ABI used when compiling for the MSVC target
2414 Microsoft,
2415}
2416
2417/// Target information obtained from libclang.
2418#[derive(Debug)]
2419pub(crate) struct TargetInfo {
2420 /// The target triple.
2421 pub(crate) triple: String,
2422 /// The width of the pointer _in bits_.
2423 pub(crate) pointer_width: usize,
2424 /// The ABI of the target
2425 pub(crate) abi: ABIKind,
2426}
2427
2428impl TargetInfo {
2429 /// Tries to obtain target information from libclang.
2430 pub(crate) fn new(tu: &TranslationUnit) -> Self {
2431 let triple;
2432 let pointer_width;
2433 unsafe {
2434 let ti = clang_getTranslationUnitTargetInfo(tu.x);
2435 triple = cxstring_into_string(clang_TargetInfo_getTriple(ti));
2436 pointer_width = clang_TargetInfo_getPointerWidth(ti);
2437 clang_TargetInfo_dispose(ti);
2438 }
2439 assert!(pointer_width > 0);
2440 assert_eq!(pointer_width % 8, 0);
2441
2442 let abi = if triple.contains("msvc") {
2443 ABIKind::Microsoft
2444 } else {
2445 ABIKind::GenericItanium
2446 };
2447
2448 TargetInfo {
2449 triple,
2450 pointer_width: pointer_width as usize,
2451 abi,
2452 }
2453 }
2454}
2455