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