# `pack_bools`: an easy way to pack all bools in your struct
[](https://crates.io/crates/pack_bools)
[](https://docs.rs/pack_bools)
[](https://opensource.org/licenses/MIT)
`pack_bools` transforms structs with boolean fields into a struct containing an integer with bit flags for each boolean
value:
```rust
use pack_bools::pack_bools;
#[pack_bools]
#[derive(Debug, Clone)]
struct Config<'a> {
output_name: &'a str,
verbose: bool,
pub use_colors: bool,
original_file: &'a std::path::Path,
legacy_mode: bool
}
```
gets transformed into something like this:
```rust
#[derive(Debug, Clone)]
struct Config<'a> {
output_name: &'a str,
original_file: &'a std::path::Path,
packed_bools: u8
}
impl<'a> Config<'a> {
fn get_verbose(&self) -> bool {
self.packed_bools & 1 << 0 != 0
}
fn set_verbose(&mut self, value: bool) {
if value {
self.packed_bools |= 1 << 0;
} else {
self.packed_bools &= !(1 << 0);
}
}
pub fn get_use_colors(&self) -> bool {
self.packed_bools & 1 << 1 != 0
}
pub fn set_use_colors(&mut self, value: bool) {
if value {
self.packed_bools |= 1 << 1;
} else {
self.packed_bools &= !(1 << 1);
}
}
/* getters and setters for legacy_mode omitted */
}
```
## Usage
Simply run `cargo add pack_bools` in your project directory, `use pack_bools::pack_bools;` and add the `#[pack_bools]`
macro on top of your struct. By default, this will behave as the example above: it will replace all fields of type
`bool` with a single numeric field `packed_bools` and add getters and setters for each field. By default, both the
getter and setter will inherit their visibility from the field, so if the field is declared `pub(super)`, the getters
and setters will too.
By adding options to the `#[pack_bools(..)]` attribute, you can configure options for the entire struct, using
*global options*. Additionally, you can add `#[pack_bools(..)]` to `boolean` fields to configure options for just that
field, using *local options*.
### Global options
Global options available when using `#[pack_bools(..)]` on a struct:
* `#[pack_bools(getters = [vis] [name])]` changes the name and visibility of the getters.
* Use `%` as a substitution for the field name.
* If the name is skipped, the default name template will be used.
* `vis` is a Rust visibility modifier (such as `pub`, `pub(super)` etc.). Use `self` to reference the visibility of
the field (leaving `vis` empty otherwise implies private visibility, as in Rust).
* Example: Using `#[pack_bools(getters = pub get_field_%)]` will make all getters public named
`get_field_` followed by the field name. A field named `foo` will thus get a getter with the signature
`pub fn get_field_foo(&self) -> bool`.
* Example: Using `#[pack_bools(getters = self %)]` will make all getters have the same name as the field, with the
same visibility as the field.
* As a consequence of an empty template leaving the field name unchanged together with Rust using no modifier for
private items, just `#[pack_bools(getters = )]` will make all getters private named `get_` followed by the field
name (the default template). For clarity purposes, consider using `#[pack_bools(getters = get_%)]`
* Aliased as `get`/`getter`. For setters, use `#[pack_bools(set/setter/setters)]`.
* Default values are `#[pack_bools(get = self get_%, set = self set_%)]`.
* `#[pack_bools(no_getters)]` will not generate getters (aliased as `no_get`/`no_getter`)
* Similarly `#[pack_bools(no_set/no_setter/no_setters)]` will not generate setters.
* `#[pack_bools(type = u16)]` will use `u16` as the data type for the bit flags. Available options are `u8`/`u16`/`u32`/
`u64`/`u128`/`auto`, where `auto` (the default option) automatically use the smallest of those types that can fit all
the bools in the struct.
* `#[pack_bools(field = <name>)]` will set the name of the field containing the bitflags, by default `packed_bools`.
* `#[pack_bools(inline)]` will use the inline pattern for the bitflag field, i.e. create fields of the pattern
`packed_bools: u8`. This is the default option. Compare to `newtype` below.
* `#[pack_bools(newtype [= name])]` will make a new single-valued tuple struct for holding the bitflags, similar to
`struct MyStructPackedBools(u8);`. If a name is specified, the newtype struct will be defined with that name,
otherwise `PackedBools` will be suffixed to the name of the struct. The example at the top of this document,
with `#[pack_bools(newtype)]` will be compiled into:
```rust
#[derive(Debug, Clone)]
struct Config<'a> {
output_name: &'a str,
original_file: &'a std::path::Path,
packed_bools: ConfigPackedBools
}
#[derive(Copy, Clone, Debug)]
#[repr(transparent)]
struct ConfigPackedBools(u8);
impl<'a> Config<'a> {
fn get_verbose(&self) -> bool {
self.packed_bools.0 & 1 << 0 != 0
}
fn set_verbose(&mut self, value: bool) {
if value {
self.packed_bools.0 |= 1 << 0;
} else {
self.packed_bools.0 &= !(1 << 0);
}
}
/* additional getters and setters omitted */
}
```
### Local options
You may add the `#[pack_bools(..)]` attribute on fields of type `bool` to configure the output of that specific field.
Available options are:
* `#[pack_bools(skip)]` excludes that field from being packed with the other bools.
* `#[pack_bools(getter = [vis] [name])` changes the name (and possibly visibility) of the getter to that field.
* This uses a concrete name instead of a template, otherwise it has the same syntax as the global
`#[pack_bools(getter = ..)]` attribute, see above.
* `#[pack_bools(getter = pub debug_mode)]` added to a field `debug: bool` will create a getter like
`pub fn debug_mode(&self) -> bool { .. }`. Aliased as `get`.
* For setters, use `#[pack_bools(set/setter = [vis] [name])]`.
* `#[pack_bools(no_getter)]` skips generating a getter for that field. Aliased as `no_get`. For setters, use
`#[pack_bools(no_set/no_setter)]`.
* `#[pack_bools(default = <true/false>)]` sets the default value for the field. If set to `true`, the `newtype` pattern
must be used, but then a `impl Default` will be generated for that newtype with this field set to `true`. If all other
fields of the struct has appropriate default values, this will allow you to use `#[derive(Default)]` on the struct,
while having some boolean values set to `true`. Defaults to `false`.
## Changelog
### 0.1.0
* Initial commit
### 0.1.1
* Fix some small documentation mistakes
### 0.1.2
* Add `self` as an inheriting visibility modifier.
* Made name optional in `#[pack_bools(get = ..)]` for both global and local config