# Copyright: 2001-2004 The Perl Foundation.  All Rights Reserved.
# $Id: pdd01_overview.pod 5470 2004-02-28 09:16:37Z mikescott $

=head1 NAME

docs/pdds/pdd01_overview.pod - A high-level overview of the Parrot system

=head1 ABSTRACT

This PDD provides a high-level overview of the Parrot system. 

=head1 DESCRIPTION

=head2 Major components

The Parrot system generally looks like this:

 +----------------------------------------------------+
 |                   Embedding App                    |
 +----------+------------+-------------+--------------+
 |          |            |             |              |
 |  parser <-> compiler <-> optimizer <-> interpreter |
 |          |            |             |              |
 +----------+------------+-------------+--------------+
 |                Extensions to Parrot                |
 +----------------------------------------------------+ 

=over 4

=item Parser

The parser takes source code of some sort and creates a syntax tree of
that source.

Different high level languages will generally have their own parser
modules, implemented in whatever language is most convenient. For instance,
we currently intend to write the parser for Perl 6 in Perl 6, to allow
for easy extension. Generally there will be one parser per language, though
there's no reason that there can't be multiple independent parsers.

=item Bytecode compiler

The bytecode compiler module takes a syntax tree from the parser and
emits an unoptimized stream of bytecode. This code is suitable for
passing straight to the interpreter, though it is probably not going
to be very fast.

=item Optimizer

The optimizer module takes the bytecode stream from the compiler and
optionally the syntax tree the bytecode was generated from, and
optimizes the bytecode.

=item Interpreter

The interpreter module takes the bytecode stream from either the
optimizer or the bytecode compiler and executes it. There must always
be at least one interpreter module available for any program that can
handle all of Perl, since it's required for use statements and BEGIN
blocks.

While there must be at least one interpreter, there may be multiple
interpreter modules linked into an executable. This would be the case,
for example, for programs that produced Java bytecode, where one of
the interpreter modules would take the bytecode stream and spit out
Java bytecode instead of interpreting it.

=back

=head2 Independent subsystems

Parrot also has a number of subsystems that are independent of any
single module.

=over 4

=item ParrotIO subsystem

The ParrotIO subsystem provides source- and platform-independent
asynchronous I/O to Parrot. The intent is to make Parrot (and any
languages that run on it) independent of C's stdio system. (And good 
riddance--it sucks) How this maps to the OS's underlying I/O code is not 
generally Parrot's concern, and a platform isn't obligated to provide 
asynchronous I/O.

Additionally, the ParrotIO subsystem allows a program to push filters
onto an input stream if necessary, to manipulate the data before it is
presented to a program. 

=item Regex engine

By providing a regular expression engine as a separate subsystem of
Parrot, we intend to make it easily available to any language running
on Parrot (cf. the Perl 5 regex engine, which is intimately linked to
the perl core). The job of the regex engine is to turn regexes into objects, 
and apply those regex objects to strings. 

=back

=head2 API levels

=over 4

=item Embedding

The embedding API is the set of calls exported to the embedding
application. This is a small, simple set of calls, requiring minimum
effort to use. 

The goal is to provide an interface that a competent programmer who is
uninterested in Parrot internals can use to provide access to a Parrot
interpreter within another application with very little programming or
intellectual effort. Generally it should take less than thirty minutes
for a simple interface, though more complete integration will take
longer.

Backwards binary compatibility at this level is guaranteed across the
life of Parrot.

=item Extensions

The extension API is the set of calls exported to Parrot
extensions. They provide access to most of the things an extension
needs to do, while hiding the implementation details. (So that, for
example, we can change the way scalars are stored without having to
rewrite, or even recompile, an extension).

Binary compatibility is a serious goal, though it may be broken if
absolutely necessary.

=item Guts

The guts-level APIs are the routines used within a component. These
aren't guaranteed to be stable, and shouldn't be used outside a
component. (For example, an extension to the interpreter shouldn't
call any of the parser's internal routines).

No binary compatibility is guaranteed, and routines here may be
changed without notice.

=back

=head1 VARIATIONS ON A THEME

One of the explicit goals of the Parrot project is to generate Java 
bytecode and .NET code, as well as to run on small devices such as the Palm. 
The modular nature of the Parrot system makes this reasonably straightforward.

=over 4

=item Parrot for small platforms

For small platforms, any parser, compiler, and optimizer modules are
replaced with a small bytecode loader module which reads in Parrot
bytecode and passes it to the interpreter for execution. Note that 
the lack of a parser will limit the available functionality in some 
languages: for instance, in Perl, string eval, do, use, and require 
will not be available (although loading of precompiled modules via do, 
use, or require may be supported).

=item Bytecode compilation

One straightforward use of the Parrot system is to precompile a 
program into bytecode and save it for later use. Essentially, we
would compile a program as normal, but then simply freeze the 
bytecode to disk for later loading.

=item Perl in, Java (or whatever) out

The previous section implicitly assumes that we will be emitting 
Parrot bytecode. However, there are other possibilities: we could
translate the bytecode to Java bytecode or .NET code, or even to a
native executable. In principle, Parrot could also act as a front end to 
other modular compilers such as gcc or HP's GEM compiler system.

=item Standalone pieces

Each piece of Parrot can, with enough support hidden away (in the form
of an interpreter for the parsing module, for example), stand on its
own. This means it's feasible to make the parser, bytecode compiler,
optimizer and interpreter separate executables.

This allows us to develop pieces independently--the first version of
the Perl 6 parser, for example, can be written mainly in perl 5 using an
embedded interpreter. It also means we can have a standalone optimizer
which can spend a lot of time groveling over bytecode, far more than
you might want to devote to optimizing one-liners or code that'll run
only once or twice.

=back

=head1 VERSION

=head2 CURRENT

    Maintainer: Dan Sugalski
    Class: Meta
    PDD Number: 1
    Version: 1
    Status: Developing
    Last Modified: 12 August 2003
    PDD Format: 1
    Language: English

=head2 HISTORY

=over

=item 1.1

12 Aug 2003

=item 1.0

02 Jan 2001

=back

=head1 CHANGES

=over

=item 1.1

Changed perl to Parrot where appropriate. Rewrote some sections to 
reflect the language agnostic nature of the project.

=item 1.0

None. First version

=back
