From f1d6f42d3096d5dc9f8cfaf4073c3abd2e75ba64 Mon Sep 17 00:00:00 2001 From: Lucas Franceschino Date: Tue, 14 Nov 2023 12:19:04 +0100 Subject: [PATCH 1/2] feat(macros): init --- src/SUMMARY.md | 2 +- src/contributing/libraries_macros.md | 25 +++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index e6b54ed..f0ce91d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -15,7 +15,7 @@ - [Engine]() - [Backends]() - [Utilities]() - - [Libraries & Macros]() + - [Libraries & Macros](contributing/libraries_macros.md) - [`libcore`]() --- diff --git a/src/contributing/libraries_macros.md b/src/contributing/libraries_macros.md index e69de29..7298cb4 100644 --- a/src/contributing/libraries_macros.md +++ b/src/contributing/libraries_macros.md @@ -0,0 +1,25 @@ +# Libraries + +# Macros and attributes +The hax engine understands only one attribute: `#[_hax::json(PAYLOAD)]`, +where `PAYLOAD` is a JSON serialization of the Rust enum +`hax_lib_macros_types::AttrPayload`. + +Note `#[_hax::json(PAYLOAD)]` is a [tool +attribute](https://github.com/rust-lang/rust/issues/66079): an +attribute that is never expanded. + +In the engine, the OCaml module `Attr_payloads` offers an API to query +attributes easily. The types in crate `hax_lib_macros_types` and +corresponding serializers/deserializers are automatically generated in +OCaml, thus there is no manual parsing involved. + +## User experience +Asking the user to type `#[_hax::json(some_long_json)]` is not very +friendly. Thus, the crate `hax-lib-macros` defines a bunch of [proc +macros](https://doc.rust-lang.org/beta/reference/procedural-macros.html) +that defines nice and simple-to-use macros. Those macro take care of +cooking some `hax_lib_macros_types::AttrPayload` payload(s), then +serialize those payloads to JSON and produce one or more +`#[_hax::json(serialized_pyaload)]` attributes. + From ee4c4335cb8f47a8ca8cf903a382a9d541dc83d0 Mon Sep 17 00:00:00 2001 From: Lucas Franceschino Date: Tue, 14 Nov 2023 15:46:22 +0100 Subject: [PATCH 2/2] Fix typo Co-authored-by: jschneider-bensch <124457079+jschneider-bensch@users.noreply.github.com> --- src/contributing/libraries_macros.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/contributing/libraries_macros.md b/src/contributing/libraries_macros.md index 7298cb4..dfd145c 100644 --- a/src/contributing/libraries_macros.md +++ b/src/contributing/libraries_macros.md @@ -21,5 +21,5 @@ macros](https://doc.rust-lang.org/beta/reference/procedural-macros.html) that defines nice and simple-to-use macros. Those macro take care of cooking some `hax_lib_macros_types::AttrPayload` payload(s), then serialize those payloads to JSON and produce one or more -`#[_hax::json(serialized_pyaload)]` attributes. +`#[_hax::json(serialized_payload)]` attributes.