|
1 | | -// ------------------------------------- |
2 | | -// ----------- CUSTOM MACROS ----------- |
| 1 | +//! **ergo_std**: items that could be in the standard library. |
| 2 | +//! |
| 3 | +//! This is the "core types" library as part of the [`ergo`] crates ecosystem. It contains useful |
| 4 | +//! types, traits and functions for general purpose programming projects which do not fall |
| 5 | +//! into the other [`ergo`] crates but which are boons to ergonomics and productivity. |
| 6 | +//! |
| 7 | +//! # How to Use |
| 8 | +//! |
| 9 | +//! ```rust |
| 10 | +//! #[macro_use] extern crate failure; |
| 11 | +//! extern crate serde; |
| 12 | +//! #[macro_use] extern crate serde_derive; |
| 13 | +//! #[macro_use] extern crate ergo_std; |
| 14 | +//! use ergo_std::*; |
| 15 | +//! # fn main() { |
| 16 | +//! # } |
| 17 | +//! ``` |
| 18 | +//! |
| 19 | +//! > _As you notice, this crate does not include `serde` or `failure`. This is due to a bug |
| 20 | +//! > which makes it impossible for this crate to rexport their `#[derive(...)]` macros. |
| 21 | +//! |
| 22 | +//! # Exported Items |
| 23 | +//! |
| 24 | +//! The following crates and types are exported. See their docs for how to use them. |
| 25 | +//! |
| 26 | +//! - **[`std_prelude`]**: extends rust's additional prelude with commonly used types. The |
| 27 | +//! crate is well documented with justification and usecases for each type. |
| 28 | +//! - **[`lazy_static!`]**: the `lazy_static!` macro is the current standard way to create |
| 29 | +//! global variables and constants in a majority of crates. |
| 30 | +//! - **[`itertools`]**: the itertools prelude provides traits that extends rust's already |
| 31 | +//! extensive iterator API. |
| 32 | +//! - **[`maplit`]**: provides `hashmap!`, `hashset!`, `btreemap!` and `btreeset!` macros to |
| 33 | +//! compliment rust's existing `vec!` macro. These |
| 34 | +//! - **[`Regex`]**: the regular expression type from the `regex` crate. |
| 35 | +//! |
| 36 | +//! [`ergo`]: https://github.com/rust-crates/ergo |
| 37 | +//! [`std_prelude`]: ../std_prelude/index.html |
| 38 | +//! [`itertools`]: ../itertools/index.html |
| 39 | +//! [`lazy_static!`]: ../lazy_static/index.html |
| 40 | +//! [`maplit`]: ../maplit/index.html |
| 41 | +//! [`Regex`]: struct.Regex.html |
| 42 | +//! |
| 43 | +//! ### Special thanks |
| 44 | +//! |
| 45 | +//! The crates that are exported are: |
| 46 | +//! |
| 47 | +//! - [**std_prelude**](https://github.com/vitiral/std_prelude): |
| 48 | +//! Multi-producer multi-consumer channels for message passing |
| 49 | +//! - [**lazy_static**](TODO): TODO |
| 50 | +//! - [**itertools**](TODO): TODO |
| 51 | +//! - [**maplit**](TODO): TODO |
| 52 | +//! - [**regex**](TODO): TODO |
| 53 | +//! |
| 54 | +//! Consider supporting their development individually and starring them on github. |
| 55 | +//! |
| 56 | +//! ## Future crates |
| 57 | +//! |
| 58 | +//! The following crates will be added in the future: |
| 59 | +//! |
| 60 | +//! - `indexmap`: the current crate is `ordermap`, which is renaming itself |
| 61 | +//! `indexmap` and changing what `ordermap` is... it's confusing but it |
| 62 | +//! will be comming shortly |
| 63 | +
|
| 64 | +#[macro_use] |
| 65 | +pub extern crate itertools; |
| 66 | +#[macro_use] |
| 67 | +pub extern crate lazy_static; |
| 68 | +#[macro_use] |
| 69 | +pub extern crate maplit; |
| 70 | +pub extern crate std_prelude; |
| 71 | +pub extern crate regex; |
| 72 | + |
| 73 | +pub use std_prelude::*; |
| 74 | +pub use itertools::prelude::*; |
| 75 | +pub use lazy_static::*; |
| 76 | +pub use itertools::Itertools; |
| 77 | +pub use maplit::*; |
| 78 | +pub use regex::Regex; |
3 | 79 |
|
4 | | -#[macro_export] |
5 | | -/// Use to take mutable ownership of _specific_ variables within a closure. |
6 | | -/// |
7 | | -/// Closures try to be "smart" about how much scope they capture. If you don't mutate a variable |
8 | | -/// they take `&var`, if you do mutate they take `&mut var`. However, if you require ownership you use |
9 | | -/// `move`, i.e. `move || {... do stuff with var...}`... _right_? |
10 | | -/// |
11 | | -/// The problem with `move` is that it moves _every_ variable that is referenced. If you only need |
12 | | -/// to move _one_ variable it can be a pain. Interestingly, you can tell the compiler to only move |
13 | | -/// _specific_ variables like so: |
14 | | -/// |
15 | | -/// ```no_compile |
16 | | -/// let x = x; |
17 | | -/// let y = y; |
18 | | -/// // ... etc |
19 | | -/// ``` |
20 | | -/// |
21 | | -/// But this is quite silly and not obvious to someone who doesn't know about it. Instead, use the |
22 | | -/// `own!` macro and your code will be self documenting. |
23 | | -/// |
24 | | -/// > Note: this macro always does `let mut x = x` to mimick its primary usecase of closures |
25 | | -/// > (which infer mutability automatically). If you require non-mutable ownership use `let x = x` |
26 | | -/// > directly. |
27 | | -/// |
28 | | -/// # Examples |
29 | | -/// ``` |
30 | | -/// #[macro_use] extern crate std_prelude; |
31 | | -/// |
32 | | -/// # fn main() { |
33 | | -/// let y = vec![1, 2, 3]; |
34 | | -/// let mut x = vec![1, 2, 3]; |
35 | | -/// let z = vec![10]; |
36 | | -/// |
37 | | -/// // create scope in which we mutate `x` |
38 | | -/// { |
39 | | -/// let closure = || { |
40 | | -/// own!(y, z); |
41 | | -/// x.push(4); // mutate reference to x |
42 | | -/// z.push(10); |
43 | | -/// |
44 | | -/// println!("&x: {:?}", &x); |
45 | | -/// println!("moved y: {:?}", y); |
46 | | -/// println!("moved z: {:?}", z); |
47 | | -/// }; |
48 | | -/// |
49 | | -/// closure(); |
50 | | -/// } |
51 | | -/// |
52 | | -/// println!("&x after: {:?}", x); // We can still print x! |
53 | | -/// // println!("y after: {:?}", y); // ERROR: use of moved value |
54 | | -/// // println!("z after: {:?}", z); // ERROR: use of moved value |
55 | | -/// # } |
56 | | -/// ``` |
57 | | -macro_rules! own { |
58 | | - ( $( $x:ident ),* ) => { |
59 | | - #[allow(unused_mut)] |
60 | | - $( |
61 | | - let mut $x = $x; |
62 | | - )* |
63 | | - }; |
64 | | -} |
|
0 commit comments