diff --git a/docs/Getting-Started.md b/docs/Getting-Started.md index 466c94f..e2ef43e 100644 --- a/docs/Getting-Started.md +++ b/docs/Getting-Started.md @@ -12,7 +12,7 @@ The easiest way to get started with Metafacture is the Playground. Take a look a For commands available in the Flux, see [the Flux commands documentation](flux/flux-commands.html). -For functions and usage of the Fix, see [the Fix functions and cookbook](fix/Fix-functions-and-Cookbook.html). +For functions of the Fix, see [the Fix functions](fix/Fix-functions-and-Cookbook.html). For next steps get familar with [FLUX](flux/Flux-User-Guide.html) and [FIX](fix/Fix-User-Guide.html). And try out some Metafacture workflows. diff --git a/docs/MF-in-5-min.md b/docs/MF-in-5-min.md index 38c2e0d..ae92b9b 100644 --- a/docs/MF-in-5-min.md +++ b/docs/MF-in-5-min.md @@ -93,7 +93,7 @@ $ cat yaml2json.flux ## FIX LANGUAGE -Many data conversions need a mapping from one field to another field plus optional conversions of the data inside these fields. Metafacture provides the transformation module `fix` that uses the Catmandu-inspired Fix language to assist in these mappings. See the [full list of Fix functions](fix/Fix-functions-and-Cookbook.html#functions). +Many data conversions need a mapping from one field to another field plus optional conversions of the data inside these fields. Metafacture provides the transformation module `fix` that uses the Catmandu-inspired Fix language to assist in these mappings. See the [full list of Fix functions](fix/Fix-functions.html#functions). Fixes can be provided inline as text argument of the fix module in the Flux script, or as a pointer to a Fix script. A Fix script groups one or more fixes in a file. diff --git a/docs/fix/Fix-User-Guide.md b/docs/fix/Fix-User-Guide.md index 668429a..4623587 100644 --- a/docs/fix/Fix-User-Guide.md +++ b/docs/fix/Fix-User-Guide.md @@ -230,8 +230,6 @@ vars.put("rights", "CC-0"); final Metafix metafix = new metafix("fixdef.fix", vars); ``` - - ## Splitting Fixes for Reuse In a complex project setting there may be several Fixes in use, @@ -244,7 +242,7 @@ Another scenario would be to reduce the size of a single fix file and create sev To accomodate for such reuse, Fix offers an include mechanism: -`````` +```perl # Setup adds maps, macros and vars once do once("setup") include ("./fix/maps.fix") @@ -254,3 +252,43 @@ end ``` For performance reasons it is useful to integrate macros and maps that are used often in a `do once` bind. + +## Cookbook + +This page is a replication of the passages [Best practices and guidelines for working with Metafacture Fix](https://github.com/metafacture/metafacture-fix?tab=readme-ov-file#best-practices-and-guidelines-for-working-with-metafacture-fix) and [Glossary](https://github.com/metafacture/metafacture-fix?tab=readme-ov-file#glossary) of the Fix Readme.md. Status: [Fix Release 1.1.2](https://github.com/metafacture/metafacture-fix/releases/tag/1.1.2) + +### Best practices and guidelines for working with Metafacture Fix + +- We recommend to use double quotation marks for arguments and values in functions, binds and conditionals. +- If using a `list` bind with a variable, the `var` option requires quotation marks (`do list(path: "", "var": "")`). +- Fix turns repeated fields into arrays internally but only marked arrays (with `[]` at the end of the field name) are also emitted as "arrays" (entities with indexed literals), all other arrays are emitted as repeated fields. +- Every Fix file should end with a final newline. + +### Glossary + +#### Array wildcards + +Array wildcards resemble [Catmandu's concept of wildcards](http://librecat.org/Catmandu/#wildcards). + +When working with arrays and repeated fields you can use wildcards instead of an index number to select elements of an array. + +| Wildcard | Meaning | +|----------|:--------| +| `*` | Selects _all_ elements of an array. | +| `$first` | Selects only the _first_ element of an array. | +| `$last` | Selects only the _last_ element of an array. | +| `$prepend` | Selects the position _before_ the first element of an array. Can only be used when adding new elements to an array. | +| `$append` | Selects the position _after_ the last element of an array. Can only be used when adding new elements to an array. | + +#### Path wildcards + +Path wildcards resemble [Metamorph's concept of wildcards](https://github.com/metafacture/metafacture-core/wiki/Metamorph-User-Guide#addressing-pieces-of-data). They are not supported in Catmandu (it has [specialized Fix functions](https://librecat.org/Catmandu/#marc-mab-pica-paths) instead). + +You can use path wildcards to select fields matching a pattern. They only match path _segments_ (field names), though, not _whole_ paths of nested fields. These wildcards cannot be used to add new elements. + +| Wildcard | Meaning | +|----------|:--------| +| `*` | Placeholder for zero or more characters. | +| `?` | Placeholder for exactly one character. | +| `\|` | Alternation of multiple patterns. | +| `[...]` | Enumeration of characters. | diff --git a/docs/fix/Fix-functions-and-Cookbook.md b/docs/fix/Fix-functions.md similarity index 93% rename from docs/fix/Fix-functions-and-Cookbook.md rename to docs/fix/Fix-functions.md index e755454..d88c9b9 100644 --- a/docs/fix/Fix-functions-and-Cookbook.md +++ b/docs/fix/Fix-functions.md @@ -1,49 +1,11 @@ --- layout: default -title: Fix Functions and Cookbook +title: Fix Functions parent: Fix nav_order: 2 --- -This page is a replication of the passage [Fix Functions and Cookbook](https://github.com/metafacture/metafacture-fix?tab=readme-ov-file#functions-and-cookbook) of the Fix Readme.md. Status: [Fix Release 1.1.2](https://github.com/metafacture/metafacture-fix/releases/tag/1.1.2) - -## Functions and cookbook - -### Best practices and guidelines for working with Metafacture Fix - -- We recommend to use double quotation marks for arguments and values in functions, binds and conditionals. -- If using a `list` bind with a variable, the `var` option requires quotation marks (`do list(path: "", "var": "")`). -- Fix turns repeated fields into arrays internally but only marked arrays (with `[]` at the end of the field name) are also emitted as "arrays" (entities with indexed literals), all other arrays are emitted as repeated fields. -- Every Fix file should end with a final newline. - -### Glossary - -#### Array wildcards - -Array wildcards resemble [Catmandu's concept of wildcards](http://librecat.org/Catmandu/#wildcards). - -When working with arrays and repeated fields you can use wildcards instead of an index number to select elements of an array. - -| Wildcard | Meaning | -|----------|:--------| -| `*` | Selects _all_ elements of an array. | -| `$first` | Selects only the _first_ element of an array. | -| `$last` | Selects only the _last_ element of an array. | -| `$prepend` | Selects the position _before_ the first element of an array. Can only be used when adding new elements to an array. | -| `$append` | Selects the position _after_ the last element of an array. Can only be used when adding new elements to an array. | - -#### Path wildcards - -Path wildcards resemble [Metamorph's concept of wildcards](https://github.com/metafacture/metafacture-core/wiki/Metamorph-User-Guide#addressing-pieces-of-data). They are not supported in Catmandu (it has [specialized Fix functions](https://librecat.org/Catmandu/#marc-mab-pica-paths) instead). - -You can use path wildcards to select fields matching a pattern. They only match path _segments_ (field names), though, not _whole_ paths of nested fields. These wildcards cannot be used to add new elements. - -| Wildcard | Meaning | -|----------|:--------| -| `*` | Placeholder for zero or more characters. | -| `?` | Placeholder for exactly one character. | -| `\|` | Alternation of multiple patterns. | -| `[...]` | Enumeration of characters. | +This page is a replication of the passage [Functions](https://github.com/metafacture/metafacture-fix?tab=readme-ov-file#functions) of the Fix Readme.md. Status: [Fix Release 1.1.2](https://github.com/metafacture/metafacture-fix/releases/tag/1.1.2) ### Functions diff --git a/docs/fix/fix.md b/docs/fix/fix.md index 2932393..76a3f38 100644 --- a/docs/fix/fix.md +++ b/docs/fix/fix.md @@ -13,7 +13,7 @@ If you are using **Metafacture as a Java library**, create a Metafix object and The transformation itself is declared in a fix-object which can be a file. For more information on how to declare transformations see [Metafix User Guide](Fix-User-Guide.html). -See [here a list for all available FIX functions and a cookbook for using fix](Fix-functions-and-Cookbook.html). +See [here a list for all available FIX functions](Fix-functions.html). {: .note } PS: There is also the transformation module MORPH. Have a look at [the old documentation](https://github.com/metafacture/metafacture-core/wiki/Metamorph-User-Guide) and the German cookbook by [Swissbib](https://swissbib.gitlab.io/metamorph-doku/). \ No newline at end of file