Vylepšení dokumentace + oprava chybiček

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.1.0-alpha.7
+- Nastavovat `prihlasen` na `false` v případě chyby i u `ziskejUzivatele`
+- Vylepšení dokumentace
+- `getFirstSession` je nyní soukromá metoda
+
 ## 0.1.0-alpha.6
 - `return` místo `throw`
 [Všechny změny](https://github.com/hernikplays/canteenlib/compare/0.1.0-alpha.5...0.1.0-alpha.6)

COMPATIBILITY.md

@@ -9,7 +9,7 @@ Výchozí verze, pro kterou aktuálně je knihovna tvořena, je **2.18.19**
 
 |  Provozovatel  | Verze iCanteen   | Funkční | Verze knihovny |
 |:--------------:|------------------|---------|----------------|
-|    SŠTE Brno   | iCanteen 2.18.19 | ✅       | 0.1.0-alpha.4    |
+|    SŠTE Brno   | iCanteen 2.18.19 | ✅       | 0.1.0-alpha.7    |
 |   SPŠ Třebíč   | iCanteen 2.10.25 | ❓       | 0.1.0-alpha    |
 
 Pokud chcete přispět s testem, otestujte tuto knihovnu na instanci iCanteen, kde, nejlépe legálně, máte přístup, a nahlašte své poznatky [zde](https://github.com/hernikplays/canteenlib/issues/new?assignees=hernikplays&labels=kompatibilita&template=hl--en--kompatibility.md&title=Kompatibilita%3A+)

README.md

@@ -1,5 +1,5 @@
 ## O knihovně
-Experimentální **neoficiální** webscrape knihovna pro komunikaci se systémem [iCanteen](https://www.z-ware.cz/internetove-objednavky)
+Experimentální **neoficiální** webscrape knihovna pro komunikaci se systémem [iCanteen](https://www.z-ware.cz/internetove-objednavky). **Knihovna je aktuálně nestabilní! Používejte na vlastní riziko!**
 
 [![wakatime](https://wakatime.com/badge/user/17178fab-a33c-430f-a764-7b3f26c7b966/project/82873d93-5b79-4978-a5f6-612e21641817.svg)](https://wakatime.com/badge/user/17178fab-a33c-430f-a764-7b3f26c7b966/project/82873d93-5b79-4978-a5f6-612e21641817) [![Pub Version (including pre-releases)](https://img.shields.io/pub/v/canteenlib?color=lightblue&include_prereleases&label=latest%20version)](https://pub.dev/packages/canteenlib)
 
@@ -11,7 +11,6 @@ Experimentální **neoficiální** webscrape knihovna pro komunikaci se systéme
 
 ## To do
 - Kompatibilita se staršími verzemi iCanteen
-- Stabilita
 
 *\* Knihovna nemusí fungovat na všech instancích systému iCanteen, proto žádám každého, kdo může a je uživatelem iCanteen, aby otestoval funkčnost této knihovny a případné problémy [nahlásil](https://github.com/hernikplays/canteenlib/issues)*
 

lib/src/canteen.dart

@@ -28,16 +28,15 @@ SOFTWARE.
 
 /// Reprezentuje kantýnu
 ///
-/// `url` - adresa kantýny
-///
-/// `cookies` - sušenky potřebné pro komunikaci
-///
-/// `prihlasen` - je uživatel přihlášen?
-///
 /// **Všechny metody v případě chyby vrací [Future] s chybovou hláškou.**
 class Canteen {
+  /// Adresa kantýny
   String url;
+
+  /// Sušenky potřebné pro komunikaci
   Map<String, String> cookies = {"JSESSIONID": "", "XSRF-TOKEN": ""};
+
+  /// Je uživatel přihlášen?
   bool prihlasen = false;
   Canteen(this.url);
 
@@ -46,6 +45,7 @@ class Canteen {
     if (!prihlasen) return Future.error("Uživatel není přihlášen");
     var r = await _getRequest("/web/setting");
     if (r.contains("přihlášení uživatele")) {
+      prihlasen = false;
       return Future.error("Uživatel není přihlášen");
     }
     var m = double.tryParse(RegExp(r' +<span id="Kredit" .+?>(.+?)(?=&)')
@@ -81,7 +81,7 @@ class Canteen {
         kredit: m ?? 0.0);
   }
 
-  Future<void> getFirstSession() async {
+  Future<void> _getFirstSession() async {
     if (url.endsWith("/")) {
       url = url.substring(0, url.length - 1);
     } // odstranit lomítko
@@ -103,13 +103,16 @@ class Canteen {
 
   /// Přihlášení do iCanteen
   ///
-  /// `user` - uživatelské jméno
-  /// `password` - heslo
+  /// Vstup:
   ///
-  /// Vrátí `true`, když se uživatel přihlásil, v případě špatného hesla `false`
+  /// - `user` - uživatelské jméno | [String]
+  /// - `password` - heslo | [String]
+  ///
+  /// Výstup:
+  /// - [bool] ve [Future], v případě přihlášení `true`, v případě špatného hesla `false`
   Future<bool> login(String user, String password) async {
     if (cookies["JSESSIONID"] == "" || cookies["XSRF-TOKEN"] == "") {
-      await getFirstSession();
+      await _getFirstSession();
     }
     var res =
         await http.post(Uri.parse(url + "/j_spring_security_check"), headers: {
@@ -164,7 +167,11 @@ class Canteen {
   }
 
   /// Získá jídelníček bez cen
-  /// **nevrací** ceny, ale umožňuje získat jídelníček bez přihlášení
+  ///
+  /// Výstup:
+  /// - [List] s [Jidelnicek], který neobsahuje ceny
+  ///
+  /// __Lze použít bez přihlášení__
   Future<List<Jidelnicek>> ziskejJidelnicek() async {
     var res = await _getRequest("/");
     var reg = RegExp(
@@ -230,7 +237,14 @@ class Canteen {
   }
 
   /// Získá jídlo pro daný den
-  /// Vyžaduje přihlášení pomocí [login]
+  ///
+  /// __Vyžaduje přihlášení pomocí [login]__
+  ///
+  /// Vstup:
+  /// - `den` - *volitelné*, určuje pro jaký den chceme získat jídelníček | [DateTime]
+  ///
+  /// Výstup:
+  /// - [Jidelnicek] obsahující detaily, které vidí přihlášený uživatel
   Future<Jidelnicek> jidelnicekDen({DateTime? den}) async {
     if (!prihlasen) {
       return Future.error("Uživatel není přihlášen");
@@ -314,7 +328,11 @@ class Canteen {
 
   /// Objedná vybrané jídlo
   ///
-  /// Vrátí upravenou instanci [Jidlo], v případě chyby vrátí chybový [Future]
+  /// Vstup:
+  /// - `j` - Jídlo, které chceme objednat | [Jidlo]
+  ///
+  /// Výstup:
+  /// - Upravená instance [Jidlo] tohoto jídla
   Future<Jidlo> objednat(Jidlo j) async {
     if (!prihlasen) {
       return Future.error("Uživatel není přihlášen");
@@ -371,7 +389,11 @@ class Canteen {
 
   /// Uloží vaše jídlo z/do burzy
   ///
-  /// Vrací upravenou instanci [Jidlo], v případě chyby vrátí chybový [Future]
+  /// Vstup:
+  /// - `j` - Jídlo, které chceme dát/vzít do/z burzy | [Jidlo]
+  ///
+  /// Výstup:
+  /// - Upravená instance [Jidlo] tohoto jídla
   Future<Jidlo> doBurzy(Jidlo j) async {
     if (!prihlasen) {
       return Future.error("Uživatel není přihlášen");
@@ -426,7 +448,8 @@ class Canteen {
 
   /// Získá aktuální jídla v burze
   ///
-  /// Vrátí [Burza], v případě chyby vrátí chybový [Future]
+  /// Výstup:
+  /// - List instancí [Burza], každá obsahuje informace o jídle v burze
   Future<List<Burza>> ziskatBurzu() async {
     if (!prihlasen) return Future.error("Uživatel není přihlášen");
     List<Burza> burza = [];
@@ -475,7 +498,11 @@ class Canteen {
 
   /// Objedná jídlo z burzy pomocí URL z instance třídy Burza
   ///
-  /// Vrací [bool] - true pokud se podařilo objednat, jinak false
+  /// Vstup:
+  /// - `b` - Jídlo __z burzy__, které chceme objednat | [Burza]
+  ///
+  /// Výstup:
+  /// - [bool], `true`, pokud bylo jídlo úspěšně objednáno z burzy, jinak `false`
   Future<bool> objednatZBurzy(Burza b) async {
     var res = await _getRequest("/faces/secured/" + b.url!);
     if (res.contains("Chyba")) return false;

lib/src/tridy.dart

@@ -38,6 +38,7 @@ class Jidlo {
       required this.naBurze});
 }
 
+/// Reprezentuje cizí jídlo na burze
 class Burza {
   /// Den, který je jídlo vydáváno
   DateTime den;
@@ -62,7 +63,7 @@ class Burza {
       this.varianta});
 }
 
-/// Reprezentuje jídelníček pro jeden dan
+/// Reprezentuje jídelníček pro jeden den
 class Jidelnicek {
   /// Den, pro který je jídelníček zveřejněn
   DateTime den;
@@ -80,7 +81,7 @@ class Uzivatel {
   /// Jméno, jak je uvedené v základních údajích o uživateli
   String? jmeno;
 
-  /// příjmení, jak je uvedené v základních údajích o uživateli
+  /// Příjmení, jak je uvedené v základních údajích o uživateli
   String? prijmeni;
 
   /// Kategorie uživatele

pubspec.yaml

@@ -1,6 +1,6 @@
 name: canteenlib
-description: Knihovna pro komunikaci se stravovacím systémem iCanteen s možností objednávání jídla
-version: 0.1.0-alpha.6
+description: Library for communication with the czech canteen food ordering system iCanteen
+version: 0.1.0-alpha.7
 repository: 'https://github.com/hernikplays/canteenlib'
 issue_tracker: 'https://github.com/hernikplays/canteenlib/issues'