@paginate(treelike, count)
@paginateFn(count)

This returns a new tree that groups the original keys and values into “pages”: fixed-size sets of items that are no bigger than count. A typical use for this is breaking a long list of blog posts, search results, etc., into multiple web pages.

$ cat countries.yaml
- name: France
  flag: 🇫🇷
- name: Greece
  flag: 🇬🇷
- name: Italy
  flag: 🇮🇹
- name: Portugal
  flag: 🇵🇹
- name: Spain
  flag: 🇪🇸

The above set of countries can be broken into pages of (up to) 3 items each:

$ ori @paginate countries.yaml, 3
"1":
  items:
    - name: France
      flag: 🇫🇷
    - name: Greece
      flag: 🇬🇷
    - name: Italy
      flag: 🇮🇹
  nextPage: 2
  pageCount: 2
  pageNumber: 1
  previousPage: null
"2":
  items:
    "3":
      name: Portugal
      flag: 🇵🇹
    "4":
      name: Spain
      flag: 🇪🇸
  nextPage: null
  pageCount: 2
  pageNumber: 2
  previousPage: 1

Each page includes:

  • items: the items assigned to this page
  • nextPage: the number of the next page, or null for the last page
  • pageCount: the total number of pages
  • pageNumber: the number assign to this page, starting with 1
  • previousPage: the number of the previous page, or null for the first page
g 0 [data for France] ->0 0 1 [data for Greece] ->1 1 2 [data for Italy] ->2 2 3 [data for Portugal] ->3 3 4 [data for Spain] ->4 4
g 1 ->1 1 2 ->2 2 1/items 1->1/items items 1/nextPage 2 1->1/nextPage nextPage 1/pageCount 2 1->1/pageCount pageCount 1/pageNumber 1 1->1/pageNumber pageNumber 1/previousPage null 1->1/previousPage previousPage 1/items/0 [data for France] 1/items->1/items/0 0 1/items/1 [data for Greece] 1/items->1/items/1 1 1/items/2 [data for Italy] 1/items->1/items/2 2 2/items 2->2/items items 2/nextPage null 2->2/nextPage nextPage 2/pageCount 2 2->2/pageCount pageCount 2/pageNumber 2 2->2/pageNumber pageNumber 2/previousPage 1 2->2/previousPage previousPage 2/items/3 [data for Portugal] 2/items->2/items/3 3 2/items/4 [data for Spain] 2/items->2/items/4 4
Input tree
Grouped into pages

See also @addNextPrevious, which cross-links a series of items without grouping them into pages.