except_plugin/lib.rs
1//!# Except-Plugin
2//!
3//!- author：syf20020816@outlook.com
4//!- docName：Except-Plugin README
5//!- createDate：20230814
6//!- updateDate：20230814
7//!- version：0.0.1
8//!- email：syf20020816@outlook.com
9//!
10//!## LICEMSE
11//!
12//!MIT
13//!
14//!## Except-Plugin Introduction
15//!
16//!exception-plugin is a common exception in Rust， which helps developers better control their programs
17//!
18//!### Default Support Exception
19//!
20//!1. SuperException : It is the top-level implementation of all exceptions , you can get this from all more specific exceptions' recover param .Although it is the parent of all exceptions, it is actually the lowest level exception.
21//!2. EasyException : Like SuperException, it also has no special features, but has two additional attributes: error file and error line.
22//!3. NullPointerException
23//!4. ArrayIndexOutOfBoundsException
24//!5. UnSupportedOpException : UnsupportedOpException is a broad error that includes many possible causes, such as lack of permissions, inaccessible files, IO exceptions ...
25//!6. SQLException : SQLException is an error that may be caused when accessing or manipulating a database, such as no table, empty table data, and no columns ...
26//!
27//!## QuickStart
28//!
29//!```rust
30//!use std::error::Error;
31//!use std::{line, file};
32//!use std::path::PathBuf;
33//!use except_plugin::{
34//! ExceptionLevel, ExceptionFactory, EasyException, EasyExceptionBuilder, NewFrom, SuperBuilderImpl,
35//! DerefException, Exception, TargetParamImpl, CommonParamImpl, easy_e,
36//!};
37//!
38//!pub fn test_easy() -> Result<(), Box<dyn Error>> {
39//! /// create a easy exception
40//! /// you can use macro to create : easy_e!(666)
41//! /// if you wanna use macro , you should add feature : macros
42//! let e = ExceptionFactory::new::<EasyException, EasyExceptionBuilder>()
43//! .set_code(500)
44//! .set_level(ExceptionLevel::Warn)
45//! .set_line(line!())
46//! .set_path(PathBuf::from(file!()))
47//! .build();
48//! dbg!(&e);
49//! Err(Box::new(
50//! e
51//! ))
52//!}
53//!```
54//!
55//!## Define a self Exception
56//!
57//!```rust
58//!use std::error::Error;
59//!use std::fmt::{Debug, Display, Formatter};
60//!use std::ops::Deref;
61//!use std::time::Duration;
62//!use except_plugin::{
63//! SuperBuilderImpl, Exception, ExceptionLevel, exception_impl, display_err_impl, Exceptions, builder_impl,
64//! NewFrom, FromBuilder, ExceptionFactory,
65//!};
66//!
67//!/// # step1 : create a new exception
68//!///
69//!/// mut contain 4 param!:
70//!/// - code
71//!/// - msg
72//!/// - level
73//!/// - timestamp
74//!#[derive(Debug, Clone, PartialEq, Default)]
75//!pub struct MyException {
76//! code: u32,
77//! msg: String,
78//! level: ExceptionLevel,
79//! timestamp: Duration,
80//! /// here I define a new param!
81//! define: String,
82//!}
83//!
84//!/// # step2 : use macro to impl Exception for MyException
85//!/// if you wanna impl Exception trait , you must impl Error,Debug,Display,as followings:
86//!/// ```rust
87//!/// impl Error for MyException {}
88//!/// impl Debug for MyException {}
89//!/// impl Display for MyException {}
90//!/// impl Exception for MyException { // fn ... }
91//!/// ```
92//!/// it is very complicated , so you can use exception_impl! and display_err_impl!
93//!display_err_impl!(MyException);
94//!exception_impl!(MyException,Exceptions::Define);
95//!
96//!/// # step3 : impl the other param for define Exception
97//!/// actually , now it is enough
98//!/// but you need to continue!!!
99//!impl MyException {
100//! pub fn get_define(&self) -> &str { &self.define }
101//! pub fn set_define(&mut self, value: &str) -> &mut Self {
102//! self.define = String::from(value);
103//! self
104//! }
105//!}
106//!
107//!/// # step4 : create a builder for define Exception
108//!/// builder is quite simple and you should add a param : `e_type: Exceptions`
109//!#[derive(Debug, Clone, PartialEq, Default)]
110//!pub struct MyExceptionBuilder {
111//! code: u32,
112//! msg: String,
113//! level: ExceptionLevel,
114//! timestamp: Duration,
115//! /// here I define a new param!
116//! define: String,
117//! e_type: Exceptions,
118//!}
119//!
120//!impl MyExceptionBuilder {
121//! pub fn get_define(&self) -> &str { &self.define }
122//! pub fn set_define(&mut self, value: &str) -> &mut Self {
123//! self.define = String::from(value);
124//! self
125//! }
126//!}
127//!
128//!/// # step5 : add builder_impl! macro for Define Exception
129//!builder_impl!(MyExceptionBuilder,MyException);
130//!
131//!/// # step6 : impl NewFrom and FromBuilder
132//!impl NewFrom for MyException {
133//! type Builder = MyExceptionBuilder;
134//! fn new() -> Self::Builder {
135//! MyExceptionBuilder::new()
136//! }
137//! fn from_super(e: Box<dyn Exception>) -> Self where Self: Sized {
138//! MyException {
139//! code: e.code(),
140//! msg: String::from(e.msg()),
141//! level: e.level(),
142//! timestamp: e.timestamp(),
143//! define: String::new(),
144//! }
145//! }
146//!}
147//!
148//!impl FromBuilder for MyException {
149//! type Output = MyException;
150//! type Input = MyExceptionBuilder;
151//! fn from_builder(builder: &Self::Input) -> Self::Output {
152//! Self::Output {
153//! code: builder.code(),
154//! msg: String::from(builder.msg()),
155//! level: builder.level(),
156//! timestamp: builder.timestamp(),
157//! define: String::from(builder.get_define()),
158//! }
159//! }
160//!}
161//!
162//!/// # step 7: test
163//!pub fn test_my_exception() -> () {
164//! // [src\lib\define_exception.rs:110] my_e = MyException {
165//! // code: 1000,
166//! // msg: "",
167//! // level: Info,
168//! // timestamp: 0ns,
169//! // define: "this is my exception",
170//! // }
171//! let my_e = ExceptionFactory::new::<MyException, MyExceptionBuilder>()
172//! .set_code(1000)
173//! .set_define("this is my exception")
174//! .build();
175//! dbg!(my_e);
176//!}
177//!```
178//!
179//! ```txt
180//! @author:syf20020816@Outlook.com
181//! @date:2023/8/16
182//! @version:0.0.1
183//! @description:
184//! ```
185
186mod core;
187
188pub use crate::core::{
189 SuperBuilder, ExceptionLevel, SuperException, Exception, NewFrom, ExceptionFactory, Exceptions, SuperBuilderImpl,
190 DerefException, EasyException, NullPointerException, TargetParamImpl, EasyExceptionBuilder, CommonParamImpl,
191 NullPointerExceptionBuilder, ArrayIndexOutOfBoundsException, ArrayIndexOutOfBoundsBuilder, OutOfBoundsParamImpl,
192 ExceptionCode, UnSupportedOpExceptionBuilder, UnSupportedOpException, ReasonParamImpl, Reasons, SQLReasons, UnSupportedReasons,
193 SQLException, SQLParamImpl, SQLExceptionBuilder, FromBuilder,
194};