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)] 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 } 18 19 impl Default for MacroParsingBehavior { default() -> Self20 fn default() -> Self { 21 MacroParsingBehavior::Default 22 } 23 } 24 25 /// A trait to allow configuring different kinds of types in different 26 /// situations. 27 pub trait ParseCallbacks: fmt::Debug { 28 #[cfg(feature = "cli")] 29 #[doc(hidden)] cli_args(&self) -> Vec<String>30 fn cli_args(&self) -> Vec<String> { 31 vec![] 32 } 33 34 /// This function will be run on every macro that is identified. will_parse_macro(&self, _name: &str) -> MacroParsingBehavior35 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. generated_name_override( &self, _item_info: ItemInfo<'_>, ) -> Option<String>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. int_macro(&self, _name: &str, _value: i64) -> Option<IntKind>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. str_macro(&self, _name: &str, _value: &[u8])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. func_macro(&self, _name: &str, _value: &[&[u8]])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. enum_variant_behavior( &self, _enum_name: Option<&str>, _original_variant_name: &str, _variant_value: EnumVariantValue, ) -> Option<EnumVariantCustomBehavior>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`. enum_variant_name( &self, _enum_name: Option<&str>, _original_variant_name: &str, _variant_value: EnumVariantValue, ) -> Option<String>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`. item_name(&self, _original_item_name: &str) -> Option<String>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. include_file(&self, _filename: &str)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` blocklisted_type_implements_trait( &self, _name: &str, _derive_trait: DeriveTrait, ) -> Option<ImplementsTrait>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`. add_derives(&self, _info: &DeriveInfo<'_>) -> Vec<String>117 fn add_derives(&self, _info: &DeriveInfo<'_>) -> Vec<String> { 118 vec![] 119 } 120 121 /// Process a source code comment. process_comment(&self, _comment: &str) -> Option<String>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] 131 pub 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. 140 pub 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] 151 pub 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] 160 pub enum ItemKind { 161 /// A Function 162 Function, 163 /// A Variable 164 Var, 165 } 166