=begin maintainer_notes

For now I'm basing this on the perlintro manpage.  I expect that a
somewhat different structure will emerge over time, but it seems like as
good a place to start as any.  -- Skud

=end maintainer_notes


=head1 NAME

Perl6::Doc::Intro -- a brief introduction and overview of Perl 6

=head1 DESCRIPTION

This introduction is aimed at the beginning Perl 6 programmer.  For the
moment, it is assumed that such programmers are coming from a background
of Perl 5.  However, this document tries to be simple and general enough
for anyone with some programming experience to pick up Perl 6.  Those
who want more information about the changes from Perl 5 should look
elsewhere.

=head2 What is Perl 6?

Perl 6, like its predecessors, is a multi-purpose dynamic language
combining ease of use and powerful programming features.

=head2 Running a Perl 6 program

You will need to install Pugs, which can be found at
L<http://pugscode.org/>.

Having done so, you can run your Perl 6 program from the command line as
follows:

    pugs myprogram.p6

Alternatively, you may specify the pugs interpreter to use in the first
line of your script, like this:

    #!/usr/bin/env pugs

... then run your program as:

    ./myprogram.p6

To run one-liners from the command-line, use the -e flag:

    pugs -e 'say "Hello, world!"'

You can also start up pugs without any arguments, then type Perl 6 commands at
its command line.  To exit, type C<ctrl-D> or C<:q>.

=head2 Basic syntax overview

A Perl 6 program consists of one or more statements.  These statements are simply 
written in a plain text file, one after another.  There is no need to have a
C<main()> function or anything of that kind.

Perl 6 statements end in a semi-colon:

   say "Hello, world";

Comments start with a hash symbol and run to the end of the line

   # This is a comment

Whitespace is irrelevant:

   say 
       "Hello, world"
       ;

... except inside quoted strings:

   # this would print with a linebreak in the middle
   say "Hello
   world";

Double quotes or single quotes may be used around literal strings:

   say "Hello, world";
   say 'Hello, world';

However, only double quotes "interpolate" variables and special characters such 
as newlines (C<\n>):

   my $name = 'Johnny';
   print "Hello, $name\n";     # prints: Hello, Johnny  (followed by a newline)
   print 'Hello, $name\n';     # prints: Hello, $name\n (no newline)

Numbers don't need quotes around them:

   say 42;

Most of the time, you can use parentheses for functions' arguments or omit them
according to your personal taste.  

   say("Hello, world");
   say "Hello, world";

=head2 Perl variable types

Perl has three main variable types: scalars, arrays, and hashes.
Variables are declared with C<my>.

=over 4

=item Scalars

A scalar represents a single value:

    my $animal = "camel";
    my $answer = 42;

Scalar variables start with dollar signs. Scalar values can be strings,
integers or floating point numbers, and Perl will automatically convert
between them as required.  There is no need to pre-declare your variable
types (though you can if you want -- see L<XXX>).

Scalar values can be used in various ways:

    say $animal;
    say "The animal is $animal";
    say "The square of $answer is ", $answer * $answer;

There is a "magic" scalar with the name C<$_>, and it is referred to as
the "topic".  It's used as the default argument to a number of functions
in Perl, and it's set implicitly by certain constructs (so-called
"topicalizing" constructs).

    say;          # prints contents of $_ by default

=item Arrays

Array variables start with an at sign, and they represent lists of
values:

    my @animals = ("camel", "llama", "owl");
    my @numbers = (23, 42, 69);
    my @mixed   = ("camel", 42, 1.23);

Arrays are zero-indexed.  Here's how you get at elements in an array:

    say @animals[0];              # prints "camel"
    say @animals[1];              # prints "llama"

The numeric index of the last element of an array can by found with C<@array.end>:

    say @animals[@animals.end];   # prints "owl"

However, negative indices count backwards from the end of the list, so
that could also have been written:

    say @animals[-1];             # prints "owl"

To find the number of elements in an array, use the C<elems> method:

    say @mixed.elems;       # last element, prints 1.23

To get multiple values from an array:

    @animals[0,1];                  # gives ("camel", "llama");
    @animals[0..2];                 # gives ("camel", "llama", "owl");
    @animals[1..@animals.end];      # gives all except the first element

This is called an "array slice".

You can do various useful things to lists:

    my @sorted    = @animals.sort;
    my @backwards = @numbers.reverse;

There are a couple of special arrays too, such as C<@*ARGS> (the command
line arguments to your script) and C<@_> (the arguments passed to a
subroutine, if formal parameters are not declared).  These are documented
in L<XXX>.

=item Hashes

Hash variables start with a percent sign, and represent sets of
key/value pairs:

    my %fruit_color = ("apple" => "red", "banana" => "yellow");

You can use whitespace and the C<< => >> operator to lay them out more
nicely:

    my %fruit_color = (
        apple  => "red",
        banana => "yellow",
    );

To get at hash elements:

    %fruit_color{"apple"};           # gives "red"

You can get at lists of keys and values with C<keys()> and
C<values()>.

    my @fruits = %fruit_colors.keys;    # ("apple", "banana")
    my @colors = %fruit_colors.values;  # ("red", "yellow")

Hashes have no particular internal order, though you can sort the keys
and loop through them.

Just like special scalars and arrays, there are also special hashes.
The most well known of these is C<%*ENV> which contains environment
variables.  Read all about it (and other special variables) in
L<XXX>.

=back

Scalars, arrays and hashes are documented more fully in L<perldata>.

More complex data types can be constructed using references, which allow
you to build lists and hashes within lists and hashes.

A reference is a scalar value and can refer to any other Perl data
type. So by storing a reference as the value of an array or hash
element, you can easily create lists and hashes within lists and
hashes. The following example shows a 2 level hash of hash
structure using anonymous hash references.

    my $variables = {
        scalar  =>  {
                     description => "single item",
                     sigil => '$',
                    },
        array   =>  {
                     description => "ordered list of items",
                     sigil => '@',
                    },
        hash    =>  {
                     description => "key/value pairs",
                     sigil => '%',
                    },
    };

    print "Scalars begin with a $variables{'scalar'}{'sigil'}\n";

Exhaustive information on the topic of references can be found in
L<perlreftut>, L<perllol>, L<perlref> and L<perldsc>.


=head2 Variable scoping

=head2 Conditional and looping constructs

=head2 Built-in operators and functions

=head2 Regular expressions

=head2 Writing subroutines

=head2 Object oriented Perl 6

=head2 Using third-party modules

=head1 AUTHOR

Kirrily "Skud" Robert <skud@cpan.org>

