From a6d0260572e096409c7b80b5feae8b4628d93934 Mon Sep 17 00:00:00 2001 From: Nico Wagner Date: Fri, 21 Jul 2023 09:56:16 +0200 Subject: [PATCH 1/3] Add `slice` documentation --- docs/book/src/SUMMARY.md | 1 + docs/book/src/referenz/kommandos/index.md | 1 + docs/book/src/referenz/kommandos/slice.md | 87 +++++++++++++++++++++++ pica-toolkit/tests/snapshot.rs | 1 + 4 files changed, 90 insertions(+) create mode 100644 docs/book/src/referenz/kommandos/slice.md 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..18492dc6c 100644 --- a/docs/book/src/referenz/kommandos/index.md +++ b/docs/book/src/referenz/kommandos/index.md @@ -13,5 +13,6 @@ * [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 +* [slice](./slice.md) — Ausschneiden eines 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..de67e75c8 --- /dev/null +++ b/docs/book/src/referenz/kommandos/slice.md @@ -0,0 +1,87 @@ +# slice + +![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square) + +Das `slice`-Kommando schneidet einen Teilbereich aus der Eingabe aus. + + +## Beschreibung + +Mittels des `slice`-Kommandos kann ein Teilbereich aus der Eingabe +ausgeschnitten werden. Dabei wird der Teilbereich als halb-offenes +Intervall angegeben, wobei die Positionen von 0 gezählt werden. +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öß + +Wenn die Eingabe ausreichend Datensätze enthält, kann beginnend bei +einer festen Position (`--start`) eine 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"); } From f86523c6d54fe294a11b0998dabb89e20c142858 Mon Sep 17 00:00:00 2001 From: Nico Wagner Date: Fri, 21 Jul 2023 09:58:25 +0200 Subject: [PATCH 2/3] Typo --- docs/book/src/referenz/kommandos/slice.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book/src/referenz/kommandos/slice.md b/docs/book/src/referenz/kommandos/slice.md index de67e75c8..8d759dacd 100644 --- a/docs/book/src/referenz/kommandos/slice.md +++ b/docs/book/src/referenz/kommandos/slice.md @@ -67,7 +67,7 @@ der Konfiguration. ## Beispiele -### Ausschneiden eines Teilbereichs fester Größ +### Ausschneiden eines Teilbereichs fester Größe Wenn die Eingabe ausreichend Datensätze enthält, kann beginnend bei einer festen Position (`--start`) eine Teilbereich mit einer festen From d899a22557acc4d9100992196d07b39a2d31ecaa Mon Sep 17 00:00:00 2001 From: Nico Wagner Date: Fri, 21 Jul 2023 10:40:44 +0200 Subject: [PATCH 3/3] Review --- docs/book/src/referenz/kommandos/index.md | 6 ++++-- docs/book/src/referenz/kommandos/slice.md | 18 ++++++++++-------- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/book/src/referenz/kommandos/index.md b/docs/book/src/referenz/kommandos/index.md index 18492dc6c..7dbde865d 100644 --- a/docs/book/src/referenz/kommandos/index.md +++ b/docs/book/src/referenz/kommandos/index.md @@ -10,9 +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 -* [slice](./slice.md) — Ausschneiden eines Teilbereichs aus der Eingabe + 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 index 8d759dacd..1746f0a97 100644 --- a/docs/book/src/referenz/kommandos/slice.md +++ b/docs/book/src/referenz/kommandos/slice.md @@ -2,17 +2,19 @@ ![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square) -Das `slice`-Kommando schneidet einen Teilbereich aus der Eingabe aus. +Das `slice`-Kommando schneidet einen zusammenhängenden Teilbereich aus +der Eingabe aus. ## Beschreibung -Mittels des `slice`-Kommandos kann ein Teilbereich aus der Eingabe -ausgeschnitten werden. Dabei wird der Teilbereich als halb-offenes -Intervall angegeben, wobei die Positionen von 0 gezählt werden. -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. +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: @@ -70,7 +72,7 @@ der Konfiguration. ### Ausschneiden eines Teilbereichs fester Größe Wenn die Eingabe ausreichend Datensätze enthält, kann beginnend bei -einer festen Position (`--start`) eine Teilbereich mit einer festen +einer festen Position (`--start`) ein Teilbereich mit einer festen Länge (`--length`) ausgeschnitten werden. Im folgenden Beispiel wird beginnend beim dritten Datensatz (Position 2)