diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 5ea59d610..e6f77f395 100644 --- a/docs/book/src/SUMMARY.md +++ b/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) diff --git a/docs/book/src/referenz/kommandos/index.md b/docs/book/src/referenz/kommandos/index.md index 42f2ef77d..7dbde865d 100644 --- a/docs/book/src/referenz/kommandos/index.md +++ b/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 diff --git a/docs/book/src/referenz/kommandos/slice.md b/docs/book/src/referenz/kommandos/slice.md new file mode 100644 index 000000000..1746f0a97 --- /dev/null +++ b/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` `` — Startposition des Teilbereichs (Voreinstellung: + `0`). +* `--end` `` — 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` `` — 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 + + + +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 diff --git a/pica-toolkit/tests/snapshot.rs b/pica-toolkit/tests/snapshot.rs index 1dc95282f..850600eb0 100644 --- a/pica-toolkit/tests/snapshot.rs +++ b/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"); }