TITLE

Iterators that can predict number of values


SUBTITLE

A C<PredictiveIterator> is a special kind of L<C<Iterator>|/type/Iterator> that can know
how many values it will (still) generate B<without> actually needing to
generate those values.


The main addition to the API of the L<C<Iterator>|/type/Iterator> role, is the C<count-only>
method, which should return the number of values the Iterator is still
able to generate.


The other addition is the C<bool-only> method, that should return a
L<C<Bool>|/type/Bool> indicating whether the Iterator is still capable of producing
values (aka, is not exhausted yet).  By default, this is the Booleanification
of the result of the call to the C<count-only> method.


head

It is expected to return the number of values the iterator can still produce
B<without> actually producing them. The returned number B<must adjust itself>
for items already pulled, so that the method can be called on a partially
consumed L<C<Iterator>|/type/Iterator>.


It will be used in situations where only the B<number> of values of an iterator
is needed, e.g. when the C<.elems> method is called.


B<Important:> it's expected the L<C<Iterator>|/type/Iterator>s that implement this method can
return that number B<without> producing any values.  In other words,
it's expected the user of the class will be able to still L<pull-one|/routine/pull-one>
after calling this method, and eventually receive as many values as the
return value of this method indicated.


Defaults to the Booleanification of the result of calling the C<count-only>
method.  If it is possible to have a faster way of finding out whether the
iterator is capable of producing any value, it should be implemented.


method bool-only(--> Bool:D) { self.count-only.Bool }


root

Invocable code object


role Callable


Object that can be treated as a date


role Dateish


Distribution


role Distribution


Support for character encodings.


role Encoding


Provide leading/trailing doc functionality


class RakuAST::Doc::DeclaratorTarget


Number stored as numerator and denominator


role Rational


Non-complex number


role Real


String or object that can act as a string


role Stringy


para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

role PredictiveIterator


Running process (filehandle-based interface)


C<Proc> is a representation of an invocation of an external
process. It provides access to the input, output and error stream as well as
the exit code. It is typically created through the X<C<run>|Subroutines,run> subroutine:


code

Piping several commands is easy too. To achieve the equivalent of the
pipe C<echo "Hello, world" | cat -n> in Raku, and capture the output
from the second command, you can do


You can also feed the C<:in> (standard input) pipe directly from your program,
by setting it to C<True>, which will make the pipe available via C<.in> method
on the C<Proc>:


In order to capture the standard error, C<:err> can be supplied:


In sink context, a C<Proc> will call its C<sink> method, throwing an exception
if the process has exited with an exit code different from zero:


B<Note:> Versions of L<Rakudo|/language/glossary#Rakudo> older than 2017.04 do
not have C<.slurp> available on L<C<IO::Pipe>|/type/IO::Pipe> objects; use
L«C<.slurp-rest>|/routine/slurp-rest» instead.


Use L<C<Proc::Async>|/type/Proc::Async> for non-blocking operations.


If you run an external program with C<:out> and C<:err> (so
capturing standard output and standard error separately), a deadlock
can occur, for example in the following scenario:


item

You can avoid this by using C<:merge> to join the external program's
standard output and error streams, so that you only need to read from
one pipe. This presupposes that you do not need separate access
to the two streams. If you do, the only safe approach is to use
L<C<Proc::Async>|/type/Proc::Async>.


A similar deadlock can occur when you call an external program with
both the C<:in> option (to open a pipe to its standard input) and
one of the C<:out>, C<:err> or C<:merge> options. In this scenario,
it can happen that your Raku script blocks reading from the external
program's output while it waits for input, and vice versa.


In this scenario, switching to L<C<Proc::Async>|/type/Proc::Async> is the most
robust solution.


=begin code :skip-test<compile time error>
method new(Proc:U:
        :$in = '-',
        :$out = '-',
        :$err = '-',
        Bool :$bin = False,
        Bool :$chomp = True,
        Bool :$merge = False,
        Str:D :$enc = 'UTF-8',
        Str:D :$nl = "\n",
    --> Proc:D)

sub shell(
        $cmd,
        :$in = '-',
        :$out = '-',
        :$err = '-',
        Bool :$bin = False,
        Bool :$chomp = True,
        Bool :$merge = False,
        Str:D :$enc = 'UTF-8',
        Str:D :$nl = "\n",
        :$cwd = $*CWD,
        Hash() :$env = %*ENV
    --> Proc:D)
=end code


C<new> creates a new C<Proc> object, whereas C<run> or C<shell> create one and
spawn it with the command and arguments provided in C<@args> or C<$cmd>,
respectively.


