From 333cf8fdc6458023bfe39251080f531410d4396e Mon Sep 17 00:00:00 2001 From: Nico Wagner Date: Tue, 18 Jul 2023 14:10:07 +0200 Subject: [PATCH] Add `hash` documentation (#667) --- docs/book/src/SUMMARY.md | 1 + docs/book/src/referenz/kommandos/hash.md | 110 ++++++++++++++++++++++ docs/book/src/referenz/kommandos/index.md | 1 + pica-toolkit/tests/snapshot.rs | 1 + 4 files changed, 113 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..4353a7aa1 --- /dev/null +++ b/docs/book/src/referenz/kommandos/hash.md @@ -0,0 +1,110 @@ +# 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 enthält. + + +## 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 auf unterschiedlichen Abzügen die Hashwerte der +Datensätze bestimmt werden. Durch Vergleich dieser Tabelle ist es +möglich, die Datensätze zu identifizieren, die sich geändert haben, +gelöscht oder neu hinzugefügt wurden. Das folgende Beispiel demonstriert +die Erzeugung dieser Hash-Tabellen: + +```console +$ pica hash -s DUMP.dat.gz +idn,sha256 +118540238,762cf3a1b18a0cad2d0401cd2b573a89ff9c81b43c4ddab76e136d7a10a851f3 +118607626,8d75e2cdfec20aa025d36018a40b150363d79571788cd92e7ff568595ba4f9ee +040993396,0361c33e1f7a80e21eecde747b2721b7884e003ac4deb8c271684ec0dc4d059a +... +``` + + +## 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 +... +``` + + +## Anmerkung + +Zur Berechnung des [_SHA-256_]-Hashwerts wird der abschließende +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 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"); }