Good call, nferraz

You are right, in my opinion, to leave the question open as to whether the idiom is useful or not. I agree with gaal that such an interface needs to be clearly documented.

However, I can see problems with using such an interface, as it is inherently ambiguous to the unwary. Can you be 100% sure that you are using it in a particular context? The perl builtins have enough traps for the unwary, see Is this a bug, or expected behavior? for an example. In terms of a popular module using your idiom already, the Class::DBI methods search and retrieve_all are an example.

What's wrong with having two separate functions, one which gives you an iterator and one which returns the list of values? Alternatively, if you are using an OO interface, return an object from ->new() which is basically an iterator with a $obj->next method, but also provide a $obj->all method to give the whole list.

I use this latter approach in File::Wildcard. To my mind, it's easier to document, to write test cases for, and does not place the burden of understanding the ambiguity with someone trying to use the module.