C<$in>, C<$out> and C<$err> are the three standard streams of the to-be-launched
program, and default to C<"-"> meaning they inherit the stream from the parent
process. Setting one (or more) of them to C<True> makes the stream available as
an L<C<IO::Pipe>|/type/IO::Pipe> object of the same name, like for example
C<$proc.out>. You can set them to C<False> to discard them. Or you can pass an
existing L<C<IO::Handle>|/type/IO::Handle> object (for example L<C<IO::Pipe>|/type/IO::Pipe>) in, in
which case this handle is used for the stream.


Please bear in mind that the process streams reside in process
variables, not in the dynamic variables that make them available to our
programs. Thus, modifying
L<the dynamic filehandle variables (such as C<$*OUT>)|/language/variables#Special_filehandles:_STDIN,_STDOUT_and_STDERR>
inside the host process will have no effect in the spawned process,
unlike C<$*CWD> and C<$*ENV>, whose changes will be actually reflected
in it.


=begin code
my $p-name = "/tmp/program.raku";
my $program = Q:to/END/;
    #!/usr/bin/env raku

    $*OUT.say( qq/\t$*PROGRAM: This goes to standard output/ );
END

spurt $p-name, $program;

$*OUT.put: "1. standard output before doing anything weird";

{
    temp $*OUT = open '/tmp/out.txt', :w;
    $*OUT.put: "2. temp redefine standard output before this message";
    shell( "raku $p-name" ).so;
}

$*OUT.put: "3. everything should be back to normal";
# OUTPUT
# 1. standard output before doing anything weird
#     /tmp/program.raku: This goes to standard output
# 3. everything should be back to normal

# /tmp/out.txt will contain:
# 2. temp redefine standard output before this message
=end code


This program shows that the program spawned with C<shell> is not using
the temporary C<$*OUT> value defined in the host process (redirected to
C</tmp/out.txt>), but the initial C<STDOUT> defined in the process.


C<$bin> controls whether the streams are handled as binary (i.e.
L<C<Blob>|/type/Blob> object) or text (i.e. L<C<Str>|/type/Str> objects). If
C<$bin> is False, C<$enc> holds the character encoding to encode strings
sent to the input stream and decode binary data from the output and
error streams.


With C<$chomp> set to C<True>, newlines are stripped from the output and
err streams when reading with C<lines> or C<get>. C<$nl> controls what
your idea of a newline is.


If C<$merge> is set to True, the standard output and error stream end up
merged in C<$proc.out>.


When sunk, the C<Proc> object will throw L<C<X::Proc::Unsuccessful>|/type/X::Proc::Unsuccessful>
if the process it ran exited unsuccessfully.


method spawn(*@args ($, *@), :$cwd = $*CWD, Hash() :$env = %*ENV, :$arg0,
             :$win-verbatim-args = False --> Bool:D)


Runs the C<Proc> object with the given command, argument list, working directory,
and environment.


If C<:arg0> is set to a value, that value is passed as arg0 to the process
instead of the program name.


On Windows the flag C<$win-verbatim-args> disables all automatic quoting of
process arguments. See L<this blog|https://docs.microsoft.com/en-us/archive/blogs/twistylittlepassagesallalike/everyone-quotes-command-line-arguments-the-wrong-way>
for more information on windows command quoting. The flag is ignored on all
other platforms. The flag was introduced in Rakudo version 2020.06 and is not
present in older releases.


method shell($cmd, :$cwd = $*CWD, :$env --> Bool:D)


Runs the C<Proc> object with the given command and environment which are
passed through to the shell for parsing and execution. See
L<C<shell>|/type/independent-routines#sub_shell> for an explanation of which shells
are used by default in the most common operating systems.


The command method is an accessor to a list containing the arguments
that were passed when the Proc object was executed via C<spawn> or
C<shell> or C<run>.


Member variable


class Attribute


Removal of a task from a Scheduler before normal completion


class Cancellation


Thread-safe queue for sending values from producers to consumers


class Channel


CompUnit


class CompUnit


CompUnit::Repository::FileSystem


class CompUnit::Repository::FileSystem


CompUnit::Repository::Installation


class CompUnit::Repository::Installation


Distribution related information


class Distro


Formal grammar made up of named regexes


class Grammar


Iterate over contents of files specified on command line


class IO::ArgFiles


Use multiple IO handles as if they were one


class IO::CatHandle


Opened file or stream


class IO::Handle


Asynchronous notification for file and directory changes





class IO::Notification


Changes in a file, produced by watch-file


