Merge pull request #5 from dinosaure/new-api

New api

README.md

@@ -1,13 +1,10 @@
-Emile (& [Images](https://youtube.com/watch?v=S70NaQqAfaw))
-============================================================
+## Emile (& [Images](https://youtube.com/watch?v=S70NaQqAfaw))
 
 [![Build Status](https://travis-ci.org/dinosaure/emile.svg?branch=master)](https://travis-ci.org/dinosure/emile)
 ![MirageOS](https://img.shields.io/badge/MirageOS-%F0%9F%90%AB-red.svg)
 
 Emile is a library to parse an e-mail address in OCaml. This project is an
-extraction of [MrMime](https://github.com/oklm-wsh/MrMime.git) - but we use
-[Angstrom](https://github.com/inhabitedtype/angstrom.git) instead of an 
-internal decoder.
+extraction of [mrmime](https://github.com/mirage/mrmime.git).
 
 This implementation follow some RFCs:
 - [RFC 822](https://www.ietf.org/rfc/rfc822.txt)
@@ -18,10 +15,15 @@ This implementation follow some RFCs:
 
 We handle UTF-8 ([RFC 6532](https://www.ietf.org/rfc/rfc6532.txt)), domain
 defined on the SMTP protocol ([RFC 5321](https://www.ietf.org/rfc/rfc5321.txt)),
-and general e-mail address purpose (RFC 822, RFC 2822, RFC 5322) including
+and general e-mail address purpose (RFC 822, RFC 2822, RFC 5322) __without__
 _folding-whitespace_.
 
-The last means we can parse something like:
+### Folding whitespace
+
+According RFC 822, an e-mail address into an e-mail can be splitted by a
+_folding-whitespace_. However, this kind of form is not an usual case where user
+mostly wants to parse input from a form (for example). At the end, `emile` is
+not able to parse this kind of input:
 
 ```
 A Group(Some people)
@@ -30,33 +32,40 @@ A Group(Some people)
  John <[email protected]> (my dear friend); (the end of the group)"
 ```
 
-For a general purpose, it's not needed and is close e-mail purpose.
+However, a pre-process (like
+[unstrctrd](https://github.com/dinosaure/unstrctrd)) can _fold_ input and give
+you an usual output. `emile` can not be used into an e-mail context without this
+kind of pre-process.
+
+### Domain
 
 Then, for domain part (explained on RFC 5321 - SMTP protocol), we handle this
-kind of domain:
+kind of domain (IPv4 and IPv6 domain) with
+[ipaddr](https://github.com/mirage/ipaddr.git):
 
 ```
 first.last@[12.34.56.78]
 first.last@[IPv6:1111:2222:3333::4444:12.34.56.78]
 ```
 
-The parser of `IPv*` is done by [Ipaddr](https://github.com/mirage/ipaddr.git).
-As a old specification, we handle multiple-domains like:
+It's possible to notify multiple domains for one local-part like this:
 
 ```
 <@a.com,b.com:[email protected]>
 ```
 
-Obviously, we handle (nested) comments:
+It's a valid form according [RFC 882](https://www.ietf.org/rfc/rfc822.txt).
+
+### Comments
+
+Even if we don't handle the _folding-whitespace_, we are able to discard
+comments.
 
 ```
 a(a(b(c)d(e(f))g)h(i)j)@iana.org
 ```
 
-All parsers are binded with a comment which explain where you can find the ABNF
-description and some notes about implementation. All was check by hands.
-
 ## Advise
 
 If you think it's easy to parse an e-mail address, you should look
-[tests](https://github.com/dinosaure/emile/blob/master/test/test.ml).
+[tests](https://github.com/mirage/emile/blob/master/test/test.ml).