README.md
1# Derive Getters
2
3Simple `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.
4
5The 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.
6
7Getters will be generated according to [convention](https://github.com/rust-lang/rfcs/blob/master/text/0344-conventions-galore.md#gettersetter-apis). This means that the generated methods will reside within the struct namespace.
8
9With 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.
10
11## What this crate won't do
12There are no mutable getters and it's not planned. There are no setters either nor will there ever be.
13
14## Rust Docs
15[Documentation is here.](https://docs.rs/derive-getters/0.2.0)
16
17## Installation
18
19Add to your `Cargo.toml`:
20```toml
21[dependencies]
22derive-getters = "0.2.0"
23```
24
25Then import the `Getters` or `Dissolve` macro in whichever module it's needed (assuming 2018 edition).
26```rust
27use derive_getters::{Getters, Dissolve};
28
29```
30Otherwise just import at crate root.
31```rust
32#[macro_use]
33extern crate derive_getters;
34```
35
36## Usage
37
38When you have a struct you want to automatically derive getters for... Just add the derive at the top like so;
39```rust
40#[derive(Getters)]
41pub struct MyCheesyStruct {
42 x: i64,
43 y: i64,
44}
45```
46
47A new impl will be produced for `MyCheesyStruct`.
48```rust
49impl MyCheesyStruct {
50 pub fn x(&self) -> &i64 {
51 &self.x
52 }
53
54 pub fn y(&self) -> &i64 {
55 &self.y
56 }
57}
58```
59
60This crate can also handle structs with simple generic parameters and lifetime annotations. Check [docs](https://docs.rs/derive-getters/0.2.0) for further details.
61```rust
62#[derive(Getters)]
63pub struct StructWithGeneric<'a, T> {
64 concrete: f64,
65 generic: T,
66 text: &'a str,
67}
68```
69
70With `Dissolve`, use it like so;
71```rust
72#[derive(Dissolve)]
73pub struct Solid {
74 a: u64,
75 b: f64,
76 c: i64,
77}
78```
79
80An impl will be produced for `Solid` like so;
81```rust
82impl Solid {
83 pub fn dissolve(self) -> (u64, f64, i64) {
84 (self.a, self.b, self.c)
85 }
86}
87```
88
89### Attributes
90This macro comes with two optional field attributes for `Getters`.
91* `#[getter(skip)]` to skip generating getters for a field.
92* `#[getter(rename = "name")]` to change the getter name to "name".
93
94And one optional struct attribute for `Dissolve`.
95* `#[dissolve(rename = "name")]` to change the name of the dissolve function to "name".
96
97## Caveats
981. Will not work on unit structs, tuples or enums. Derive `Getters` or `Dissolve` over them and the macro will chuck a wobbly.
992. All getter methods return an immutable reference, `&`, to their field. This means for some types it can get awkward.
100
101## Alternatives
102[getset](https://github.com/Hoverbear/getset).
103