From 6d4c9a715a0b9521ac22e166d34f75900db75f17 Mon Sep 17 00:00:00 2001 From: Nico Wagner Date: Tue, 18 Jul 2023 13:02:33 +0200 Subject: [PATCH 1/2] Add `hash` documentation --- docs/book/src/SUMMARY.md | 1 + docs/book/src/referenz/kommandos/hash.md | 108 ++++++++++++++++++++++ docs/book/src/referenz/kommandos/index.md | 1 + pica-toolkit/tests/snapshot.rs | 1 + 4 files changed, 111 insertions(+) create mode 100644 docs/book/src/referenz/kommandos/hash.md diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index ba74e7324..c3f7a515f 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -15,4 +15,5 @@ - [completions](./referenz/kommandos/completions.md) - [count](./referenz/kommandos/count.md) - [frequency](./referenz/kommandos/frequency.md) + - [hash](./referenz/kommandos/hash.md) - [invalid](./referenz/kommandos/invalid.md) diff --git a/docs/book/src/referenz/kommandos/hash.md b/docs/book/src/referenz/kommandos/hash.md new file mode 100644 index 000000000..86172064a --- /dev/null +++ b/docs/book/src/referenz/kommandos/hash.md @@ -0,0 +1,108 @@ +# hash + +![stability-badge](https://img.shields.io/badge/stability-unstable-red?style=flat-square) + +Mithilfe des Kommandos `hash` lässt sich eine Tabelle erzeugen, die in +der ersten Spalte die IDN (Feld `003@.0`) eines Datensatzes und in der +zweiten Spalte den [_SHA-256_] Hashwert, der über den kompletten +Datensatz (ink. Zeilenumbruch) gebildet wird, erzeugen. + +## Beschreibung + +Mitunter kommt es vor, dass eine regelmäßige und aufwändige Berechnung +für Datensätze ausgeführt werden muss und es nicht praktikabel ist, die +Berechnung über alle Datensätze durchzuführen. Mittels des +`hash`-Kommandos können die Datensätze identifiziert werden, die +mindestens eine Änderung erfahren haben. Hierfür wird für jeden +Datensatz der [_SHA-256_]-Hashwert über den kompletten Datensatz +ermittelt und tabellarisch ausgegeben. + +Das folgende Beispiel demonstriert die Erzeugung dieser Tabelle: + +```console +$ pica hash -s DUMP.dat.gz +idn,sha256 +118540238,762cf3a1b18a0cad2d0401cd2b573a89ff9c81b43c4ddab76e136d7a10a851f3 +118607626,8d75e2cdfec20aa025d36018a40b150363d79571788cd92e7ff568595ba4f9ee +040993396,0361c33e1f7a80e21eecde747b2721b7884e003ac4deb8c271684ec0dc4d059a +... +``` + +Die Berechnung des [_SHA-256_]-Hashwerts beinhaltet bewusst den +abschließenden Zeilenumbruch, um einen gleichen Hashwert zu erzeugen, +der entsteht, wenn der Hashwert über die gesamte Zeile aus der Eingabe +ermittelt wird. Im folgenden Beispiel wird zuerst der erste gültige +Datensatz in die Datei `1.dat` geschrieben. Anschließend wird der +Hashwert einmal mit dem `hash`-Kommando und einmal mit dem Unix-Programm +[_sha256sum_] gebildet. Beide Ergebnisse sind gleich. + +```console +$ pica filter -s -l1 "003@?" DUMP.dat.gz -o 1.dat +$ pica hash 1.dat +idn,sha256 +118540238,762cf3a1b18a0cad2d0401cd2b573a89ff9c81b43c4ddab76e136d7a10a851f3 + +$ sha256sum 1.dat +762cf3a1b18a0cad2d0401cd2b573a89ff9c81b43c4ddab76e136d7a10a851f3 +``` + + +## Optionen + +* `-s`, `--skip-invalid` — überspringt jene Zeilen aus der Eingabe, die + nicht dekodiert werden konnten. +* `-H`, `--header` `
` — Kopfzeile, die den Ergebnissen + vorangestellt wird. +* `-t`, `--tsv` — Ausgabe erfolgt im TSV-Format. +* `-o`, `--output` — Angabe, in welche Datei die Ausgabe geschrieben + werden soll. + + +## Konfiguration + + + +Die Option zum Ignorieren invalider Datensätze lässt sich in der +`Pica.toml` konfigurieren: + +```toml +[hash] +skip-invalid = true +``` + +Die Werte der Kommandozeilen-Optionen haben Vorrang vor den Werten aus +der Konfiguration. + + +## Beispiele + +### Ausgabe im TSV-Format + +Die Ausgabe lässt sich mittels der Option `--tsv` (bzw. `-t`) in das +TSV-Format ändern. + +```console +$ pica hash -s --tsv DUMP.dat.gz +idn sha256 +118540238 762cf3a1b18a0cad2d0401cd2b573a89ff9c81b43c4ddab76e136d7a10a851f3 +118607626 8d75e2cdfec20aa025d36018a40b150363d79571788cd92e7ff568595ba4f9ee +040993396 0361c33e1f7a80e21eecde747b2721b7884e003ac4deb8c271684ec0dc4d059a +... +``` + +### Hinzufügen einer Kopfzeile + +Eine individuelle Kopfzeile lässt sich mit der Option `--header` (bzw. +`-H`) ausgeben: + +```console +$ pica hash -s --header 'ppn,hash' DUMP.dat.gz +ppn,hash +118540238,762cf3a1b18a0cad2d0401cd2b573a89ff9c81b43c4ddab76e136d7a10a851f3 +118607626,8d75e2cdfec20aa025d36018a40b150363d79571788cd92e7ff568595ba4f9ee +040993396,0361c33e1f7a80e21eecde747b2721b7884e003ac4deb8c271684ec0dc4d059a +... +``` + +[_SHA-256_]: https://de.wikipedia.org/wiki/SHA-2 +[_sha256sum_]: https://manpages.ubuntu.com/manpages/trusty/de/man1/sha256sum.1.html diff --git a/docs/book/src/referenz/kommandos/index.md b/docs/book/src/referenz/kommandos/index.md index fabe6aae3..9f3cb4c5a 100644 --- a/docs/book/src/referenz/kommandos/index.md +++ b/docs/book/src/referenz/kommandos/index.md @@ -10,4 +10,5 @@ * [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 * [invalid](./invalid.md) — Findet ungültige Zeilen in der Eingabe diff --git a/pica-toolkit/tests/snapshot.rs b/pica-toolkit/tests/snapshot.rs index 7dd19826c..a421ace88 100644 --- a/pica-toolkit/tests/snapshot.rs +++ b/pica-toolkit/tests/snapshot.rs @@ -33,5 +33,6 @@ fn cli_tests() { fn doc_tests() { trycmd::TestCases::new() .case("../docs/book/src/referenz/kommandos/frequency.md") + .case("../docs/book/src/referenz/kommandos/hash.md") .case("../docs/book/src/referenz/kommandos/invalid.md"); } From 03ec0af5f23f6df66d718cae4311b35c96704a4d Mon Sep 17 00:00:00 2001 From: Nico Wagner Date: Tue, 18 Jul 2023 13:35:02 +0200 Subject: [PATCH 2/2] Review --- docs/book/src/referenz/kommandos/hash.md | 34 +++++++++++------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/docs/book/src/referenz/kommandos/hash.md b/docs/book/src/referenz/kommandos/hash.md index 86172064a..957eb1ed8 100644 --- a/docs/book/src/referenz/kommandos/hash.md +++ b/docs/book/src/referenz/kommandos/hash.md @@ -4,8 +4,7 @@ Mithilfe des Kommandos `hash` lässt sich eine Tabelle erzeugen, die in der ersten Spalte die IDN (Feld `003@.0`) eines Datensatzes und in der -zweiten Spalte den [_SHA-256_] Hashwert, der über den kompletten -Datensatz (ink. Zeilenumbruch) gebildet wird, erzeugen. +zweiten Spalte den [_SHA-256_] Hashwert enthält. ## Beschreibung @@ -28,23 +27,6 @@ idn,sha256 ... ``` -Die Berechnung des [_SHA-256_]-Hashwerts beinhaltet bewusst den -abschließenden Zeilenumbruch, um einen gleichen Hashwert zu erzeugen, -der entsteht, wenn der Hashwert über die gesamte Zeile aus der Eingabe -ermittelt wird. Im folgenden Beispiel wird zuerst der erste gültige -Datensatz in die Datei `1.dat` geschrieben. Anschließend wird der -Hashwert einmal mit dem `hash`-Kommando und einmal mit dem Unix-Programm -[_sha256sum_] gebildet. Beide Ergebnisse sind gleich. - -```console -$ pica filter -s -l1 "003@?" DUMP.dat.gz -o 1.dat -$ pica hash 1.dat -idn,sha256 -118540238,762cf3a1b18a0cad2d0401cd2b573a89ff9c81b43c4ddab76e136d7a10a851f3 - -$ sha256sum 1.dat -762cf3a1b18a0cad2d0401cd2b573a89ff9c81b43c4ddab76e136d7a10a851f3 -``` ## Optionen @@ -104,5 +86,19 @@ ppn,hash ... ``` +## Anmerkung + +Zur Berechnung des [_SHA-256_]-Hashwerts wird der abschließenden Zeilenumbruch mit einbezogen, um einen gleichen Hashwert zu erzeugen, der entsteht, wenn der Hashwert über die gesamte Zeile aus der Eingabe ermittelt wird. Im folgenden Beispiel wird zuerst der erste gültige Datensatz in die Datei `1.dat` geschrieben. Anschließend wird der Hashwert einmal mit dem `hash`-Kommando und einmal mit dem Unix-Programm [_sha256sum_] gebildet. Beide Ergebnisse sind gleich. + +```console +$ pica filter -s -l1 "003@?" DUMP.dat.gz -o 1.dat +$ pica hash 1.dat +idn,sha256 +118540238,762cf3a1b18a0cad2d0401cd2b573a89ff9c81b43c4ddab76e136d7a10a851f3 + +$ sha256sum 1.dat +762cf3a1b18a0cad2d0401cd2b573a89ff9c81b43c4ddab76e136d7a10a851f3 +``` + [_SHA-256_]: https://de.wikipedia.org/wiki/SHA-2 [_sha256sum_]: https://manpages.ubuntu.com/manpages/trusty/de/man1/sha256sum.1.html