Bearbeiten von „Datei search engine.dart“

= Links =
* [[Projekt dgrep]]

= Die Funktion usage() =
Die Funktion usage() gibt eine Beschreibung der Benutzung des Programms aus und evt.
eine Fehlermeldung.
<pre>/// Shows a message how to use the program.
/// [message]: null or an error message
/// [parser]: delivers the description of the program's options
void usage(String message, {ArgParser parser}) {
  print('''Usage: dgrep [<options>] <pattern> [<file1> [<file2> ...]]
  Searches <pattern> in <file1> <file2>...
  <fileN>: a directory or a shell file pattern like '*.txt'
    or both like /home/*.txt
<option>:''');
  if (parser == null) {
    print('  Use -h or --help for more info');
  } else {
    print(parser.usage);
  }
  if (message != null) {
    print('+++ ' + message);
  }
}
</pre>
* <code>///</code> markiert einen Kommentar, der automatisch für die Dokumentation ausgewertet wird.
* <code>print(parser.usage);</code> Das Attribut <code>usage</code> der Klasse <code>ArgParser</code> gibt eine automatisch erstellte Beschreibung der Optionen aus.
* Es wird eine mehrzeiliger Stringkonstante benutzt, die mit drei Apostrophen <code>"'Usage:...<option>:'"</code> eingeschlossen ist. Hinweis: drei Apostrophe sind im Wiki nicht darstellbar, daher die "Simulation" mit Gänsefüßchen und Apostroph.

= Klasse ExitException =
Diese Klasse wird als Ausnahme benutzt, um aus einer verschachtelten Situation unkompliziert ans Ende des Programms zu gelangen, wenn bestimmte Bedingungen erfüllt sind.
<pre>/// Used for jump out of nested calls.
class ExitException {
  final String reason;
  ExitException(this.reason);
}
</pre>

= Die Klasse FileOptions =
Diese Klasse speichert die Optionen, die sich auf die Dateiauswahl beziehen.
<pre>/// Stores file selection options.
class FileOptions {
  bool recursive;
  RegExp excluded;
  RegExp excludedDirs;
  bool processBinaries;
  FileOptions(
      {this.recursive = false,
      this.excluded,
      this.excludedDirs,
      this.processBinaries = false});
  FileOptions.fromArgument(ArgResults results) {
    recursive = results['recursive'];
    excluded = results['excluded'] == null ? null : RegExp(results['excluded']);
    excludedDirs = results['excluded-dirs'] == null
        ? null
        : RegExp(results['excluded-dirs']);
    processBinaries = results['process-binaries'];
  }
}
</pre>
* Es existieren zwei Konstruktoren:
** <code>FileOptions()</code> wird nur in Tests benutzt.
** <code>FileOptions.fromArgument()</code> holt die Optionen aus einem Objekt der Klasse <code>ArgResult</code> aus dem externen Paket <code>args</code>.
* <code>recursive = results['recursive'];</code> Das boolsche Attribut <code>recursive</code> wird direkt aus dem Objekt der Klasse <code>ArgResult</code> übernommen. Wir lernen: Zugriff auf die Optionen erfolgt mittels Namen <code>recursive</code>  mit dem eckige-Klammer-Operator wie bei Maps.

= Die Klasse SearchEngine =
Die Klasse implementiert ("realisiert") die Suche.

