Iterator

Iterator binds the WpIterator C API, which is the generic mechanism that the library uses to return collections of items. Scripts get one from ObjectManager.iterate(), Node.iterate_params(), Settings.iterate() and several other APIs.

These functions do not return a plain iterator object; they return the pair of values that a Lua for loop expects, so they are meant to be used directly in a for loop:

for node in om:iterate { type = "node" } do
  do_stuff (node)
end

The type of the items depends on the API that returned the iterator; it is documented on each of those functions.

Warning

Because two values are returned, assigning the result to a single variable captures the iteration function, not the iterator:

-- WRONG: 'it' is a function here, not an Iterator
local it = node:iterate_params ("Props")

The iterator object is the second return value:

local _, it = node:iterate_params ("Props")

Methods

The following methods are available on the iterator object, for the cases where a plain for loop is not enough:

Iterator.next(self)

Binds wp_iterator_next()

Advances the iterator and returns the next item.

Returns:

the next item, or nil when the iteration is finished

Iterator.reset(self)

Binds wp_iterator_reset()

Rewinds the iterator back to the beginning, so that it can be iterated again.

Iterator.iterate(self)

Returns the iterator again in the form expected by a Lua for loop, so that an iterator held in a variable can be looped over:

local _, it = node:iterate_params ("Props")
for pod in it:iterate () do
  -- ...
end

Note

Some APIs, such as Settings.iterate() and Metadata.iterate(), yield several values per step rather than a single item. These methods do not know about that: they always apply the generic item conversion, so next() and iterate() on such an iterator return the raw item object instead of the values that the for loop would have yielded. Use the for loop for those APIs.