feat: initial impls

Author: AlseinX

.github/workflows/check.yml

@@ -0,0 +1,29 @@
+name: Check
+
+on:
+  push:
+    branches:
+      - slaveholder
+  pull_request:
+    branches:
+      - slaveholder
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Run cargo fmt
+        run: cargo fmt --check --verbose
+
+      - name: Run cargo clippy
+        run: cargo clippy --verbose
+
+      - name: Run tests
+        run: cargo test --verbose

.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  bump-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Bump version
+        run: 'cargo install vproj && vproj ${GITHUB_REF##*/} && git add . && git -c user.name="AlseinX" -c user.email="xyh951115@live.com" commit -am "chore: bump release version ${GITHUB_REF##*/}"'
+
+      - name: Run cargo fmt
+        run: cargo fmt --check --verbose
+
+      - name: Run cargo clippy
+        run: cargo clippy --verbose
+
+      - name: Run tests
+        run: cargo test --verbose
+
+      - name: Publish
+        id: publish-crates
+        uses: katyo/publish-crates@v2
+        with:
+          registry-token: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
+      - name: Publish Result
+        if: fromJSON(steps.publish-crates.outputs.published).*
+        run: |
+          LIST="${{ join(fromJSON(steps.publish-crates.outputs.published).*.name, ', ') }}"
+          echo "Published crates: $LIST"

.gitignore

@@ -0,0 +1,2 @@
+/target
+/Cargo.lock

Cargo.toml

