1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

// License: see LICENSE file at root directory of `master` branch

//! # R/O
//!
//! ## Project
//!
//! - Repository: <https://bitbucket.org/haibison/ro>
//! - License: Nice License 1.0.0 _(see LICENSE file at root directory of `master` branch)_
//! - _This project follows [Semantic Versioning 2.0.0]_
//!
//! ## Features
//!
//! This crate helps make stuff read-only.
//!
//! ## Inconvenient builder pattern
//!
//! An example with builder pattern:
//!
//! - You make new struct with all fields private.
//! - For each field, you might want to add 2 functions:
//!
//!     + `set_x(&mut self, ...)`: to change the field's value.
//!     + `get_x(&self, ...)`: to access the field's value.
//!
//! That works fine if your struct has several private fields. But it will be inconvenient when you add more and more fields: for each field,
//! there's a chance that you will need to add 2 more functions. The more public API, the more you will have to maintain.
//!
//! ## [`ReadOnly`][::ReadOnly]
//!
//! This struct can help shorten your code:
//!
//! - You can make any of your struct's fields public.
//! - Then you can implement [`Default`][core:Default]. This could help your users with what you think good default values should be. They can
//!   adjust those values if needed.
//! - Your code can freely accepts your own struct, and converts it into a read-only version. Then you can wrap that version inside an
//!   [`Arc`][std:Arc], and share it across threads without worrying about [`Arc::get_mut()`][std:Arc#get_mut()].
//! - Even in case your struct has some mutable functions, the read-only version still does its job well: mutable functions are _not_
//!   accessible.
//!
//! ## Notes
//!
//! The author believes that this crate should be used in binary programs, not in library crates. [`ReadOnly`][::ReadOnly] itself is _extremely_
//! simple to code. So it would help your users _a lot_ if you try _not_ to include this crate as a dependency in your own libraries.
//!
//! But, it's your choice.
//!
//! [Semantic Versioning 2.0.0]: https://semver.org/spec/v2.0.0.html
//! [::ReadOnly]: struct.ReadOnly.html
//! [core:Default]: https://doc.rust-lang.org/stable/core/default/trait.Default.html
//! [std:Arc]: https://doc.rust-lang.org/std/sync/struct.Arc.html
//! [std:Arc#get_mut()]: https://doc.rust-lang.org/std/sync/struct.Arc.html#method.get_mut

#![warn(missing_docs)]
#![no_std]
#![forbid(unsafe_code)]

// ╔═════════════════╗
// ║   IDENTIFIERS   ║
// ╚═════════════════╝

macro_rules! code_name  { () => { "r/o" }}
macro_rules! version    { () => { "1.0.0" }}

/// # Crate name
pub const NAME: &str = "R/O";

/// # Crate code name
pub const CODE_NAME: &str = code_name!();

/// # ID of this crate
pub const ID: &str = concat!(
    "232323ad-5e101351-db09d4c1-8f2551c7-a8891a49-f9e74895-a8719deb-19ec7261-",
    "bd30d07a-16027a15-35d72930-624c04eb-c686981f-b914af24-9630e343-4fce4864",
);

/// # Crate version
pub const VERSION: &str = version!();

/// # Crate release date (year/month/day)
pub const RELEASE_DATE: (u16, u8, u8) = (2019, 12, 9);

/// # Tag, which can be used for logging...
pub const TAG: &str = concat!(code_name!(), "::232323ad::", version!());

// ╔════════════════════╗
// ║   IMPLEMENTATION   ║
// ╚════════════════════╝

pub mod version_info;

mod ro;

pub use crate::ro::*;

#[test]
fn test_crate_version() {
    assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
}