Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add pending documentation #19

Merged
merged 7 commits into from
Jul 12, 2021
Merged

Add pending documentation #19

Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
59592b1
Add documentation for link
marcelolx May 20, 2021
2b89de9
Merge branch 'master' into docs
marcelolx Jun 1, 2021
625b193
Add docs for uniq_by
marcelolx Jun 1, 2021
950f604
Add doc for array_presence: first_only
marcelolx Jul 10, 2021
736081a
Add doc for in_parent
marcelolx Jul 10, 2021
18a168f
Add doc for keep_if
marcelolx Jul 10, 2021
5aee5d7
Apply suggestions from code review
marcelolx Jul 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
290 changes: 289 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,294 @@ schemas:
}
```

### link

Works as a JOIN SQL, it gets the value through the expression provided by the tag `link` and replaces the tag `<link>` contained in the tag `path` with the value to search values related to the node which you are parsing. This is needed when the data in the XML is all in the same level and this levels are linked between them and you need to navigate to each level to find all the data in the XML.
marcelolx marked this conversation as resolved.
Show resolved Hide resolved

Example:
```yml
schemas:
bookings:
array_of: booking
date: booking_date
document: id
products:
array_of:
accomodation:
path: ../hotel[booking_id=<link>]/accomodation
link: id
```
```xml
<xml>
<booking>
<id>1</id>
<booking_date>2020-01-01</booking_date>
</booking>
<booking>
<id>2</id>
<booking_date>2020-01-02</booking_date>
</booking>
<hotel>
<booking_id>1</booking_id>
<accomodation>Standard</accomodation>
</hotel>
<hotel>
<booking_id>2</booking_id>
<accomodation>Premium</accomodation>
</hotel>
</xml>
```
```ruby
{
bookings: [
{
date: "2020-01-01",
document: "1"
products: [
{ accomodation: "Standard" }
]
},
{
date: "2020-01-02",
document: "2"
products: [
{ accomodation: "Premium" }
]
}
]
}
```

In this example if I didn't use the `link` to get only the hotel of each booking, it would have returned two accomodations for each booking and instead of extract a string with the accomodation it would extract an array with all the accomodations for each booking.

You can combine the `link` with `array_of` if you want search for a list of elements filtering by some field, just provide the `path` and the `link`:

```yml
schemas:
bookings:
array_of: booking
date: date
document: id
products:
array_of:
path: ../products[booking_id=<link>]
link: id
....
```

### uniq_by

Can only be used with **array_of**.

Has a similar behavior like Ruby **uniq** method on arrays, do you provide a path to the `uniq_by` tag and then we will keep only on the array_of the paths that have a diferrent values in the path provided on the tag `uniq_by`, if the value of the path provided in the tag `uniq_by` is equal in more than one path, we will keep the first path and the remaining paths will be ignored. This functionality is useful when some node in the XML is duplicated and it is only necessary to obtain the info from one of the nodes.
marcelolx marked this conversation as resolved.
Show resolved Hide resolved

```yml
schemas:
bookings:
array_of:
path: booking
uniq_by: id
date: bdate
document: id
```
```xml
<xml>
<booking>
<id>1</id>
<bdate>2020-01-01</bdate>
</booking>
<booking>
<id>1</id>
<bdate>2020-01-01</bdate>
</booking>
</xml>
```
```ruby
{
bookings: [
{
date: "2020-01-01",
document: "1"
}
]
}
```

In this example if we don't use the tag `uniq_by` there would be extracted two elements with the same data, like:

```ruby
{
bookings: [
{
date: "2020-01-01",
document: "1"
},
{
date: "2020-01-01",
document: "1"
}
]
}
```

### array_presence: first_only
Copy link
Contributor

@fernand-o fernand-o Jul 12, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not related, but I believe this command should be changed to first_only: true

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it's on my radar. As soon as I start working on #2 I will make the change


The field that contains this property will be only added to the first item of the array.

Can only be used in fields that belong to a node of `array_of`.

```yml
passengers:
array_of: bookings/booking/passengers/passenger
id:
path: document
modifier: to_s
name:
attr: [FirstName, LastName]
modifier:
- name: join
params: [" "]
rav_tax:
array_presence: first_only
path: ../rav
modifier: to_f
```
```xml
<bookings>
<booking>
<rav>150<rav>
<passengers>
<passenger>
<document>109.111.019-79</document>
<FirstName>Marcelo</FirstName>
<LastName>Lauxen</LastName>
</passenger>
<passenger>
<document>110.155.019-78</document>
<FirstName>Corona</FirstName>
<LastName>Virus</LastName>
</passenger>
</passengers>
</booking>
</bookings>
```
```ruby
{
bookings: [
{
passengers: [
{
id: "109.111.019-79",
name: "Marcelo Lauxen",
tax_rav: 150.00
},
{
id: "110.155.019-78",
name: "Corona Virus"
}
]
}
]
}
```

In this example the field `tax_rav` was only included on the first passenger because this field has the `array_presence: first_only` property.

### in_parent

This option allows you to navigate to a parent node of the current node.

```yml
passengers:
array_of: bookings/booking/passengers/passenger
id:
path: document
modifier: to_s
bookings_id:
in_parent: bookings
path: id
```
```xml
<bookings>
<bookings_id>8888</bookings_id>
<booking>
<passengers>
<passenger>
<document>109.111.019-79</document>
</passenger>
<passenger>
<document>110.155.019-78</document>
</passenger>
</passengers>
</booking>
</bookings>
```
```ruby
{
bookings: [
{
passengers: [
{
id: "109.111.019-79",
bookings_id: 8888
},
{
id: "110.155.019-78",
bookings_id: 8888
}
]
}
]
}
```

In this example the value of `bookings_id` will be extracted starting at the node provided in `in_parent` instead of the current node. It's possible to navigate to a parent node with `../` too (xpath provides this functionality), but with `in_parent` you just need to provide the name of the parent node, it doesn't matters if the parent node is the parent of the current node or if it's the parent of the parent of the current node.
marcelolx marked this conversation as resolved.
Show resolved Hide resolved

### keep_if

This option allows you to keep the part of the block of the hash in the final result only if the condition matches.

```yml
schemas:
dummy:
within: data
description: additional_desc
exchange: currency_info/value
price: price
payment:
type: payment_info/method
value: payment_info/price
keep_if: "'type' == 'invoice'"
```
```xml
<data>
<additional_desc>Keep walking</additional_desc>
<currency_info kind="USD">
<value>4.15</value>
</currency_info>
<price>55.09</price>
<payment_info>
<method>card</method>
<price>55.48</price>
<payment>
<installments>2</installments>
<card_number>333</card_number>
</payment>
</payment>
<data>
```
```ruby
{
dummy: {
description: "Keep walking",
exchange: "4.15",
price: "55.09"
}
}
```

In this example the condition didn't match since the payment method was `card` instead of `invoice` and then the extracted payment hash was removed from the final result.

### Formatting:

#### fixed
Expand Down Expand Up @@ -379,7 +667,7 @@ schemas:
path: [firstname, lastname]
modifier:
- name: join
params: [" "]
params: [" "]
- downcase
```
```xml
Expand Down