Debian Codegraph @

.cargo/vendor/bindgen/callbacks.rs

raw
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 file inclusion, with the full path of the included file.
103 fn include_file(&self, _filename: &str) {}
104
105 /// This will be called every time `bindgen` reads an environment variable whether it has any
106 /// content or not.
107 fn read_env_var(&self, _key: &str) {}
108
109 /// This will be called to determine whether a particular blocklisted type
110 /// implements a trait or not. This will be used to implement traits on
111 /// other types containing the blocklisted type.
112 ///
113 /// * `None`: use the default behavior
114 /// * `Some(ImplementsTrait::Yes)`: `_name` implements `_derive_trait`
115 /// * `Some(ImplementsTrait::Manually)`: any type including `_name` can't
116 /// derive `_derive_trait` but can implemented it manually
117 /// * `Some(ImplementsTrait::No)`: `_name` doesn't implement `_derive_trait`
118 fn blocklisted_type_implements_trait(
119 &self,
120 _name: &str,
121 _derive_trait: DeriveTrait,
122 ) -> Option<ImplementsTrait> {
123 None
124 }
125
126 /// Provide a list of custom derive attributes.
127 ///
128 /// If no additional attributes are wanted, this function should return an
129 /// empty `Vec`.
130 fn add_derives(&self, _info: &DeriveInfo<'_>) -> Vec<String> {
131 vec![]
132 }
133
134 /// Process a source code comment.
135 fn process_comment(&self, _comment: &str) -> Option<String> {
136 None
137 }
138 }
139
140 /// Relevant information about a type to which new derive attributes will be added using
141 /// [`ParseCallbacks::add_derives`].
142 #[derive(Debug)]
143 #[non_exhaustive]
144 pub struct DeriveInfo<'a> {
145 /// The name of the type.
146 pub name: &'a str,
147 /// The kind of the type.
148 pub kind: TypeKind,
149 }
150
151 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
152 /// The kind of the current type.
153 pub enum TypeKind {
154 /// The type is a Rust `struct`.
155 Struct,
156 /// The type is a Rust `enum`.
157 Enum,
158 /// The type is a Rust `union`.
159 Union,
160 }
161
162 /// A struct providing information about the item being passed to [`ParseCallbacks::generated_name_override`].
163 #[non_exhaustive]
164 pub struct ItemInfo<'a> {
165 /// The name of the item
166 pub name: &'a str,
167 /// The kind of item
168 pub kind: ItemKind,
169 }
170
171 /// An enum indicating the kind of item for an ItemInfo.
172 #[non_exhaustive]
173 pub enum ItemKind {
174 /// A Function
175 Function,
176 /// A Variable
177 Var,
178 }