Skip to content

Commit

Permalink
Update Fix-functions-and-Cookbook.md
Browse files Browse the repository at this point in the history 
Bring the documentation to status of Fix Release 1.0.0

https://github.com/metafacture/metafacture-fix/releases/tag/1.0.0
  • Loading branch information
@TobiasNx
TobiasNx committed Apr 9, 2024
1 parent 6c1659c commit fbb9576
Showing 1 changed file with 72 additions and 2 deletions.
74 changes: 72 additions & 2 deletions docs/fix/Fix-functions-and-Cookbook.md
View file
Expand Up @@ -5,7 +5,7 @@ parent: Fix
nav_order: 2
---

This page is a replication of the passage of the Fix Readme.md.
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.0.0](https://github.com/metafacture/metafacture-fix/releases/tag/1.0.0)

## Functions and cookbook

Expand Down Expand Up @@ -73,6 +73,8 @@ Does nothing. It is used for benchmarking in Catmandu.
nothing()
```

[Example in Playground](https://metafacture.org/playground/?example=nothing)

##### `put_filemap`

Defines an external map for [lookup](#lookup) from a file or a URL. Maps with more than 2 columns are supported but are reduced to a defined key and a value column.
Expand All @@ -81,6 +83,8 @@ Defines an external map for [lookup](#lookup) from a file or a URL. Maps with mo
put_filemap("<sourceFile>", "<mapName>", sep_char: "\t")
```

[Example in Playground](https://metafacture.org/playground/?example=put_filemap)

The separator (`sep_char`) will vary depending on the source file, e.g.:

| Type | Separator |
Expand Down Expand Up @@ -110,6 +114,8 @@ put_map("<mapName>",
)
```

[Example in Playground](https://metafacture.org/playground/?example=put_map)

##### `put_rdfmap`

Defines an external RDF map for lookup from a file or an HTTP(S) resource.
Expand All @@ -121,6 +127,8 @@ put_rdfmap("<rdfResource>", "<rdfMapName>", target: "<rdfProperty>")
put_rdfmap("<rdfResource>", "<rdfMapName>", target: "<rdfProperty>", select_language: "<rdfLanguageTag>")
```

[Example in Playground](https://metafacture.org/playground/?example=put_rdfmap)

##### `put_var`

Defines a single global variable that can be referenced with `$[<variableName>]`.
Expand All @@ -129,6 +137,8 @@ Defines a single global variable that can be referenced with `$[<variableName>]`
put_var("<variableName>", "<variableValue>")
```

[Example in Playground](https://metafacture.org/playground/?example=put_var)

##### `put_vars`

Defines multiple global variables that can be referenced with `$[<variableName>]`.
Expand All @@ -140,6 +150,8 @@ put_vars(
)
```

[Example in Playground](https://metafacture.org/playground/?example=put_vars)

#### Record-level functions

##### `add_field`
Expand All @@ -150,6 +162,8 @@ Creates a field with a defined value.
add_field("<targetFieldName>", "<fieldValue>")
```

[Example in Playground](https://metafacture.org/playground/?example=add_field)

##### `array`

Converts a hash/object into an array.
Expand Down Expand Up @@ -184,6 +198,8 @@ end
call_macro("<macroName>"[, <dynamicLocalVariables>...])
```

[Example in Playground](https://metafacture.org/playground/?example=call_macro)

##### `copy_field`

Copies a field from an existing field.
Expand All @@ -192,6 +208,9 @@ Copies a field from an existing field.
copy_field("<sourceField>", "<targetField>")
```

[Example in Playground](https://metafacture.org/playground/?example=copy_field)


##### `format`

Replaces the value with a formatted (`sprintf`-like) version.
Expand Down Expand Up @@ -224,6 +243,9 @@ Moves a field from an existing field. Can be used to rename a field.
move_field("<sourceField>", "<targetField>")
```

[Example in Playground](https://metafacture.org/playground/?example=move_field)


##### `parse_text`

Parses a text into an array or hash of values.
Expand Down Expand Up @@ -255,6 +277,8 @@ paste("my.string", "~Hi", "a", "~how are you?")
# "my.string": "Hi eeny how are you?"
```

[Example in Playground](https://metafacture.org/playground/?example=paste)

##### `print_record`

Prints the current record as JSON either to standard output or to a file.
Expand Down Expand Up @@ -304,6 +328,8 @@ Removes a field.
remove_field("<sourceField>")
```

[Example in Playground](https://metafacture.org/playground/?example=remove_field)

##### `rename`

Replaces a regular expression pattern in subfield names of a field. Does not change the name of the source field itself.
Expand All @@ -312,6 +338,8 @@ Replaces a regular expression pattern in subfield names of a field. Does not cha
rename("<sourceField>", "<regexp>", "<replacement>")
```

[Example in Playground](https://metafacture.org/playground/?example=rename)

##### `retain`

Deletes all fields except the ones listed (incl. subfields).
Expand All @@ -320,6 +348,8 @@ Deletes all fields except the ones listed (incl. subfields).
retain("<sourceField_1>"[, ...])
```

[Example in Playground](https://metafacture.org/playground/?example=retain)

##### `set_array`

Creates a new array (with optional values).
Expand All @@ -329,6 +359,8 @@ set_array("<targetFieldName>")
set_array("<targetFieldName>", "<value_1>"[, ...])
```

[Example in Playground](https://metafacture.org/playground/?example=set_array)

##### `set_field`

Creates (or replaces) a field with a defined value.
Expand Down Expand Up @@ -368,6 +400,8 @@ Deletes empty fields, arrays and objects.
vacuum()
```

[Example in Playground](https://metafacture.org/playground/?example=vacuum)

#### Field-level functions

##### `append`
Expand All @@ -378,6 +412,8 @@ Adds a string at the end of a field value.
append("<sourceField>", "<appendString>")
```

[Example in Playground](https://metafacture.org/playground/?example=append)

##### `capitalize`

Upcases the first character in a field value.
Expand All @@ -386,6 +422,8 @@ Upcases the first character in a field value.
capitalize("<sourceField>")
```

[Example in Playground](https://metafacture.org/playground/?example=capitalize)

##### `count`

Counts the number of elements in an array or a hash and replaces the field value with this number.
Expand All @@ -402,6 +440,8 @@ Downcases all characters in a field value.
downcase("<sourceField>")
```

[Example in Playground](https://metafacture.org/playground/?example=downcase)

##### `filter`

Only keeps field values that match the regular expression pattern. Works only with array of strings/repeated fields.
Expand All @@ -418,6 +458,8 @@ Flattens a nested array field.
flatten("<sourceField>")
```

[Example in Playground](https://metafacture.org/playground/?example=flatten)

##### `from_json`

Replaces the string with its JSON deserialization.
Expand Down Expand Up @@ -452,6 +494,8 @@ Options:
isbn("<sourceField>"[, to: "<isbnFormat>"][, verify_check_digit: "<boolean>"][, error_string: "<errorValue>"])
```

[Example in Playground](https://metafacture.org/playground/?example=isbn)

##### `join_field`

Joins an array of strings into a single string.
Expand All @@ -460,6 +504,8 @@ Joins an array of strings into a single string.
join_field("<sourceField>", "<separator>")
```

[Example in Playground](https://metafacture.org/playground/?example=join_field)

##### `lookup`

Looks up matching values in a map and replaces the field value with this match. [External files](#put_filemap), [internal maps](#put_map) as well as [RDF resources](#put_rdfmap) can be used.
Expand Down Expand Up @@ -527,6 +573,8 @@ Adds a string at the beginning of a field value.
prepend("<sourceField>", "<prependString>")
```

[Example in Playground](https://metafacture.org/playground/?example=prepend)

##### `replace_all`

Replaces a regular expression pattern in field values with a replacement string. Regexp capturing is possible; refer to capturing groups by number (`$<number>`) or name (`${<name>}`).
Expand All @@ -535,6 +583,8 @@ Replaces a regular expression pattern in field values with a replacement string.
replace_all("<sourceField>", "<regexp>", "<replacement>")
```

[Example in Playground](https://metafacture.org/playground/?example=replace_all)

##### `reverse`

Reverses the character order of a string or the element order of an array.
Expand All @@ -553,6 +603,8 @@ sort_field("<sourceField>", reverse: "true")
sort_field("<sourceField>", numeric: "true")
```

[Example in Playground](https://metafacture.org/playground/?example=sort_field)

##### `split_field`

Splits a string into an array and replaces the field value with this array.
Expand All @@ -561,6 +613,8 @@ Splits a string into an array and replaces the field value with this array.
split_field("<sourceField>", "<separator>")
```

[Example in Playground](https://metafacture.org/playground/?example=split_field)

##### `substring`

Replaces a string with its substring as defined by the start position (offset) and length.
Expand Down Expand Up @@ -598,6 +652,8 @@ Deletes whitespace at the beginning and the end of a field value.
trim("<sourceField>")
```

[Example in Playground](https://metafacture.org/playground/?example=trim)

##### `uniq`

Deletes duplicate values in an array.
Expand All @@ -606,6 +662,9 @@ Deletes duplicate values in an array.
uniq("<sourceField>")
```

[Example in Playground](https://metafacture.org/playground/?example=uniq)


##### `upcase`

Upcases all characters in a field value.
Expand All @@ -614,6 +673,8 @@ Upcases all characters in a field value.
upcase("<sourceField>")
```

[Example in Playground](https://metafacture.org/playground/?example=upcase)

##### `uri_encode`

Encodes a field value as URI. Aka percent-encoding.
Expand Down Expand Up @@ -645,6 +706,8 @@ if <condition>
end
```

[Example in Playground](https://metafacture.org/playground/?example=reject)

### Binds

#### `do list`
Expand All @@ -657,6 +720,8 @@ do list(path: "<sourceField>")
end
```

[Example in Playground](https://metafacture.org/playground/?example=do_list)

Only the current element is accessible in this case (as the root element).

When specifying a variable name for the current element, the record remains accessible as the root element and the current element is accessible through the variable name:
Expand All @@ -667,6 +732,8 @@ do list(path: "<sourceField>", "var": "<variableName>")
end
```

[Example in Playground](https://metafacture.org/playground/?example=do_list_with_var)

#### `do list_as`

Iterates over each _named_ element of an array (like [`do list`](#do-list) with a variable name). If multiple arrays are given, iterates over the _corresponding_ elements from each array (i.e., all elements with the same array index, skipping elements whose arrays have already been exhausted).
Expand Down Expand Up @@ -700,6 +767,8 @@ do once()
end
```

[Example in Playground](https://metafacture.org/playground/?example=do_once)

In order to execute multiple blocks only once, tag them with unique identifiers:

```perl
Expand Down Expand Up @@ -736,6 +805,8 @@ end
call_macro("<macroName>"[, <dynamicLocalVariables>...])
```

[Example in Playground](https://metafacture.org/playground/?example=do_put_macro)

### Conditionals

Conditionals start with `if` in case of affirming the condition or `unless` rejecting the condition.
Expand Down Expand Up @@ -871,4 +942,3 @@ Executes the functions if/unless the field value does not match the regular expr
##### `str_match`

Executes the functions if/unless the string matches the regular expression pattern.

0 comments on commit fbb9576

Please sign in to comment.