cdumay_result 1.0.2

A library to serialize and deserialize result using serde
Documentation 
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
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167

//! [![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue)](./LICENSE)
//! [![cdumay_result on crates.io](https://img.shields.io/crates/v/cdumay_result)](https://crates.io/crates/cdumay_result)
//! [![cdumay_result on docs.rs](https://docs.rs/cdumay_result/badge.svg)](https://docs.rs/cdumay_result)
//! [![Source Code Repository](https://img.shields.io/badge/Code-On%20GitHub-blue?logo=GitHub)](https://github.com/cdumay/cdumay_result)
//!
//! A Rust library for standardizing operation results and their serialization using [serde](https://docs.serde.rs/serde/).
//! This crate provides a flexible and consistent way to handle operation results, including success and error cases,
//! with support for structured data, stdout/stderr outputs, and serialization.
//!
//! ## Features
//!
//! - Structured result type with support for return values and output streams
//! - UUID generation for result tracking
//! - Integration with error handling systems
//! - Builder pattern for easy result construction
//!
//! ## Installation
//!
//! Add this to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! cdumay_result = "1.0"
//! serde_json = "1.0"  # For JSON serialization
//! cdumay_error = "1.0"  # For error handling
//! cdumay_error_standard = "1.0"  # For error example
//! cdumay_context = "1.0" # For context use
//! ```
//!
//! ## Basic Usage
//!
//! Here's a simple example of creating and using a successful result:
//!
//! ```rust
//! use cdumay_result::{ResultBuilder, Result};
//! use std::collections::BTreeMap;
//! use serde_value::Value;
//!
//! // Creating a successful result with data
//! let result = ResultBuilder::default()
//!     .stdout("Operation completed successfully".into())
//!     .retval({
//!         let mut values = BTreeMap::new();
//!         values.insert("status".into(), Value::String("completed".into()));
//!         values.insert("count".into(), Value::U8(42.into()));
//!         values
//!     })
//!     .build();
//!
//! // Serialize to JSON
//! println!("{}", serde_json::to_string_pretty(&result).unwrap());
//! ```
//!
//! ## Context Usage
//!
//! Here's a simple example of creating and using a successful result using `cdumay_context`:
//!
//! ```rust
//! use cdumay_result::{ResultBuilder, Result};
//! use cdumay_context::Context;
//! use std::collections::BTreeMap;
//! use serde_value::Value;
//!
//! // Creating a context
//! let mut context = Context::new();
//! context.insert("status".into(), Value::String("completed".into()));
//! context.insert("count".into(), Value::U8(42.into()));
//!
//! // Creating a successful result with data
//! let result = ResultBuilder::default()
//!     .stdout("Operation completed successfully".into())
//!     .retval(context.into())
//!     .build();
//!
//! // Serialize to JSON
//! println!("{}", serde_json::to_string_pretty(&result).unwrap());
//! ```
//!
//! ## Error Handling
//!
//! Example using error handling with `cdumay_error_standard`:
//!
//! ```rust
//! use cdumay_result::Result;
//! use cdumay_error_standard::Unexpected;
//! use cdumay_error::{AsError, Error};
//! use serde_value::Value;
//!
//! fn process_data() -> Result {
//!     // Simulate an error condition
//!     let error = Unexpected::new()
//!         .set_message("Failed to process data".into())
//!         .set_details({
//!             let mut details = std::collections::BTreeMap::new();
//!             details.insert(
//!                 "error_type".into(),
//!                 Value::String("processing_error".into())
//!             );
//!             details
//!         });
//!
//!     // Convert error into Result
//!     Result::from(Error::from(error))
//! }
//! ```
//!
//! ## Custom Result Builder
//!
//! Example of using the builder pattern with custom data:
//!
//! ```rust
//! use cdumay_result::ResultBuilder;
//! use std::collections::BTreeMap;
//! use std::fmt::format;
//! use serde_value::Value;
//! use uuid::Uuid;
//!
//! // Create a custom result with specific UUID
//! let result = ResultBuilder::default()
//!     .uuid( Uuid::parse_str("da1c7a76-33a8-448e-9ada-3a1b17c12279").unwrap())
//!     .stdout("Custom operation result".into())
//!     .retval({
//!         let mut data = BTreeMap::new();
//!         data.insert("custom_field".into(), Value::String("custom_value".into()));
//!         data
//!     })
//!     .build();
//!
//! assert_eq!(format!("{}", result.uuid), "da1c7a76-33a8-448e-9ada-3a1b17c12279".to_string());
//! ```
//!
//! ## JSON Output Format
//!
//! The JSON output format for successful results looks like this:
//!
//! ```json
//! {
//!   "uuid": "550e8400-e29b-41d4-a716-446655440000",
//!   "retcode": 0,
//!   "stdout": "Operation completed successfully",
//!   "stderr": null,
//!   "retval": {
//!     "status": "completed",
//!     "count": 42
//!   }
//! }
//! ```
//!
//! For error results:
//!
//! ```json
//! {
//!   "uuid": "550e8400-e29b-41d4-a716-446655440000",
//!   "retcode": 1,
//!   "stdout": null,
//!   "stderr": "Failed to process data",
//!   "retval": {
//!     "error_type": "processing_error"
//!   }
//! }
//! ```

pub use builder::ResultBuilder;
pub use result::Result;

mod result;
mod builder;