@@ -0,0 +1,36 @@
+[package]
+name = "ffi-enum"
+readme = "README.md"
+version.workspace = true
+description.workspace = true
+homepage.workspace = true
+repository.workspace = true
+documentation.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+keywords.workspace = true
+
+[dependencies]
+macros = { package = "ffi-enum-macros", path = "macros" }
+
+thiserror = "2"
+
+[dev-dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1" }
+
+[workspace]
+members = [".", "macros"]
+resolver = "2"
+
+[workspace.package]
+version = "0.0.0"
+description = "Simply write and use `enum`s like rust native enums, freely passing through ffi"
+homepage = "https://github.com/AlseinX/ffi-enum"
+repository = "https://github.com/AlseinX/ffi-enum"
+documentation = "https://docs.rs/ffi-enum"
+authors = ["AlseinX <xyh951115@live.com>"]
+license = "MIT OR Apache-2.0"
+edition = "2021"
+keywords = ["ffi", "c-abi", "derive", "enum"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AlseinX <xyh951115@live.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,38 @@
+# ffi-enum
+
+Simply write and use `enum`s like rust native enums, freely passing through ffi.
+
+## Why not using `#[repr(C)]` and `#[non_exhaustive]` ?
+
++ Rust's `#[repr(C)]` is not fully equal to a C-abi `enum`, and it is still an **undefined behavior** when an `enum` defined with `#[repr(C)]` recieves a value that is not listed in the definition of `enum`, from ffi.
++ `#[non_exhaustive]` is only designed for inter-crate compatibility, while the compiler might still optimize based on the assumption that the binary pattern of an `enum` value is always in its defined range.
+
+## Why not existing alternatives?
+
+The current alternatives mostly define complex DSL with function macros, which could be hard to read/maintain and not supported by `rustfmt` or `rust-analyzer`, and they do not support derive macros.
+
+While this crate offers a nearly native experience by trying the best to fully mimic the behaviors of native `enums`, despite it requires non-exhaustive matching even inside the defining crate. FFi enums are defined with native rust enum item syntax with full support of formatting, code hint, and auto completion.
+
+```rust
+use ffi_enum::{prelude::*, FfiEnum};
+use serde::{Deserialize, Serialize};
+
+#[ffi_enum]
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Animal {
+    Cat,
+    Dog,
+}
+
+fn main() {
+    let json = serde_json::to_string(&Animal::Cat).unwrap();
+    assert_eq!(json, "\"cat\"");
+    let value: Animal = serde_json::from_str(&json).unwrap();
+    assert_eq!(value, Animal::Cat);
+    let json = serde_json::to_string(&Animal::from(100u8)).unwrap();
+    assert_eq!(json, "\"<Unknown>\"");
+    let value: Animal = serde_json::from_str(&json).unwrap();
+    assert_eq!(value, Animal::UNKNOWN);
+}
+```

examples/derive_serde.rs

@@ -0,0 +1,21 @@
+use ffi_enum::{prelude::*, FfiEnum};
+use serde::{Deserialize, Serialize};
+
+#[ffi_enum]
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Animal {
+    Cat,
+    Dog,
+}
+
+fn main() {
+    let json = serde_json::to_string(&Animal::Cat).unwrap();
+    assert_eq!(json, "\"cat\"");
+    let value: Animal = serde_json::from_str(&json).unwrap();
+    assert_eq!(value, Animal::Cat);
+    let json = serde_json::to_string(&Animal::from(100u8)).unwrap();
+    assert_eq!(json, "\"<Unknown>\"");
+    let value: Animal = serde_json::from_str(&json).unwrap();
+    assert_eq!(value, Animal::UNKNOWN);
+}

macros/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "ffi-enum-macros"
+readme = "README.md"
+version.workspace = true
+description.workspace = true
+homepage.workspace = true
+repository.workspace = true
+documentation.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+keywords.workspace = true
+
+[lib]
+proc-macro = true
+
+[dependencies]
+syn = { version = "2", features = ["full"] }
+quote = "1"
+proc-macro2 = "1"

macros/README.md

@@ -0,0 +1,5 @@
+# ffi-enum-macros
+
+Do not directly use this proc-macro crate.
+
+Take a look at [ffi-enum](https://crates.io/crates/ffi-enum)

macros/src/delegate.rs

@@ -0,0 +1,157 @@
+use proc_macro2::{Span, TokenStream};
+use quote::quote_spanned;
+use syn::{
+    Attribute, Expr, ExprLit, Ident, Lit, Meta, MetaNameValue, Path, PathArguments, PathSegment,
+    Token, Type,
+};
+
+use crate::utils::extract_meta_from_lists;
+
+struct Context<'a, 'b> {
+    name: &'a str,
+    span: Span,
+    target: &'a Type,
+    origin: &'a Type,
+    attrs: &'a [Attribute],
+    impls: &'b mut TokenStream,
+}
+
+impl Context<'_, '_> {
+    fn debug(self) {
+        let Self {
+            span,
+            target,
+            origin,
+            impls,
+            ..
+        } = self;
+
+        impls.extend(quote_spanned! { span =>
+            impl ::core::fmt::Debug for #target {
+                #[inline(always)]
+                fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
+                    if let Ok(origin) = <#origin as ::core::convert::TryFrom<#target>>::try_from(*self) {
+                        <#origin as ::core::fmt::Debug>::fmt(&origin, f)?;
+                        write!(f, "({})", self.repr)
+                    } else {
+                        write!(f, "<Unknown>({})", self.repr)
+                    }
+                }
+            }
+        })
+    }
+
+    fn serialize(self) {
+        let Self {
+            name,
+            target,
+            origin,
+            span,
+            attrs,
+            impls,
+            ..
+        } = self;
+
+        let serde = locate_serde(attrs);
+
+        impls.extend(quote_spanned! { span =>
+            impl #serde::Serialize for #target {
+                #[inline(always)]
+                fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+                where
+                    S: #serde::Serializer,
+                {
+                    if let Ok(origin) = <#origin as ::core::convert::TryFrom<#target>>::try_from(*self) {
+                        <#origin as #serde::Serialize>::serialize(&origin, serializer)
+                    } else {
+                        <S as #serde::Serializer>::serialize_unit_variant(serializer, #name, <#target as ::ffi_enum::FfiEnum>::UNKNOWN.repr as _, "<Unknown>")
+                    }
+                }
+            }
+        });
+    }
+
+    fn deserialize(self) {
+        let Self {
+            target,
+            origin,
+            span,
+            attrs,
+            impls,
+            ..
+        } = self;
+        let serde = locate_serde(attrs);
+
+        impls.extend(quote_spanned! { span =>
+            impl<'de> #serde::Deserialize<'de> for #target {
+                #[inline(always)]
+                fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+                where
+                    D: #serde::Deserializer<'de>,
+                {
+                    Ok(<#origin as #serde::Deserialize>::deserialize(deserializer).map(Into::into).unwrap_or_else(|_|<#target as ::ffi_enum::FfiEnum>::UNKNOWN))
+                }
+            }
+        });
+    }
+}
+
+fn locate_serde(attrs: &[Attribute]) -> Path {
+    extract_meta_from_lists(attrs, "serde")
+        .find_map(|meta| {
+            let MetaNameValue { path, value, .. } = meta.require_name_value().ok()?;
+            if !path.is_ident("crate") {
+                return None;
+            }
+            let Expr::Lit(ExprLit {
+                lit: Lit::Str(s), ..
+            }) = value
+            else {
+                return None;
+            };
+            s.parse::<Path>().ok()
+        })
+        .unwrap_or_else(|| Path {
+            leading_colon: Some(Token![::](Span::mixed_site())),
+            segments: [PathSegment {
+                ident: Ident::new("serde", Span::mixed_site()),
+                arguments: PathArguments::None,
+            }]
+            .into_iter()
+            .collect(),
+        })
+}
+
+pub fn delegate<'a, 'b>(
+    name: &'a str,
+    target: &'a Type,
+    origin: &'a Type,
+    attrs: &'a [Attribute],
+    impls: &'b mut TokenStream,
+) -> impl FnMut(Meta) + use<'a, 'b> {
+    |meta| {
+        let Meta::Path(path) = meta else {
+            return;
+        };
+
+        let Some(ident) = path.get_ident() else {
+            return;
+        };
+
+        let context = Context {
+            name,
+            span: ident.span().resolved_at(Span::mixed_site()),
+            target,
+            origin,
+            attrs,
+            impls,
+        };
+
+        match ident.to_string().as_str() {
+            "Debug" => context.debug(),
+            "Serialize" => context.serialize(),
+            "Deserialize" => context.deserialize(),
+            _ => return,
+        };
+    }
+}