=begin pod

=TITLE Glossary

=SUBTITLE Glossary of Perl 6 terminology

=head1 Anonymous

A subroutine, method or submethod is called I<anonymous> if it can't be
called by name.

    # named subroutine
    sub double($x) { 2 * $x };

    # anonymous subroutine, stored in a named scalar
    my $double = sub ($x) { 2 * $x };

Note that it is still allowed to have a name

    # anonymous, but knows its own name
    my $s = anon sub triple($x) { 3 * $x }
    say $s.name;        # triple

=head1 Adverb

Generically, an adverb is a named argument to a function.  There are also
some specific syntax forms that allow adverbs to be tucked into some
convenient places:

    q:w"foo bar"   # ":w" is a Quotelike form modifier adverb
    m:g/a|b|c/     # ":g" is also
    4 +> 5 :rotate # ":rotate" is an operator adverb
    @h{3}:exists   # ":exists" is also, but is known as a subscript adverb

Adverbs are usually expressed with colon pair notation, and for this
reason colon pair notation is also known as the adverbial pair form:

    :a(4)          # Same as "a" => 4

Some other forms that use a colon in ways that have adverb-like semantics
are called adverbial forms.

=head1 Autothreading

Autothreading is what happens if you pass a junction to a sub that expects a
parameter of type C<Any> or a subtype thereof. The call is executed multiple
times, each time with a different eigenstate of the junction. The result of
these calls is assembled in a junction of the same type as the original
junction.

    sub f($x) { 2 * $x };
    if f(1|2|3) == 4 {
        say 'success';
    }

Here C<f()> is a sub with one parameter, and since it has no explicit type,
it is implicitly typed as C<Any>.  The C<Junction> argument causes the
C<f(1|2|3)> call to be internally executed as C<f(1)|f(2)|f(3)>, and the
resulting junction is C<2|4|6>. This process of separating junction
arguments into multiple calls to a function is called I<autothreading>.

=head1 Colon Pair and Colon List

A colon pair is a shorthand syntax used to create or visually present
a Pair object.  The two most common forms are:

    :a(4)          # Same as "a" => 4,   same as Pair.new(:key<a>,:value(4))
    :a<4>          # Same as "a" => "4", same as Pair.new(:key<a>,:value<4>)

This is also known as the adverbial pair form.  Note: when the part after
the colon and before the brackets is not a legal identifier, other
semantics apply, not all of which produce Pair objects.

Two other common forms are:

    :a             # Same as :a(True)
    :!a            # Same as :a(False)

A colon list just means that a list that contains only colon pairs,
does not need commas, or even spaces:

    :a(4):c:!d:c   # Same as a => 4, c => True, d => False, c => True

=head1 Constraint

Constraints are a restriction placed on acceptable types for a parameter
or subset type.  They are introduced with the word C<where>.  In the
following example, a constraint is used to make sure an error occurs if
anyone ever calls a subroutine named C<abbreviate> with a string which is
shorter than 10 characters:

    sub abbreviate (Str $thing where { .chars >= 10 }) { ... }

The C<Str> in the above example is also a constraint, but is usually
referred to as a "type constraint."

=head1 Instance

An I<instance> of a class is also called an I<object> in some other
programming languages. It has storage for attributes and is often the return
value of a call to a method called C<new>, or a literal.

Instances of most types are defined to be C<True> e.g.,
C<defined($instance)> is C<True>.

    my Str $str = "hello";  ## this is with builtin types, e.g. Str
    if defined($str) {
        say "Oh, yeah. I'm defined.";
    }
    else {
        say "No. Something off? ";
    }

    ## if you wanted objects...
    class A {
        # nothing here for now.
    }

    my $an_instance = A.new;
    say $an_instance.defined.perl;# defined($an_instance) works too.

To put things another way, a class contains the blueprints of methods and
attributes, and an instance carries it into the real world.

=head1 Invocant

The object upon which a method is called, is referred to as the I<invocant>
in Perl 6.  It is what C<self> refers to in a method.

    say 'str'.uc;   # 'str' is the invocant of method uc

=head1 Literal

A I<literal> is a piece of code that directly stands for an (often built-in)
object and also refers to the object itself.

    my $x = 2;      # the 2 is a literal
    say $x;         # $x is not a literal, but a variable

=head1 lvalue

An I<lvalue>, or a I<left value>, is anything that can appear on the left
hand side of the assignment operator C<=>.  It is anything you can assign
to.

Typical lvalues are variables, private and C<is rw> attributes, lists of
variables and lvalue subroutines.

Examples of lvalues:

    Declaration             lvalue          Comments

    my $x;                  $x
    my ($a, $b);            ($a, $b)
    has $!attribute;        $!attribute     Only inside classes
    has $.attrib is rw;     $.attrib
    sub a is rw { $x };     a()

Examples of things that are not lvalues:

    3                        # literals
    constant x = 3;          # constants
    has $.attrib;            # attributes; you can only assign to $!attrib
    sub f { }; f();          # "normal" subs are not writable
    sub f($x) { $x = 3 };    # error - parameters are read-only by default

=head1 Mainline

The C<mainline> is the program text that is not part of any kind of block.

    use v6;     # mainline
    sub f {
                # not in mainline, in sub f
    }
    f();        # in mainline again

=head1 Slurpy

A parameter of a sub or method is said to be I<slurpy> if it can consume an
arbitrary number of arguments. It is indicated by an asterisk C<*> in front
of the parameter name.

    sub sum (*@numbers) {
        return [+] @numbers;
    }

=head1 Type Object

A I<type object> is an object representing a class, role, package, grammar
or enum. It is generally accessible with the same name as the type.

    class A { };
    say A;              # A is the type object
    my $x = A.new();    # same here

    my $x = class {
        method greet() {
            say "hi";
        }
    }

    # $x now holds a type object returned from the
    # anonymous class definition

If a variable is declared to be of a certain type, but never defined, then
it will evaluate to the type object of that type.  As such, type objects can
often turn up in places where "undefined" or "null" would in other
languages:

    # perl6 -e 'my Int $a; sub f(Int $x) { $x + 1 }; f($a);'
    Invocant requires an instance, but a type object was passed

=end pod
