Bearbeiten von „Datei helper.dart“

= Links =
* [[Projekt dgrep]]

= Zielsetzung =
Die Datei <code>helper.dart</code> enthält Funktionen, die wiederverwendbar sind.

= Import =
<pre>import 'dart:io';
import 'package:args/args.dart';
import 'package:path/path.dart';
</pre>
* Es werden also ein "internes" Paket <code>dart:io</code> und zwei externe Pakete eingebunden: args und path

= Die Funktion isBinary() =
Test, ob eine Datei eine Binärdatei ist.

Algorithmus: Untersuche die ersten 4 kByte der Datei, ob dort mindestens ein Nullbyte vorkommt oder die Anzahl der Kontrollzeichen (ASCII-Code < Leerzeichen und keine
Tabulator oder Zeilenendenzeichen) über 25% ist.

<pre>/// Tests whether a file named [filename] is a binary file.
/// Returns true if ASCII control characters lower than ' ' are greater than 25%
bool isBinary(String filename) {
  final file = File(filename);
  var rc = false;
  if (file.existsSync()) {
    final handle = file.openSync();
    final buffer = handle.readSync(4096);
    handle.close();
    var countControl = 0;
    for (var ix = 0; ix < buffer.lengthInBytes; ix++) {
      final byte = buffer[ix];
      if (byte == 0) {
        rc = true;
        break;
      }
      if (byte < 8 /* TAB */ || byte > 13 /* LF */ && byte < 32 /* ' '*/) {
        countControl++;
      }
    }
    rc = rc || countControl * 4 > buffer.lengthInBytes;
  }
  return rc;
}
</pre>
* <code>/// Tests ...</code> Eine kurze Beschreibung der Funktion. Hinweis: Kommentare mit  3 Schrägstrichen <code>///</code> werden automatisch in die Dokumentation übernommen. Verweise in den Code werden mit eckigen Klammern angezeigt, z.B. [filename] besagt, dass <code>filename</code> ein Parameter ist.
* <code>bool isBinary(String filename) {</code> Die Funktion hat als Ergebnis einen Wahrheitswert (bool) und als Parameter einen String, der den vollen Dateinamen angibt.
* <code>file = File(filename);</code>
** Im Paket "dart:io" gibt es die Klasse <code>File</code>, die im Konstruktor den Dateinamen bekommt.
** Mit einem Objekt dieser Klasse können viele Dateioperationen erledigt werden.
* <code>if (file.existsSync()) {</code> Es wird geprüft, ob die Datei existiert. '''Hinweis''': das <code>Sync</code> im Namen bedeutet, dass die Methode synchron ausgeführt wir, also sofort. Im nächsten Kapitel werden im Gegensatz dazu asynchrone Funktionen erklärt.
* Wenn nein, passiert nichts, die Variable <code>rc</code> hat dann den Wert <code>false</code>:
** Wenn die Datei existiert:
** <code>handle = file.openSync();</code> Die Datei wird geöffnet, kein Parameter bedeutet, sie wird zum Lesen geöffnet.
** <code>buffer = handle.readSync(4096);</code> Es werden bis zu 4096 Bytes gelesen, dieser Inhalt landet in der Variable <code>buffer</code>.
** <code>handle.close();</code> Wichtig: Wenn eine Datei geöffnet wird, muss sie auch wieder geschlossen werden, sonst werden Resourcen wie Arbeitsspeicher nicht wieder freigegeben.
** <code>for (var ix = 0; ix < buffer.lengthInBytes; ix++) {</code> Wir gehen in einer Schleife alle Bytes des bis zu 4-kByte Blockes durch:
** <code>byte = buffer[ix]</code> Wir merken uns das aktuelle Byte.
** <code>if (byte == 0)</code> Hat das aktuelle Byte den Wert 0 (dieser Wert kommt in Textdateien nie vor).
** <code>rc = true;</code> Der Rückgabewert ist <code>true</code>, die Datei ist binär.
** <code>break</code> Wir brechen die Schleife ab.
** <code>if (byte < 8 /* TAB */ || byte > 13 /* LF */ && byte < 32 /* ' '*/) {</code>
*** Es wird geprüft, ob ein in Texten selten vorkommendes Zeichen vorliegt
*** <code>countControl++;</code> Wenn ja, zählen wir dieses Controlzeichen
* <code>rc = rc || countControl * 4 > buffer.lengthInBytes;</code>
** Wir befinden uns hinter der '''for'''-Schleife.
** Es findet eine boolsche Operation mit dem Operator <code>||</code> statt:
** Wenn <code>rc</code> den Wert <code>true</code> hat, dann wurde ein Nullbyte gefunden, das Ergebnis ist <code>true</code>, denn: (true || irgendwas) ist true
** Wenn <code>rc</code> false ist (also kein Nullbyte gefunden wurde), dann wird geprüft, ob die Anzahl der Kontrollzeichen mehr als ein Viertel (also 25%) der Gesamtzahl ist. Wenn ja, ist das Ergebnis <code>true</code>, die Datei ist eine Binärdatei.

= Die Funktion intValue() =
Wandelt einen String in eine Ganzzahl unter Berücksichtigung von <code>null</code>.
<pre>/// Converts a string [value] into an int.
/// Returns null on null or invalid numbers.
int intValue(String value){
  return value == null ? null : int.tryParse(value);
}

</pre>
* Wenn der Parameter <code>value</code> <code>null</code> ist, ist das Ergebnis null.
* Wenn nicht, wird aus dem String eine Zahl, wobei <code>int.tryParse()</code> auch null liefert, wenn der String keine Zahl ist, ansonsten die entsprechende Ganzzahl.

= Die Funktion regExprEscape() =
<pre>/// Escapes all meta characters in [string] for a regular expression string.
/// Returns [string] with all meta characters escaped by a preceding backslash.
/// Note: the algorithm is taken from the Python standard library.
String regExprEscape(String string) {
  String rc;
  if (string != null) {
    rc = '';
    for (var ii = 0; ii < string.length; ii++) {
      final cc = string[ii];
      if ('()[]{}?*+-|^\$\\.&~# \t\n'.contains(cc)) {
        rc += r'\';
      }
      rc += cc;
    }
  }
  return rc;
}
</pre>
* Die Funktion wandelt alle Zeichen, die in einem regulären Ausdruck eine Sonderbedeutung haben (''Metazeichen'') in das gleiche Zeichen mit vorausgehendem Gegenstrich <code>\</code> um, also aus <code>*+</code> wird <code>\*\+</code>. Alle anderen Zeichen bleiben gleich.
* <code>for (var ii = 0; ii < string.length; ii++) {</code> In einer Schleife werden alle Zeichen des Parameters <code>string</code> bearbeitet.
* <code>cc = string[ii]</code> Das aktuelle Zeichen wird in der Variablen <code>cc</code> bereitgestellt
* <code>if ('()[]{}?*+-|^\$\\.&~# \t\n'.contains(cc))</code> Der String <code>'()[]{}?*+-|^\$\\.&~# \t\n'</code> enthält alle Metazeichen, mittels der Methode <code>contains()</code> wird festgestellt, ob das Zeichen <code>cc</code> sich darin befindet.
* <code>rc += r'\';</code> Wenn ja, wird ein Gegenstrich ans Ergebnis angeheftet.
* <code>rc += cc;</code> Jetzt wird das Zeichen selbst angehängt.

= Die Funktion shellPatternToRegExp() =
Diese Funktion wandelt ein Suchmuster, wie sie in Kommandozeile üblich ist, in den String
eines analogen regulären Ausdrucks um: <code>*.txt</code> wird zu <code>.*\.txt</code>.

* Das Jokerzeichen <code>*</code> (beliebiger String) wird zu <code>.*</code>.
* Das Jokerzeichen <code>?</code> (genau ein beliebiges Zeichen) wird zu <code>.</code>.
* Eine negierte Zeichenklasse <code>[!X]</code> wird zu <code>[^X]</code>.
* In Zeichenklassen werden bestimmte Zeichen mit vorausgehenem Gegenstrich <code>\</code> maskiert, damit sie nicht als Metazeichen interpretiert werden.
<pre>/// Translates a unix shell pattern into a regular expression pattern.
/// Example: '*.txt' is translated into r'.*\.txt'
/// Note: the algorithm is a simplified version of the algorithm in the Python standard library.
/// [addBeginOfString]: true: the result starts with '^'.
/// [addEndOfString]: true: the result ends with r'$'.
String shellPatternToRegExp(String pattern,
    {bool addBeginOfString = true, bool addEndOfString = true}) {
  var rc;
  if (pattern == null) {
    rc = null;
  } else {
    var i = 0;
    var length = pattern.length;
    rc = '';
    while (i < length) {
      final c = pattern[i++];
      if (c == '*') {
        rc += '.*';
      } else if (c == '?') {
        rc += '.';
      } else if (c == '[') {
        var j = i;
        if (j < length && pattern[j] == '!') {
          j++;
        }
        if (j < length && pattern[j] == ']') {
          j++;
        }
        while (j < length && pattern[j] != ']') {
          j++;
        }
        if (j >= length) {
          rc += r'\[' + pattern.substring(i);
          break;
        }
        var stuff = pattern.substring(i, j);
        if (stuff[0] == '!') {
          stuff = '^' + stuff.substring(1);
        }
        stuff = stuff.replaceAll(r'\', r'\\').replaceAll(']', r'\]');
        rc += '[$stuff]';
        i = j + 1;
      } else {
        rc += regExprEscape(c);
      }
    }
    if (addBeginOfString) {
      rc = '^' + rc;
    }
    if (addEndOfString) {
      rc += r'$';
    }
  }
  return rc;
}
</pre>
* Der Algorithmus ist aus der Standardroutine von Python abgeschaut, eine reine Fleißaufgabe, nichts Aufregendes oder Neues.

= testIntArguments() =
Die Funktion prüft, ob für eine Liste von Programmoptionen jeweils eine Ganzzahl eingegeben wurde.
<pre>/// Tests whether the [options] are integers. If not the callback usage is called.
/// Returns true if all arguments are integers.
bool testIntArguments(
    ArgResults argResults, List<String> options, Function usage) {
  var rc = true;
  for (var opt in options) {
    if (argResults[opt] != null && int.tryParse(argResults[opt]) == null) {
      usage('$opt is not an integer: ${argResults[opt]}');
      rc = false;
      break;
    }
  }
  return rc;
}
</pre>
* <code>bool testIntArguments(ArgResults argResults, List<String> options, Function usage) </code>
** Das Funktionsergebnis ist '''bool''', als Argument wird übergeben:
*** Ein Objekt der Klasse <code>ArgResults</code> aus dem Paket <code>args</code> (siehe Inport).
*** Die Liste der Optionsnamen, die überprüft werden soll: <code>options</code>
*** Eine Callbackfunktion, die im Fehlerfall aufgerufen wird.
* In einer Schleife werden alle Elemente der Optionsnamensliste untersucht:
* Ist der Optionswert keine Zahl, dann wird die Callbackfunktion mit der Fehlermeldung als Parameter aufgerufen und der Ergebniswert auf <code>false</code> gesetzt.

= Die Funktion testRegExpArguments() =
Analogon zur Funktion <code>testIntArguments()</code>, nur dass hier geprüft wird, ob ein syntaktisch korrekter regulärer Ausdruck vorliegt.

<pre>/// Tests whether the [options] are integers. If not the callback usage is called.
/// Returns true if all arguments are integers.
bool testRegExpArguments(
    ArgResults argResults, List<String> options, Function usage) {
  var rc = true;
  for (var opt in options) {
    try {
      if (argResults[opt] != null) {
        RegExp(argResults[opt]);
      }
    } on FormatException catch (exc) {
      usage('$opt: error in regular expression "${argResults[opt]}": $exc');
      rc = false;
      break;
    }
  }
  return rc;
}
</pre>

= Die Funktion writeString() =
Diese Funktion schreibt eine String oder eine Stringliste in eine Datei.
Es wird geprüft, ob das Verzeichnis, in der die Datei steht, existiert.
Wenn nicht, wird dieses Verzeichnis angelegt.

<pre>/// Writes a [string] or a [list] into a [file].
/// The path is
void writeString(String filename, {String string, List<String> list}) {
  try {
    final base = dirname(filename);
    if (base.isNotEmpty) {
      Directory(base).createSync(recursive: true);
    }
    if (list != null) {
      string = list.join('\n');
    }
    File(filename).writeAsStringSync(string);
  } on FileSystemException catch (exc) {
    print('+++ $exc');
  }
}
</pre>
* <code>void writeString(String filename, {String string, List<String> list}) {</code>
** Es werden benannte Parameter benutzt: <code>string</code> und <code>list</code>.
** <code>try { ... } on FileSystemException catch (exc) {</code> Passiert bei einer Dateioperation ein Fehler (z.B. keine Berechtigung beim Erzeugen der Datei), wird dieser Fehler gemeldet: <code>print('+++ $exc');</code>
* <code>final base = dirname(filename);</code> Wir verwenden das Paket <code>path</code>. Dort ist die Funktion <code>dirname()</code> definiert, die den Namen des Verzeichnisses einer Datei ermittelt, für alle Betriebssysteme.
* <code>if (base.isNotEmpty)</code> Wenn ein Verzeichnis Teil des Dateinamens ist...
* <code>Directory(base).createSync(recursive: true);</code>
** ... wird ein Verzeichnis angelegt, wenn es noch nicht existiert:
** <code>Directory</code> ist eine Klasse aus "dart:io", die als Konstruktor den Namen des Verzeichnisses bekommt
** <code>createSync()</code> legt das Verzeichis mit allen "Vaterverzeichnissen" an. Wenn es schon existiert, passiert nichts.
* Die benannten Parameter <code>string</code> und <code>list</code> sind alternativ.
* Im Fall von <code>list</code> wird diese in einen String umgewandelt, mit der Methode <code>join()</code>, die alle Elemente zusammenfügt, mit dem als Parameter übergebenen Trenner, in unserem Fall ein Zeilenwechsel <code>\n</code>
* <code>File(filename).writeAsStringSync(string);</code>
** Die Klasse <code>File</code> aus "dart:io" wird mit dem Dateinamen im Konstruktor instantiiert (als Objekt erstellt)
** und der String wird in diese Datei geschrieben und zwar mit dem Zeichensatz UTF-8 (einen anderen Zeichensatz kann man per Parameter wählen).
* Geht beim Dateischreiben was schief, beispielsweise ein Rechteproblem, wird eine Ausnahme vom Typ <code>FileSystemException</code> geworfen. Im diesem Fall wird eine Fehlermeldung ausgegeben.
** <code>on FileSystemException catch (exc)</code> das Objekt der Ausnahme steht in der Variablen <code>exc</code> zur Verfügung
** Wie jede Klasse hat auch <code>FileSystemException</code> eine Methode <code>toString()</code>, die bei der Interpretation von <code>+++ $exc</code> die Fehlermeldung einbaut.