tree:

paginate(tree, 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.