Add slice documentation (#672)

docs/book/src/SUMMARY.md

@@ -18,4 +18,5 @@
     - [hash](./referenz/kommandos/hash.md)
     - [invalid](./referenz/kommandos/invalid.md)
     - [print](./referenz/kommandos/print.md)
+    - [slice](./referenz/kommandos/slice.md)
     - [split](./referenz/kommandos/split.md)

docs/book/src/referenz/kommandos/index.md

@@ -10,8 +10,11 @@
 * [count](./count.md) — Zählen von Datensätzen, Felder und Unterfeldern
 * [frequency](./frequency.md) — Ermitteln einer Häufigkeitsverteilung
   über ein oder mehrere Unterfelder
-* [hash](./hash.md) — Erzeugt SHA-256 Hashwerte von Datensätzen
+* [hash](./hash.md) — Erzeugt SHA-256-Hashwerte von Datensätzen
 * [invalid](./invalid.md) — Findet ungültige Zeilen in der Eingabe
 * [print](./print.md) — Gibt Datensätze in einer menschenlesbaren Form
+  aus
+* [slice](./slice.md) — Ausschneiden eines zusammenhängenden
+  Teilbereichs aus der Eingabe
 * [split](./split.md) — Teilt eine Menge an Datensätzen in Dateien fester
   Größe

docs/book/src/referenz/kommandos/slice.md

@@ -0,0 +1,89 @@
+# slice
+
+![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square)
+
+Das `slice`-Kommando schneidet einen zusammenhängenden Teilbereich aus
+der Eingabe aus.
+
+
+## Beschreibung
+
+Mittels des `slice`-Kommandos kann ein zusammenhängender Teilbereich aus
+der Eingabe ausgeschnitten werden. Dabei wird der Teilbereich als
+halb-offenes Intervall angegeben, wobei die Positionen von 0 an gezählt
+werden. Beim Auftreten eines ungültigen Datensatzes wird die Position
+weitergezählt. Enthält bspw. die Eingabe 1.000 Zeilen, mit 990
+Datensätzen und 10 ungültigen Zeilen, dann sind die Positionen von `0`
+bis 999 durchnummeriert.
+
+Das folgende Beispiel extrahiert alle (gültigen) Datensätze aus den
+Positionen 2 bis 4:
+
+
+```console
+$ pica slice -s --start 2 --end 5 DUMP.dat.gz -o slice.dat
+$ pica count --records slice.dat
+3
+
+```
+
+
+## Optionen
+
+* `-s`, `--skip-invalid` — überspringt jene Zeilen aus der Eingabe, die
+  nicht dekodiert werden konnten.
+* `--start` `<n>` — Startposition des Teilbereichs (Voreinstellung:
+  `0`).
+* `--end` `<n>` — Endposition des Teilbereichs; diese Position ist nicht
+  mehr Teil der Ausgabe. Ist keine Endposition angegeben, wird der
+  Teilbereich bis zum Ende der Eingabe fortgeführt. Diese Option ist
+  nicht kombinierbar mit `--length`.
+* `--length` `<n>` — Festlegen der maximalen Anzahl an Datensätzen, die
+  in der Ausgabe enthalten sind. Diese Option kann nicht mit `--end`
+  kombiniert werden.
+* `-g`, `--gzip` — Komprimieren der Ausgabe im [Gzip]-Format.
+* `--append` — Wenn die Ausgabedatei bereits existiert, wird die
+  Ausgabe an die Datei angehangen. Ist das Flag nicht gesetzt, wird eine
+  bestehende Datei standardmäßig überschrieben.
+* `-o`, `--output` — Angabe, in welche Datei die Ausgabe geschrieben
+  werden soll. Standardmäßig wird die Ausgabe in die Standardausgabe
+  `stdout` geschrieben.
+
+
+## Konfiguration
+
+<!-- TODO: Link zum allgemeinen Kapitel über die Konfigurationsdatei -->
+
+Einige Kommandozeilen-Optionen lassen sich per Konfigurationsdatei
+(`Pica.toml`) einstellen:
+
+```toml
+[slice]
+skip-invalid = true
+gzip = true
+```
+
+Die Werte der Kommandozeilen-Optionen haben Vorrang vor den Werten aus
+der Konfiguration.
+
+
+## Beispiele
+
+### Ausschneiden eines Teilbereichs fester Größe
+
+Wenn die Eingabe ausreichend Datensätze enthält, kann beginnend bei
+einer festen Position (`--start`) ein Teilbereich mit einer festen
+Länge (`--length`) ausgeschnitten werden.
+
+Im folgenden Beispiel wird beginnend beim dritten Datensatz (Position 2)
+ein Teilbereich mit einer Länge von zwei ausgeschnitten:
+
+```console
+$ pica slice -s --start 2 --length 2 DUMP.dat.gz -o slice.dat
+$ pica count --records slice.dat
+2
+
+```
+
+
+[Gzip]: https://de.wikipedia.org/wiki/Gzip

pica-toolkit/tests/snapshot.rs

@@ -37,5 +37,6 @@ fn doc_tests() {
         .case("../docs/book/src/referenz/kommandos/hash.md")
         .case("../docs/book/src/referenz/kommandos/invalid.md")
         .case("../docs/book/src/referenz/kommandos/print.md")
+        .case("../docs/book/src/referenz/kommandos/slice.md")
         .case("../docs/book/src/referenz/kommandos/split.md");
 }