class IO::Notification::Change


File or directory path


class IO::Path


IO::Path pre-loaded with IO::Spec::Cygwin


class IO::Path::Cygwin


IO::Path parts encapsulation


class IO::Path::Parts


IO::Path pre-loaded with IO::Spec::QNX


class IO::Path::QNX


IO::Path pre-loaded with IO::Spec::Unix


class IO::Path::Unix


IO::Path pre-loaded with IO::Spec::Win32


class IO::Path::Win32


Buffered inter-process string or binary stream


class IO::Pipe


Asynchronous socket in TCP or UDP


class IO::Socket::Async


A tap for listening TCP sockets


class IO::Socket::Async::ListenSocket


TCP Socket


class IO::Socket::INET


Platform specific operations on file and directory paths


class IO::Spec


Platform specific operations on file and directory paths for Cygwin


class IO::Spec::Cygwin


Platform specific operations on file and directory paths QNX


class IO::Spec::QNX


Platform specific operations on file and directory paths for POSIX


class IO::Spec::Unix


Platform specific operations on file and directory paths for Windows


class IO::Spec::Win32


Path to special I/O device


class IO::Special


Kernel related information


class Kernel


A low-level, re-entrant, mutual exclusion lock


class Lock


Condition variables used in locks


class Lock::ConditionVariable


Result of a successful regex match


class Match


Block in a Pod document


class Pod::Block


Verbatim code block in a Pod document


class Pod::Block::Code


Comment in a Pod document


class Pod::Block::Comment


Declarator block in a Pod document


class Pod::Block::Declarator


Named block in a Pod document


class Pod::Block::Named


Paragraph in a Pod document


class Pod::Block::Para


Table in a Pod document


class Pod::Block::Table


Pod definition list


class Pod::Defn


Pod formatting code


class Pod::FormattingCode


Heading in a Pod document


class Pod::Heading


Item in a Pod enumeration list


class Pod::Item


Running process (asynchronous interface)


class Proc::Async


Status/result of an asynchronous computation


class Promise


String pattern


class Regex


Control access to shared resources by multiple threads


class Semaphore


Live Supply factory


class Supplier


Cached live Supply factory


class Supplier::Preserving


Asynchronous data stream with multiple subscribers


class Supply


Subscription to a Supply


class Tap


Concurrent execution of code (low-level)


class Thread


Scheduler that distributes work among a pool of threads


class ThreadPoolScheduler


Unicode related information


class Unicode


Raku Virtual Machine related information


class VM


class Proc


This role provides an interface by which an object can
be coerced into a L<C<Positional>|/type/Positional> when binding to L<C<Positional>|/type/Positional> parameters.


For example, L<C<Seq>|/type/Seq> type is not L<C<Positional>|/type/Positional>, but you can still write
the following, because it L<does|/routine/does> C<PositionalBindFailover> role:


sub fifths(@a) {        # @a is constraint to Positional
    @a[4];
}
my $seq := gather {     # a Seq, which is not Positional
    take $_ for 1..*;
}
say fifths($seq);       # OUTPUT: «5␤»


The invocation of C<fifths> in the example above would ordinarily give a type
error, because C<$seq> is of type L<C<Seq>|/type/Seq>, which doesn't do the
L<C<Positional>|/type/Positional> interface that the C<@>-sigil implies.


But the signature binder recognizes that L<C<Seq>|/type/Seq> does the
C<PositionalBindFailover> role, and calls its C<cache> method to coerce it to
a L<C<List>|/type/List>, which does the L<C<Positional>|/type/Positional> role.


The same happens with custom classes that do the role; they simply
need to provide an C<iterator> method that produces an L<C<Iterator>|/type/Iterator>:


class Foo does PositionalBindFailover {
    method iterator {
        class :: does Iterator {
            method pull-one {
                return 42 unless $++;
                IterationEnd
            }
        }.new
    }
}


sub first-five (@a) { @a[^5].say }
first-five Foo.new; # OUTPUT: # OUTPUT: «(42 Nil Nil Nil Nil)␤»


method cache(PositionalBindFailover:D: --> List:D)


Returns a L<C<List>|/type/List> based on the C<iterator> method, and caches it.
Subsequent calls to C<cache> always return the same L<C<List>|/type/List> object.


Returns a L<C<List>|/type/List> based on the C<iterator> method without caching it.


method iterator(PositionalBindFailover:D:) { ... }


This method stub ensure that a class implementing role
C<PositionalBindFailover> provides an C<iterator> method.


role PredictiveIterator

Methods

method count-only

method bool-only

See Also