ext/Parrot-Embed/lib/Parrot/Interpreter.pm

   1 package Parrot::Interpreter;
   2
   3 # $Id$
   4
   5 use strict;
   6 use warnings;
   7 our $VERSION = '0.02';
   8
   9 use Parrot::Embed;
  10
  11 1;
  12
  13 __END__
  14
  15 =head1 NAME
  16
  17 Parrot::Interpreter - access a Parrot interpreter from Perl 5
  18
  19 =head1 VERSION
  20
  21 Version 0.02
  22
  23 =head1 SYNOPSIS
  24
  25         # the first interpreter created in the program
  26         my $interp       = Parrot::Interpreter->new();
  27
  28         # all subsequent interpreters need a parent
  29         my $child_interp = $interp->new( $interp );
  30
  31         # load a file that Parrot can recognize as code
  32         $interp->load_file( 'some_parrot_file.pbc' );
  33         $interp->load_file( 'some_parrot_file.pir' );
  34         $interp->load_file( 'some_parrot_file.pasm' );
  35
  36         # compile a string of Parrot code
  37         $interp->compile( $some_parrot_code );
  38
  39         # find a subroutine to invoke
  40         my $sub_pmc       = $interp->find_global( 'some_parrot_sub' );
  41         my $other_sub_pmc = $interp->find_global( 'another_sub', 'NameSpace' );
  42
  43         # invoke the subroutine
  44         my $result_pmc    = $sub_pmc->invoke( $signature, @args );
  45
  46         # get the values out of it
  47         print "Invoking the Sub gave ", $result_pmc->get_string( $interp ), "!\n";
  48
  49 All Parrot access goes through an I<interpreter>, mediated through a
  50 C<Parrot::Interpreter> object.  There is always one or more interpreters active
  51 in a system.
  52
  53 An interpreter allows you to load code, to compile code, and to find and store
  54 global symbols in Parrot.
  55
  56 =head3 Memory and Resource Implications
  57
  58 If you have multiple active interpreters, the second and subsequent
  59 interpreters must each have an active interpreter as a parent.  In general,
  60 this may not be an issue, but if you forget, you will receive strange error
  61 messages.
  62
  63 Note that the parent interpreter must outlive its children, in Perl 5 terms.
  64 In general, you do not need to worry about this.  However, if you cache these
  65 objects, be aware that they do keep references to each other appropriately
  66 internally.
  67
  68 As well, all C<Parrot::PMC> objects keep references to their parent
  69 interpreters for similar reasons.
  70
  71 =head1 METHODS
  72
  73 This class provides several methods:
  74
  75 =over 4
  76
  77 =item * C<new( [ $parent ] )>
  78
  79 This class method creates and returns a new C<Parrot::Interpreter> object.  If
  80 there is an existing and active C<Parrot::Interpreter> object, pass it as
  81 C<$parent>.  Otherwise, pass no argument.
  82
  83 =item * C<load_file( $filename )>
  84
  85 Given the path to a file on disk, loads and compiles the code into the
  86 interpreter.  This will throw an exception if Parrot could not load or compile
  87 the code successfully.
  88
  89 =item * C<compile( $code )>
  90
  91 Given a string containing Parrot PIR code, compiles the code into the
  92 interpreter.  This will return a C<Parrot::PMC> object representing the code.
  93
  94 A future version of this method may allow compiling other types of code.
  95
  96 =item * C<find_global( $name, [ $namespace ] )>
  97
  98 Given the name of a global and, optionally, the namespace of the global,
  99 attempts to find a global PMC associated with that name in the invoking
 100 interpreter.  This will return a C<Parrot::PMC> object if successful and
 101 C<undef> if there is no PMC found.
 102
 103 This method right now supports only single-level string namespaces; this will
 104 change in the future.
 105
 106 =back
 107
 108 =head1 AUTHOR
 109
 110 chromatic, C<< <chromatic at wgz.org> >>
 111
 112 =head1 BUGS
 113
 114 This code might be able to detect the presence or absence of a parent
 115 interpreter and act appropriately.
 116
 117 This code needs to support more operations on interpreters.
 118
 119 Patches welcome.
 120
 121 Please report any bugs or feature requests to the Parrot Porters mailing list.
 122 Someday there may be a CPAN version of this code.  Who knows?
 123
 124 =head1 COPYRIGHT & LICENSE
 125
 126 Copyright (C) 2006-2007 The Perl Foundation / chromatic.
 127
 128 This program is free software; you can redistribute it and/or modify it
 129 under the same terms as Parrot itself.
 130
 131 =cut
 132
 133 # Local Variables:
 134 #   mode: cperl
 135 #   cperl-indent-level: 4
 136 #   fill-column: 100
 137 # End:
 138 # vim: expandtab shiftwidth=4: