From 8e63eef65d616b4d8cfb584358fcdbfbc47e54a5 Mon Sep 17 00:00:00 2001
From: Benjamin Bannier <benjamin.bannier@corelight.com>
Date: Mon, 11 Mar 2024 10:34:58 +0100
Subject: [PATCH] Expand documentation on exporting Spicy types

---
 devel/spicy/reference.rst | 85 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/devel/spicy/reference.rst b/devel/spicy/reference.rst
index 4e6716a10..5bcbe66c0 100644
--- a/devel/spicy/reference.rst
+++ b/devel/spicy/reference.rst
@@ -602,6 +602,91 @@ optional on the Zeek-side, as they may not have been set during
 parsing. Unit variables are non-optional by default, unless declared
 as ``&optional`` in Spicy.
 
+.. _spicy_unit_export:
+
+Controlling created Zeek types
+""""""""""""""""""""""""""""""
+
+If needed the automatic unit type exporting described above can be customized. The general syntax for this is
+
+.. code-block:: spicy-evt
+
+    export SPICY_ID [with { [SIPCY_FIELD_NAME [&log], ]... }];
+    export SPICY_ID [as ZEEK_ID (with { [SIPCY_FIELD_NAME [&log], ]...) }];
+
+.. rubric:: Controlling exported fields
+
+Assume we are given a Spicy unit type ``foo::X``
+
+.. code-block:: spicy
+
+    module foo;
+
+    public type X = unit {
+        x: uint8;
+        y: uint8;
+        z: uint8;
+    };
+
+To create a Zeek type with only the field ``x`` to following ``export`` statements are equivalent:
+
+.. code-block:: spicy-evt
+
+    export foo::X with { y, z };
+    export foo::X as foo::X with { y, z };
+    export foo::X without { x };
+    export foo::X as foo::X without { x };
+
+.. rubric:: Adding Zeek ``&log`` attributes to created Zeek types
+
+Data intended to be written to Zeek log streams needs to be marked ``&log``. We
+can trigger creating of this attribute in exported types either per-field or
+for the whole ``record``.
+
+The forms
+
+.. code-block:: spicy-evt
+
+    export foo::X &log;
+    export foo::X as foo::X &log;
+
+both create a Zeek type
+
+.. code-block:: zeek
+
+    module foo;
+
+    export {
+
+      type X: record {
+        x: count &optional &log;
+        y: count &optional &log;
+        z: count &optional &log;
+      };
+
+    }
+
+To mark individual fields ``&log`` we would use the attribute on the respective fields, e.g.,
+
+.. code-block:: spicy-evt
+
+    export foo::X with { x &log, y, z };
+    export foo::X as foo::X with { x &log, y, z };
+
+.. code-block:: zeek
+
+    module foo;
+
+    export {
+
+      type X: record {
+        x: count &optional &log;
+        y: count &optional;
+        z: count &optional;
+      };
+
+    }
+
 .. _spicy_struct:
 
 Struct Types