== Die Attribute ==
Zuerst werden die Attribute definiert:
<pre>
/// Searches a regular expression in files.
class SearchEngine {
  static bool storeResult = false;
  final List<String> filePatterns;
  final String pattern;
  final SearchOptions searchOptions;
  final FileOptions fileOptions;
  int handledFiles = 0;
  int handledDirs = 0;
  int totalHitLines = 0;
  int totalHitFiles = 0;
  int ignoredFiles = 0;
  int ignoredDirs = 0;
  int countBinaries = 0;
  int verboseLevel = 4;
  RegExp regExp;
  String rc;
  final lines = <String>[];
  static final formatPlaceholders = RegExp(r'%[#fpnFehcl1-9]%');
</pre>
* Das Attribut <code>formatPlaceholders</code> ist als <code>static</code> definiert, damit findet die Initialiserung nur einmal statt, nicht bei jedem Objekt. Das ist möglich, weil sich der Ausdruck zur Beschreibung eines Platzhalters im Formatstring nie was ändert.

== Der Konstruktor ==
<pre>SearchEngine(this.pattern, this.filePatterns,
    {this.fileOptions, this.searchOptions, this.verboseLevel = 0});
</pre>
* Es werden das Suchmuster <code>pattern</code>, eine Liste von Dateimustern <code>filePatterns</code>, Dateioptionen, Suchoptionen und ein Level für Meldungen <code>verboseLevel</code> übergeben und gespeichert.

== Die Methode formatLine() ==
Diese Methode stellt einen String zur Ausgabe zusammen, gesteuert durch ein Format, das per Option definiert wird.

Die notwendigen Daten werden per Parameter übergeben, auch das Format, da es zwei Formate gibt: das für Trefferzeilen und das für Zeilen "der Umgebung" (siehe Option <code>--above-lines</code>
oder <code>below-lines</code>).

<pre>/// Creates an output line depending on a given [format].
String formatLine(
    String format, String file, String line, int lineNo, String prefix,
    {RegExpMatch match, int hits}) {
  String line2;
  if (format == null) {
    line2 = '$prefix$file-$lineNo: $line';
  } else {
    line2 = searchOptions.format;
    for (var match2 in formatPlaceholders.allMatches(format)) {
      final placeholder = match2.group(0);
      switch (placeholder[1]) {
        case '#':
          line2 = line2.replaceAll(placeholder, lineNo.toString());
          break;
        case 'f':
          line2 = line2.replaceAll(placeholder, file);
          break;
        case 'p':
          line2 = line2.replaceAll(placeholder, dirname(file));
          break;
        case 'n':
          line2 = line2.replaceAll(placeholder, basename(file));
          break;
        case 'F':
          line2 = line2.replaceAll(
              placeholder, basenameWithoutExtension(file));
          break;
        case 'e':
          line2 = line2.replaceAll(placeholder, extension(file));
          break;
        case 'h':
          line2 = line2.replaceAll(placeholder, match?.group(0) ?? '');
          break;
        case 'c':
          line2 = line2.replaceAll(placeholder, hits?.toString() ?? '');
          break;
        case 'l':
          line2 = line2.replaceAll(placeholder, line);
          break;
        case '1':
        case '2':
        case '3':
        case '4':
        case '5':
        case '6':
        case '7':
        case '8':
        case '9':
          final groupNo = placeholder.codeUnitAt(1) - '0'.codeUnitAt(0);
          line2 = line2.replaceAll(placeholder, match?.group(groupNo) ?? '');
          break;
        default:
          break;
      }
    }
  }
  return line2;
}
</pre>
* <code>if (format == null)</code> Wenn das Format <code>null</code> ist, liegt keine Definition per Option vor, es wird ein Standardformat benutzt, mit Dateiname, Zeilennummer und Zeile.
* Ist ein Format definiert:
** <code>line2 = searchOptions.format;</code> Das Format wird kopiert in die Variable <code>line2</code> kopiert, da das Orginal unverändert bleiben muss.
** <code>for (var match2 in formatPlaceholders.allMatches(format))</code>
*** <code>formatPlaceholders</code> ist ein regulärer Ausdruck, der alle Platzhalter im Format beschreibt: <code>RegExp(r'%[#fpnFehcl1-9]%')</code> Zwei Prozentzeichen, zwischen denen eines der aufgeführten Zeichen <code>#</code> ... <code>l</code> oder eine Ziffer <code>1-9</code> liegt.
*** Die Klasse <code>RegExp</code> liefert mit der Methode <code>allMatches()</code> nacheinander alle Treffer des regulären Ausdrucks in dem als Parameter übergebenen String (hier <code>format</code>) liefert. Über diese Treffer wird die Schleife gebildet.
** <code>final placeholder = match2.group(0);</code> Der Treffer (beispielsweise <code>%f%</code>) wird in der Variablen <code>placeholder</code> gemerkt.
** <code>switch(placeholder[1])</code> Es wird das zweite Zeichen (gezählt wird ab 0) als Fallunterscheidung genommen:
*** <code>case '#':</code> Ist dieses 2.te Zeichen ein <code>#</code> ...
*** <code>line2 = line2.replaceAll(placeholder, lineNo.toString());</code> Es werden alle diese Platzhalter (<code>%#%</code>) durch die Zeilenummer, gewandelt in einen String, ersetzt.
** Nach diesem Schema werden die auch die anderen Platzhalter ersetzt.
** <code>match?.group(0) ?? "</code> Der Operator <code>?.</code> sorgt dafür, dass kein Fehler auftritt, wenn das Objekt <code>match</code> vor dem Operator <code>null</code> ist, sondern das Ergebnis von <code>match?.group(0)</code> ist dann <code>null</code>. Der Operator <code>??</code> wird dann aktiv, wenn er Operand vor dem Operator null ist, dann ist das Gesamtergebnis der Operand nach dem Operator, also der Leerstring.
* <code>groupNo = placeholder.codeUnitAt(1) - '0'.codeUnitAt(0);</code>
** <code>placeholder.codeUnitAt(1)</code> liefert den Ganzzahlwert des 2.ten Zeichens (gezählt ab 0), von diesem wird der Ganzzahlwert der Ziffer '0' abgezogen. Da die Ganzzahlwerte der Ziffern "hintereinander" liegen, ergibt die Differenz die gewünschte Gruppennummer.
** Eine verständliche aber inneffizentere Variante wäre:
** <code>groupNo = int.parse(placeholder[1]);</code>

== Methode search() ==
Die Methode bereitet die Suche vor und startet sie.

<pre>/// Prepares the search and do it.
void search() {
  String exitMessage;
  try {
    final pattern2 = searchOptions.word ? '\\b$pattern\\b' : pattern;
    regExp = RegExp(pattern2, caseSensitive: !searchOptions.ignoreCase);
    final regExpList = <RegExp>[];
    final paths = <String>[];
    for (var item in filePatterns) {
      if (FileSystemEntity.isDirectorySync(item)) {
        paths.add(item);
        regExpList.add(null);
      } else {
        final directory = dirname(item);
        final filePattern = basename(item);
        paths.add(item.isEmpty ? '.' : directory);
        regExpList.add(filePattern.isEmpty ? null : RegExp(shellPatternToRegExp(filePattern)));
      }
    }
    try {
      for (var ix = 0; ix < paths.length; ix++) {
        searchFilePattern(regExpList[ix], paths[ix], 0);
      }
    } on ExitException catch (exc) {
      exitMessage = '= search stopped: ' + exc.reason;
    }
    if (verboseLevel >= 1) {
      var hits = searchOptions.count || searchOptions.list
          ? ''
          : ' matching lines: $totalHitLines';
      print(
          '= processed directories: $handledDirs processed files: $handledFiles$hits');
      print(
          '= ignored directories: $ignoredDirs ignored files: $ignoredFiles binary files: $countBinaries');
      if (exitMessage != null) {
        print(exitMessage);
      }
    }
  } on FormatException catch (exc) {
    usage('error in regular expression "$pattern": $exc');
  }
}
</pre>
* <code>final pattern2 = searchOptions.word ? '\\b$pattern\\b' : pattern;</code>
** Bedingter Ausdruck:
** Wenn die Option <code>--word</code> gesetzt wurde, wird an das Suchmuster ein <code>\b</code> vorangestellt und angehängt: dieses Metazeichen steht für nicht für einen String, sondern für eine Wortgrenze, also genau das was wir hier brauchen.
** Ohne die Word-Option wird das Muster <code>pattern</code> direkt verwendet.
* <code>regExp = RegExp(pattern2, caseSensitive: !searchOptions.ignoreCase);</code>
** Die Option <code>--ignore-case</code> wird hier berücksichtigt. Da ''case-sensitiv'' die logische Umkehrung von ''ignore-case'' ist, wird der logische Operator <code>!</code> eingesetzt, der aus <code>true</code> <code>false</code> macht und umgekehrt.
* <code>for (var item in filePatterns)</code> Die Dateinamensmuster können Pfade enthalten oder nicht, diese Info wird in dieser Schleife ermittelt, in Form von zwei Listen mit Pfaden <code>paths</code> und mit Dateimuster<code>regExprList</code>
** <code>if (FileSystemEntity.isDirectorySync(item))</code> Test, ob die Angabe nur ein Verzeichnis ist.
** Wenn ja, Eintrag in die Pfadliste und <code>null</code> in die Namensmusterliste (für "alle Dateien")
** Wenn nein, wird die Angabe in Verzeichnis <code>directory</code> und Dateinamensmuster <code>filePattern</code> zerlegt.
** In die Pfadliste wird das aktuelle Verzeichnis <code>'.'</code> eingetragen, wenn <code>directory</code> leer ist, sonst das Verzeichnis.
* <code>for (var ix = 0; ix < paths.length; ix++)</code> eine Schleife über alle Indizes der Pfadliste.
* <code>searchFilePattern(regExprList[ix], paths[ix], 0);</code> Diese Methode realisiert die eigentliche Suche.
* <code>try { ... } on ExitException catch (exc)</code> Hier werden die "Schnellabbrüche" aufgefangen. Das passiert, wenn eine Bedingung der Optionen <code>--exit-lines</code> oder <code>--exit-files</code> erfüllt ist.
* <code>try {...} on FormatException catch (exc) {</code> Die Ausnahme wird geworfen, wenn der reguläre Ausdruck in <code>regExp = RegExp(pattern2,...)</code> inkorrekt ist. Es wird dann eine Fehlermeldung mittels der Funktion <code>usage()</code> ausgegeben.

== Die Methode searchFile() ==
Die Methode durchsucht eine Datei nach dem spezifizierten Suchstring.
Sie ist relativ umfangreich, was an den vielen Suchoptionen liegt.

<pre>/// Read the [file]'s content and search for the search pattern respecting
/// the search options.
/// Uses [showLine()] to show the matching lines.
void searchFile(String file) {
  if (verboseLevel >= 3) {
    print('= processing $file ...');
  }
  try {
    final lines = File(file).readAsLinesSync();
    handledFiles++;
    var hitLines = 0;
    var lineNo = 0;
    var lastShowedLine = 0;
    var aboveBound = 0;
    var line2;
    final prefixMatch =
        searchOptions.belowContext > 0 || searchOptions.aboveContext > 0
            ? '='
            : '';
    for (var line in lines) {
      lineNo++;
      final match = regExp.firstMatch(line);
      final isHit = !searchOptions.invertMatch && match != null ||
          searchOptions.invertMatch && match == null;
      if (!isHit) {
        if (lineNo <= aboveBound) {
          line2 = formatLine(
              searchOptions.formatContext, file, line, lineNo, '>');
          showLine(line2);
          lastShowedLine = lineNo;
        }
      } else {
        hitLines++;
        totalHitLines++;
        if (searchOptions.list) {
          showLine(file);
          break;
        }
        aboveBound = lineNo + searchOptions.aboveContext;
        if (!searchOptions.count) {
          if (searchOptions.belowContext > 0) {
            for (var lineNo2 = lineNo - searchOptions.belowContext;
                lineNo2 < lineNo;
                lineNo2++) {
              if (lineNo2 > lastShowedLine) {
                line2 = formatLine(searchOptions.formatContext, file,
                    lines[lineNo2 - 1], lineNo2, '<');
                showLine(line2);
              }
            }
          }
          line2 = formatLine(
              searchOptions.format, file, line, lineNo, prefixMatch,
              match: match);
          showLine(line2);
          lastShowedLine = lineNo;
        }
        if (searchOptions.exitLines != null &&
            totalHitLines >= searchOptions.exitLines) {
          throw ExitException('hit lines: $totalHitLines');
        }
        if (searchOptions.breakLines != null &&
            hitLines >= searchOptions.breakLines) {
          break;
        }
      }
    }
    if (searchOptions.count) {
      showLine(searchOptions.format == null
          ? '$hitLines $file'
          : formatLine(searchOptions.format, file, '', 0, '',
              hits: hitLines));
    }
  } on FileSystemException {
    ignoredFiles++;
  }
}
</pre>
* <code>final lines = File(file).readAsLinesSync();</code> Die Klasse <code>File></code> instantiiert ein Objekt mit dem Dateinamen <code>file</code>, die Methode <code>readAsLinesSync()</code> liefert den Dateiinhalt als Liste von Zeilen.
* <code>for (var line in lines)</code> iteriert über alle Zeilen
* <code>final match = regExp.firstMatch(line);</code> Test, ob die Zeile <code>line</code> das Suchmuster enthält.
* <code>isHit = !searchOptions.invertMatch && match != null || searchOptions.invertMatch && match == null;</code>
** Ein Treffer liegt vor, wenn die Option <code>--invert-match</code> gesetzt ist und das Suchmuster nicht gefunden wurde oder wenn  Option <code>--invert-match</code> '''nicht''' gesetzt ist und das Suchmuster gefunden wurde.
* <code>if (!isHit)</code> Wenn kein Treffer vorliegt, Behandlung des "nachfolgenden Contexts" (Option <code>--above-lines</code>)
* <code>if (searchOptions.list)</code> Wenn die Option <code>--list</code> gesetzt ist, wird der Dateiname ausgegeben <code>showLine(file);</code> und die Suche in dieser Datei beendet (<code>break</code>).
* <code>if (!searchOptions.count)</code> Wenn die Option <code>--count</code> nicht gesetzt ist...
* <code>line2 = formatLine(searchOptions.format, file, line, lineNo, prefixMatch,               match: match);</code> Der Treffer wird aufbereitet ...
* <code>showLine(line2);</code> ... und ausgegeben
* <code>if (searchOptions.exitLines != null && totalHitLines >= searchOptions.exitLines)</code> Wenn die Option <code>--exit-lines</code> gesetzt ist und die Zahl der Trefferzeilen erreicht ist, Schnellabbruch mit der Ausnahme <code>ExitException</code>.
* <code>if (searchOptions.breakLines != null && hitLines >= searchOptions.breakLines)</code> Wenn die Option <code>--break-lines</code> gesetzt ist und die Zahl der Trefferzeilen in der Datei erreicht ist, wird die Suchschleife beendet (<code>break</code>).
* <code>if (searchOptions.count)</code> Wenn die Option <code>--count</code> gesetzt ist, wird die Anzahl der Treffer in dieser Datei ausgegeben (nach der Suchschleife, wenn die Treffer gezählt sind).
* <code>try { ... } on FileSystemException {</code> Beim Lesen der Datei kann ein Problem auftreten, beispielsweise ein Rechteproblem, es wird dann die Ausnahme <code>FileSystemException</code> geworfen. Wir zählen das Problem, fertig.

== Die Methode searchFilePattern() ==
Die Methode sucht die Dateien gemäß den Dateioptionen aus dem Dateibaum.

Die Methode ist rekursiv, das heißt sie ruft sich selber auf: Sie durchsucht ein Verzeichnis,
das mit dem Parameter <code>directory</code> spezifiziert ist, auf passende Dateien und ermittelt nebenbei alle Unterverzeichnisse. 
Danach ist eine Suche in den Unterverzeichnissen notwendig, und genau das kann die Methode, sie muss
sich nur mit einem anderen Parameter <code>directory</code> aufrufen.

<pre>/// Searches the files matching the [filePattern] in a [directory].
/// This method is recursive on subdirectories.
/// [depth] is the nesting level of the recursive calls.
void searchFilePattern(RegExp filePattern, String directory, int depth) {
  if (verboseLevel >= 2 && depth <= 1 || verboseLevel >= 3) {
    print('= processing $directory ...');
  }
  final subDirectories = <String>[];
  try {
    handledDirs++;
    for (var file in Directory(directory).listSync()) {
      final name = file.path;
      final node = basename(name);
      if (FileSystemEntity.isDirectorySync(name)) {
        if (fileOptions.excludedDirs != null &&
            fileOptions.excludedDirs.firstMatch(node) != null) {
          if (verboseLevel >= 4) {
            print('= ignoring not matching directory $name');
          }
          ignoredDirs++;
        } else {
          subDirectories.add(name);
        }
        continue;
      }
      if (filePattern != null && filePattern.firstMatch(node) == null) {
        ignoredFiles++;
        if (verboseLevel >= 4) {
          print('= ignoring not matching $name');
        }
        continue;
      }
      if (fileOptions.excluded != null &&
          fileOptions.excluded.firstMatch(node) != null) {
        ignoredFiles++;
        if (verboseLevel >= 4) {
          print('= ignoring excluded $name');
        }
        continue;
      }
      if (!fileOptions.processBinaries && isBinary(name)) {
        if (verboseLevel >= 4) {
          print('= ignoring binary $name');
        }
        countBinaries++;
        continue;
      }
      final safeHits = totalHitLines;
      searchFile(name);
      if (totalHitLines > safeHits) {
        totalHitFiles++;
        if (searchOptions.exitFiles != null &&
            totalHitFiles >= searchOptions.exitFiles) {
          throw ExitException('hit files: $totalHitFiles');
        }
      }
    }
  } on FileSystemException {
    handledDirs--;
    ignoredDirs++;
  }
  if (fileOptions.recursive) {
    for (var subDir in subDirectories) {
      searchFilePattern(filePattern, subDir, depth + 1);
    }
  }
}
</pre>
* <code>final subDirectories = <String>[];</code> Eine leere Liste für die Unterverzeichnisse wird angelegt.
* <code>for (var file in Directory(directory).listSync())</code>
** Ein Objekt der Klasse <code>Directory</code> wird instantiiert, mit dem Verzeichnisnamen als Parameter. Dieses Objekt liefert mit der Methode <code>listSync()</code> eine Liste von <code>File</code>-Objekten ab, die mit der Schleife abgearbeitet wird.
* <code>name = file.path;</code> Das Attribut <code>path</code> liefert den vollen Namen der Datei.
* <code>node = path.basename(name);</code> Die Funktion <code>basename()</code> entfernt die Pfadangabe vom Dateinamen.
* <code>if (FileSystemEntity.isDirectorySync(name))</code> Es wird geprüft, ob die Datei ein Verzeichnis ist: Wenn ja, wird untersucht, ob ein Ausschluss des Verzeichnisses mittels der Option <code>--excluded-dirs</code> definiert ist. Wenn nicht, wird der volle Dateiname an die Liste der Unterverzeichnisse angehängt: <code>subDirectories.add(name);</code> und die Schleife mit <code>continue;</code> fortgesetzt, also mit der nächsten Zeile weitergemacht.
* <code>if (filePattern != null && filePattern.firstMatch(node) == null)</code>
** Es wird geprüft, ob ein Dateimuster vorliegt (<code>filePattern != null</code>), aber kein Treffer vorliegt: Dann kommt die Datei nicht in Frage.
** <code>continue;</code> es geht mit dem nächsten Eintrag aus der <code>File</code>-Liste weiter.
* <code>if (fileOptions.excluded != null && fileOptions.excluded.firstMatch(node) != null)</code>
** Wenn eine Dateiauschlussoption (<code>--excluded</code> definiert ist, und das Suchmuster passt, kommt die Datei nicht in Frage, es geht mit dem nächsten Eintrag weiter (<code>continue</code>).
* <code>if (!fileOptions.processBinaries && isBinary(name))</code>Wenn die Option <code>--process-binary</code> nicht gesetzt ist und die Datei binär ist, geht es zum nächsten Listeneintrag (<code>continue</code>). Die Funktion <code>isBinary</code> stammt aus der [[Datei helper.dart]].
* <code>searchFile(name);</code> Hier findet die Suche in der Datei statt.
* <code>if (totalHitLines > safeHits)</code> Wenn sich die Zahl der Trefferzeilen geändert hat, erhöht sich die Zahl der Trefferdateien. Wenn mit der Option <code>--exit-files</code> hier eine Grenze definiert wurde und diese erreicht ist, wird ein Schnellausstieg mit dem Werfen der Ausnahme <code>ExitException</code> getätigt.
* <code>try { ... } on FileSystemException {</code> Beim Aufruf der Methode <code>listSync()</code> kann ein Problem auftreten, das das Werfen der Ausnahme <code>FileSystemException</code> auslöst. In diesem Fall wird die Statistik berichtigt und die Suche in diesem Verzeichnis beendet.
* <code>if (fileOptions.recursive)</code> Wenn die Option <code>--recursive</code> gesetzt ist, wird die Liste der Unterverzeichnisse in einer Schleife <code>for (var subDir in subDirectories)</code> abgearbeitet. Das geschieht durch Aufruf der Methode <code>searchFilePattern()</code>, also einem '''rekursiven Aufruf''' von "sich selber". Die Verschachtelungstiefe <code>depth</code> erhöht sich dann um <code>1</code>.

== Die Methode showLine() ==
Eine übersichtliche Methode, die entweder die übergebenen Zeile in der Klassenvariablen <code>lines</code> speichert (anhängt), was für Unittests benötigt wird, oder die Zeile mittels <code>print()</code> ausgibt.
<pre>/// Prints or stores the output line, depending on the option [storeResult].
void showLine(String line) {
  if (storeResult) {
    lines.add(line);
  } else {
    print(line);
  }
}
</pre>

== Die Methode addFlags() ==
Die Methode fügt zum Objekt der Klasse <code>ArgParser</code> aus dem externen Paket <code>args</code> die Beschreibungen der Boolschen Optionen (genannt "Flags") hinzu.

<pre>// Adds all boolean options to the argument [parser].
static void addFlags(ArgParser parser) {
  parser.addFlag('count',
      abbr: 'c',
      help: 'Show only the count of lines with hits (per file)',
      negatable: false);
  parser.addFlag('ignore-case',
      abbr: 'i', help: 'The search is case insensitive', negatable: false);
...
}
</pre>
* <code>parser.addFlag('count',</code> Hinzufügen eines Optionsflags namens <code>count</code>, das bedeutet, die Option wird mit <code>--count</code> in der Kommandozeile aufgerufen.
* <code>abbr: 'c',</code> Es gibt eine abkürzende Notierung, nämlich <code>-c</code>.
* <code>help: 'Show only the count of lines with hits (per file)',</code> Eine Beschreibung der Option. Wird das Attribut <code>usage</code> der Klasse <code>ArgParser</code> abgefragt, erscheint dieser Hilfetext darin.
* <code>negatable: false);</code> Normalerweise kann ein Flag auch in invertierter Form aufgerufen werden, <code>no-count</code> würde den Wert negieren. Das wird mit diesem Parameter <code>negatable</code> ausgeschaltet.
* Der Rest der Methode funktioniert nach dem gleichen Schema für alle anderen Boolschen Optionen.

== Die Methode addOption() ==
Die Methode fügt zum Objekt der Klasse <code>ArgParser</code> aus dem externen Paket <code>args</code> die Beschreibungen von Optionen hinzu.

<pre>// Adds all not boolean options to the argument [parser].
static void addOptions(ArgParser parser) {
  parser.addOption('excluded',
      abbr: 'x',
      help: 'A regular expression for files to skip, e.g. ".*\.(bak|sic)"');
  parser.addOption('excluded-dirs',
      abbr: 'X',
      help:
          'A regular expression for directory to skip, e.g. "test|\.git|\.config');
...
}
</pre>
* <code>parser.addOption('excluded',</code> definiert eine Option namens <code>excluded</code>. Die Option kann in der Kommandzeile mit <code>--excluded=<string></code> (Wert mit '=' abgetrennt) aufgerufen werden, oder mit <code>--excluded <string></code> (Wert mit Leerzeichen abgetrennt).
* <code>abbr: 'x',</code> Definiert die Abkürzung, aufzurufen mit <code>-x<string></code> (ohne Trennzeichen) bzw. <code>-x <string></code> (mit Leerzeichen dazwischen).
* <code>help: 'A regular expression for files to skip, e.g. ".*\.(bak|sic)"');</code> definiert die Beschreibung, die für den Hilfetext verwendet wird.
* Die übrigen Optionen werden nach dem gleichen Schema definiert.

== Die Methode execute() ==
Diese statische Methode kann in <code>main()</code> aufgerufen werden, sie übernimmt die 
Programmargumente mit dem Parameter <code>arguments</code>.

Als Ergebnis wird ein Objekt der Klasse <code>SearchEngine</code> zurückgegeben, das wird ausgiebig bei den Unittests genutzt, die die Attribute der Klasse dann untersuchen.

Durch diese Konstruktion können die Tests mit größtmöglicher Nähe zum "normalen" Ablauf ablaufen.
Das ist eine sinnvolle Designentscheidung.

<pre>/// Executes the total search defined by the program [arguments].
static SearchEngine execute(List<String> arguments) {
  SearchEngine engine;
  final parser = ArgParser();
  addFlags(parser);
  addOptions(parser);
  try {
    final results = parser.parse(arguments);
    final intArgs = [
      'above-context',
      'context',
      'below-context',
      'break-lines',
      'exit-lines',
      'exit-files',
      'verbose-level'
    ];
    if (results['help']) {
      usage(null, parser: parser);
    } else if (results.rest.isEmpty) {
        usage('too few arguments');
    } else if (testIntArguments(results, intArgs, usage) &&
        testRegExpArguments(results, ['excluded', 'excluded-dirs'], usage)) {
      if (results.rest.isEmpty) {
        usage('too few arguments', parser: parser);
      } else {
        engine = SearchEngine(results.rest[0],
            results.rest.length == 1 ? ['.'] : results.rest.sublist(1),
            searchOptions: SearchOptions.fromArgument(results),
            verboseLevel: intValue(results['verbose-level']),
            fileOptions: FileOptions.fromArgument(results));
        engine.search();
      }
    }
  } on FormatException catch (exc) {
    usage(exc.toString());
  }
  return engine;
}
</pre>
* <code>final parser = ArgParser();</code> Initialisierung der Verarbeitung von Programmargumenten.
* <code>addFlags(parser);</code> und <code>addOptions(parser);</code> fügen die Optionen dazu.
* <code>results = parser.parse(arguments);</code> Die Verarbeitung der Programmargumente wird erledigt, Ergebnis ist ein Objekt vom Typ <code>ArgResults</code>.
* <code>if (results['help'])</code> Wurde die Option <code>--help</code> angegeben? Wenn ja wird die Beschreibung mittels <code>usage(null, parser: parser);</code> ausgegeben, ohne Fehlermeldung (erster Parameter ist <code>null</code>). Wir sehen hier, dass auf die Optionen von <code>results</code> mittels der eckigen Klammern zugegriffen werden kann, wie bei einer Map.
* <code>if (results.rest.isEmpty)</code> Das Attribut <code>rest</code> der Klasse <code>ArgResults</code> enthält alle Programmargumente, die keine Optionen sind, die also nicht mit '-' anfangen. Diese Liste wird getestet, ob sie leer ist. Wenn ja, liegt der Fehler "zu wenig Argumente" vor, der mit der Funktion <code>usage()</code> ausgegeben wird.
* <code>if (testIntArguments(...)</code> Test, ob die Optionen mit Ganzzahlen korrekt belegt wurden. Siehe [[Datei helper.dart]].
* <code>&& testRegExpArguments(...)</code> Test, ob die regulären Ausdrücke korrekt sind. Siehe [[Datei helper.dart]].
* <code>engine = SearchEngine(...)</code> Die Suchverarbeitung wird initialisiert...
* <code>engine.search()</code> ... und durchgeführt.
* <code>return engine;</code> Das Ergebnis ist das Objekt mit den Suchergebnissen.

= Die Klasse SearchOptions =
Diese Klasse speichert die Optionen, die sich auf die Textsuche beziehen.
<pre>class SearchOptions {
  bool count;
  bool ignoreCase;
  bool invertMatch;
  bool list;
  bool word;
  String format;
  String formatContext;
  int aboveContext;
  int belowContext;
  int breakLines;
  int exitLines;
  int exitFiles;

  SearchOptions(
      {this.count = false,
      this.ignoreCase = false,
      this.invertMatch = false,
      this.list = false,
      this.word = false,
      this.format,
      this.formatContext,
      this.aboveContext = 0,
      this.belowContext = 0,
      this.exitFiles,
      this.breakLines,
      this.exitLines});

  SearchOptions.fromArgument(ArgResults results) {
    count = results['count'];
    ignoreCase = results['ignore-case'];
    invertMatch = results['invert-match'];
    list = results['list'];
    word = results['word'];
    format = results['format'];
    formatContext = results['format-context'];
    aboveContext = intValue(results['above-context']);
    belowContext = intValue(results['below-context']);
    final context = intValue(results['context']);
    if (context > 0) {
      aboveContext = belowContext = context;
    }
    breakLines = intValue(results['break-lines']);
    exitLines = intValue(results['exit-lines']);
    exitFiles = intValue(results['exit-files']);
  }
}
</pre>