Source code
Revision control
Copy as Markdown
Other Tools
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
use askama::Template;
use heck::ToSnakeCase;
use indexmap::{IndexMap, IndexSet};
use serde::Deserialize;
use crate::bindings::python::filters;
use uniffi_pipeline::Node;
/// Initial IR, this stores the metadata and other data
#[derive(Debug, Clone, Node)]
pub struct Root {
/// In library mode, the library path the user passed to us
pub cdylib: Option<String>,
pub namespaces: IndexMap<String, Namespace>,
}
#[derive(Debug, Clone, Node, Template)]
#[template(syntax = "py", escape = "none", path = "Module.py")]
pub struct Namespace {
pub name: String,
pub crate_name: String,
pub config_toml: Option<String>,
pub config: PythonConfig,
pub docstring: Option<String>,
pub functions: Vec<Function>,
pub type_definitions: Vec<TypeDefinition>,
pub ffi_definitions: IndexSet<FfiDefinition>,
pub checksums: Vec<Checksum>,
pub ffi_rustbuffer_alloc: RustFfiFunctionName,
pub ffi_rustbuffer_from_bytes: RustFfiFunctionName,
pub ffi_rustbuffer_free: RustFfiFunctionName,
pub ffi_rustbuffer_reserve: RustFfiFunctionName,
pub ffi_uniffi_contract_version: RustFfiFunctionName,
// Correct contract version value
pub correct_contract_version: String,
pub string_type_node: TypeNode,
pub cdylib_name: String,
pub has_async_fns: bool,
pub has_callback_interface: bool,
pub has_async_callback_method: bool,
pub imports: Vec<String>,
pub exported_names: Vec<String>,
}
// Config options to customize the generated python.
#[derive(Debug, Clone, Deserialize, Node)]
pub struct PythonConfig {
pub(super) cdylib_name: Option<String>,
#[serde(default)]
pub custom_types: IndexMap<String, CustomTypeConfig>,
#[serde(default)]
pub external_packages: IndexMap<String, String>,
}
#[derive(Debug, Clone, Deserialize, Node)]
#[serde(default)]
pub struct CustomTypeConfig {
pub imports: Option<Vec<String>>,
pub type_name: Option<String>, // b/w compat alias for lift
pub into_custom: String, // b/w compat alias for lift
pub lift: String,
pub from_custom: String, // b/w compat alias for lower
pub lower: String,
}
#[derive(Debug, Clone, Node)]
pub struct Function {
pub callable: Callable,
pub docstring: Option<String>,
}
#[derive(Debug, Clone, Node)]
pub enum TypeDefinition {
Interface(Interface),
CallbackInterface(CallbackInterface),
Record(Record),
Enum(Enum),
Custom(CustomType),
/// Type that doesn't contain any other type
Simple(TypeNode),
/// Compound types
Optional(OptionalType),
Sequence(SequenceType),
Map(MapType),
/// User types that are defined in another crate
External(ExternalType),
}
#[derive(Debug, Clone, Node)]
pub struct Constructor {
pub callable: Callable,
pub docstring: Option<String>,
}
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub struct Method {
pub callable: Callable,
pub docstring: Option<String>,
}
/// Common data from Function/Method/Constructor
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub struct Callable {
pub name: String,
pub is_async: bool,
pub async_data: Option<AsyncData>,
pub kind: CallableKind,
pub arguments: Vec<Argument>,
pub return_type: ReturnType,
pub throws_type: ThrowsType,
pub checksum: Option<u16>,
pub ffi_func: RustFfiFunctionName,
}
#[allow(clippy::large_enum_variant)]
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub enum CallableKind {
/// Toplevel function
Function,
/// Interface/Trait interface method
Method { self_type: TypeNode },
/// Interface constructor
Constructor {
interface_name: String,
primary: bool,
},
/// Method inside a VTable or a CallbackInterface
///
/// For trait interfaces this only applies to the Callables inside the `vtable.methods` field.
/// Callables inside `Interface::methods` will still be `Callable::Method`.
VTableMethod { trait_name: String },
}
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub struct ReturnType {
pub ty: Option<TypeNode>,
pub type_name: String,
}
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub struct ThrowsType {
pub ty: Option<TypeNode>,
}
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub struct AsyncData {
// FFI types for async Rust functions
pub ffi_rust_future_poll: RustFfiFunctionName,
pub ffi_rust_future_cancel: RustFfiFunctionName,
pub ffi_rust_future_free: RustFfiFunctionName,
pub ffi_rust_future_complete: RustFfiFunctionName,
// FFI types for async foreign functions
pub ffi_foreign_future_complete: FfiFunctionTypeName,
pub ffi_foreign_future_result: FfiStructName,
}
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub struct Argument {
pub name: String,
pub ty: TypeNode,
pub optional: bool,
pub default: Option<DefaultValueNode>,
}
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub enum DefaultValue {
Default(TypeNode),
Literal(LiteralNode),
}
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub struct DefaultValueNode {
#[node(wraps)]
pub default: DefaultValue,
/// The default value rendered as a Python string
pub py_default: String,
/// The default value as specified as a literal in function args.
pub arg_literal: String,
/// Convenience - whether the arg literal is our literal.
pub is_arg_literal: bool,
}
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub struct LiteralNode {
pub lit: Literal,
/// The literal rendered as a Python string
pub py_lit: String,
}
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub enum Literal {
Boolean(bool),
String(String),
// Integers are represented as the widest representation we can.
// Number formatting vary with language and radix, so we avoid a lot of parsing and
// formatting duplication by using only signed and unsigned variants.
UInt(u64, Radix, TypeNode),
Int(i64, Radix, TypeNode),
// Pass the string representation through as typed in the UDL.
// This avoids a lot of uncertainty around precision and accuracy,
// though bindings for languages less sophisticated number parsing than WebIDL
// will have to do extra work.
Float(String, TypeNode),
Enum(String, TypeNode),
EmptySequence,
EmptyMap,
None,
Some { inner: Box<DefaultValue> },
}
// Represent the radix of integer literal values.
// We preserve the radix into the generated bindings for readability reasons.
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub enum Radix {
Decimal = 10,
Octal = 8,
Hexadecimal = 16,
}
#[derive(Debug, Clone, Node)]
pub struct Record {
pub name: String,
pub fields_kind: FieldsKind,
pub fields: Vec<Field>,
pub docstring: Option<String>,
pub self_type: TypeNode,
pub constructors: Vec<Constructor>,
pub methods: Vec<Method>,
pub uniffi_trait_methods: UniffiTraitMethods,
}
#[derive(Debug, Clone, Node)]
pub enum FieldsKind {
Unit,
Named,
Unnamed,
}
#[derive(Debug, Clone, Node)]
pub struct Field {
pub name: String,
pub ty: TypeNode,
pub default: Option<DefaultValueNode>,
pub docstring: Option<String>,
}
#[derive(Debug, Clone, Node)]
pub enum EnumShape {
Enum,
Error { flat: bool },
}
#[derive(Debug, Clone, Node)]
pub struct Enum {
pub name: String,
/// Is this a "flat" enum -- one with no associated data
pub is_flat: bool,
pub shape: EnumShape,
pub variants: Vec<Variant>,
pub meta_discr_type: Option<TypeNode>,
pub discr_type: TypeNode,
pub docstring: Option<String>,
pub self_type: TypeNode,
pub constructors: Vec<Constructor>,
pub methods: Vec<Method>,
pub uniffi_trait_methods: UniffiTraitMethods,
}
#[derive(Debug, Clone, Node)]
pub struct Variant {
pub name: String,
pub meta_discr: Option<LiteralNode>,
pub discr: LiteralNode,
pub fields_kind: FieldsKind,
pub fields: Vec<Field>,
pub docstring: Option<String>,
}
#[derive(Debug, Clone, Node)]
pub struct Interface {
pub name: String,
pub base_classes: Vec<String>,
pub protocol: Protocol,
pub docstring: Option<String>,
pub constructors: Vec<Constructor>,
pub has_primary_constructor: bool,
pub methods: Vec<Method>,
pub uniffi_trait_methods: UniffiTraitMethods,
pub trait_impls: Vec<ObjectTraitImpl>,
pub imp: ObjectImpl,
pub self_type: TypeNode,
pub vtable: Option<VTable>,
pub ffi_func_clone: RustFfiFunctionName,
pub ffi_func_free: RustFfiFunctionName,
}
#[derive(Debug, Clone, Node)]
pub struct Protocol {
pub name: String,
pub base_classes: Vec<String>,
pub docstring: Option<String>,
pub methods: Vec<Method>,
}
#[derive(Debug, Clone, Node)]
pub struct CallbackInterface {
pub name: String,
pub docstring: Option<String>,
pub protocol: Protocol,
pub vtable: VTable,
pub methods: Vec<Method>,
pub self_type: TypeNode,
}
#[derive(Debug, Clone, Node)]
pub struct VTable {
/// Vtable struct. This has field for each callback interface method that stores a function
/// pointer for that method.
pub struct_type: FfiTypeNode,
/// Name of the interface/callback interface that this vtable is for
pub interface_name: String,
/// Rust FFI function to initialize the vtable.
///
/// Foreign code should call this function, passing it a pointer to the VTable struct.
pub init_fn: RustFfiFunctionName,
pub clone_fn_type: FfiFunctionTypeName,
pub free_fn_type: FfiFunctionTypeName,
pub methods: Vec<VTableMethod>,
}
/// Single method in a vtable
#[derive(Debug, Clone, Node)]
pub struct VTableMethod {
pub callable: Callable,
/// FfiType::Function type that corresponds to the method
pub ffi_type: FfiTypeNode,
pub ffi_default_value: String,
}
#[derive(Debug, Clone, Node)]
pub struct ObjectTraitImpl {
pub ty: TypeNode,
pub trait_ty: TypeNode,
}
#[derive(Debug, Clone, Node)]
pub struct CustomType {
pub name: String,
pub builtin: TypeNode,
pub docstring: Option<String>,
pub config: Option<CustomTypeConfig>,
pub self_type: TypeNode,
}
#[derive(Debug, Clone, Node)]
pub struct OptionalType {
pub inner: TypeNode,
pub self_type: TypeNode,
}
#[derive(Debug, Clone, Node)]
pub struct SequenceType {
pub inner: TypeNode,
pub self_type: TypeNode,
}
#[derive(Debug, Clone, Node)]
pub struct MapType {
pub key: TypeNode,
pub value: TypeNode,
pub self_type: TypeNode,
}
#[derive(Debug, Clone, Node)]
pub struct ExternalType {
pub namespace: String,
pub name: String,
pub self_type: TypeNode,
}
/// Wrap `Type` so that we can add extra fields that are set for all variants.
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub struct TypeNode {
pub ty: Type,
pub canonical_name: String,
pub is_used_as_error: bool,
pub type_name: String,
pub ffi_converter_name: String,
pub ffi_type: FfiTypeNode,
}
/// Like `TypeNode` but for FFI types.
///
/// This exists so that language bindings generators can add extra fields
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub struct FfiTypeNode {
pub ty: FfiType,
pub type_name: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Hash, Node)]
pub enum Type {
// Primitive types.
UInt8,
Int8,
UInt16,
Int16,
UInt32,
Int32,
UInt64,
Int64,
Float32,
Float64,
Boolean,
String,
Bytes,
Timestamp,
Duration,
// Structurally recursive types.
Optional {
inner_type: Box<Type>,
},
Sequence {
inner_type: Box<Type>,
},
Map {
key_type: Box<Type>,
value_type: Box<Type>,
},
// User defined types in the API
Interface {
namespace: String,
/// Python package name for external types
external_package_name: Option<String>,
name: String,
imp: ObjectImpl,
},
Record {
namespace: String,
external_package_name: Option<String>,
name: String,
},
Enum {
namespace: String,
external_package_name: Option<String>,
name: String,
},
CallbackInterface {
namespace: String,
external_package_name: Option<String>,
name: String,
},
Custom {
namespace: String,
external_package_name: Option<String>,
name: String,
builtin: Box<Type>,
},
}
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub enum ObjectImpl {
// A single Rust type
Struct,
// A trait that's can be implemented by Rust types
Trait,
// A trait + a callback interface -- can be implemented by both Rust and foreign types.
CallbackTrait,
}
/// flattened uniffi_traits.
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub struct UniffiTraitMethods {
pub debug_fmt: Option<Method>,
pub display_fmt: Option<Method>,
pub eq_eq: Option<Method>,
pub eq_ne: Option<Method>,
pub hash_hash: Option<Method>,
pub ord_cmp: Option<Method>,
}
#[derive(Debug, Clone, Node, Eq, PartialEq, Hash)]
pub enum FfiDefinition {
/// FFI Function exported in the Rust library
RustFunction(FfiFunction),
/// FFI Function definition used in the interface, language, for example a callback interface method.
FunctionType(FfiFunctionType),
/// Struct definition used in the interface, for example a callback interface Vtable.
Struct(FfiStruct),
}
/// Name of a FFI function from the Rust library
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub struct RustFfiFunctionName(pub String);
/// Name of an FfiStruct
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub struct FfiStructName(pub String);
/// Name of an FfiFunctionType (i.e. a function pointer type)
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub struct FfiFunctionTypeName(pub String);
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub struct FfiFunction {
pub name: RustFfiFunctionName,
pub is_async: bool,
pub async_data: Option<AsyncData>,
pub arguments: Vec<FfiArgument>,
pub return_type: FfiReturnType,
pub has_rust_call_status_arg: bool,
pub kind: FfiFunctionKind,
}
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub enum FfiFunctionKind {
Scaffolding,
ObjectClone,
ObjectFree,
RustFuturePoll,
RustFutureComplete,
RustFutureCancel,
RustFutureFree,
RustBufferFromBytes,
RustBufferFree,
RustBufferAlloc,
RustBufferReserve,
RustVtableInit,
UniffiContractVersion,
Checksum,
}
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub struct FfiFunctionType {
pub name: FfiFunctionTypeName,
pub arguments: Vec<FfiArgument>,
pub return_type: FfiReturnType,
pub has_rust_call_status_arg: bool,
}
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub struct FfiReturnType {
pub ty: Option<FfiTypeNode>,
}
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub struct FfiStruct {
pub name: FfiStructName,
pub fields: Vec<FfiField>,
}
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub struct FfiField {
pub name: String,
pub ty: FfiTypeNode,
}
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub struct FfiArgument {
pub name: String,
pub ty: FfiTypeNode,
}
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub enum FfiType {
// N.B. there are no booleans at this layer, since they cause problems for JNA.
UInt8,
Int8,
UInt16,
Int16,
UInt32,
Int32,
UInt64,
Int64,
Float32,
Float64,
/// A byte buffer allocated by rust, and owned by whoever currently holds it.
/// If you've got one of these, you must either call the appropriate rust function to free it
/// or pass it to someone that will.
///
/// For user-defined types like Record, Enum, CustomType, etc., the inner value will be the
/// module name for that type. This is needed for some languages, because each module
/// defines a different RustBuffer type and using the wrong one will result in a type
/// error.
///
/// For builtin types like String, this is always None. It's safe to assume that the
/// RustBuffer is for the local module -- at least this has been true for all our languages
/// so far, maybe we should revisit this.
RustBuffer(Option<String>),
/// A borrowed reference to some raw bytes owned by foreign language code.
/// The provider of this reference must keep it alive for the duration of the receiving call.
ForeignBytes,
/// Value for a FfiDefinition::FunctionType.
Function(FfiFunctionTypeName),
/// Pointer to a FFI struct (e.g. a VTable). The inner value matches one of the struct
/// definitions in [crate::ComponentInterface::ffi_definitions].
Struct(FfiStructName),
/// Opaque 64-bit handle
///
/// These are used to pass objects across the FFI.
Handle(HandleKind),
RustCallStatus,
/// Const pointer to an FfiType.
Reference(Box<FfiType>),
/// Mutable pointer to an FfiType.
MutReference(Box<FfiType>),
/// Opaque pointer
VoidPointer,
}
#[derive(Debug, Clone, Node, PartialEq, Eq, Hash)]
pub enum HandleKind {
RustFuture,
ForeignFuture,
ForeignFutureCallbackData,
StructInterface {
module_name: String,
interface_name: String,
},
TraitInterface {
module_name: String,
interface_name: String,
},
}
#[derive(Debug, Clone, Node)]
pub struct Checksum {
pub fn_name: RustFfiFunctionName,
pub checksum: u16,
}
impl Callable {
pub fn is_method(&self) -> bool {
matches!(self.kind, CallableKind::Method { .. })
}
pub fn self_type(&self) -> Option<TypeNode> {
match &self.kind {
CallableKind::Method { self_type, .. } => Some(self_type.clone()),
_ => None,
}
}
pub fn is_primary_constructor(&self) -> bool {
matches!(self.kind, CallableKind::Constructor { primary: true, .. })
}
}
impl CustomTypeConfig {
fn lift(&self, name: &str) -> String {
let converter = if self.lift.is_empty() {
&self.into_custom
} else {
&self.lift
};
converter.replace("{}", name)
}
fn lower(&self, name: &str) -> String {
let converter = if self.lower.is_empty() {
&self.from_custom
} else {
&self.lower
};
converter.replace("{}", name)
}
}
impl Variant {
fn has_unnamed_fields(&self) -> bool {
matches!(self.fields_kind, FieldsKind::Unnamed)
}
}