railsgun/

lib.rs

//! # RailsGun
//!
//! RailsGun or Railgun, call it how you want it.
//! This crate add a lot of small but valuable functionality to the existing
//! Rail paradigm in rust.
//!
//! If you are used to using rails in rust, you know what it's all about! If
//! its the first time you hear about it, I would highly suggest you read
//! the following [Railway Oriented Programming](https://fsharpforfunandprofit.com/rop/);
//! In short its a programming style that I have found over multiple projects
//! and services to reduce the errors.
//!
//! This crate supplies you with some extra missing tools and simplifications
//! as follows:
//!
//! ## rail-tap, tap_err, tap_ref, tap_err_ref
//! This is an excellent little trait that adds the ability to "rail-tap" the contents.
//! This means that you can get a copy/clone of the original content that
//! you can use for analysis or other destructive operations without
//! actually touching the original.
//!
//! > Note:
//! > `tap_ref` and `tap_err_ref` unfortunatly
//! > is just a reference so destructive actions should not be taken.
//!
//! ## merge, merge2, merge3, merge4
//!
//! This is for merging multiple results. If you have worked with rails
//! before you have probably tried the following:
//!
//! ```rust
//! use railsgun::Merge;
//!
//! fn func_xyz(x: u32, y: u32, z: u32) -> Result<u32,u32> {
//!     Ok( x + y + z)
//! }
//!
//! let x = Ok(1);
//! let y = Ok(2);
//! let z = Ok(3);
//!
//! x.and_then(|var_x|
//!     y.and_then(|var_y|
//!         z.and_then(|var_z|
//!             func_xyz(var_x, var_y, var_z)
//!         )
//!     )
//! ).ok();
//! ```
//! This is a hideous method of combining three results, you could
//! split it out into multiple functions, but at times that is very
//! excessive. Merge supplies you with superior functionality for this.
//! ```rust
//! use railsgun::Merge;
//!
//! fn func_xyz(x: u32, y: u32, z: u32) -> Result<u32,u32> {
//!     Ok( x + y + z)
//! }
//!
//! # async fn run() -> () {
//! let x = Ok(1);
//! let y = Ok(2);
//! let z = Ok(3);
//! x.merge2(y, z, |var_x, var_y, var_z| func_xyz(var_x, var_y, var_z)).ok();
//! # }
//! ```
//! As you can see, this simplifies the rail significantly and makes
//! it more readable/maintainable.
//!
//! # Todo
//! There is a significant need for more documentation on the trait and others
//! as this library has been in my private stack for a long time and did get the
//! doc-care it needed.
//! 1. rail-tap needs doc
//! 2. merge needs doc
//! 3. Implement `BlockInPlace` for `AsyncResult`
//! 4. More unit tests are needed.
//!
//! Please open a ticket for more ideas!
//!
//! # Contribution
//! Feel free to contribute to the project. Currently, the project is hosted
//! on both [GitHub](https://github.com/nebula-technologies/Railgun) and
//! my private [GitLab](https://gitlab.nebula.technology/rust/railsgun).
//! The main repository is the GitLab repository, where all of the pipelines
//! and all of my projects exist.
//!
//! # License
//! The MIT License (MIT)
//!
//! Copyright © 2021 <copyright holders>
//!
//! Permission is hereby granted, free of charge, to any person obtaining a copy of this Software
//! and associated documentation files (the “Software”), to deal in the Software without restriction,
//! including without limitation the rights to use, copy, modify, merge, publish, distribute,
//! sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
//! furnished to do so, subject to the following conditions:
//!
//! The above copyright notice and this permission notice shall be included in all copies or
//! substantial portions of the Software.
//!
//! THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
//! BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
//! NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
//! DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//! OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#[macro_use]
extern crate tokio;
#[cfg(feature = "rail-merge")]
pub mod rail_merge;
#[cfg(feature = "rail-tap")]
pub mod rail_tap;
pub mod futures;
#[cfg(feature = "option-extended")]
pub mod option_extended;
pub mod iterators;

#[cfg(feature = "future-result")]
pub use futures::future_result::{IntoFuture, FutureResult};

#[cfg(feature = "map-iter")]
pub use iterators::map_iterator::ResultMapIterator;

#[cfg(feature = "rail-merge")]
pub use rail_merge::Merge;
#[cfg(feature = "rail-merge")]
pub use rail_merge::MergeOption;

#[cfg(feature = "rail-tap")]
pub use rail_tap::{Tap, TapErr, TapErrRef, TapRef, ThreadTap, ThreadTapErr};

#[cfg(feature = "option-extended")]
pub use option_extended::{OptionsExtended, IntoOption};