Debian Codegraph @

.cargo/vendor/bindgen/clang.rs

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