=head1 NAME

jako - No frills programming for Parrot

=head1 SYNOPSIS

Jako is a simple programming language that targets the Parrot
virtual machine.

=head1 DESCRIPTION

Jako should be familiar to those who have seen C and Perl.

=head2 Lexical Structure

Jako's lexical structure is similar to its relative: Perl. Whitespace between
tokens is not significant, and comments are introduced with an octothorp
('#') and continue to the end of the line.

=over 4

=item * Labels

An identifier followed by a colon at the beginning of a line is a label.
Labels can be the targets of B<goto> statements, and can also provide a
way to refer to specific loops when using the loop control statements
(see below).

=item * Literals

=over 4

=item * Integers

=over 4

=item * Binary

"0b" followed by any number of binary digits ("0" or "1").

=item * Octal

"0" followed by any number of octal digits ("0" to "7").

=item * Decimal

Starting with a non-zero decimal digit, with any number of decimal digits
following. Optional prefixed "-" for negative integers.

=item * Hexadecimal

"0x" followed by any number of hexadecimal digits ("0" to "9", "a", "b", "c", "d", "e", or "f").

=back

=item * Numbers

One or more decimal digits, a decimal point, and one ore more decimal digits.
Optional prefixed "-" for negative numbers.

=item * Strings

A double-quote character, followed by the contents of the string, and another double-quote
character. Inside the string literal, double quotes are to be escaped with "\" (back slash,
a.k.a. "whack"). To include a back slash in the string, precede it with another back slash.

=back

=item * Identifiers

Start with a letter, followed by any combination of letters, decimal digits and underscores.

=item * Types

The built-in types are recognized as keywords: B<int>, B<num>, B<pmc>, B<str>.

=back

=head2 Syntax

=over 4

=item * Blocks

A block is a sequence of statements and declarations between a matching pair
of open and close braces ("B<{>" and "B<}>"). Each block represents a scope for
lexical symbols (variables and constants). There is an implicit block which
represents the entire compilation unit (usually a file). Subroutines may
only appear at this level.

=item * Constant Declarations

B<const> introduces a constant declaration. What follows must be a type, a
list of identifiers, "B<=>", and a value of an appropriate type.

        const int a, b, c = 2;
        const int pi_in   = 3;             # Indiana
        const num pi      = 3.141592;      # Everywhere else
        const str d       = "Como estas?";

=item * Variable Declarations

B<var> introduces a variable declaration. What follows must be a type and
a list of identifiers, optionally followed by "B<=>" and an expression.

        var int a, b, c;
        var num d, e, f = 42.0;
        var str g = "Howdy";

=item * Subroutines

B<sub> introduces a subroutine declaration (and possibly definition). What
follows is an optional type, and identifier (the name of the subroutine), an
optional set of properties, and a list of formal arguments in parenthesis.
The formal arguments are written as a comma-separated list of type-name pairs.
Finally, there must be a block which contains the implementation of the
subroutine.

Simple cases of subroutine definitions are:

        sub foo() { ... }
        sub int bar(int x, int y) { ... }

NOTE: The below requires C<jakoc> to be able to determine the best match among
a number of alternatives with the same name, but different signatures.

The B<op> property can have a string value that gives the op name, if it is
different from the sub name. There is also an B<oplib> property that gives
the oplib, if the op is not core.

TODO: Presumably, there should be an implicit "use 'core'", that would pull in
the definitions of the core ops as subs (if any).

One wonders if this mechanism could be expanded to account for the
arithmetic operators, etc.

Also, if the Parrot .ops files could be processed to automatically
produce the include files for the various categories of ops and subs.

  sub num coversine { oplib = "obscure", op = "covers" } (num);

  sub int BlitSurface { fnlib = "libsdl", fn = "SDL_BlitSurface" } (
    pmc { nat = "p" } src,
    pmc { nat = "p" } srcrect,
    pmc { nat = "p" } dst,
    pmc { nat = "p" } dstrect
  );

NOTE: The B<oplib> sub property is not implemented yet.

NOTE: Type properties are not implemented yet.

=item * Assignments

Following tradition, basic assignments are written as

         left = right;

Conversions between B<int> and B<num> values are implicit.

=item * Conditionals

There are two kinds of conditional block: B<if> and B<unless>, with the latter
being short for the more familiar B<if>, but with the condition inverted. In
both cases, what follows the keyword is a parenthesized boolean expression and
a block.

        if     (happy)   { smile(); }
        unless (raining) { play();  }

Even though each is redundant given the presence of the other, both are
retained in the language for the same reason as in Perl: allowing more natural
expression.

Further, there can be a subsequent block, introduced with B<else>:

        if     (paid) { work();     } else { complain(); }
        unless (paid) { complain(); } else { work();     }

=item * Loops

There are two kinds of loop: B<while> and B<until>, with the same reversal of
sense as exists between B<if> and B<unless>.

        while (1) {
          while (overdue != 0.0) { work(); invoice();     }
          until (overdue == 0.0) { send_dunning_letter(); }
        }

You can control loops with the B<next>, B<last> and B<redo> loop control
statements. B<next> jumps immediately to the next iteration of the loop,
without executing the intervening statements, B<last> jumps immediately
out of the loop, again without executing the intervening statements. And,
B<redo> jumps back to the beginning of the current iteration.

Loops can be followed by an optional B<continue> block, which provides
code to be executed between iterations.

=back

=head2 Semantics

=over 4

=item * String interpolation

An unescaped dollar sign ("$") in a string causes Jako to interpolate variables
into a final string before the string is used in an expression. In case the
text to follow the interpolated value starts with identifier characters that
would interfere with the correct determination of the variable to interpolate,
use the form "${...}".

=back

=head1 HISTORY

Jako was the first language to target the Parrot virtual machine. It was also
the first language to support subroutines (although in a rudimentary, hackish
way) for Parrot. It has since grown up a bit and now uses PIR to get real
subroutine support.

=head1 AUTHOR

You can blame gregor <gregor@focusresearch.com> for the Jako language and its
compiler.

=head1 COPYRIGHT

Copyright (C) 2001-2007, The Perl Foundation.

=head1 LICENSE

The Jako compiler is free software. It is subject to the same license as the
Parrot interpreter.