Add annotation for getting field as Rust Option (#403)

* Add annotation for getting field as Rust Option

Given

    struct Test {
        field @0 :Text $Rust.getOption;
    }

you get getters like so

    assert_eq!(struct_with.get_field(), Some("foo"));
    assert_eq!(struct_without.get_field(), None));

The setters are unchanged to match the Rust convention.

Fixes #249.

* Fix typo

* Support asOption on AnyPointer

* use is_pointer_field_null instead of get_pointer_field(...).is_null

* Fix bug in StructReader::is_pointer_field_null

* add ::core prefix

* Make builder getters return Option<Builder>

* Rename to Rust.option

* Fix: forgot to rename annotation in test

Author: dzfranklin

capnp/src/private/layout.rs

@@ -3479,6 +3479,15 @@ impl<'a> StructReader<'a> {
         }
     }
 
+    #[inline]
+    pub fn is_pointer_field_null(&self, ptr_index: WirePointerCount) -> bool {
+        if ptr_index < self.pointer_count as WirePointerCount {
+            unsafe { (*self.pointers.add(ptr_index)).is_null() }
+        } else {
+            true
+        }
+    }
+
     pub fn total_size(&self) -> Result<MessageSize> {
         let mut result = MessageSize {
             word_count: u64::from(wire_helpers::round_bits_up_to_words(u64::from(

capnpc/rust.capnp

@@ -26,3 +26,26 @@ annotation parentModule @0xabee386cd1450364 (file) :Text;
 #      }
 #    }
 #  }
+
+annotation option @0xabfef22c4ee1964e (field) :Void;
+# Make the generated getters return Option<T> instead of T. Supported on
+# pointer types (e.g. structs, lists, and blobs).
+#
+# Capnp pointer types are nullable. Normally get_field will return the default
+# value if the field isn't set. With this annotation you get Some(...) when
+# the field is set and None when it isn't.
+#
+# Given
+#
+#     struct Test {
+#         field @0 :Text $Rust.option;
+#     }
+#
+# you get getters like so
+#
+#     assert_eq!(struct_with.get_field(), Some("foo"));
+#     assert_eq!(struct_without.get_field(), None));
+#
+# The setters are unchanged to match the Rust convention.
+#
+# Note: Support for this annotation on interfaces isn't implemented yet.

capnpc/src/codegen.rs

@@ -489,6 +489,7 @@ fn module_name(camel_case: &str) -> String {
 // Annotation IDs, as defined in rust.capnp.
 const NAME_ANNOTATION_ID: u64 = 0xc2fe4c6d100166d0;
 const PARENT_MODULE_ANNOTATION_ID: u64 = 0xabee386cd1450364;
+const OPTION_ANNOTATION_ID: u64 = 0xabfef22c4ee1964e;
 
 fn name_annotation_value(annotation: schema_capnp::annotation::Reader) -> capnp::Result<&str> {
     if let schema_capnp::value::Text(t) = annotation.get_value()?.which()? {
@@ -553,6 +554,32 @@ fn capnp_name_to_rust_name(capnp_name: &str, name_kind: NameKind) -> String {
     }
 }
 
+fn is_option_field(field: schema_capnp::field::Reader) -> capnp::Result<bool> {
+    use capnp::schema_capnp::*;
+
+    let enabled = field
+        .get_annotations()?
+        .iter()
+        .any(|a| a.get_id() == OPTION_ANNOTATION_ID);
+
+    if enabled {
+        let supported = match field.which()? {
+            field::Which::Group(_) => false,
+            field::Which::Slot(field) => {
+                let ty = field.get_type()?;
+                ty.is_pointer()? && !matches!(ty.which()?, type_::Interface(_))
+            }
+        };
+        if !supported {
+            return Err(capnp::Error::failed(
+                "$Rust.option annotation only supported on pointer fields (support for optional interfaces isn't implemented yet)".to_string(),
+            ));
+        }
+    }
+
+    Ok(enabled)
+}
+
 fn prim_default(value: &schema_capnp::value::Reader) -> ::capnp::Result<Option<String>> {
     use capnp::schema_capnp::value;
     match value.which()? {
@@ -665,37 +692,46 @@ pub fn getter_text(
                 offset: usize,
                 default: T,
                 zero: T,
-            ) -> FormattedText {
+            ) -> String {
                 if default == zero {
-                    Line(format!("self.{member}.get_data_field::<{typ}>({offset})"))
+                    format!("self.{member}.get_data_field::<{typ}>({offset})")
                 } else {
-                    Line(format!(
-                        "self.{member}.get_data_field_mask::<{typ}>({offset}, {default})"
-                    ))
+                    format!("self.{member}.get_data_field_mask::<{typ}>({offset}, {default})")
                 }
             }
 
             let raw_type = reg_field.get_type()?;
-            let typ = raw_type.type_string(ctx, module)?;
+            let inner_type = raw_type.type_string(ctx, module)?;
             let default_value = reg_field.get_default_value()?;
             let default = default_value.which()?;
             let default_name = format!(
                 "DEFAULT_{}",
                 snake_to_upper_case(&camel_to_snake_case(get_field_name(*field)?))
             );
+            let should_get_option = is_option_field(*field)?;
 
-            let mut result_type = match raw_type.which()? {
-                type_::Enum(_) => fmt!(ctx, "::core::result::Result<{typ},{capnp}::NotInSchema>"),
-                type_::AnyPointer(_) if !raw_type.is_parameter()? => typ.clone(),
-                type_::Interface(_) => {
+            let typ = if should_get_option {
+                format!("Option<{}>", inner_type)
+            } else {
+                inner_type
+            };
+
+            let (is_fallible, mut result_type) = match raw_type.which()? {
+                type_::Enum(_) => (
+                    true,
+                    fmt!(ctx, "::core::result::Result<{typ},{capnp}::NotInSchema>"),
+                ),
+                type_::AnyPointer(_) if !raw_type.is_parameter()? => (false, typ.clone()),
+                type_::Interface(_) => (
+                    true,
                     fmt!(
                         ctx,
                         "{capnp}::Result<{}>",
                         raw_type.type_string(ctx, Leaf::Client)?
-                    )
-                }
-                _ if raw_type.is_prim()? => typ.clone(),
-                _ => fmt!(ctx, "{capnp}::Result<{typ}>"),
+                    ),
+                ),
+                _ if raw_type.is_prim()? => (false, typ.clone()),
+                _ => (true, fmt!(ctx, "{capnp}::Result<{typ}>")),
             };
 
             if is_fn {
@@ -706,80 +742,114 @@ pub fn getter_text(
                 }
             }
 
-            let getter_code = match (raw_type.which()?, default) {
+            let getter_fragment = match (raw_type.which()?, default) {
                 (type_::Void(()), value::Void(())) => {
                     if is_fn {
-                        Line("".to_string())
+                        "".to_string()
                     } else {
-                        Line("()".to_string())
+                        "()".to_string()
                     }
-                },
+                }
                 (type_::Bool(()), value::Bool(b)) => {
                     if b {
-                        Line(format!("self.{member}.get_bool_field_mask({offset}, true)"))
+                        format!("self.{member}.get_bool_field_mask({offset}, true)")
                     } else {
-                        Line(format!("self.{member}.get_bool_field({offset})"))
+                        format!("self.{member}.get_bool_field({offset})")
                     }
                 }
                 (type_::Int8(()), value::Int8(i)) => primitive_case(&typ, &member, offset, i, 0),
                 (type_::Int16(()), value::Int16(i)) => primitive_case(&typ, &member, offset, i, 0),
                 (type_::Int32(()), value::Int32(i)) => primitive_case(&typ, &member, offset, i, 0),
                 (type_::Int64(()), value::Int64(i)) => primitive_case(&typ, &member, offset, i, 0),
                 (type_::Uint8(()), value::Uint8(i)) => primitive_case(&typ, &member, offset, i, 0),
-                (type_::Uint16(()), value::Uint16(i)) => primitive_case(&typ, &member, offset, i, 0),
-                (type_::Uint32(()), value::Uint32(i)) => primitive_case(&typ, &member, offset, i, 0),
-                (type_::Uint64(()), value::Uint64(i)) => primitive_case(&typ, &member, offset, i, 0),
-                (type_::Float32(()), value::Float32(f)) =>
-                    primitive_case(&typ, &member, offset, f.to_bits(), 0),
-                (type_::Float64(()), value::Float64(f)) =>
-                    primitive_case(&typ, &member, offset, f.to_bits(), 0),
+                (type_::Uint16(()), value::Uint16(i)) => {
+                    primitive_case(&typ, &member, offset, i, 0)
+                }
+                (type_::Uint32(()), value::Uint32(i)) => {
+                    primitive_case(&typ, &member, offset, i, 0)
+                }
+                (type_::Uint64(()), value::Uint64(i)) => {
+                    primitive_case(&typ, &member, offset, i, 0)
+                }
+                (type_::Float32(()), value::Float32(f)) => {
+                    primitive_case(&typ, &member, offset, f.to_bits(), 0)
+                }
+                (type_::Float64(()), value::Float64(f)) => {
+                    primitive_case(&typ, &member, offset, f.to_bits(), 0)
+                }
                 (type_::Enum(_), value::Enum(d)) => {
                     if d == 0 {
-                        Line(format!("::core::convert::TryInto::try_into(self.{member}.get_data_field::<u16>({offset}))"))
+                        format!("::core::convert::TryInto::try_into(self.{member}.get_data_field::<u16>({offset}))")
                     } else {
-                        Line(
-                            format!(
-                                "::core::convert::TryInto::try_into(self.{member}.get_data_field_mask::<u16>({offset}, {d}))"))
+                        format!(
+                                "::core::convert::TryInto::try_into(self.{member}.get_data_field_mask::<u16>({offset}, {d}))")
                     }
                 }
 
-                (type_::Text(()), value::Text(_)) |
-                (type_::Data(()), value::Data(_)) |
-                (type_::List(_), value::List(_)) |
-                (type_::Struct(_), value::Struct(_)) => {
+                (type_::Text(()), value::Text(_))
+                | (type_::Data(()), value::Data(_))
+                | (type_::List(_), value::List(_))
+                | (type_::Struct(_), value::Struct(_)) => {
                     let default = if reg_field.get_had_explicit_default() {
                         default_decl = Some(crate::pointer_constants::word_array_declaration(
                             ctx,
                             &default_name,
                             ::capnp::raw::get_struct_pointer_section(default_value).get(0),
-                            crate::pointer_constants::WordArrayDeclarationOptions {public: true})?);
-                        format!("Some(&_private::{default_name}[..])")
+                            crate::pointer_constants::WordArrayDeclarationOptions { public: true },
+                        )?);
+                        format!("::core::option::Option::Some(&_private::{default_name}[..])")
                     } else {
                         "::core::option::Option::None".to_string()
                     };
 
                     if is_reader {
-                        Line(fmt!(ctx,
-                            "{capnp}::traits::FromPointerReader::get_from_pointer(&self.{member}.get_pointer_field({offset}), {default})"))
+                        fmt!(ctx,
+                            "{capnp}::traits::FromPointerReader::get_from_pointer(&self.{member}.get_pointer_field({offset}), {default})")
                     } else {
-                        Line(fmt!(ctx,"{capnp}::traits::FromPointerBuilder::get_from_pointer(self.{member}.get_pointer_field({offset}), {default})"))
+                        fmt!(ctx,"{capnp}::traits::FromPointerBuilder::get_from_pointer(self.{member}.get_pointer_field({offset}), {default})")
                     }
                 }
 
                 (type_::Interface(_), value::Interface(_)) => {
-                    Line(fmt!(ctx,"match self.{member}.get_pointer_field({offset}).get_capability() {{ ::core::result::Result::Ok(c) => ::core::result::Result::Ok({capnp}::capability::FromClientHook::new(c)), ::core::result::Result::Err(e) => ::core::result::Result::Err(e)}}"))
+                    fmt!(ctx,"match self.{member}.get_pointer_field({offset}).get_capability() {{ ::core::result::Result::Ok(c) => ::core::result::Result::Ok({capnp}::capability::FromClientHook::new(c)), ::core::result::Result::Err(e) => ::core::result::Result::Err(e)}}")
                 }
                 (type_::AnyPointer(_), value::AnyPointer(_)) => {
                     if !raw_type.is_parameter()? {
-                        Line(fmt!(ctx,"{capnp}::any_pointer::{module_string}::new(self.{member}.get_pointer_field({offset}))"))
+                        fmt!(ctx,"{capnp}::any_pointer::{module_string}::new(self.{member}.get_pointer_field({offset}))")
                     } else if is_reader {
-                        Line(fmt!(ctx,"{capnp}::traits::FromPointerReader::get_from_pointer(&self.{member}.get_pointer_field({offset}), ::core::option::Option::None)"))
+                        fmt!(ctx,"{capnp}::traits::FromPointerReader::get_from_pointer(&self.{member}.get_pointer_field({offset}), ::core::option::Option::None)")
                     } else {
-                        Line(fmt!(ctx,"{capnp}::traits::FromPointerBuilder::get_from_pointer(self.{member}.get_pointer_field({offset}), ::core::option::Option::None)"))
+                        fmt!(ctx,"{capnp}::traits::FromPointerBuilder::get_from_pointer(self.{member}.get_pointer_field({offset}), ::core::option::Option::None)")
                     }
                 }
                 _ => return Err(Error::failed("default value was of wrong type".to_string())),
             };
+
+            let getter_code = if should_get_option {
+                Branch(vec![
+                    Line(format!(
+                        "if self.{member}.is_pointer_field_null({offset}) {{"
+                    )),
+                    Indent(Box::new(Line(
+                        if is_fallible {
+                            "core::result::Result::Ok(core::option::Option::None)"
+                        } else {
+                            "::core::option::Option::None"
+                        }
+                        .to_string(),
+                    ))),
+                    Line("} else {".to_string()),
+                    Indent(Box::new(Line(if is_fallible {
+                        format!("{getter_fragment}.map(::core::option::Option::Some)")
+                    } else {
+                        format!("::core::option::Option::Some({getter_fragment})")
+                    }))),
+                    Line("}".to_string()),
+                ])
+            } else {
+                Line(getter_fragment)
+            };
+
             Ok((result_type, getter_code, default_decl))
         }
     }
@@ -2454,7 +2524,7 @@ fn generate_node(
                 )));
 
                 client_impl_interior.push(Indent(Box::new(Line(format!(
-                    "self.client.new_call(_private::TYPE_ID, {ordinal}, None)"
+                    "self.client.new_call(_private::TYPE_ID, {ordinal}, ::core::option::Option::None)"
                 )))));
                 client_impl_interior.push(Line("}".to_string()));
 

capnpc/src/codegen_types.rs

@@ -97,6 +97,7 @@ pub trait RustNodeInfo {
 // this is a collection of helpers acting on a "Type" (someplace where a Type is used, not defined)
 pub trait RustTypeInfo {
     fn is_prim(&self) -> Result<bool, Error>;
+    fn is_pointer(&self) -> Result<bool, Error>;
     fn is_parameter(&self) -> Result<bool, Error>;
     fn is_branded(&self) -> Result<bool, Error>;
     fn type_string(&self, ctx: &GeneratorContext, module: Leaf) -> Result<String, Error>;
@@ -330,6 +331,19 @@ impl<'a> RustTypeInfo for type_::Reader<'a> {
             _ => Ok(false),
         }
     }
+
+    #[inline(always)]
+    fn is_pointer(&self) -> Result<bool, Error> {
+        Ok(matches!(
+            self.which()?,
+            type_::Text(())
+                | type_::Data(())
+                | type_::List(_)
+                | type_::Struct(_)
+                | type_::Interface(_)
+                | type_::AnyPointer(_)
+        ))
+    }
 }
 
 ///

capnpc/test/test.capnp

@@ -446,6 +446,20 @@ struct TestNewUnionVersion {
   }
 }
 
+struct TestFieldGetOption {
+  text @0 :Text $Rust.option;
+  data @1 :Data $Rust.option;
+  list @2 :List(UInt8) $Rust.option;
+  emptyStruct @3 :EmptyStruct $Rust.option;
+  simpleStruct @4 :SimpleStruct $Rust.option;
+  any @5 :AnyPointer $Rust.option;
+
+  struct EmptyStruct {}
+  struct SimpleStruct {
+    field @0 :Text $Rust.option;
+  }
+}
+
 struct TestGenerics(Foo, Bar) {
   foo @0 :Foo;
   bar @1 :Bar;