From f86479666dd42437a8f6a4e20bbfdb1ff5948f40 Mon Sep 17 00:00:00 2001 From: Nico Wagner Date: Mon, 24 Jul 2023 09:32:49 +0200 Subject: [PATCH 1/3] Add `filter` documentation --- docs/book/src/SUMMARY.md | 3 +- docs/book/src/referenz/kommandos/cat.md | 2 +- docs/book/src/referenz/kommandos/filter.md | 196 +++++++++++++++++++++ docs/book/src/referenz/kommandos/index.md | 1 + pica-toolkit/tests/snapshot.rs | 1 + 5 files changed, 201 insertions(+), 2 deletions(-) create mode 100644 docs/book/src/referenz/kommandos/filter.md diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index e6f77f395..e9cf5b18f 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -11,9 +11,10 @@ # Referenz - [Kommandos](./referenz/kommandos/index.md) - [cat](./referenz/kommandos/cat.md) - - [convert](./referenz/kommandos/convert.md) - [completions](./referenz/kommandos/completions.md) + - [convert](./referenz/kommandos/convert.md) - [count](./referenz/kommandos/count.md) + - [filter](./referenz/kommandos/filter.md) - [frequency](./referenz/kommandos/frequency.md) - [hash](./referenz/kommandos/hash.md) - [invalid](./referenz/kommandos/invalid.md) diff --git a/docs/book/src/referenz/kommandos/cat.md b/docs/book/src/referenz/kommandos/cat.md index 904426527..1c3254372 100644 --- a/docs/book/src/referenz/kommandos/cat.md +++ b/docs/book/src/referenz/kommandos/cat.md @@ -39,7 +39,7 @@ $ pica cat ger.dat eng.dat -o ger_eng.dat * `--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. -* `--tee ` — abzweigen der Ausgabe in eine zusätzliche Datei. +* `--tee ` — Abzweigen der Ausgabe in eine zusätzliche Datei. * `-g`, `--gzip` — Komprimieren der Ausgabe im [gzip](https://de.wikipedia.org/wiki/Gzip)-Format. * `-o`, `--output` — Angabe, in welche Datei die Ausgabe geschrieben diff --git a/docs/book/src/referenz/kommandos/filter.md b/docs/book/src/referenz/kommandos/filter.md new file mode 100644 index 000000000..9f721ccfe --- /dev/null +++ b/docs/book/src/referenz/kommandos/filter.md @@ -0,0 +1,196 @@ +# filter + +![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square) + +Mithilfe des `filter`-Kommandos können Datensätze anhand eines Kriterums +aus der Eingabe gefiltert werden. + + +## Beschreibung + +Das `filter`-Kommando bildet das Herzstück des Toolkits. Es ermöglicht +es aus einer (mitunter sehr großen) Datenmenge, bspw. dem Gesamtabzug +des Katalogsystems, eine kleinere Menge effizient zu extrahieren, um sie +anschließend weiterzuverarbeiten. Dies erfolgt über die Angabe eines +Filterausdrucks, der darüber entscheidet, ob ein Datensatz in die +Zielmenge eingeht, oder nicht. + +Das folgende Beispiel filter aus der Datei `DUMP.dat.gz` alle +Datensätze, die ein Feld `003@` enthalten, das ein Unterfeld `0` +besitzt, welches mit dem Wert `118540238` belegt ist. + +```console +$ pica filter -s '003@.0 == "118540238"' DUMP.dat.gz -o goethe.dat +$ pica print goethe.dat +001A $0 1250:01-07-88 +001B $0 9999:15-04-22 $t 15:15:00.000 +001D $0 0292:01-08-19 +001U $0 utf8 +001X $0 0 +002@ $0 Tpz +003@ $0 118540238 +003U $a http://d-nb.info/gnd/118540238 $z http://d-nb.info/gnd/185808069 $z http://d-nb.info/gnd/185848826 $z http://d-nb.info/gnd/101488358X $z http://d-nb.info/gnd/1014927390 $z http://d-nb.info/gnd/1022736213 $z http://d-nb.info/gnd/1095607278 $z http://d-nb.info/gnd/1131918517 +004B $a piz +006Y $S isni $0 0000 0001 2099 9104 +006Y $S wikidata $0 Q5879 +... +028A $d Johann Wolfgang $c von $a Goethe +... +``` + +## Optionen + +* `-s`, `--skip-invalid` — überspringt jene Zeilen aus der Eingabe, die + nicht dekodiert werden konnten. +* `-v`, `--invert-match` — Gibt alle Datensätze aus, die **nicht** dem + Filterausdruck entsprechen. +* `-i`, `--ignore-case` — Groß- und Kleinschreibung wird bei Vergleichen + ignoriert. +* `--strsim-threshold ` — Festlegen des Schwellenwerts beim + Ähnlichkeitsvergleich von Zeichenketten mittels `=*`. +* `-k`, `--keep` — Es werden nur die Felder eines Datensatzes + beibehalten, die in der Liste aufgeführt werden. +* `-k`, `--keep` — Es werden die Felder eines Datensatzes verworfen, + die in der Liste aufgeführt werden. +* `-F`, `--file` `` — Es wird der Filterausdruck aus der Datei + `` eingelesen. Es darf **keine** weitere Angabe eines + Filterausdrucks als Kommandozeilenargument erfolgen! +* `-A`, `--allow-list` `` — Es werden alle Datensätze ignoriert, + die nicht explizit in der Positivliste[^1] auftauchen. Werden mehrere + Positivlisten angegeben, wird die Mengenvereinigung aus allen Listen + gebildet. +* `-D`, `--deny-list` `` — Es werden alle Datensätze ignoriert, + die in der Negativliste[^1] auftauchen. Werden mehrere Negativlisten + angegeben, wird die Mengenvereinigung aus allen Listen gebildet. +* `-l`, `--limit` `` — Eingrenzung der Ausgabe auf die ersten `` + (gültigen) Datensätze. +* `--and` `` — Hinzufügen eines zusätzlichen Filters mittels der + booleschen `&&`-Verknüpfung. Der ursprüngliche Filterausdruck + `` wird zum Ausdruck ` && `. +* `--or` `` — Hinzufügen eines zusätzlichen Filters mittels der + booleschen `||`-Verknüpfung. Der ursprüngliche Filterausdruck + `` wird zum Ausdruck ` || `. +* `--not` `` — Hinzufügen eines zusätzlichen Filters. Der + ursprüngliche Filterausdruck `` wird zum Ausdruck ` && + !()`. +* `-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 überschrieben. +* `--tee ` — Abzweigen der Ausgabe in eine zusätzliche Datei. +* `-o`, `--output` — Angabe, in welche Datei die Ausgabe geschrieben + werden soll. Standardmäßig wird die Ausgabe in die Standardausgabe + `stdout` geschrieben. Endet der Dateiname mit dem Suffix `.gz`, wird + die Ausgabe automatisch im gzip-Format komprimiert. + + + +## Konfiguration + + + +Die Optionen zum Ignorieren invalider Datensätze sowie das Komprimieren +der Ausgabe lassen sich in der `Pica.toml` konfigurieren: + +```toml +[filter] +skip-invalid = true +gzip = false +``` + +Die Werte der Kommandozeilen-Optionen haben Vorrang vor den Werten aus +der Konfiguration. + + +## Beispiele + +### Invertierte Treffermenge (_invert match_) + +Mitunter ist es einfacher einen Ausdruck zu formulieren, der alle +Datensätze umfasst, die nicht in der Treffermenge gewünscht sind. Durch +die Option `-v`/`--invert-match` werden dann nur die Datensätze +ausgegeben, die nicht dem Filterkriterum entsprechen. + +Beispielweise enthält der Abzug `DUMP.dat.gz` verschiedene +Normdatensätze. Werden nur die Datensätze benötigt die **nicht** vom +Satztyp Werk sind, ist es einfacher zuerst nach den Werken zu suchen, +und dann durch das Flag `-v` alle Datensätze zu erhalten, die nicht dem +Filterkriterium entsprechen. + +```console +$ pica filter -s -v '002@.0 =^ "Tu"' DUMP.dat.gz -o not-Tu.dat.gz +$ pica frequency '002@.0' not-Tu.dat.gz +Tsz,2 +Tg1,1 +Tp1,1 +Tpz,1 +Ts1,1 + +``` + +### Groß- und Kleinschreibung ingorieren + +Standardmäßig wird bei Vergleichen von Zeichenketten die Groß- und +Kleinschreibung beachtet. Dies lässt sich mit dem Flag +`-i`/`--ignore-case` deaktivieren: + +```console +$ pica filter -s -i '028A.a == "GOETHE"' DUMP.dat.gz -o goethe.dat +$ pica print goethe.dat +... +028A $d Johann Wolfgang $c von $a Goethe +... +``` + +### Felder eines Datensatzes reduzieren + +Teilweise ist die Anzahl der Felder pro Datensatz sehr groß werden, +was zu erheblichen Laufzeiteinbußen nachfolgender Datenanalysen führen +kann. Mittels der Optionen `-k`/`--keep` bzw. `-d`/`--discard` lassen +sich Datensätze auf eine Teilmenge der Felder reduzieren. + +Wird für einen Datenanalyse nur die IDN/PPN (`003@`), die Satzart +(`002@`) und die Entätenkodierung (`004B`) benötigt, können die +Datensätze wie folgt auf die Felder reduziert werden: + +```console +$ pica filter -s --keep '00[23]@,004B' "003@?" DUMP.dat.gz -o out.dat +$ pica print out.dat +002@ $0 Tpz +003@ $0 118540238 +004B $a piz + +002@ $0 Tp1 +003@ $0 118607626 +004B $a piz +... +``` + +Sollen bestimmte Felder entfernt werden, kann dies mit der Option +`-d`/`--discard` erfolgen. Der folgende Aufruf entfent das Feld `004B`, +sofern vorhanden, aus allen Datensätzen: + +```console +$ pica filter -s --keep '00[23]@,004B' "003@?" DUMP.dat.gz -o out.dat +$ pica filter --discard '004B' "003@?" out.dat -o out2.dat +$ pica print out2.dat +002@ $0 Tpz +003@ $0 118540238 + +002@ $0 Tp1 +003@ $0 118607626 +... +``` + + + +[^1]: Eine Positiv- oder Negativliste muss entweder als [CSV]-Datei + vorliegen, die in der **ersten Spalte** die IDN/PPN des Datensatzes + enthält, oder als eine [Arrow]-Datei, die eine `idn`-Spalte enthält. + Alle Dateien werden automatisch als [CSV]-Datei interpretiert, es + sei denn, die Datei endet mit `.ipc`, `.arrow` oder `.feather`, dann + erfolgt die Interpretation im [Arrow]-Format. + +[Arrow]: https://arrow.apache.org/ +[CSV]: https://de.wikipedia.org/wiki/CSV_(Dateiformat) +[Gzip]: https://de.wikipedia.org/wiki/Gzip diff --git a/docs/book/src/referenz/kommandos/index.md b/docs/book/src/referenz/kommandos/index.md index 7dbde865d..843478bec 100644 --- a/docs/book/src/referenz/kommandos/index.md +++ b/docs/book/src/referenz/kommandos/index.md @@ -8,6 +8,7 @@ * [completions](./completions.md) — Erzeugung von Shell-Skripten zur Autovervollständigung * [count](./count.md) — Zählen von Datensätzen, Felder und Unterfeldern +* [filter](./filter.md) — Filtert Datensätze anhand eines Kriteriums * [frequency](./frequency.md) — Ermitteln einer Häufigkeitsverteilung über ein oder mehrere Unterfelder * [hash](./hash.md) — Erzeugt SHA-256-Hashwerte von Datensätzen diff --git a/pica-toolkit/tests/snapshot.rs b/pica-toolkit/tests/snapshot.rs index 850600eb0..6176ba000 100644 --- a/pica-toolkit/tests/snapshot.rs +++ b/pica-toolkit/tests/snapshot.rs @@ -33,6 +33,7 @@ fn cli_tests() { fn doc_tests() { trycmd::TestCases::new() .case("../docs/book/src/referenz/kommandos/count.md") + .case("../docs/book/src/referenz/kommandos/filter.md") .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 cced99eed74f2c7b35cc37071227941c7039cc38 Mon Sep 17 00:00:00 2001 From: Nico Wagner Date: Mon, 24 Jul 2023 13:25:18 +0200 Subject: [PATCH 2/3] Review --- docs/book/src/referenz/kommandos/filter.md | 32 +++++++++++----------- docs/book/src/referenz/kommandos/index.md | 2 +- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/book/src/referenz/kommandos/filter.md b/docs/book/src/referenz/kommandos/filter.md index 9f721ccfe..1ab8ce303 100644 --- a/docs/book/src/referenz/kommandos/filter.md +++ b/docs/book/src/referenz/kommandos/filter.md @@ -9,14 +9,14 @@ aus der Eingabe gefiltert werden. ## Beschreibung Das `filter`-Kommando bildet das Herzstück des Toolkits. Es ermöglicht -es aus einer (mitunter sehr großen) Datenmenge, bspw. dem Gesamtabzug +es, aus einer (mitunter sehr großen) Datenmenge, bspw. dem Gesamtabzug des Katalogsystems, eine kleinere Menge effizient zu extrahieren, um sie anschließend weiterzuverarbeiten. Dies erfolgt über die Angabe eines Filterausdrucks, der darüber entscheidet, ob ein Datensatz in die -Zielmenge eingeht, oder nicht. +Zielmenge eingeht oder nicht. -Das folgende Beispiel filter aus der Datei `DUMP.dat.gz` alle -Datensätze, die ein Feld `003@` enthalten, das ein Unterfeld `0` +Im folgenden Beispiel werden alle Datensätze aus der Datei +`DUMP.dat.gz`, die ein Feld `003@` enthalten, das ein Unterfeld `0` besitzt, welches mit dem Wert `118540238` belegt ist. ```console @@ -40,7 +40,7 @@ $ pica print goethe.dat ## Optionen -* `-s`, `--skip-invalid` — überspringt jene Zeilen aus der Eingabe, die +* `-s`, `--skip-invalid` — Überspringt jene Zeilen aus der Eingabe, die nicht dekodiert werden konnten. * `-v`, `--invert-match` — Gibt alle Datensätze aus, die **nicht** dem Filterausdruck entsprechen. @@ -89,7 +89,7 @@ $ pica print goethe.dat -Die Optionen zum Ignorieren invalider Datensätze sowie das Komprimieren +Die Optionen zum Ignorieren invalider Datensätze und zum Komprimieren der Ausgabe lassen sich in der `Pica.toml` konfigurieren: ```toml @@ -106,14 +106,14 @@ der Konfiguration. ### Invertierte Treffermenge (_invert match_) -Mitunter ist es einfacher einen Ausdruck zu formulieren, der alle +Mitunter ist es einfacher, einen Ausdruck zu formulieren, der alle Datensätze umfasst, die nicht in der Treffermenge gewünscht sind. Durch die Option `-v`/`--invert-match` werden dann nur die Datensätze ausgegeben, die nicht dem Filterkriterum entsprechen. Beispielweise enthält der Abzug `DUMP.dat.gz` verschiedene -Normdatensätze. Werden nur die Datensätze benötigt die **nicht** vom -Satztyp Werk sind, ist es einfacher zuerst nach den Werken zu suchen, +Normdatensätze. Werden nur die Datensätze benötigt, die **nicht** vom +Satztyp Werk sind, ist es einfacher, zuerst nach den Werken zu suchen und dann durch das Flag `-v` alle Datensätze zu erhalten, die nicht dem Filterkriterium entsprechen. @@ -144,13 +144,13 @@ $ pica print goethe.dat ### Felder eines Datensatzes reduzieren -Teilweise ist die Anzahl der Felder pro Datensatz sehr groß werden, -was zu erheblichen Laufzeiteinbußen nachfolgender Datenanalysen führen -kann. Mittels der Optionen `-k`/`--keep` bzw. `-d`/`--discard` lassen -sich Datensätze auf eine Teilmenge der Felder reduzieren. +Teilweise ist die Anzahl der Felder pro Datensatz sehr groß, was zu +erheblichen Laufzeiteinbußen nachfolgender Datenanalysen führen kann. +Mittels der Optionen `-k`/`--keep` bzw. `-d`/`--discard` lassen sich +Datensätze auf eine Teilmenge der Felder reduzieren. -Wird für einen Datenanalyse nur die IDN/PPN (`003@`), die Satzart -(`002@`) und die Entätenkodierung (`004B`) benötigt, können die +Werden für eine Datenanalyse nur die IDN/PPN (`003@`), die Satzart +(`002@`) und die Entitätenkodierung (`004B`) benötigt, können die Datensätze wie folgt auf die Felder reduziert werden: ```console @@ -167,7 +167,7 @@ $ pica print out.dat ``` Sollen bestimmte Felder entfernt werden, kann dies mit der Option -`-d`/`--discard` erfolgen. Der folgende Aufruf entfent das Feld `004B`, +`-d`/`--discard` erfolgen. Der folgende Aufruf entfernt das Feld `004B`, sofern vorhanden, aus allen Datensätzen: ```console diff --git a/docs/book/src/referenz/kommandos/index.md b/docs/book/src/referenz/kommandos/index.md index 843478bec..9cdd0f44f 100644 --- a/docs/book/src/referenz/kommandos/index.md +++ b/docs/book/src/referenz/kommandos/index.md @@ -7,7 +7,7 @@ PICA-Formaten * [completions](./completions.md) — Erzeugung von Shell-Skripten zur Autovervollständigung -* [count](./count.md) — Zählen von Datensätzen, Felder und Unterfeldern +* [count](./count.md) — Zählen von Datensätzen, Feldern und Unterfeldern * [filter](./filter.md) — Filtert Datensätze anhand eines Kriteriums * [frequency](./frequency.md) — Ermitteln einer Häufigkeitsverteilung über ein oder mehrere Unterfelder From 1dae9ab3845fce8767eab29fdbb7168ff7723a8c Mon Sep 17 00:00:00 2001 From: Nico Wagner Date: Mon, 24 Jul 2023 15:17:09 +0200 Subject: [PATCH 3/3] Review --- docs/book/src/referenz/kommandos/filter.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/book/src/referenz/kommandos/filter.md b/docs/book/src/referenz/kommandos/filter.md index 1ab8ce303..dda3e32ae 100644 --- a/docs/book/src/referenz/kommandos/filter.md +++ b/docs/book/src/referenz/kommandos/filter.md @@ -16,8 +16,8 @@ Filterausdrucks, der darüber entscheidet, ob ein Datensatz in die Zielmenge eingeht oder nicht. Im folgenden Beispiel werden alle Datensätze aus der Datei -`DUMP.dat.gz`, die ein Feld `003@` enthalten, das ein Unterfeld `0` -besitzt, welches mit dem Wert `118540238` belegt ist. +`DUMP.dat.gz` extrahiert, die ein Feld `003@` enthalten, das ein +Unterfeld `0` besitzt, welches mit dem Wert `118540238` belegt ist. ```console $ pica filter -s '003@.0 == "118540238"' DUMP.dat.gz -o goethe.dat