# $Id: /mirror/trunk/languages/pipp/docs/internals.pod 35831 2009-01-20T13:51:49.671204Z bernhard  $

=head1 TITLE

internals - Design and Implementation of Pipp

=head1 Source code

See L<pipp.pod> on where to get the code.

=head1 Issue tracking

Not decided yet. Will be documented in L<pipp.pod>.
See also F<../ROADMAP>.

=head1 Testing

See L<testing.pod>.

=head1 Parsing

Parsing is done with Parrot Compiler Toolkit, PCT.

=head1 Bytecode generation

The parse tree is transformed to a Parrot Abstrace Syntax Tree.
PIR und Bytecode is then generated from the PAST.

=head1 Variables

List of scopes and types of variables.

=over 4

=item globals in top file

Lexical. Might need extra treatment.

=item globals in included files

Lexical in scope of the included file.

=item Class constants

Class constants are stored a package variables in the namespace $?NS ~ '\\' ~ $?CLASS ~ '::'.
The trailing '::' guarantees that there is no conflict with namespace constants.

TODO: make them readonly

=item Static class members

Like class constants, but writable.

=item Class members

=item function and method scope

Lexical is scope of the function or method.

=item $this

Bound to register C<self>.

=item constants

Currently constants are stored in the hash ['pipp'; 'php_constants'].
The functions C<define> and C<defined> access this package scoped hash.
This approach works good enough for constants in the global namespace.
For namespaced constants the above approach could be extended to
consider the namespace part of the constant, the current namespace and
the active namespace aliases.

Another approach is to treat constants as namespaced variables and
work with standard PAST techniques.
Experiments using that approach are underway.

=back

=head1 Functions and closures

TODO: type hints in function declarations

=head2 Builtin functions

=head2 Closures

There is a major bug in the implementation.
TODO: see C<t/php/closures.t>

=head2 Internal functions

=head1 Object orientation

=head1 Namespaces

A namespace is introduced with the keyword B<namespace>. 
The namespaced code can be enclosed in brackets.
The namespace declaration needs to be the first statement in the file.
With brackets, there can be multiple namespaces per file. Nesting is not possible.
Namespaces don't carry over to included files.
B<define()> doesn't define in the current namespace.
The backslash character serves as the namespace separator.
Short names can be defined with B<use>.
Only classes, functions and constants are namespaced.
The current namespace can be queried with B<__NAMESPACE__>.
Namespaces are case insensitive.
No global code can precede the first B<namespace> directive.

=head2 Implementation in Pipp

In order to ease implementation and testing, there are
some divergences in Pipp. 

=over 4

=item Only the bracketed syntax is supported.

=item Code outside the scope of namespaces directives is allowed.

=item 'const' outside a declared namespace is allowed.

=back

=head2 SEE ALSO

=over 4

=item L<http://docs.php.net/manual/en/language.namespaces.php>

=item L<http://docs.php.net/manual/en/language.namespaces.faq.php>

=item L<http://wiki.php.net/rfc/namespaces>

=item L<http://wiki.php.net/rfc/namespaceseparator>

=item L<http://wiki.php.net/rfc/backslashnamespaces>

=item L<http://wiki.php.net/rfc/namespacecurlies>

=item L<http://wiki.php.net/rfc/namespaceref>

=item L<http://inside.webfactory.de/en/blog/php-namespaces-explained.html>

=item L<http://marc.info/?l=php-internals&m=121527668606247>

=item L<http://bugs.php.net/bug.php?id=46304>

=item L<http://loveandtheft.org/2008/10/26/set-sail-for-fail-php-namespaces/>

=back

=head1 Including and requiring

C<require_once()> is supported, but might have issues with variables. 

=head1 Extensions

=head2 Implementation in Pipp

Currently, Pipp has no support at all for extensions.

=head2 SEE ALSO

  TODO: Embedding and Extending PHP, by Sahrah ...
  L<http://www.php.net/manual/en/internals2.php>

=head1 Interaction with the Parrot world

Using Modules from other HLLs. Inlining PIR and other languages.

=head1 Compatability

See L<pipp.pod> for a list of divergences.

=head1 Related projects.

See the Wiki. Roadsend, Zend, PHC.

=head1 AUTHOR

Bernhard Schmalhofer - <Bernhard.Schmalhofer@gmx.de>

=cut
