1//! A public API for more fine-grained customization of bindgen behavior.
2
3pub use crate::ir::analysis::DeriveTrait;
4pub use crate::ir::derive::CanDerive as ImplementsTrait;
5pub use crate::ir::enum_ty::{EnumVariantCustomBehavior, EnumVariantValue};
6pub use crate::ir::int::IntKind;
7use std::fmt;
8
9/// An enum to allow ignoring parsing of macros.
10#[derive(Copy, Clone, Debug, PartialEq, Eq)]
11pub enum MacroParsingBehavior {
12 /// Ignore the macro, generating no code for it, or anything that depends on
13 /// it.
14 Ignore,
15 /// The default behavior bindgen would have otherwise.
16 Default,
17}
18
19impl Default for MacroParsingBehavior {
20 fn default() -> Self {
21 MacroParsingBehavior::Default
22 }
23}
24
25/// A trait to allow configuring different kinds of types in different
26/// situations.
27pub trait ParseCallbacks: fmt::Debug {
28 #[cfg(feature = "cli")]
29 #[doc(hidden)]
30 fn cli_args(&self) -> Vec<String> {
31 vec![]
32 }
33
34 /// This function will be run on every macro that is identified.
35 fn will_parse_macro(&self, _name: &str) -> MacroParsingBehavior {
36 MacroParsingBehavior::Default
37 }
38
39 /// This function will run for every extern variable and function. The returned value determines
40 /// the name visible in the bindings.
41 fn generated_name_override(
42 &self,
43 _item_info: ItemInfo<'_>,
44 ) -> Option<String> {
45 None
46 }
47
48 /// The integer kind an integer macro should have, given a name and the
49 /// value of that macro, or `None` if you want the default to be chosen.
50 fn int_macro(&self, _name: &str, _value: i64) -> Option<IntKind> {
51 None
52 }
53
54 /// This will be run on every string macro. The callback cannot influence the further
55 /// treatment of the macro, but may use the value to generate additional code or configuration.
56 fn str_macro(&self, _name: &str, _value: &[u8]) {}
57
58 /// This will be run on every function-like macro. The callback cannot
59 /// influence the further treatment of the macro, but may use the value to
60 /// generate additional code or configuration.
61 ///
62 /// The first parameter represents the name and argument list (including the
63 /// parentheses) of the function-like macro. The second parameter represents
64 /// the expansion of the macro as a sequence of tokens.
65 fn func_macro(&self, _name: &str, _value: &[&[u8]]) {}
66
67 /// This function should return whether, given an enum variant
68 /// name, and value, this enum variant will forcibly be a constant.
69 fn enum_variant_behavior(
70 &self,
71 _enum_name: Option<&str>,
72 _original_variant_name: &str,
73 _variant_value: EnumVariantValue,
74 ) -> Option<EnumVariantCustomBehavior> {
75 None
76 }
77
78 /// Allows to rename an enum variant, replacing `_original_variant_name`.
79 fn enum_variant_name(
80 &self,
81 _enum_name: Option<&str>,
82 _original_variant_name: &str,
83 _variant_value: EnumVariantValue,
84 ) -> Option<String> {
85 None
86 }
87
88 /// Allows to rename an item, replacing `_original_item_name`.
89 fn item_name(&self, _original_item_name: &str) -> Option<String> {
90 None
91 }
92
93 /// This will be called on every file inclusion, with the full path of the included file.
94 fn include_file(&self, _filename: &str) {}
95
96 /// This will be called to determine whether a particular blocklisted type
97 /// implements a trait or not. This will be used to implement traits on
98 /// other types containing the blocklisted type.
99 ///
100 /// * `None`: use the default behavior
101 /// * `Some(ImplementsTrait::Yes)`: `_name` implements `_derive_trait`
102 /// * `Some(ImplementsTrait::Manually)`: any type including `_name` can't
103 /// derive `_derive_trait` but can implemented it manually
104 /// * `Some(ImplementsTrait::No)`: `_name` doesn't implement `_derive_trait`
105 fn blocklisted_type_implements_trait(
106 &self,
107 _name: &str,
108 _derive_trait: DeriveTrait,
109 ) -> Option<ImplementsTrait> {
110 None
111 }
112
113 /// Provide a list of custom derive attributes.
114 ///
115 /// If no additional attributes are wanted, this function should return an
116 /// empty `Vec`.
117 fn add_derives(&self, _info: &DeriveInfo<'_>) -> Vec<String> {
118 vec![]
119 }
120
121 /// Process a source code comment.
122 fn process_comment(&self, _comment: &str) -> Option<String> {
123 None
124 }
125}
126
127/// Relevant information about a type to which new derive attributes will be added using
128/// [`ParseCallbacks::add_derives`].
129#[derive(Debug)]
130#[non_exhaustive]
131pub struct DeriveInfo<'a> {
132 /// The name of the type.
133 pub name: &'a str,
134 /// The kind of the type.
135 pub kind: TypeKind,
136}
137
138#[derive(Debug, Clone, Copy, PartialEq, Eq)]
139/// The kind of the current type.
140pub enum TypeKind {
141 /// The type is a Rust `struct`.
142 Struct,
143 /// The type is a Rust `enum`.
144 Enum,
145 /// The type is a Rust `union`.
146 Union,
147}
148
149/// An struct providing information about the item being passed to `ParseCallbacks::generated_name_override`.
150#[non_exhaustive]
151pub struct ItemInfo<'a> {
152 /// The name of the item
153 pub name: &'a str,
154 /// The kind of item
155 pub kind: ItemKind,
156}
157
158/// An enum indicating the kind of item for an ItemInfo.
159#[non_exhaustive]
160pub enum ItemKind {
161 /// A Function
162 Function,
163 /// A Variable
164 Var,
165}
166