1 //! A higher level Clang API built on top of the generated bindings in the
2 //! `clang_sys` module.
4 #![allow(non_upper_case_globals, dead_code)]
5 #![deny(clippy::missing_docs_in_private_items)]
7 use crate::ir::context::BindgenContext;
11 use std::ffi::{CStr, CString};
14 use std::hash::Hasher;
15 use std::os::raw::{c_char, c_int, c_longlong, c_uint, c_ulong, c_ulonglong};
16 use std::{mem, ptr, slice};
18 /// Type representing a clang attribute.
20 /// Values of this type can be used to check for different attributes using the `has_attrs`
22 pub(crate) struct Attribute {
24 kind: Option<CXCursorKind>,
25 token_kind: CXTokenKind,
29 /// A `warn_unused_result` attribute.
30 pub(crate) const MUST_USE: Self = Self {
31 name: b"warn_unused_result",
32 // FIXME(emilio): clang-sys doesn't expose `CXCursor_WarnUnusedResultAttr` (from clang 9).
34 token_kind: CXToken_Identifier,
37 /// A `_Noreturn` attribute.
38 pub(crate) const NO_RETURN: Self = Self {
41 token_kind: CXToken_Keyword,
44 /// A `[[noreturn]]` attribute.
45 pub(crate) const NO_RETURN_CPP: Self = Self {
48 token_kind: CXToken_Identifier,
52 /// A cursor into the Clang AST, pointing to an AST node.
54 /// We call the AST node pointed to by the cursor the cursor's "referent".
55 #[derive(Copy, Clone)]
56 pub(crate) struct Cursor {
60 impl fmt::Debug for Cursor {
61 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
64 "Cursor({} kind: {}, loc: {}, usr: {:?})",
66 kind_to_str(self.kind()),
74 /// Get the Unified Symbol Resolution for this cursor's referent, if
77 /// The USR can be used to compare entities across translation units.
78 pub(crate) fn usr(&self) -> Option<String> {
79 let s = unsafe { cxstring_into_string(clang_getCursorUSR(self.x)) };
87 /// Is this cursor's referent a declaration?
88 pub(crate) fn is_declaration(&self) -> bool {
89 unsafe { clang_isDeclaration(self.kind()) != 0 }
92 /// Is this cursor's referent an anonymous record or so?
93 pub(crate) fn is_anonymous(&self) -> bool {
94 unsafe { clang_Cursor_isAnonymous(self.x) != 0 }
97 /// Get this cursor's referent's spelling.
98 pub(crate) fn spelling(&self) -> String {
99 unsafe { cxstring_into_string(clang_getCursorSpelling(self.x)) }
102 /// Get this cursor's referent's display name.
104 /// This is not necessarily a valid identifier. It includes extra
105 /// information, such as parameters for a function, etc.
106 pub(crate) fn display_name(&self) -> String {
107 unsafe { cxstring_into_string(clang_getCursorDisplayName(self.x)) }
110 /// Get the mangled name of this cursor's referent.
111 pub(crate) fn mangling(&self) -> String {
112 unsafe { cxstring_into_string(clang_Cursor_getMangling(self.x)) }
115 /// Gets the C++ manglings for this cursor, or an error if the manglings
116 /// are not available.
117 pub(crate) fn cxx_manglings(&self) -> Result<Vec<String>, ()> {
120 let manglings = clang_Cursor_getCXXManglings(self.x);
121 if manglings.is_null() {
124 let count = (*manglings).Count as usize;
126 let mut result = Vec::with_capacity(count);
128 let string_ptr = (*manglings).Strings.add(i);
129 result.push(cxstring_to_string_leaky(*string_ptr));
131 clang_disposeStringSet(manglings);
136 /// Returns whether the cursor refers to a built-in definition.
137 pub(crate) fn is_builtin(&self) -> bool {
138 let (file, _, _, _) = self.location().location();
139 file.name().is_none()
142 /// Get the `Cursor` for this cursor's referent's lexical parent.
144 /// The lexical parent is the parent of the definition. The semantic parent
145 /// is the parent of the declaration. Generally, the lexical parent doesn't
146 /// have any effect on semantics, while the semantic parent does.
148 /// In the following snippet, the `Foo` class would be the semantic parent
149 /// of the out-of-line `method` definition, while the lexical parent is the
150 /// translation unit.
157 /// void Foo::method() { /* ... */ }
159 pub(crate) fn lexical_parent(&self) -> Cursor {
162 x: clang_getCursorLexicalParent(self.x),
167 /// Get the referent's semantic parent, if one is available.
169 /// See documentation for `lexical_parent` for details on semantic vs
171 pub(crate) fn fallible_semantic_parent(&self) -> Option<Cursor> {
174 x: clang_getCursorSemanticParent(self.x),
177 if sp == *self || !sp.is_valid() {
183 /// Get the referent's semantic parent.
185 /// See documentation for `lexical_parent` for details on semantic vs
187 pub(crate) fn semantic_parent(&self) -> Cursor {
188 self.fallible_semantic_parent().unwrap()
191 /// Return the number of template arguments used by this cursor's referent,
192 /// if the referent is either a template instantiation. Returns `None`
195 /// NOTE: This may not return `Some` for partial template specializations,
196 /// see #193 and #194.
197 pub(crate) fn num_template_args(&self) -> Option<u32> {
198 // XXX: `clang_Type_getNumTemplateArguments` is sort of reliable, while
199 // `clang_Cursor_getNumTemplateArguments` is totally unreliable.
200 // Therefore, try former first, and only fallback to the latter if we
206 unsafe { clang_Cursor_getNumTemplateArguments(self.x) };
211 debug_assert_eq!(n, -1);
216 let canonical = self.canonical();
217 if canonical != *self {
218 canonical.num_template_args()
225 /// Get a cursor pointing to this referent's containing translation unit.
227 /// Note that we shouldn't create a `TranslationUnit` struct here, because
228 /// bindgen assumes there will only be one of them alive at a time, and
229 /// disposes it on drop. That can change if this would be required, but I
230 /// think we can survive fine without it.
231 pub(crate) fn translation_unit(&self) -> Cursor {
232 assert!(self.is_valid());
234 let tu = clang_Cursor_getTranslationUnit(self.x);
235 let cursor = Cursor {
236 x: clang_getTranslationUnitCursor(tu),
238 assert!(cursor.is_valid());
243 /// Is the referent a top level construct?
244 pub(crate) fn is_toplevel(&self) -> bool {
245 let mut semantic_parent = self.fallible_semantic_parent();
247 while semantic_parent.is_some() &&
248 (semantic_parent.unwrap().kind() == CXCursor_Namespace ||
249 semantic_parent.unwrap().kind() ==
250 CXCursor_NamespaceAlias ||
251 semantic_parent.unwrap().kind() == CXCursor_NamespaceRef)
254 semantic_parent.unwrap().fallible_semantic_parent();
257 let tu = self.translation_unit();
258 // Yes, this can happen with, e.g., macro definitions.
259 semantic_parent == tu.fallible_semantic_parent()
262 /// There are a few kinds of types that we need to treat specially, mainly
263 /// not tracking the type declaration but the location of the cursor, given
264 /// clang doesn't expose a proper declaration for these types.
265 pub(crate) fn is_template_like(&self) -> bool {
268 CXCursor_ClassTemplate |
269 CXCursor_ClassTemplatePartialSpecialization |
270 CXCursor_TypeAliasTemplateDecl
274 /// Is this Cursor pointing to a function-like macro definition?
275 pub(crate) fn is_macro_function_like(&self) -> bool {
276 unsafe { clang_Cursor_isMacroFunctionLike(self.x) != 0 }
279 /// Get the kind of referent this cursor is pointing to.
280 pub(crate) fn kind(&self) -> CXCursorKind {
284 /// Returns true if the cursor is a definition
285 pub(crate) fn is_definition(&self) -> bool {
286 unsafe { clang_isCursorDefinition(self.x) != 0 }
289 /// Is the referent a template specialization?
290 pub(crate) fn is_template_specialization(&self) -> bool {
291 self.specialized().is_some()
294 /// Is the referent a fully specialized template specialization without any
295 /// remaining free template arguments?
296 pub(crate) fn is_fully_specialized_template(&self) -> bool {
297 self.is_template_specialization() &&
298 self.kind() != CXCursor_ClassTemplatePartialSpecialization &&
299 self.num_template_args().unwrap_or(0) > 0
302 /// Is the referent a template specialization that still has remaining free
303 /// template arguments?
304 pub(crate) fn is_in_non_fully_specialized_template(&self) -> bool {
305 if self.is_toplevel() {
309 let parent = self.semantic_parent();
310 if parent.is_fully_specialized_template() {
314 if !parent.is_template_like() {
315 return parent.is_in_non_fully_specialized_template();
321 /// Is the referent any kind of template parameter?
322 pub(crate) fn is_template_parameter(&self) -> bool {
325 CXCursor_TemplateTemplateParameter |
326 CXCursor_TemplateTypeParameter |
327 CXCursor_NonTypeTemplateParameter
331 /// Does the referent's type or value depend on a template parameter?
332 pub(crate) fn is_dependent_on_template_parameter(&self) -> bool {
334 found_template_parameter: &mut bool,
336 ) -> CXChildVisitResult {
337 // If we found a template parameter, it is dependent.
338 if cur.is_template_parameter() {
339 *found_template_parameter = true;
340 return CXChildVisit_Break;
343 // Get the referent and traverse it as well.
344 if let Some(referenced) = cur.referenced() {
345 if referenced.is_template_parameter() {
346 *found_template_parameter = true;
347 return CXChildVisit_Break;
351 .visit(|next| visitor(found_template_parameter, next));
352 if *found_template_parameter {
353 return CXChildVisit_Break;
357 // Continue traversing the AST at the original cursor.
361 if self.is_template_parameter() {
365 let mut found_template_parameter = false;
366 self.visit(|next| visitor(&mut found_template_parameter, next));
368 found_template_parameter
371 /// Is this cursor pointing a valid referent?
372 pub(crate) fn is_valid(&self) -> bool {
373 unsafe { clang_isInvalid(self.kind()) == 0 }
376 /// Get the source location for the referent.
377 pub(crate) fn location(&self) -> SourceLocation {
380 x: clang_getCursorLocation(self.x),
385 /// Get the source location range for the referent.
386 pub(crate) fn extent(&self) -> CXSourceRange {
387 unsafe { clang_getCursorExtent(self.x) }
390 /// Get the raw declaration comment for this referent, if one exists.
391 pub(crate) fn raw_comment(&self) -> Option<String> {
393 cxstring_into_string(clang_Cursor_getRawCommentText(self.x))
402 /// Get the referent's parsed comment.
403 pub(crate) fn comment(&self) -> Comment {
406 x: clang_Cursor_getParsedComment(self.x),
411 /// Get the referent's type.
412 pub(crate) fn cur_type(&self) -> Type {
415 x: clang_getCursorType(self.x),
420 /// Given that this cursor's referent is a reference to another type, or is
421 /// a declaration, get the cursor pointing to the referenced type or type of
422 /// the declared thing.
423 pub(crate) fn definition(&self) -> Option<Cursor> {
426 x: clang_getCursorDefinition(self.x),
429 if ret.is_valid() && ret.kind() != CXCursor_NoDeclFound {
437 /// Given that this cursor's referent is reference type, get the cursor
438 /// pointing to the referenced type.
439 pub(crate) fn referenced(&self) -> Option<Cursor> {
442 x: clang_getCursorReferenced(self.x),
453 /// Get the canonical cursor for this referent.
455 /// Many types can be declared multiple times before finally being properly
456 /// defined. This method allows us to get the canonical cursor for the
458 pub(crate) fn canonical(&self) -> Cursor {
461 x: clang_getCanonicalCursor(self.x),
466 /// Given that this cursor points to either a template specialization or a
467 /// template instantiation, get a cursor pointing to the template definition
468 /// that is being specialized.
469 pub(crate) fn specialized(&self) -> Option<Cursor> {
472 x: clang_getSpecializedCursorTemplate(self.x),
482 /// Assuming that this cursor's referent is a template declaration, get the
483 /// kind of cursor that would be generated for its specializations.
484 pub(crate) fn template_kind(&self) -> CXCursorKind {
485 unsafe { clang_getTemplateCursorKind(self.x) }
488 /// Traverse this cursor's referent and its children.
490 /// Call the given function on each AST node traversed.
491 pub(crate) fn visit<Visitor>(&self, mut visitor: Visitor)
493 Visitor: FnMut(Cursor) -> CXChildVisitResult,
495 let data = &mut visitor as *mut Visitor;
497 clang_visitChildren(self.x, visit_children::<Visitor>, data.cast());
501 /// Traverse all of this cursor's children, sorted by where they appear in source code.
503 /// Call the given function on each AST node traversed.
504 pub(crate) fn visit_sorted<Visitor>(
506 ctx: &mut BindgenContext,
507 mut visitor: Visitor,
509 Visitor: FnMut(&mut BindgenContext, Cursor),
511 // FIXME(#2556): The current source order stuff doesn't account well for different levels
512 // of includes, or includes that show up at the same byte offset because they are passed in
514 const SOURCE_ORDER_ENABLED: bool = false;
515 if !SOURCE_ORDER_ENABLED {
516 return self.visit(|c| {
518 CXChildVisit_Continue
522 let mut children = self.collect_children();
523 for child in &children {
524 if child.kind() == CXCursor_InclusionDirective {
525 if let Some(included_file) = child.get_included_file_name() {
526 let location = child.location();
527 let (source_file, _, _, offset) = location.location();
529 if let Some(source_file) = source_file.name() {
530 ctx.add_include(source_file, included_file, offset);
536 .sort_by(|child1, child2| child1.cmp_by_source_order(child2, ctx));
537 for child in children {
542 /// Compare source order of two cursors, considering `#include` directives.
544 /// Built-in items provided by the compiler (which don't have a source file),
545 /// are sorted first. Remaining files are sorted by their position in the source file.
546 /// If the items' source files differ, they are sorted by the position of the first
547 /// `#include` for their source file. If no source files are included, `None` is returned.
548 fn cmp_by_source_order(
551 ctx: &BindgenContext,
553 let (file, _, _, offset) = self.location().location();
554 let (other_file, _, _, other_offset) = other.location().location();
556 let (file, other_file) = match (file.name(), other_file.name()) {
557 (Some(file), Some(other_file)) => (file, other_file),
558 // Built-in definitions should come first.
559 (Some(_), None) => return cmp::Ordering::Greater,
560 (None, Some(_)) => return cmp::Ordering::Less,
561 (None, None) => return cmp::Ordering::Equal,
564 if file == other_file {
565 // Both items are in the same source file, compare by byte offset.
566 return offset.cmp(&other_offset);
569 let include_location = ctx.included_file_location(&file);
570 let other_include_location = ctx.included_file_location(&other_file);
571 match (include_location, other_include_location) {
572 (Some((file2, offset2)), _) if file2 == other_file => {
573 offset2.cmp(&other_offset)
575 (Some(_), None) => cmp::Ordering::Greater,
576 (_, Some((other_file2, other_offset2))) if file == other_file2 => {
577 offset.cmp(&other_offset2)
579 (None, Some(_)) => cmp::Ordering::Less,
580 (Some((file2, offset2)), Some((other_file2, other_offset2))) => {
581 if file2 == other_file2 {
582 offset2.cmp(&other_offset2)
587 (None, None) => cmp::Ordering::Equal,
591 /// Collect all of this cursor's children into a vec and return them.
592 pub(crate) fn collect_children(&self) -> Vec<Cursor> {
593 let mut children = vec![];
596 CXChildVisit_Continue
601 /// Does this cursor have any children?
602 pub(crate) fn has_children(&self) -> bool {
603 let mut has_children = false;
611 /// Does this cursor have at least `n` children?
612 pub(crate) fn has_at_least_num_children(&self, n: usize) -> bool {
614 let mut num_left = n;
620 CXChildVisit_Continue
626 /// Returns whether the given location contains a cursor with the given
627 /// kind in the first level of nesting underneath (doesn't look
629 pub(crate) fn contains_cursor(&self, kind: CXCursorKind) -> bool {
630 let mut found = false;
633 if c.kind() == kind {
637 CXChildVisit_Continue
644 /// Is the referent an inlined function?
645 pub(crate) fn is_inlined_function(&self) -> bool {
646 unsafe { clang_Cursor_isFunctionInlined(self.x) != 0 }
649 /// Is the referent a defaulted function?
650 pub(crate) fn is_defaulted_function(&self) -> bool {
651 unsafe { clang_CXXMethod_isDefaulted(self.x) != 0 }
654 /// Is the referent a deleted function?
655 pub(crate) fn is_deleted_function(&self) -> bool {
656 // Unfortunately, libclang doesn't yet have an API for checking if a
657 // member function is deleted, but the following should be a good
658 // enough approximation.
659 // Deleted functions are implicitly inline according to paragraph 4 of
660 // [dcl.fct.def.delete] in the C++ standard. Normal inline functions
661 // have a definition in the same translation unit, so if this is an
662 // inline function without a definition, and it's not a defaulted
663 // function, we can reasonably safely conclude that it's a deleted
665 self.is_inlined_function() &&
666 self.definition().is_none() &&
667 !self.is_defaulted_function()
670 /// Is the referent a bit field declaration?
671 pub(crate) fn is_bit_field(&self) -> bool {
672 unsafe { clang_Cursor_isBitField(self.x) != 0 }
675 /// Get a cursor to the bit field's width expression, or `None` if it's not
677 pub(crate) fn bit_width_expr(&self) -> Option<Cursor> {
678 if !self.is_bit_field() {
682 let mut result = None;
684 // The first child may or may not be a TypeRef, depending on whether
685 // the field's type is builtin. Skip it.
686 if cur.kind() == CXCursor_TypeRef {
687 return CXChildVisit_Continue;
690 // The next expression or literal is the bit width.
699 /// Get the width of this cursor's referent bit field, or `None` if the
700 /// referent is not a bit field or if the width could not be evaluated.
701 pub(crate) fn bit_width(&self) -> Option<u32> {
702 // It is not safe to check the bit width without ensuring it doesn't
703 // depend on a template parameter. See
704 // https://github.com/rust-lang/rust-bindgen/issues/2239
705 if self.bit_width_expr()?.is_dependent_on_template_parameter() {
710 let w = clang_getFieldDeclBitWidth(self.x);
719 /// Get the integer representation type used to hold this cursor's referent
721 pub(crate) fn enum_type(&self) -> Option<Type> {
724 x: clang_getEnumDeclIntegerType(self.x),
734 /// Get the boolean constant value for this cursor's enum variant referent.
736 /// Returns None if the cursor's referent is not an enum variant.
737 pub(crate) fn enum_val_boolean(&self) -> Option<bool> {
739 if self.kind() == CXCursor_EnumConstantDecl {
740 Some(clang_getEnumConstantDeclValue(self.x) != 0)
747 /// Get the signed constant value for this cursor's enum variant referent.
749 /// Returns None if the cursor's referent is not an enum variant.
750 pub(crate) fn enum_val_signed(&self) -> Option<i64> {
752 if self.kind() == CXCursor_EnumConstantDecl {
753 #[allow(clippy::unnecessary_cast)]
754 Some(clang_getEnumConstantDeclValue(self.x) as i64)
761 /// Get the unsigned constant value for this cursor's enum variant referent.
763 /// Returns None if the cursor's referent is not an enum variant.
764 pub(crate) fn enum_val_unsigned(&self) -> Option<u64> {
766 if self.kind() == CXCursor_EnumConstantDecl {
767 #[allow(clippy::unnecessary_cast)]
768 Some(clang_getEnumConstantDeclUnsignedValue(self.x) as u64)
775 /// Does this cursor have the given attributes?
776 pub(crate) fn has_attrs<const N: usize>(
778 attrs: &[Attribute; N],
780 let mut found_attrs = [false; N];
781 let mut found_count = 0;
784 let kind = cur.kind();
785 for (idx, attr) in attrs.iter().enumerate() {
786 let found_attr = &mut found_attrs[idx];
788 // `attr.name` and` attr.token_kind` are checked against unexposed attributes only.
789 if attr.kind.map_or(false, |k| k == kind) ||
790 (kind == CXCursor_UnexposedAttr &&
791 cur.tokens().iter().any(|t| {
792 t.kind == attr.token_kind &&
793 t.spelling() == attr.name
799 if found_count == N {
800 return CXChildVisit_Break;
806 CXChildVisit_Continue
812 /// Given that this cursor's referent is a `typedef`, get the `Type` that is
814 pub(crate) fn typedef_type(&self) -> Option<Type> {
816 x: unsafe { clang_getTypedefDeclUnderlyingType(self.x) },
819 if inner.is_valid() {
826 /// Get the linkage kind for this cursor's referent.
828 /// This only applies to functions and variables.
829 pub(crate) fn linkage(&self) -> CXLinkageKind {
830 unsafe { clang_getCursorLinkage(self.x) }
833 /// Get the visibility of this cursor's referent.
834 pub(crate) fn visibility(&self) -> CXVisibilityKind {
835 unsafe { clang_getCursorVisibility(self.x) }
838 /// Given that this cursor's referent is a function, return cursors to its
841 /// Returns None if the cursor's referent is not a function/method call or
843 pub(crate) fn args(&self) -> Option<Vec<Cursor>> {
844 // match self.kind() {
845 // CXCursor_FunctionDecl |
846 // CXCursor_CXXMethod => {
847 self.num_args().ok().map(|num| {
850 x: unsafe { clang_Cursor_getArgument(self.x, i as c_uint) },
856 /// Given that this cursor's referent is a function/method call or
857 /// declaration, return the number of arguments it takes.
859 /// Returns Err if the cursor's referent is not a function/method call or
861 pub(crate) fn num_args(&self) -> Result<u32, ()> {
863 let w = clang_Cursor_getNumArguments(self.x);
872 /// Get the access specifier for this cursor's referent.
873 pub(crate) fn access_specifier(&self) -> CX_CXXAccessSpecifier {
874 unsafe { clang_getCXXAccessSpecifier(self.x) }
877 /// Is the cursor's referrent publically accessible in C++?
879 /// Returns true if self.access_specifier() is `CX_CXXPublic` or
880 /// `CX_CXXInvalidAccessSpecifier`.
881 pub(crate) fn public_accessible(&self) -> bool {
882 let access = self.access_specifier();
883 access == CX_CXXPublic || access == CX_CXXInvalidAccessSpecifier
886 /// Is this cursor's referent a field declaration that is marked as
888 pub(crate) fn is_mutable_field(&self) -> bool {
889 unsafe { clang_CXXField_isMutable(self.x) != 0 }
892 /// Get the offset of the field represented by the Cursor.
893 pub(crate) fn offset_of_field(&self) -> Result<usize, LayoutError> {
894 let offset = unsafe { clang_Cursor_getOffsetOfField(self.x) };
897 Err(LayoutError::from(offset as i32))
903 /// Is this cursor's referent a member function that is declared `static`?
904 pub(crate) fn method_is_static(&self) -> bool {
905 unsafe { clang_CXXMethod_isStatic(self.x) != 0 }
908 /// Is this cursor's referent a member function that is declared `const`?
909 pub(crate) fn method_is_const(&self) -> bool {
910 unsafe { clang_CXXMethod_isConst(self.x) != 0 }
913 /// Is this cursor's referent a member function that is virtual?
914 pub(crate) fn method_is_virtual(&self) -> bool {
915 unsafe { clang_CXXMethod_isVirtual(self.x) != 0 }
918 /// Is this cursor's referent a member function that is pure virtual?
919 pub(crate) fn method_is_pure_virtual(&self) -> bool {
920 unsafe { clang_CXXMethod_isPureVirtual(self.x) != 0 }
923 /// Is this cursor's referent a struct or class with virtual members?
924 pub(crate) fn is_virtual_base(&self) -> bool {
925 unsafe { clang_isVirtualBase(self.x) != 0 }
928 /// Try to evaluate this cursor.
929 pub(crate) fn evaluate(&self) -> Option<EvalResult> {
930 EvalResult::new(*self)
933 /// Return the result type for this cursor
934 pub(crate) fn ret_type(&self) -> Option<Type> {
936 x: unsafe { clang_getCursorResultType(self.x) },
945 /// Gets the tokens that correspond to that cursor.
946 pub(crate) fn tokens(&self) -> RawTokens {
950 /// Gets the tokens that correspond to that cursor as `cexpr` tokens.
951 pub(crate) fn cexpr_tokens(self) -> Vec<cexpr::token::Token> {
954 .filter_map(|token| token.as_cexpr_token())
958 /// Obtain the real path name of a cursor of InclusionDirective kind.
960 /// Returns None if the cursor does not include a file, otherwise the file's full name
961 pub(crate) fn get_included_file_name(&self) -> Option<String> {
962 let file = unsafe { clang_sys::clang_getIncludedFile(self.x) };
967 cxstring_into_string(clang_sys::clang_getFileName(file))
973 /// A struct that owns the tokenizer result from a given cursor.
974 pub(crate) struct RawTokens<'a> {
976 tu: CXTranslationUnit,
977 tokens: *mut CXToken,
981 impl<'a> RawTokens<'a> {
982 fn new(cursor: &'a Cursor) -> Self {
983 let mut tokens = ptr::null_mut();
984 let mut token_count = 0;
985 let range = cursor.extent();
986 let tu = unsafe { clang_Cursor_getTranslationUnit(cursor.x) };
987 unsafe { clang_tokenize(tu, range, &mut tokens, &mut token_count) };
996 fn as_slice(&self) -> &[CXToken] {
997 if self.tokens.is_null() {
1000 unsafe { slice::from_raw_parts(self.tokens, self.token_count as usize) }
1003 /// Get an iterator over these tokens.
1004 pub(crate) fn iter(&self) -> ClangTokenIterator {
1005 ClangTokenIterator {
1007 raw: self.as_slice().iter(),
1012 impl<'a> Drop for RawTokens<'a> {
1013 fn drop(&mut self) {
1014 if !self.tokens.is_null() {
1016 clang_disposeTokens(
1019 self.token_count as c_uint,
1026 /// A raw clang token, that exposes only kind, spelling, and extent. This is a
1027 /// slightly more convenient version of `CXToken` which owns the spelling
1028 /// string and extent.
1030 pub(crate) struct ClangToken {
1032 /// The extent of the token. This is the same as the relevant member from
1034 pub(crate) extent: CXSourceRange,
1035 /// The kind of the token. This is the same as the relevant member from
1037 pub(crate) kind: CXTokenKind,
1041 /// Get the token spelling, without being converted to utf-8.
1042 pub(crate) fn spelling(&self) -> &[u8] {
1043 let c_str = unsafe {
1044 CStr::from_ptr(clang_getCString(self.spelling) as *const _)
1049 /// Converts a ClangToken to a `cexpr` token if possible.
1050 pub(crate) fn as_cexpr_token(&self) -> Option<cexpr::token::Token> {
1053 let kind = match self.kind {
1054 CXToken_Punctuation => token::Kind::Punctuation,
1055 CXToken_Literal => token::Kind::Literal,
1056 CXToken_Identifier => token::Kind::Identifier,
1057 CXToken_Keyword => token::Kind::Keyword,
1058 // NB: cexpr is not too happy about comments inside
1059 // expressions, so we strip them down here.
1060 CXToken_Comment => return None,
1062 warn!("Found unexpected token kind: {:?}", self);
1069 raw: self.spelling().to_vec().into_boxed_slice(),
1074 impl Drop for ClangToken {
1075 fn drop(&mut self) {
1076 unsafe { clang_disposeString(self.spelling) }
1080 /// An iterator over a set of Tokens.
1081 pub(crate) struct ClangTokenIterator<'a> {
1082 tu: CXTranslationUnit,
1083 raw: slice::Iter<'a, CXToken>,
1086 impl<'a> Iterator for ClangTokenIterator<'a> {
1087 type Item = ClangToken;
1089 fn next(&mut self) -> Option<Self::Item> {
1090 let raw = self.raw.next()?;
1092 let kind = clang_getTokenKind(*raw);
1093 let spelling = clang_getTokenSpelling(self.tu, *raw);
1094 let extent = clang_getTokenExtent(self.tu, *raw);
1104 /// Checks whether the name looks like an identifier, i.e. is alphanumeric
1105 /// (including '_') and does not start with a digit.
1106 pub(crate) fn is_valid_identifier(name: &str) -> bool {
1107 let mut chars = name.chars();
1108 let first_valid = chars
1110 .map(|c| c.is_alphabetic() || c == '_')
1113 first_valid && chars.all(|c| c.is_alphanumeric() || c == '_')
1116 extern "C" fn visit_children<Visitor>(
1120 ) -> CXChildVisitResult
1122 Visitor: FnMut(Cursor) -> CXChildVisitResult,
1124 let func: &mut Visitor = unsafe { &mut *(data as *mut Visitor) };
1125 let child = Cursor { x: cur };
1130 impl PartialEq for Cursor {
1131 fn eq(&self, other: &Cursor) -> bool {
1132 unsafe { clang_equalCursors(self.x, other.x) == 1 }
1136 impl Eq for Cursor {}
1138 impl Hash for Cursor {
1139 fn hash<H: Hasher>(&self, state: &mut H) {
1140 unsafe { clang_hashCursor(self.x) }.hash(state)
1144 /// The type of a node in clang's AST.
1145 #[derive(Clone, Copy)]
1146 pub(crate) struct Type {
1150 impl PartialEq for Type {
1151 fn eq(&self, other: &Self) -> bool {
1152 unsafe { clang_equalTypes(self.x, other.x) != 0 }
1158 impl fmt::Debug for Type {
1159 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1162 "Type({}, kind: {}, cconv: {}, decl: {:?}, canon: {:?})",
1164 type_to_str(self.kind()),
1167 self.declaration().canonical()
1172 /// An error about the layout of a struct, class, or type.
1173 #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
1174 pub(crate) enum LayoutError {
1175 /// Asked for the layout of an invalid type.
1177 /// Asked for the layout of an incomplete type.
1179 /// Asked for the layout of a dependent type.
1181 /// Asked for the layout of a type that does not have constant size.
1183 /// Asked for the layout of a field in a type that does not have such a
1186 /// An unknown layout error.
1190 impl ::std::convert::From<i32> for LayoutError {
1191 fn from(val: i32) -> Self {
1192 use self::LayoutError::*;
1195 CXTypeLayoutError_Invalid => Invalid,
1196 CXTypeLayoutError_Incomplete => Incomplete,
1197 CXTypeLayoutError_Dependent => Dependent,
1198 CXTypeLayoutError_NotConstantSize => NotConstantSize,
1199 CXTypeLayoutError_InvalidFieldName => InvalidFieldName,
1206 /// Get this type's kind.
1207 pub(crate) fn kind(&self) -> CXTypeKind {
1211 /// Get a cursor pointing to this type's declaration.
1212 pub(crate) fn declaration(&self) -> Cursor {
1215 x: clang_getTypeDeclaration(self.x),
1220 /// Get the canonical declaration of this type, if it is available.
1221 pub(crate) fn canonical_declaration(
1223 location: Option<&Cursor>,
1224 ) -> Option<CanonicalTypeDeclaration> {
1225 let mut declaration = self.declaration();
1226 if !declaration.is_valid() {
1227 if let Some(location) = location {
1228 let mut location = *location;
1229 if let Some(referenced) = location.referenced() {
1230 location = referenced;
1232 if location.is_template_like() {
1233 declaration = location;
1238 let canonical = declaration.canonical();
1239 if canonical.is_valid() && canonical.kind() != CXCursor_NoDeclFound {
1240 Some(CanonicalTypeDeclaration(*self, canonical))
1246 /// Get a raw display name for this type.
1247 pub(crate) fn spelling(&self) -> String {
1248 let s = unsafe { cxstring_into_string(clang_getTypeSpelling(self.x)) };
1249 // Clang 5.0 introduced changes in the spelling API so it returned the
1250 // full qualified name. Let's undo that here.
1251 if s.split("::").all(is_valid_identifier) {
1252 if let Some(s) = s.split("::").last() {
1253 return s.to_owned();
1260 /// Is this type const qualified?
1261 pub(crate) fn is_const(&self) -> bool {
1262 unsafe { clang_isConstQualifiedType(self.x) != 0 }
1266 fn is_non_deductible_auto_type(&self) -> bool {
1267 debug_assert_eq!(self.kind(), CXType_Auto);
1268 self.canonical_type() == *self
1272 fn clang_size_of(&self, ctx: &BindgenContext) -> c_longlong {
1274 // Work-around https://bugs.llvm.org/show_bug.cgi?id=40975
1275 CXType_RValueReference | CXType_LValueReference => {
1276 ctx.target_pointer_size() as c_longlong
1278 // Work-around https://bugs.llvm.org/show_bug.cgi?id=40813
1279 CXType_Auto if self.is_non_deductible_auto_type() => -6,
1280 _ => unsafe { clang_Type_getSizeOf(self.x) },
1285 fn clang_align_of(&self, ctx: &BindgenContext) -> c_longlong {
1287 // Work-around https://bugs.llvm.org/show_bug.cgi?id=40975
1288 CXType_RValueReference | CXType_LValueReference => {
1289 ctx.target_pointer_size() as c_longlong
1291 // Work-around https://bugs.llvm.org/show_bug.cgi?id=40813
1292 CXType_Auto if self.is_non_deductible_auto_type() => -6,
1293 _ => unsafe { clang_Type_getAlignOf(self.x) },
1297 /// What is the size of this type? Paper over invalid types by returning `0`
1299 pub(crate) fn size(&self, ctx: &BindgenContext) -> usize {
1300 let val = self.clang_size_of(ctx);
1308 /// What is the size of this type?
1309 pub(crate) fn fallible_size(
1311 ctx: &BindgenContext,
1312 ) -> Result<usize, LayoutError> {
1313 let val = self.clang_size_of(ctx);
1315 Err(LayoutError::from(val as i32))
1321 /// What is the alignment of this type? Paper over invalid types by
1323 pub(crate) fn align(&self, ctx: &BindgenContext) -> usize {
1324 let val = self.clang_align_of(ctx);
1332 /// What is the alignment of this type?
1333 pub(crate) fn fallible_align(
1335 ctx: &BindgenContext,
1336 ) -> Result<usize, LayoutError> {
1337 let val = self.clang_align_of(ctx);
1339 Err(LayoutError::from(val as i32))
1345 /// Get the layout for this type, or an error describing why it does not
1346 /// have a valid layout.
1347 pub(crate) fn fallible_layout(
1349 ctx: &BindgenContext,
1350 ) -> Result<crate::ir::layout::Layout, LayoutError> {
1351 use crate::ir::layout::Layout;
1352 let size = self.fallible_size(ctx)?;
1353 let align = self.fallible_align(ctx)?;
1354 Ok(Layout::new(size, align))
1357 /// Get the number of template arguments this type has, or `None` if it is
1358 /// not some kind of template.
1359 pub(crate) fn num_template_args(&self) -> Option<u32> {
1360 let n = unsafe { clang_Type_getNumTemplateArguments(self.x) };
1364 debug_assert_eq!(n, -1);
1369 /// If this type is a class template specialization, return its
1370 /// template arguments. Otherwise, return None.
1371 pub(crate) fn template_args(&self) -> Option<TypeTemplateArgIterator> {
1372 self.num_template_args().map(|n| TypeTemplateArgIterator {
1379 /// Given that this type is a function prototype, return the types of its parameters.
1381 /// Returns None if the type is not a function prototype.
1382 pub(crate) fn args(&self) -> Option<Vec<Type>> {
1383 self.num_args().ok().map(|num| {
1386 x: unsafe { clang_getArgType(self.x, i as c_uint) },
1392 /// Given that this type is a function prototype, return the number of arguments it takes.
1394 /// Returns Err if the type is not a function prototype.
1395 pub(crate) fn num_args(&self) -> Result<u32, ()> {
1397 let w = clang_getNumArgTypes(self.x);
1406 /// Given that this type is a pointer type, return the type that it points
1408 pub(crate) fn pointee_type(&self) -> Option<Type> {
1411 CXType_RValueReference |
1412 CXType_LValueReference |
1413 CXType_MemberPointer |
1414 CXType_BlockPointer |
1415 CXType_ObjCObjectPointer => {
1417 x: unsafe { clang_getPointeeType(self.x) },
1419 debug_assert!(ret.is_valid());
1426 /// Given that this type is an array, vector, or complex type, return the
1427 /// type of its elements.
1428 pub(crate) fn elem_type(&self) -> Option<Type> {
1429 let current_type = Type {
1430 x: unsafe { clang_getElementType(self.x) },
1432 if current_type.is_valid() {
1439 /// Given that this type is an array or vector type, return its number of
1441 pub(crate) fn num_elements(&self) -> Option<usize> {
1442 let num_elements_returned = unsafe { clang_getNumElements(self.x) };
1443 if num_elements_returned != -1 {
1444 Some(num_elements_returned as usize)
1450 /// Get the canonical version of this type. This sees through `typedef`s and
1451 /// aliases to get the underlying, canonical type.
1452 pub(crate) fn canonical_type(&self) -> Type {
1455 x: clang_getCanonicalType(self.x),
1460 /// Is this type a variadic function type?
1461 pub(crate) fn is_variadic(&self) -> bool {
1462 unsafe { clang_isFunctionTypeVariadic(self.x) != 0 }
1465 /// Given that this type is a function type, get the type of its return
1467 pub(crate) fn ret_type(&self) -> Option<Type> {
1469 x: unsafe { clang_getResultType(self.x) },
1478 /// Given that this type is a function type, get its calling convention. If
1479 /// this is not a function type, `CXCallingConv_Invalid` is returned.
1480 pub(crate) fn call_conv(&self) -> CXCallingConv {
1481 unsafe { clang_getFunctionTypeCallingConv(self.x) }
1484 /// For elaborated types (types which use `class`, `struct`, or `union` to
1485 /// disambiguate types from local bindings), get the underlying type.
1486 pub(crate) fn named(&self) -> Type {
1489 x: clang_Type_getNamedType(self.x),
1494 /// Is this a valid type?
1495 pub(crate) fn is_valid(&self) -> bool {
1496 self.kind() != CXType_Invalid
1499 /// Is this a valid and exposed type?
1500 pub(crate) fn is_valid_and_exposed(&self) -> bool {
1501 self.is_valid() && self.kind() != CXType_Unexposed
1504 /// Is this type a fully instantiated template?
1505 pub(crate) fn is_fully_instantiated_template(&self) -> bool {
1506 // Yep, the spelling of this containing type-parameter is extremely
1507 // nasty... But can happen in <type_traits>. Unfortunately I couldn't
1508 // reduce it enough :(
1509 self.template_args().map_or(false, |args| args.len() > 0) &&
1511 self.declaration().kind(),
1512 CXCursor_ClassTemplatePartialSpecialization |
1513 CXCursor_TypeAliasTemplateDecl |
1514 CXCursor_TemplateTemplateParameter
1518 /// Is this type an associated template type? Eg `T::Associated` in
1522 /// template <typename T>
1524 /// typename T::Associated member;
1527 pub(crate) fn is_associated_type(&self) -> bool {
1528 // This is terrible :(
1529 fn hacky_parse_associated_type<S: AsRef<str>>(spelling: S) -> bool {
1531 static ref ASSOC_TYPE_RE: regex::Regex = regex::Regex::new(
1532 r"typename type\-parameter\-\d+\-\d+::.+"
1536 ASSOC_TYPE_RE.is_match(spelling.as_ref())
1539 self.kind() == CXType_Unexposed &&
1540 (hacky_parse_associated_type(self.spelling()) ||
1541 hacky_parse_associated_type(
1542 self.canonical_type().spelling(),
1547 /// The `CanonicalTypeDeclaration` type exists as proof-by-construction that its
1548 /// cursor is the canonical declaration for its type. If you have a
1549 /// `CanonicalTypeDeclaration` instance, you know for sure that the type and
1550 /// cursor match up in a canonical declaration relationship, and it simply
1551 /// cannot be otherwise.
1552 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
1553 pub(crate) struct CanonicalTypeDeclaration(Type, Cursor);
1555 impl CanonicalTypeDeclaration {
1557 pub(crate) fn ty(&self) -> &Type {
1561 /// Get the type's canonical declaration cursor.
1562 pub(crate) fn cursor(&self) -> &Cursor {
1567 /// An iterator for a type's template arguments.
1568 pub(crate) struct TypeTemplateArgIterator {
1574 impl Iterator for TypeTemplateArgIterator {
1576 fn next(&mut self) -> Option<Type> {
1577 if self.index < self.length {
1578 let idx = self.index as c_uint;
1581 x: unsafe { clang_Type_getTemplateArgumentAsType(self.x, idx) },
1589 impl ExactSizeIterator for TypeTemplateArgIterator {
1590 fn len(&self) -> usize {
1591 assert!(self.index <= self.length);
1592 (self.length - self.index) as usize
1596 /// A `SourceLocation` is a file, line, column, and byte offset location for
1597 /// some source text.
1598 pub(crate) struct SourceLocation {
1599 x: CXSourceLocation,
1602 impl SourceLocation {
1603 /// Get the (file, line, column, byte offset) tuple for this source
1605 pub(crate) fn location(&self) -> (File, usize, usize, usize) {
1607 let mut file = mem::zeroed();
1611 clang_getSpellingLocation(
1612 self.x, &mut file, &mut line, &mut col, &mut off,
1614 (File { x: file }, line as usize, col as usize, off as usize)
1619 impl fmt::Display for SourceLocation {
1620 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1621 let (file, line, col, _) = self.location();
1622 if let Some(name) = file.name() {
1623 write!(f, "{}:{}:{}", name, line, col)
1625 "builtin definitions".fmt(f)
1630 impl fmt::Debug for SourceLocation {
1631 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1632 write!(f, "{}", self)
1636 /// A comment in the source text.
1638 /// Comments are sort of parsed by Clang, and have a tree structure.
1639 pub(crate) struct Comment {
1644 /// What kind of comment is this?
1645 pub(crate) fn kind(&self) -> CXCommentKind {
1646 unsafe { clang_Comment_getKind(self.x) }
1649 /// Get this comment's children comment
1650 pub(crate) fn get_children(&self) -> CommentChildrenIterator {
1651 CommentChildrenIterator {
1653 length: unsafe { clang_Comment_getNumChildren(self.x) },
1658 /// Given that this comment is the start or end of an HTML tag, get its tag
1660 pub(crate) fn get_tag_name(&self) -> String {
1661 unsafe { cxstring_into_string(clang_HTMLTagComment_getTagName(self.x)) }
1664 /// Given that this comment is an HTML start tag, get its attributes.
1665 pub(crate) fn get_tag_attrs(&self) -> CommentAttributesIterator {
1666 CommentAttributesIterator {
1668 length: unsafe { clang_HTMLStartTag_getNumAttrs(self.x) },
1674 /// An iterator for a comment's children
1675 pub(crate) struct CommentChildrenIterator {
1681 impl Iterator for CommentChildrenIterator {
1682 type Item = Comment;
1683 fn next(&mut self) -> Option<Comment> {
1684 if self.index < self.length {
1685 let idx = self.index;
1688 x: unsafe { clang_Comment_getChild(self.parent, idx) },
1696 /// An HTML start tag comment attribute
1697 pub(crate) struct CommentAttribute {
1698 /// HTML start tag attribute name
1699 pub(crate) name: String,
1700 /// HTML start tag attribute value
1701 pub(crate) value: String,
1704 /// An iterator for a comment's attributes
1705 pub(crate) struct CommentAttributesIterator {
1711 impl Iterator for CommentAttributesIterator {
1712 type Item = CommentAttribute;
1713 fn next(&mut self) -> Option<CommentAttribute> {
1714 if self.index < self.length {
1715 let idx = self.index;
1717 Some(CommentAttribute {
1719 cxstring_into_string(clang_HTMLStartTag_getAttrName(
1724 cxstring_into_string(clang_HTMLStartTag_getAttrValue(
1736 pub(crate) struct File {
1741 /// Get the name of this source file.
1742 pub(crate) fn name(&self) -> Option<String> {
1743 if self.x.is_null() {
1746 Some(unsafe { cxstring_into_string(clang_getFileName(self.x)) })
1750 fn cxstring_to_string_leaky(s: CXString) -> String {
1751 if s.data.is_null() {
1752 return "".to_owned();
1754 let c_str = unsafe { CStr::from_ptr(clang_getCString(s) as *const _) };
1755 c_str.to_string_lossy().into_owned()
1758 fn cxstring_into_string(s: CXString) -> String {
1759 let ret = cxstring_to_string_leaky(s);
1760 unsafe { clang_disposeString(s) };
1764 /// An `Index` is an environment for a set of translation units that will
1765 /// typically end up linked together in one final binary.
1766 pub(crate) struct Index {
1771 /// Construct a new `Index`.
1773 /// The `pch` parameter controls whether declarations in pre-compiled
1774 /// headers are included when enumerating a translation unit's "locals".
1776 /// The `diag` parameter controls whether debugging diagnostics are enabled.
1777 pub(crate) fn new(pch: bool, diag: bool) -> Index {
1780 x: clang_createIndex(pch as c_int, diag as c_int),
1786 impl fmt::Debug for Index {
1787 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1788 write!(fmt, "Index {{ }}")
1792 impl Drop for Index {
1793 fn drop(&mut self) {
1795 clang_disposeIndex(self.x);
1800 /// A translation unit (or "compilation unit").
1801 pub(crate) struct TranslationUnit {
1802 x: CXTranslationUnit,
1805 impl fmt::Debug for TranslationUnit {
1806 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1807 write!(fmt, "TranslationUnit {{ }}")
1811 impl TranslationUnit {
1812 /// Parse a source file into a translation unit.
1813 pub(crate) fn parse(
1816 cmd_args: &[Box<str>],
1817 unsaved: &[UnsavedFile],
1818 opts: CXTranslationUnit_Flags,
1819 ) -> Option<TranslationUnit> {
1820 let fname = CString::new(file).unwrap();
1821 let _c_args: Vec<CString> = cmd_args
1823 .map(|s| CString::new(s.as_bytes()).unwrap())
1825 let c_args: Vec<*const c_char> =
1826 _c_args.iter().map(|s| s.as_ptr()).collect();
1827 let mut c_unsaved: Vec<CXUnsavedFile> =
1828 unsaved.iter().map(|f| f.x).collect();
1830 clang_parseTranslationUnit(
1834 c_args.len() as c_int,
1835 c_unsaved.as_mut_ptr(),
1836 c_unsaved.len() as c_uint,
1843 Some(TranslationUnit { x: tu })
1847 /// Get the Clang diagnostic information associated with this translation
1849 pub(crate) fn diags(&self) -> Vec<Diagnostic> {
1851 let num = clang_getNumDiagnostics(self.x) as usize;
1852 let mut diags = vec![];
1854 diags.push(Diagnostic {
1855 x: clang_getDiagnostic(self.x, i as c_uint),
1862 /// Get a cursor pointing to the root of this translation unit's AST.
1863 pub(crate) fn cursor(&self) -> Cursor {
1866 x: clang_getTranslationUnitCursor(self.x),
1871 /// Is this the null translation unit?
1872 pub(crate) fn is_null(&self) -> bool {
1877 impl Drop for TranslationUnit {
1878 fn drop(&mut self) {
1880 clang_disposeTranslationUnit(self.x);
1885 /// A diagnostic message generated while parsing a translation unit.
1886 pub(crate) struct Diagnostic {
1891 /// Format this diagnostic message as a string, using the given option bit
1893 pub(crate) fn format(&self) -> String {
1895 let opts = clang_defaultDiagnosticDisplayOptions();
1896 cxstring_into_string(clang_formatDiagnostic(self.x, opts))
1900 /// What is the severity of this diagnostic message?
1901 pub(crate) fn severity(&self) -> CXDiagnosticSeverity {
1902 unsafe { clang_getDiagnosticSeverity(self.x) }
1906 impl Drop for Diagnostic {
1907 /// Destroy this diagnostic message.
1908 fn drop(&mut self) {
1910 clang_disposeDiagnostic(self.x);
1915 /// A file which has not been saved to disk.
1916 pub(crate) struct UnsavedFile {
1918 /// The name of the unsaved file. Kept here to avoid leaving dangling pointers in
1919 /// `CXUnsavedFile`.
1920 pub(crate) name: CString,
1925 /// Construct a new unsaved file with the given `name` and `contents`.
1926 pub(crate) fn new(name: &str, contents: &str) -> UnsavedFile {
1927 let name = CString::new(name.as_bytes()).unwrap();
1928 let contents = CString::new(contents.as_bytes()).unwrap();
1929 let x = CXUnsavedFile {
1930 Filename: name.as_ptr(),
1931 Contents: contents.as_ptr(),
1932 Length: contents.as_bytes().len() as c_ulong,
1934 UnsavedFile { x, name, contents }
1938 impl fmt::Debug for UnsavedFile {
1939 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1942 "UnsavedFile(name: {:?}, contents: {:?})",
1943 self.name, self.contents
1948 /// Convert a cursor kind into a static string.
1949 pub(crate) fn kind_to_str(x: CXCursorKind) -> String {
1950 unsafe { cxstring_into_string(clang_getCursorKindSpelling(x)) }
1953 /// Convert a type kind to a static string.
1954 pub(crate) fn type_to_str(x: CXTypeKind) -> String {
1955 unsafe { cxstring_into_string(clang_getTypeKindSpelling(x)) }
1958 /// Dump the Clang AST to stdout for debugging purposes.
1959 pub(crate) fn ast_dump(c: &Cursor, depth: isize) -> CXChildVisitResult {
1960 fn print_indent<S: AsRef<str>>(depth: isize, s: S) {
1964 println!("{}", s.as_ref());
1967 fn print_cursor<S: AsRef<str>>(depth: isize, prefix: S, c: &Cursor) {
1968 let prefix = prefix.as_ref();
1971 format!(" {}kind = {}", prefix, kind_to_str(c.kind())),
1975 format!(" {}spelling = \"{}\"", prefix, c.spelling()),
1977 print_indent(depth, format!(" {}location = {}", prefix, c.location()));
1980 format!(" {}is-definition? {}", prefix, c.is_definition()),
1984 format!(" {}is-declaration? {}", prefix, c.is_declaration()),
1989 " {}is-inlined-function? {}",
1991 c.is_inlined_function()
1995 let templ_kind = c.template_kind();
1996 if templ_kind != CXCursor_NoDeclFound {
2000 " {}template-kind = {}",
2002 kind_to_str(templ_kind)
2006 if let Some(usr) = c.usr() {
2007 print_indent(depth, format!(" {}usr = \"{}\"", prefix, usr));
2009 if let Ok(num) = c.num_args() {
2010 print_indent(depth, format!(" {}number-of-args = {}", prefix, num));
2012 if let Some(num) = c.num_template_args() {
2015 format!(" {}number-of-template-args = {}", prefix, num),
2019 if c.is_bit_field() {
2020 let width = match c.bit_width() {
2021 Some(w) => w.to_string(),
2022 None => "<unevaluable>".to_string(),
2024 print_indent(depth, format!(" {}bit-width = {}", prefix, width));
2027 if let Some(ty) = c.enum_type() {
2030 format!(" {}enum-type = {}", prefix, type_to_str(ty.kind())),
2033 if let Some(val) = c.enum_val_signed() {
2034 print_indent(depth, format!(" {}enum-val = {}", prefix, val));
2036 if let Some(ty) = c.typedef_type() {
2039 format!(" {}typedef-type = {}", prefix, type_to_str(ty.kind())),
2042 if let Some(ty) = c.ret_type() {
2045 format!(" {}ret-type = {}", prefix, type_to_str(ty.kind())),
2049 if let Some(refd) = c.referenced() {
2054 String::from(prefix) + "referenced.",
2060 let canonical = c.canonical();
2061 if canonical != *c {
2065 String::from(prefix) + "canonical.",
2070 if let Some(specialized) = c.specialized() {
2071 if specialized != *c {
2075 String::from(prefix) + "specialized.",
2081 if let Some(parent) = c.fallible_semantic_parent() {
2085 String::from(prefix) + "semantic-parent.",
2091 fn print_type<S: AsRef<str>>(depth: isize, prefix: S, ty: &Type) {
2092 let prefix = prefix.as_ref();
2094 let kind = ty.kind();
2095 print_indent(depth, format!(" {}kind = {}", prefix, type_to_str(kind)));
2096 if kind == CXType_Invalid {
2100 print_indent(depth, format!(" {}cconv = {}", prefix, ty.call_conv()));
2104 format!(" {}spelling = \"{}\"", prefix, ty.spelling()),
2106 let num_template_args =
2107 unsafe { clang_Type_getNumTemplateArguments(ty.x) };
2108 if num_template_args >= 0 {
2112 " {}number-of-template-args = {}",
2113 prefix, num_template_args
2117 if let Some(num) = ty.num_elements() {
2120 format!(" {}number-of-elements = {}", prefix, num),
2125 format!(" {}is-variadic? {}", prefix, ty.is_variadic()),
2128 let canonical = ty.canonical_type();
2129 if canonical != *ty {
2131 print_type(depth, String::from(prefix) + "canonical.", &canonical);
2134 if let Some(pointee) = ty.pointee_type() {
2137 print_type(depth, String::from(prefix) + "pointee.", &pointee);
2141 if let Some(elem) = ty.elem_type() {
2144 print_type(depth, String::from(prefix) + "elements.", &elem);
2148 if let Some(ret) = ty.ret_type() {
2151 print_type(depth, String::from(prefix) + "return.", &ret);
2155 let named = ty.named();
2156 if named != *ty && named.is_valid() {
2158 print_type(depth, String::from(prefix) + "named.", &named);
2162 print_indent(depth, "(");
2163 print_cursor(depth, "", c);
2166 let ty = c.cur_type();
2167 print_type(depth, "type.", &ty);
2169 let declaration = ty.declaration();
2170 if declaration != *c && declaration.kind() != CXCursor_NoDeclFound {
2172 print_cursor(depth, "type.declaration.", &declaration);
2176 let mut found_children = false;
2178 if !found_children {
2180 found_children = true;
2182 ast_dump(&s, depth + 1)
2185 print_indent(depth, ")");
2187 CXChildVisit_Continue
2190 /// Try to extract the clang version to a string
2191 pub(crate) fn extract_clang_version() -> String {
2192 unsafe { cxstring_into_string(clang_getClangVersion()) }
2195 /// A wrapper for the result of evaluating an expression.
2197 pub(crate) struct EvalResult {
2203 /// Evaluate `cursor` and return the result.
2204 pub(crate) fn new(cursor: Cursor) -> Option<Self> {
2205 // Work around https://bugs.llvm.org/show_bug.cgi?id=42532, see:
2206 // * https://github.com/rust-lang/rust-bindgen/issues/283
2207 // * https://github.com/rust-lang/rust-bindgen/issues/1590
2209 let mut found_cant_eval = false;
2211 if c.kind() == CXCursor_TypeRef &&
2212 c.cur_type().canonical_type().kind() == CXType_Unexposed
2214 found_cant_eval = true;
2215 return CXChildVisit_Break;
2218 CXChildVisit_Recurse
2221 if found_cant_eval {
2226 x: unsafe { clang_Cursor_Evaluate(cursor.x) },
2227 ty: cursor.cur_type().canonical_type(),
2231 fn kind(&self) -> CXEvalResultKind {
2232 unsafe { clang_EvalResult_getKind(self.x) }
2235 /// Try to get back the result as a double.
2236 pub(crate) fn as_double(&self) -> Option<f64> {
2239 Some(unsafe { clang_EvalResult_getAsDouble(self.x) })
2245 /// Try to get back the result as an integer.
2246 pub(crate) fn as_int(&self) -> Option<i64> {
2247 if self.kind() != CXEval_Int {
2251 if unsafe { clang_EvalResult_isUnsignedInt(self.x) } != 0 {
2252 let value = unsafe { clang_EvalResult_getAsUnsigned(self.x) };
2253 if value > i64::max_value() as c_ulonglong {
2257 return Some(value as i64);
2260 let value = unsafe { clang_EvalResult_getAsLongLong(self.x) };
2261 if value > i64::max_value() as c_longlong {
2264 if value < i64::min_value() as c_longlong {
2267 #[allow(clippy::unnecessary_cast)]
2271 /// Evaluates the expression as a literal string, that may or may not be
2273 pub(crate) fn as_literal_string(&self) -> Option<Vec<u8>> {
2274 if self.kind() != CXEval_StrLiteral {
2278 let char_ty = self.ty.pointee_type().or_else(|| self.ty.elem_type())?;
2279 match char_ty.kind() {
2280 CXType_Char_S | CXType_SChar | CXType_Char_U | CXType_UChar => {
2282 CStr::from_ptr(clang_EvalResult_getAsStr(self.x))
2284 Some(ret.to_bytes().to_vec())
2286 // FIXME: Support generating these.
2287 CXType_Char16 => None,
2288 CXType_Char32 => None,
2289 CXType_WChar => None,
2295 impl Drop for EvalResult {
2296 fn drop(&mut self) {
2297 unsafe { clang_EvalResult_dispose(self.x) };
2300 /// ABI kinds as defined in
2301 /// <https://github.com/llvm/llvm-project/blob/ddf1de20a3f7db3bca1ef6ba7e6cbb90aac5fd2d/clang/include/clang/Basic/TargetCXXABI.def>
2302 #[derive(Debug, Eq, PartialEq, Copy, Clone)]
2303 pub(crate) enum ABIKind {
2304 /// All the regular targets like Linux, Mac, WASM, etc. implement the Itanium ABI
2306 /// The ABI used when compiling for the MSVC target
2310 /// Target information obtained from libclang.
2312 pub(crate) struct TargetInfo {
2313 /// The target triple.
2314 pub(crate) triple: String,
2315 /// The width of the pointer _in bits_.
2316 pub(crate) pointer_width: usize,
2317 /// The ABI of the target
2318 pub(crate) abi: ABIKind,
2322 /// Tries to obtain target information from libclang.
2323 pub(crate) fn new(tu: &TranslationUnit) -> Self {
2327 let ti = clang_getTranslationUnitTargetInfo(tu.x);
2328 triple = cxstring_into_string(clang_TargetInfo_getTriple(ti));
2329 pointer_width = clang_TargetInfo_getPointerWidth(ti);
2330 clang_TargetInfo_dispose(ti);
2332 assert!(pointer_width > 0);
2333 assert_eq!(pointer_width % 8, 0);
2335 let abi = if triple.contains("msvc") {
2338 ABIKind::GenericItanium
2343 pointer_width: pointer_width as usize,