v0.2.12

examples/018-result-erreurs-et-exceptions-examples.md

@@ -0,0 +1,259 @@
+# Exemples / DO-DON'T — Chapitre 18 — `Result`, erreurs et exceptions
+
+> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
+
+## Exemples actuellement présents dans le chapitre
+
+### Exemple 1
+
+```text
+Object
+└── Error
+    ├── ResultError
+    └── Exception
+```
+
+### Exemple 2
+
+```text
+public final class ParseError extends ResultError {
+}
+
+public final class FileNotFoundException extends Exception {
+}
+```
+
+### Exemple 3
+
+```text
+message: String
+cause: Option<Error>
+i18nMessage: Option<I18nMessage>
+```
+
+### Exemple 4
+
+```text
+message
+    message humain canonique / fallback
+
+cause
+    erreur causale purement informative
+    peut contenir un ResultError ou une Exception
+    n'est pas automatiquement propagée
+
+i18nMessage
+    clé et paramètres de localisation
+    ne contient pas un tableau de traductions
+```
+
+### Exemple 5
+
+```text
+code: ResultErrorCode
+```
+
+### Exemple 6
+
+```text
+code       -> stable, machine-readable, non localisé
+message    -> humain, canonique / fallback
+i18nMessage -> localisation externe
+```
+
+### Exemple 7
+
+```text
+throw exception;
+```
+
+### Exemple 8
+
+```text
+Result::Ok(T)
+Result::Err(E)
+```
+
+### Exemple 9
+
+```text
+E doit être ResultError ou un descendant de ResultError
+```
+
+### Exemple 10
+
+```text
+Result<Data,ResultError>
+Result<Data,ParseError>
+Result<Void,ResultError>
+```
+
+### Exemple 11
+
+```text
+Result<Data,Error>
+Result<Data,Exception>
+Result<Data,FileNotFoundException>
+```
+
+### Exemple 12
+
+```text
+Result<T>
+```
+
+### Exemple 13
+
+```text
+Result<T,ResultError>
+```
+
+### Exemple 14
+
+```text
+return Result::Ok(value);
+return Result::Err(error);
+```
+
+### Exemple 15
+
+```text
+result::expectOk(...)
+result::expectErr(...)
+```
+
+### Exemple 16
+
+```text
+ResultError -> Exception
+Exception   -> ResultError
+```
+
+### Exemple 17
+
+```text
+throw ParseException(..., Option::Some(parseError));
+```
+
+### Exemple 18
+
+```text
+catch (FileNotFoundException error) {
+    return Result::Err(FileResultError(..., Option::Some(error)));
+}
+```
+
+### Exemple 19
+
+```text
+T + throws            -> interdit
+Result<T,E>            -> valide sans throws
+Result<T,E> + throws   -> valide
+```
+
+### Exemple 20
+
+```text
+throws IOException
+```
+
+### Exemple 21
+
+```text
+supprimer entièrement des exceptions déclarées
+restreindre une famille à une ou plusieurs sous-familles compatibles
+gérer localement tout ou partie des exceptions du contrat parent
+```
+
+### Exemple 22
+
+```text
+throw FileNotFoundException(...);    // valide
+throw ParseError(...);               // erreur
+throw Error(...);                    // erreur
+```
+
+### Exemple 23
+
+```text
+catch (IOException error) {
+    throw error;
+}
+```
+
+### Exemple 24
+
+```text
+try { ... }
+try { ... } finally { ... }
+finally { ... }
+```
+
+### Exemple 25
+
+```text
+try {
+    ...
+} catch (SpecificException error) {
+    ...
+} catch (ParentException error) {
+    ...
+} finally {
+    ...
+}
+```
+
+### Exemple 26
+
+```text
+catch (FileNotFoundException error) {
+    ...
+} catch (IOException error) {
+    ...
+}
+```
+
+### Exemple 27
+
+```text
+catch (IOException error) {
+    ...
+} catch (FileNotFoundException error) {
+    ...
+}
+```
+
+### Exemple 28
+
+```text
+fin normale du try
+fin normale d'un catch
+return traversant la construction
+throw propagé
+break / continue traversant la construction
+Exception non capturée par les catch
+```
+
+### Exemple 29
+
+```text
+return
+throw
+break
+continue
+emit
+```
+
+### Exemple 30
+
+```text
+index hors limites
+division entière par zéro
+overflow checked
+représentation mémoire invalide
+borne dynamique invalide lors d'une construction directe lorsque la règle du type le définit
+```
+
+## DO / DON'T / WHY / compiler error / edge cases
+
+La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.