Implements iterator patterns through the `yield` metadata

To install, run:

haxelib install yield 1.3.0 

See using Haxelib in Haxelib documentation for more information.



MIT License TravisCI Build Status

This library adds the yield metadata, which is similar to the yield keyword in C#.

The yield metadata defines iterator blocks and indicates that the function, operator (see operator overloading), or accessor in which it appears is an iterator.

When defining an iterator with yield statements, an extra class is implicitly created to hold the state for an iteration likewise implementing the Iterator<T> or Iterable<T> pattern for a custom type (see iterators for an example).


Any @yield statements are available for classes that are annotated with the :yield metadata, or available for all classes that extend classes annotated with :yield(Extend).

class MyClass {
    // ...

When dealing with abstracts, use @:build(yield.parser.Parser.run()) instead of @:yield.

The following example shows the two forms of the yield metadata:

@yield return expression;
@yield break;

Use a @yield return statement to return each element one at a time.
Use a @yield break statement to end the iteration.

Iterator methods can be run through using a for expression or Lambda functions. When a yield return statement is reached in the iterator method, expression is returned. Execution is restarted from that location the next time that the iterator function is called.

The return type must be Iterator<T> or Iterable<T>. If no return type is defined, the type will be Dynamic, and can be unified to both Iterator or Iterable.


Here’s an example of the yield metadata usage:

function sayHello (name:String):Iterator<String> {
    @yield return “Hello”;
    @yield return name + “!”;

Here the sayHello function usage:

for (word in sayHello(“World”)) {
    trace(word); // “Hello”, “World!”

Call the sayHello method returns an Iterator<String>. The body of the method is not executed yet.
The for loop iterates over the iterator while the Iterator<String>.hasNext method returns true.
The method Iterator<String>.hasNext executes only once the body of sayHello until the next @yield statement is reached. In case of a @yield return statement, Iterator<String>.hasNext will return true, and the result of the execution can be get once by calling Iterator<String>.next.

The Iterator<String>.next method can also be used without calling Iterator<String>.hasNext. If the end of sayHello is reached, Iterator<String>.next returns the default value of the return type.

Here’s a second example:

function getCounter ():Iterator<UInt> {
    var i:UInt = 0;
    while (true) {
        @yield return i++;

var counter:Iterator<UInt> = getCounter();

counter.next(); // 0
counter.next(); // 1
counter.next(); // 2
// ...
counter.next(); // n

Advanced usage

You can compile with some options or pass several yield.YieldOption into the :yield metadata.

Available options are:

  • yieldExtend

    If the option is enabled, all extending classes will be able to use yield statements. If this option affects an interface, all implementing classes and all extending interfaces will be able to use yield statements. This is disabled by default.
    Compile with `-D yieldExtend`.
  • yieldExplicit

    If the option is enabled, the return type of iterative functions needs to be explicitly specified. This is disabled by default.
    Compile with `-D yieldExplicit`.
  • yieldKeyword

    Use a custom keyword instead of "yield".
    Compile with `-D yieldKeyword=myCustomMetaName`.

@yield return statements can be located in try blocks. This will duplicate the catch expressions as many times as there are iterator blocks.


To install the library, use haxelib install yield and compile your program with -lib yield.

1 week ago

All libraries are free

Every month, more than thousand developers use haxelib to find, share, and reuse code — and assemble it in powerful new ways. Enjoy Haxe; It is great!

Explore Haxe

Haxe Manual

Haxe Code Cookbook

Haxe API documentation

You can try Haxe in the browser! try.haxe.org

Join us on Github!

Haxe is being developed on GitHub. Feel free to contribute or report issues to our projects.

Haxe on Github