Merge a6b6126 into ccd83bc

.gitignore

@@ -12,6 +12,7 @@ node_modules/
 
 # tmp
 docs/public/js/liquid.browser.min.js
+docs/themes/navy/layout/partial/all-contributors.swig
 dist/
 demo/*/yarn.json
 

docs/source/_data/sidebar.yml

@@ -8,6 +8,7 @@ tutorials:
     express: use-in-expressjs.html
   advanced:
     caching: caching.html
+    escaping: escaping.html
     registeration: register-filters-tags.html
     access_scope_in_filters: access-scope-in-filters.html
     parse_parameters: parse-parameters.html
@@ -40,8 +41,12 @@ filters:
   downcase: downcase.html
   escape: escape.html
   escape_once: escape_once.html
+  find: find.html
+  find_exp: find_exp.html
   first: first.html
   floor: floor.html
+  group_by: group_by.html
+  group_by_exp: group_by_exp.html
   join: join.html
   json: json.html
   last: last.html
@@ -51,6 +56,8 @@ filters:
   modulo: modulo.html
   newline_to_br: newline_to_br.html
   plus: plus.html
+  pop: pop.html
+  push: push.html
   prepend: prepend.html
   raw: raw.html
   remove: remove.html
@@ -62,6 +69,7 @@ filters:
   reverse: reverse.html
   round: round.html
   rstrip: rstrip.html
+  shift: shift.html
   size: size.html
   slice: slice.html
   sort: sort.html
@@ -75,6 +83,7 @@ filters:
   truncate: truncate.html
   truncatewords: truncatewords.html
   uniq: uniq.html
+  unshift: unshift.html
   upcase: upcase.html
   url_decode: url_decode.html
   url_encode: url_encode.html

docs/source/filters/find.md

@@ -0,0 +1,25 @@
+---
+title: find
+---
+
+{% since %}v10.11.0{% endsince %}
+
+Return the first object in an array for which the queried attribute has the given value or return `nil` if no item in the array satisfies the given criteria. For the following `members` array:
+
+```javascript
+const members = [
+  { graduation_year: 2013, name: 'Jay' },
+  { graduation_year: 2014, name: 'John' },
+  { graduation_year: 2014, name: 'Jack' }
+]
+```
+
+Input
+```liquid
+{{ members | find: "graduation_year", 2014 | json }}
+```
+
+Output
+```text
+{"graduation_year":2014,"name":"John"}
+```

docs/source/filters/find_exp.md

@@ -0,0 +1,25 @@
+---
+title: find_exp
+---
+
+{% since %}v10.11.0{% endsince %}
+
+Return the first object in an array for which the given expression evaluates to true or return `nil` if no item in the array satisfies the evaluated expression.
+
+```javascript
+const members = [
+  { graduation_year: 2013, name: 'Jay' },
+  { graduation_year: 2014, name: 'John' },
+  { graduation_year: 2014, name: 'Jack' }
+]
+```
+
+Input
+```liquid
+{{ members | find_exp: "item", "item.graduation_year == 2014" | json }}
+```
+
+Output
+```text
+{"graduation_year":2014,"name":"John"}
+```

docs/source/filters/group_by.md

@@ -0,0 +1,48 @@
+---
+title: group_by
+---
+
+{% since %}v10.11.0{% endsince %}
+
+Group an array's items by a given property. For `members` array:
+
+```javascript
+const members = [
+  { graduation_year: 2003, name: 'Jay' },
+  { graduation_year: 2003, name: 'John' },
+  { graduation_year: 2004, name: 'Jack' }
+]
+```
+
+Input
+```liquid
+{{ members | group_by: "graduation_year" | json: 2 }}
+```
+
+Output
+```text
+[
+  {
+    "name": 2003,
+    "items": [
+      {
+        "graduation_year": 2003,
+        "name": "Jay"
+      },
+      {
+        "graduation_year": 2003,
+        "name": "John"
+      }
+    ]
+  },
+  {
+    "name": 2004,
+    "items": [
+      {
+        "graduation_year": 2004,
+        "name": "Jack"
+      }
+    ]
+  }
+]
+```

docs/source/filters/group_by_exp.md

@@ -0,0 +1,48 @@
+---
+title: group_by_exp
+---
+
+{% since %}v10.11.0{% endsince %}
+
+Group an array's items using a Liquid expression. For `members` array below:
+
+```javascript
+const members = [
+  { graduation_year: 2013, name: 'Jay' },
+  { graduation_year: 2014, name: 'John' },
+  { graduation_year: 2009, name: 'Jack' }
+]
+```
+
+Input
+```liquid
+{{ members | group_by_exp: "item", "item.graduation_year | truncate: 3, ''" | json: 2 }}
+```
+
+Output
+```text
+[
+  {
+    "name": "201",
+    "items": [
+      {
+        "graduation_year": 2013,
+        "name": "Jay"
+      },
+      {
+        "graduation_year": 2014,
+        "name": "John"
+      }
+    ]
+  },
+  {
+    "name": "200",
+    "items": [
+      {
+        "graduation_year": 2009,
+        "name": "Jack"
+      }
+    ]
+  }
+]
+```

docs/source/filters/json.md

@@ -16,3 +16,24 @@ Output
 ```text
 ["foo","bar","coo"]
 ```
+
+## Space
+
+{% since %}v10.11.0{% endsince %}
+
+An additional `space` parameter can be specified to format the JSON.
+
+Input
+```liquid
+{% assign arr = "foo bar coo" | split: " " %}
+{{ arr | json: 4 }}
+```
+
+Output
+```text
+[
+    "foo",
+    "bar",
+    "coo"
+]
+```

docs/source/filters/overview.md

@@ -12,7 +12,7 @@ Categories | Filters
 Math | plus, minus, modulo, times, floor, ceil, round, divided_by, abs, at_least, at_most
 String | append, prepend, capitalize, upcase, downcase, strip, lstrip, rstrip, strip_newlines, split, replace, replace_first, replace_last,remove, remove_first, remove_last, truncate, truncatewords
 HTML/URI | escape, escape_once, url_encode, url_decode, strip_html, newline_to_br
-Array | slice, map, sort, sort_natural, uniq, where, first, last, join, reverse, concat, compact, size
+Array | slice, map, sort, sort_natural, uniq, where, group_by, group_by_exp, find, find_exp, first, last, join, reverse, concat, compact, size, push, pop, shift, unshift
 Date | date
 Misc | default, json, raw
 

docs/source/filters/pop.md

@@ -0,0 +1,24 @@
+---
+title: pop
+---
+
+{% since %}v10.11.0{% endsince %}
+
+Pop an element from the array. It's NON-DESTRUCTIVE, i.e. it does not mutate the array, but rather make a copy and mutate that.
+
+Input
+```liquid
+{% assign fruits = "apples, oranges, peaches" | split: ", " %}
+
+{% assign everything = fruits | pop %}
+
+{% for item in everything %}
+- {{ item }}
+{% endfor %}
+```
+
+Output
+```text
+- apples
+- oranges
+```

docs/source/filters/push.md

@@ -0,0 +1,25 @@
+---
+title: push
+---
+
+{% since %}v10.8.0{% endsince %}
+
+Push an element into array. It's NON-DESTRUCTIVE, i.e. it does not mutate the array, but rather make a copy and mutate that.
+
+Input
+```liquid
+{% assign fruits = "apples, oranges" | split: ", " %}
+
+{% assign everything = fruits | push: "peaches" %}
+
+{% for item in everything %}
+- {{ item }}
+{% endfor %}
+```
+
+Output
+```text
+- apples
+- oranges
+- peaches
+```

docs/source/filters/shift.md

@@ -0,0 +1,24 @@
+---
+title: shift
+---
+
+{% since %}v10.11.0{% endsince %}
+
+Shift an element from the array. It's NON-DESTRUCTIVE, i.e. it does not mutate the array, but rather make a copy and mutate that.
+
+Input
+```liquid
+{% assign fruits = "apples, oranges, peaches" | split: ", " %}
+
+{% assign everything = fruits | shift %}
+
+{% for item in everything %}
+- {{ item }}
+{% endfor %}
+```
+
+Output
+```text
+- oranges
+- peaches
+```

docs/source/filters/unshift.md

@@ -0,0 +1,25 @@
+---
+title: unshift
+---
+
+{% since %}v10.11.0{% endsince %}
+
+Unshift an element to the front of the array. It's NON-DESTRUCTIVE, i.e. it does not mutate the array, but rather make a copy and mutate that.
+
+Input
+```liquid
+{% assign fruits = "oranges, peaches" | split: ", " %}
+
+{% assign everything = fruits | unshift: "apples" %}
+
+{% for item in everything %}
+- {{ item }}
+{% endfor %}
+```
+
+Output
+```text
+- apples
+- oranges
+- peaches
+```

docs/source/filters/where.md

@@ -79,4 +79,28 @@ Output
 Featured product: Hawaiian print sweater vest
 ```
 
+Additionally, `property` can be any valid Liquid variable expression as used in output syntax, except that the scope of this expression is within each item. For the following `products` array:
+
+```javascript
+const products = [
+    { meta: { details: { class: 'A' } }, order: 1 },
+    { meta: { details: { class: 'B' } }, order: 2 },
+    { meta: { details: { class: 'B' } }, order: 3 }
+]
+```
+
+Input
+```liquid
+{% assign selected = products | where: 'meta.details["class"]', "B" %}
+{% for item in selected -%}
+- {{ item.order }}
+{% endfor %}
+```
+
+Ouput
+```text
+- 2
+- 3
+```
+
 [truthy]: ../tutorials/truthy-and-falsy.html