Parrot::Interpreter - access a Parrot interpreter from Perl 5

Version 20081006

        # the first interpreter created in the program
        my $interp       = Parrot::Interpreter->new();

        # all subsequent interpreters need a parent
        my $child_interp = $interp->new( $interp );

        # load a file that Parrot can recognize as code
        $interp->load_file( 'some_parrot_file.pbc' );
        $interp->load_file( 'some_parrot_file.pir' );
        $interp->load_file( 'some_parrot_file.pasm' );

        # compile a string of Parrot code
        $interp->compile( $some_parrot_code );

        # find a subroutine to invoke
        my $sub_pmc       = $interp->find_global( 'some_parrot_sub' );
        my $other_sub_pmc = $interp->find_global( 'another_sub', 'NameSpace' );

        # invoke the subroutine
        my $result_pmc    = $sub_pmc->invoke( $signature, @args );

        # get the values out of it
        print "Invoking the Sub gave ", $result_pmc->get_string( $interp ), "!\n";

All Parrot access goes through an interpreter, mediated through a Parrot::Interpreter object. There is always at least one active interpreter in a system. An interpreter allows you to load code, to compile code, and to find and store global symbols in Parrot. These are usually subroutines but they may be other types of PMCs.

If you have multiple active interpreters, the second and subsequent interpreters must each have an active interpreter as a parent. In general, this may not be an issue, but if you forget, you will receive strange error messages.

Note that the parent interpreter must outlive its children, in Perl 5 terms. In general, you do not need to worry about this. However, if you cache these objects, be aware that they do keep references to each other appropriately internally.

As well, all Parrot::PMC objects keep references to their parent interpreters for similar reasons.

This class provides several methods:

* new( [ $parent ] )

This class method creates and returns a new Parrot::Interpreter object. If there is an existing and active Parrot::Interpreter object, pass it as $parent. Otherwise, pass no argument.

* load_file( $filename )

Given the path to a file on disk, loads and compiles the code into the interpreter. This will throw an exception if Parrot could not load or compile the code successfully.

* compile( $code )

Given a string containing Parrot PIR code, compiles the code into the interpreter. This will return a Parrot::PMC object representing the code.

A future version of this method may allow compiling other types of code.

* find_global( $name, [ $namespace ] )

Given the name of a global and, optionally, the namespace of the global, attempts to find a global PMC associated with that name in the invoking interpreter. This will return a Parrot::PMC object if successful and undef if there is no PMC found.

This method right now supports only single-level string namespaces; this will change in the future.

chromatic, <chromatic at wgz.org>

This code might be able to detect the presence or absence of a parent interpreter and act appropriately.

This code needs to support more operations on interpreters.

Patches welcome.

Please report any bugs or feature requests to the Parrot Porters mailing list. Someday there may be a CPAN version of this code. Who knows?

Copyright (C) 2006-2008, Parrot Foundation / chromatic.

This program is free software; you can redistribute it and/or modify it under the same terms as Parrot itself.