# 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.