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 /// This function will run for every extern variable and function. The returned value determines
49 /// the link name in the bindings.
50 fn generated_link_name_override(
51 &self,
52 _item_info: ItemInfo<'_>,
53 ) -> Option<String> {
54 None
55 }
56
57 /// The integer kind an integer macro should have, given a name and the
58 /// value of that macro, or `None` if you want the default to be chosen.
59 fn int_macro(&self, _name: &str, _value: i64) -> Option<IntKind> {
60 None
61 }
62
63 /// This will be run on every string macro. The callback cannot influence the further
64 /// treatment of the macro, but may use the value to generate additional code or configuration.
65 fn str_macro(&self, _name: &str, _value: &[u8]) {}
66
67 /// This will be run on every function-like macro. The callback cannot
68 /// influence the further treatment of the macro, but may use the value to
69 /// generate additional code or configuration.
70 ///
71 /// The first parameter represents the name and argument list (including the
72 /// parentheses) of the function-like macro. The second parameter represents
73 /// the expansion of the macro as a sequence of tokens.
74 fn func_macro(&self, _name: &str, _value: &[&[u8]]) {}
75
76 /// This function should return whether, given an enum variant
77 /// name, and value, this enum variant will forcibly be a constant.
78 fn enum_variant_behavior(
79 &self,
80 _enum_name: Option<&str>,
81 _original_variant_name: &str,
82 _variant_value: EnumVariantValue,
83 ) -> Option<EnumVariantCustomBehavior> {
84 None
85 }
86
87 /// Allows to rename an enum variant, replacing `_original_variant_name`.
88 fn enum_variant_name(
89 &self,
90 _enum_name: Option<&str>,
91 _original_variant_name: &str,
92 _variant_value: EnumVariantValue,
93 ) -> Option<String> {
94 None
95 }
96
97 /// Allows to rename an item, replacing `_original_item_name`.
98 fn item_name(&self, _original_item_name: &str) -> Option<String> {
99 None
100 }
101
102 /// This will be called on every header filename passed to (`Builder::header`)[`crate::Builder::header`].
103 fn header_file(&self, _filename: &str) {}
104
105 /// This will be called on every file inclusion, with the full path of the included file.
106 fn include_file(&self, _filename: &str) {}
107
108 /// This will be called every time `bindgen` reads an environment variable whether it has any
109 /// content or not.
110 fn read_env_var(&self, _key: &str) {}
111
112 /// This will be called to determine whether a particular blocklisted type
113 /// implements a trait or not. This will be used to implement traits on
114 /// other types containing the blocklisted type.
115 ///
116 /// * `None`: use the default behavior
117 /// * `Some(ImplementsTrait::Yes)`: `_name` implements `_derive_trait`
118 /// * `Some(ImplementsTrait::Manually)`: any type including `_name` can't
119 /// derive `_derive_trait` but can implemented it manually
120 /// * `Some(ImplementsTrait::No)`: `_name` doesn't implement `_derive_trait`
121 fn blocklisted_type_implements_trait(
122 &self,
123 _name: &str,
124 _derive_trait: DeriveTrait,
125 ) -> Option<ImplementsTrait> {
126 None
127 }
128
129 /// Provide a list of custom derive attributes.
130 ///
131 /// If no additional attributes are wanted, this function should return an
132 /// empty `Vec`.
133 fn add_derives(&self, _info: &DeriveInfo<'_>) -> Vec<String> {
134 vec![]
135 }
136
137 /// Process a source code comment.
138 fn process_comment(&self, _comment: &str) -> Option<String> {
139 None
140 }
141
142 /// Potentially override the visibility of a composite type field.
143 ///
144 /// Caution: This allows overriding standard C++ visibility inferred by
145 /// `respect_cxx_access_specs`.
146 fn field_visibility(
147 &self,
148 _info: FieldInfo<'_>,
149 ) -> Option<crate::FieldVisibilityKind> {
150 None
151 }
152
153 /// Process a function name that as exactly one `va_list` argument
154 /// to be wrapped as a variadic function with the wrapped static function
155 /// feature.
156 ///
157 /// The returned string is new function name.
158 #[cfg(feature = "experimental")]
159 fn wrap_as_variadic_fn(&self, _name: &str) -> Option<String> {
160 None
161 }
162}
163
164/// Relevant information about a type to which new derive attributes will be added using
165/// [`ParseCallbacks::add_derives`].
166#[derive(Debug)]
167#[non_exhaustive]
168pub struct DeriveInfo<'a> {
169 /// The name of the type.
170 pub name: &'a str,
171 /// The kind of the type.
172 pub kind: TypeKind,
173}
174
175#[derive(Debug, Clone, Copy, PartialEq, Eq)]
176/// The kind of the current type.
177pub enum TypeKind {
178 /// The type is a Rust `struct`.
179 Struct,
180 /// The type is a Rust `enum`.
181 Enum,
182 /// The type is a Rust `union`.
183 Union,
184}
185
186/// A struct providing information about the item being passed to [`ParseCallbacks::generated_name_override`].
187#[non_exhaustive]
188pub struct ItemInfo<'a> {
189 /// The name of the item
190 pub name: &'a str,
191 /// The kind of item
192 pub kind: ItemKind,
193}
194
195/// An enum indicating the kind of item for an ItemInfo.
196#[non_exhaustive]
197pub enum ItemKind {
198 /// A Function
199 Function,
200 /// A Variable
201 Var,
202}
203
204/// Relevant information about a field for which visibility can be determined using
205/// [`ParseCallbacks::field_visibility`].
206#[derive(Debug)]
207#[non_exhaustive]
208pub struct FieldInfo<'a> {
209 /// The name of the type.
210 pub type_name: &'a str,
211 /// The name of the field.
212 pub field_name: &'a str,
213}
214