third_party/rust/bindgen/callbacks.rs

   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 {
  20     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)]
  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]
 168 pub 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.
 177 pub 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]
 188 pub 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]
 197 pub 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]
 208 pub 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 }