# Copyright (C) 2005-2008, The Perl Foundation.
# $Id: /mirror/trunk/languages/lua/doc/status.pod 34221 2008-12-21T10:34:41.018374Z fperrad  $

=head1 TITLE

Status of Lua on Parrot

=head1 Introduction

Lua is an extension programming language designed to support general
procedural programming with data description facilities. It also offers
good support for object-oriented programming, functional programming, and
data-driven programming. Lua is intended to be used as a powerful,
light-weight scripting language for any program that needs one.

The homepage is L<http://www.lua.org/>.

The reference manual is available on L<http://www.lua.org/manual/>.

This implementation is aligned with Lua 5.1 specifications.

=head1 PIR Compiler/Interpreter

C<lua.pbc> is the interpreter/compiler, see F<languages/lua/src/lua51.pir>
& F<languages/lua/lua.pir>.

C<lua.pbc> is written in PIR and generates PIR from Lua sources.
C<lua.pbc> uses the following Parrot compiler toolchain components :

=over 4

=item PGE

The Lua grammar is described in F<languages/lua/src/lua51.pg>.

The PIR code is emitted by C<CodeString>.

C<PGE> is also used by the Lua pattern compiler in
F<languages/lua/src/lib/luaregex.pir>.

=item TGE

Two stages of tree transformation are used
F<languages/lua/src/PASTGrammar.tg> & F<languages/lua/src/POSTGrammar.tg>.

=item PAST

The AST is represented with F<compilers/pct/src/PAST/Node.pir>.

=item POST

The OST is represented with F<compilers/pct/src/POST/Node.pir>.

=item HLLCompiler

This Lua compiler extends the base class
F<compilers/pct/src/PCT/HLLCompiler.pir>.

=back

The lexicography part could be checked with F<languages/lua/test_lex.pir>.

The code generation could be examined with F<languages/lua/luap.pir>.

=head2 KNOWN PROBLEMS

in F<languages/lua/t/closure.t> :

    a = {}
    local x = 20
    for i=1,10 do
        local y = 0
        a[i] = function () y=y+1; return x+y end
    end

    print(a[1]())
    print(a[1]())
    print(a[2]())

    --[[
    The loop creates ten closures (that is, ten instances of the anonymous
    function). Each of these closures uses a different y variable, while all
    of them share the same x.
    ]]

C<y> variable is not different.

=head1 Perl Compiler (deprecated)

This compiler is written in Perl5 :

=over 4

=item * lexer

Implemented with Perl5 regex

F<languages/lua/src/yapp/Lua/lexer.pm>

=item * parser

Implemented with Parse::Yapp.

It supports the full grammar described in F<languages/lua/doc/lua51.bnf>.

Only one C<error> rule, so the syntax error diagnostic is minimalist.

F<languages/lua/src/yapp/Lua/lua51.yp>

=item * code generation

F<languages/lua/src/yapp/Lua/build.pm>

=item * symbole table

F<languages/lua/src/yapp/Lua/symbtab.pm>

=item * opcode representation

F<languages/lua/src/yapp/Lua/opcode.pm>

=item * opcode emission

F<languages/lua/src/yapp/Lua/pir.pm>

=back

=head1 Lua Types

There are eight basic types in Lua, each of them is implemented by a PMC.

=over 4

=item * nil F<languages/lua/src/pmc/luanil.pmc>

=item * boolean F<languages/lua/src/pmc/luaboolean.pmc>

=item * number F<languages/lua/src/pmc/luanumber.pmc>

=item * string F<languages/lua/src/pmc/luastring.pmc>

=item * function F<languages/lua/src/pmc/luafunction.pmc>

=item * userdata F<languages/lua/src/pmc/luauserdata.pmc>

This type allows OO extension.

Currently, C<file> in I/O library is an C<userdata>.

=item * thread F<languages/lua/src/pmc/luathread.pmc>

This type is used to implement coroutines.
The current implementation use the library
F<runtime/parrot/library/Parrot/Coroutine.pir>.

=item * table F<languages/lua/src/pmc/luatable.pmc>

This type is I<the> data structure of the language.

=back

F<languages/lua/src/pmc/luaany.pmc> provides an abstract base class for all
Lua types.

F<languages/lua/src/pmc/lua.pmc> is a singleton PMC what holds some static methods.

=head2 TODO

Arguments passing in C<invoke> method of C<table>. Where are there ?

=head2 IMPROVEMENT

C<table> with a mixed array and hash (like Lua 5).

=head1 Lua Standard Libraries

Lua 5.1 defines the following standard libraries:

=over 4

=item * basic library F<languages/lua/src/lib/luabasic.pir>

=item * coroutine manipulation F<languages/lua/src/lib/luacoroutine.pir>

=item * package library F<languages/lua/src/lib/luapackage.pir>

=item * string manipulation F<languages/lua/src/lib/luastring.pir>

=item * table manipulation F<languages/lua/src/lib/luatable.pir>

=item * mathematical functions F<languages/lua/src/lib/luamath.pir>

=item * input and output F<languages/lua/src/lib/luaio.pir>, F<languages/lua/src/lib/luafile.pir>

=item * operating system facilities F<languages/lua/src/lib/luaos.pir>

=item * debug facilities F<languages/lua/src/lib/luadebug.pir>

=back

F<languages/lua/src/lib/luaaux.pir> is the equivalent of Auxiliary Library.

F<languages/lua/src/lib/luaregex.pir> implements a regex compiler using PGE.

=head2 TODO

Complete some of these libraries.

=head1 Extension Libraries

These libraries are loaded dynamically with the Lua function C<require>.

=over 4

=item * alarm library F<languages/lua/src/lib/alarm.pir>

=item * base64 library F<languages/lua/src/lib/base64.pir>

=item * big number library F<languages/lua/src/lib/bc.pir>

=item * bitwise operation library F<languages/lua/src/lib/bit.pir>

=item * bitwise operation library F<languages/lua/src/lib/bitlib.pir>

=item * complex library F<languages/lua/src/lib/complex.pir>

=item * Lua File System library F<languages/lua/src/lib/lfs.pir>

=item * LPeg library F<languages/lua/src/lib/lpeg.pir>

=item * markdown library F<languages/lua/src/lib/markdown.pir>

=item * mathx library F<languages/lua/src/lib/mathx.pir>

=item * md5 & sha1 library F<languages/lua/src/lib/md5.pir>

=item * random library F<languages/lua/src/lib/random.pir>

=item * struct library F<languages/lua/src/lib/struct.pir>

=item * uuid library F<languages/lua/src/lib/uuid.pir>

=back

=head1 Next Milestones

Debugging & stabilisation.

=head2 FEEDBACK

I try to summarize all my feedback, here :
L<http://www.nntp.perl.org/group/perl.perl6.internals/2007/10/msg40493.html>.

=head1 Related Projects

Klaas-Jan Stol works on 2 projects :

=over 4

=item * Monkey, an implementation of Lua on Parrot

A Lua to PIR compiler implemented in C

=item * lua2pir

A Lua bytecode to PIR compiler

=back

See L<http://kjs.home.fmf.nl/>.

=head1 AUTHOR

Francois Perrad.

=cut

# Local Variables:
#   fill-column:78
# End:
# vim: expandtab shiftwidth=4:
