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