tag	238462623646dba00eb1048375afd2e27081e822
tagger	The Android Open Source Project <initial-contribution@android.com>	Thu Apr 04 19:54:56 2024 -0700
object	86e57d2f84e069f9b4c7d80c53d12957a073c21e

commit	86e57d2f84e069f9b4c7d80c53d12957a073c21e	[log] [tgz]
author	Android Build Coastguard Worker <android-build-coastguard-worker@google.com>	Wed May 10 16:17:00 2023 +0000
committer	Android Build Coastguard Worker <android-build-coastguard-worker@google.com>	Wed May 10 16:17:00 2023 +0000
tree	d7f5059f6c22007c41eb9f6abbbd473fedb05f34
parent	a7dd46ca5a723809f4fc15572e160ee548cc8df6 [diff]
parent	71353d2f35066576a1f0afa00ef9f78eae71ee47 [diff]

tree: d7f5059f6c22007c41eb9f6abbbd473fedb05f34

README.md

Derive Getters

Simple Getters derive macro for generating field getter methods on a named struct. Included is an additional derive, Dissolve, that consumes the named struct returning a tuple of all fields in the order they were declared.

The need for the Getters macro came about when I was making various data structures for JSON to deserialize into. These data structures had many fields in them to access and they weren't going to change once created. One could use pub everywhere but that would enable mutating the fields which is what this derive aims to avoid.

Getters will be generated according to convention. This means that the generated methods will reside within the struct namespace.

With regards to Dissolve, sometimes during conversion a structure must be consumed. One easy way to do this is to return a tuple of all the structs fields. Thus Dissolve can be considered a ‘get (move) everything’ method call.

What this crate won't do

There are no mutable getters and it's not planned. There are no setters either nor will there ever be.

Rust Docs

Documentation is here.

Installation

Add to your Cargo.toml:

[dependencies]
derive-getters = "0.2.0"

Then import the Getters or Dissolve macro in whichever module it's needed (assuming 2018 edition).

use derive_getters::{Getters, Dissolve};

Otherwise just import at crate root.

#[macro_use]
extern crate derive_getters;

Usage

When you have a struct you want to automatically derive getters for... Just add the derive at the top like so;

#[derive(Getters)]
pub struct MyCheesyStruct {
    x: i64,
    y: i64,
}

A new impl will be produced for MyCheesyStruct.

impl MyCheesyStruct {
    pub fn x(&self) -> &i64 {
        &self.x
    }

    pub fn y(&self) -> &i64 {
        &self.y
    }
}

This crate can also handle structs with simple generic parameters and lifetime annotations. Check docs for further details.

#[derive(Getters)]
pub struct StructWithGeneric<'a, T> {
    concrete: f64,
    generic: T,
    text: &'a str,
}

With Dissolve, use it like so;

#[derive(Dissolve)]
pub struct Solid {
    a: u64,
    b: f64,
    c: i64,
}

An impl will be produced for Solid like so;

impl Solid {
    pub fn dissolve(self) -> (u64, f64, i64) {
      (self.a, self.b, self.c)
    }
}

Attributes

This macro comes with two optional field attributes for Getters.

#[getter(skip)] to skip generating getters for a field.
#[getter(rename = "name")] to change the getter name to “name”.

And one optional struct attribute for Dissolve.

#[dissolve(rename = "name")] to change the name of the dissolve function to “name”.

Caveats

Will not work on unit structs, tuples or enums. Derive Getters or Dissolve over them and the macro will chuck a wobbly.
All getter methods return an immutable reference, &, to their field. This means for some types it can get awkward.

Alternatives

getset.