Add a diagram of class

This commit is contained in:
Quentin 2023-07-24 13:44:52 +02:00
parent bcb5a81d32
commit 14e4c95fe7
Signed by: quentin
GPG key ID: E9602264D639FF68
4 changed files with 28 additions and 8 deletions

View file

@ -26,22 +26,19 @@ println!(
); );
``` ```
[See more examples in the example/ folder](./example/)
## About the name ## About the name
This library does not aim at implementing a specific RFC, but to be a swiss-army knife to decode and encode ("codec") what is generaly considered an email (generally abbreviated "eml"), hence the name: **eml-codec**. This library does not aim at implementing a specific RFC, but to be a swiss-army knife to decode and encode ("codec") what is generaly considered an email (generally abbreviated "eml"), hence the name: **eml-codec**.
## Goals ## Goals
- Maintainability - modifying the code does not create regression and is possible for someone exterior to the project. Keep cyclomatic complexity low. - Maintainability - modifying the code does not create regression and is possible for someone exterior to the project.
- Composability - build your own parser by picking the relevant passes, avoid work that is not needed.
- Compatibility - always try to parse something, do not panic or return an error. - Compatibility - always try to parse something, do not panic or return an error.
- Exhaustivity - serve as a common project to encode knowledge about emails (existing mime types, existing headers, etc.). - Exhaustivity - serve as a common project to encode knowledge about emails (existing mime types, existing headers, etc.).
## Non goals [See more about this library goals in the doc/ folder](./doc/goals.md)
- Parsing optimization that would make more complicated to understand the logic.
- Optimization for a specific use case, to the detriment of other use cases.
- Pipelining/streaming/buffering as the parser can arbitrarily backtrack + our result contains reference to the whole buffer, eml-codec must keep the whole buffer in memory. Avoiding the sequential approach would certainly speed-up a little bit the parsing, but it's too much work to implement currently.
## Missing / known bugs ## Missing / known bugs
@ -55,7 +52,9 @@ Current known limitations/bugs:
## Design ## Design
Speak about parser combinators. High-level overview of the datastructures (inspired by the UML class diagram conventions):
![Diagram of class made on Draw.io](./doc/class-uml.png)
## Testing strategy ## Testing strategy
@ -101,8 +100,13 @@ IANA
## State of the art / alternatives ## State of the art / alternatives
*The following review is not an objective, neutral, impartial review. Instead, it's a temptative
to explain why I wrote this
`stalwartlab/mail_parser` `stalwartlab/mail_parser`
[See more about this library goals in the sota/ folder](./doc/sota.md)
## Support ## Support
`eml-codec`, as part of the [Aerogramme project](https://nlnet.nl/project/Aerogramme/), was funded through the NGI Assure Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 957073. `eml-codec`, as part of the [Aerogramme project](https://nlnet.nl/project/Aerogramme/), was funded through the NGI Assure Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 957073.

BIN
doc/class-uml.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 72 KiB

14
doc/goals.md Normal file
View file

@ -0,0 +1,14 @@
## Goals
- Maintainability - modifying the code does not create regression and is possible for someone exterior to the project. Keep cyclomatic complexity low.
- Composability - build your own parser by picking the relevant passes, avoid work that is not needed.
- Compatibility - always try to parse something, do not panic or return an error.
- Exhaustivity - serve as a common project to encode knowledge about emails (existing mime types, existing headers, etc.).
## Non goals
- Parsing optimization that would make more complicated to understand the logic.
- Optimization for a specific use case, to the detriment of other use cases.
- Pipelining/streaming/buffering as the parser can arbitrarily backtrack + our result contains reference to the whole buffer, eml-codec must keep the whole buffer in memory. Avoiding the sequential approach would certainly speed-up a little bit the parsing, but it's too much work to implement currently.

View file

@ -1,3 +1,5 @@
#![doc = include_str!("../README.md")]
mod error; mod error;
mod header; mod header;
mod imf; mod imf;