<commit_before>=encoding utf8

=head1 TITLE

Synopsis 11: Compilation Units

=head1 AUTHORS

    <NAME> <<EMAIL>>
    <NAME> <<EMAIL>>

=head1 VERSION

    Created: 27 Oct 2004

    Last Modified: 15 Mar 2014
    Version: 42

=head1 Overview

This synopsis discusses those portions of Apocalypse 12 that ought to have
been in Apocalypse 11.

=head1 Units

Perl 6 code is compiled per compilation unit, or I<compunit> for short.  These
are loaded with a C<use>, C<need> or C<require> statement (usually at compile
time).  Or they are created as a string in a variable and compiled with an
C<EVAL> statement (usually at runtime).  This synopsis is mostly about
compunits loaded at compile time.

In the common vernacular of a Perl 5 developer, a I<module> is the same as the
file that contains the source code of a package.  For Perl 6 developers, this
is generally not much different.  However, such a I<module> is really a
compunit that may contain 0 or more package-like statements, some of which
may be I<module>.  Confusing?  Yes it is.  On top of that, Perl 6 allows
different versions of the same compunit to be installed in a single
I<repository>.  And it allows compunits from other languages to be loaded.

In Perl, the C<use> statement is really just telling Perl to find a compunit
for the given name and load its contents.  Whether that name is the name of a
C<package>, C<module>, C<class>, C<grammar> or C<role>, a combination of these
or something else entirely in a C<slang>, is B<not> known at the moment the
compunit is searched for (and hopefully found).  Only when the contents of the
compunit are compiled, does Perl find out what's inside.

In Perl 5, the compunit's name to filename translation is generally mechanical.
C<Foo::Bar> will always refer to C<Foo/Bar.pm> in a directory: it does not need
any outside information to find out the name of the file to be loaded.

Perl 6 however, only knows about I<repositories> that contain compunits.  Each
repository is represented as an object with the L<CompUnitRepo> interface in
the C<@*INC> array.  Whenever a compunit needs to be loaded, each element in
the C<@*INC> is queried for the compunit, and any candidates are returned.
An exception occurs if there is no candidate, or more than one candidate that
matches the requirement.  Otherwise, the contents of the compunit is then
obtained and loaded.

There are 2 standard implementations of the C<CompUnitRepo> interface:
L<CompUnitRepo::Local::File> and L<CompUnitRepo::Local::Installation>.  The
first is used whenever you're specifying the C<-I> parameter when running
Perl 6.  The second is always used when searched for locally installed
compunits as files in directories.  Of course, one is free to devise any
other way of storing and searching for compunits, as long as C<API> is the
same.

See L<S22/"Distributions, Recommendations, Delivery and Installation"> for
more information about the C<CompUnitRepo> interface.

=head1 Modules

As in Perl 5, a C<module> is just a kind of package.  Unlike in Perl 5, modules
and classes are declared with separate keywords, but they're still just
packages with extra behaviors.  In the case of modules, the extra behavior is
the availability of the C<export> trait and any associated support for Perl 6
standard export semantics.

A module is declared with the C<module> keyword.  There are two basic
declaration syntaxes:

    module Foo; # rest of scope is in module Foo
    ...

    module Bar {...}    # block is in module Bar

A named module declaration can occur as part of an expression, just like
named subroutine declarations.

Since there are no barewords in Perl 6, module names must be predeclared,
or use the sigil-like C<::ModuleName> syntax.  The C<::> prefix does not
imply globalness as it does in Perl 5.  (Use C<GLOBAL::> for that.)

A bare (unscoped) C<module> declarator declares a nested C<our> module
name within the current package.  However, at the start of a compunit,
the current package is C<GLOBAL>, so the first such declaration in the
file is automatically global.

X<use>
You can use C<our module> to explicitly declare a module in the current
package.  To declare a lexically scoped module, use C<my module>.
Module names are always searched for from innermost scopes to outermost.
As with an initial C<::>, the presence of a C<::> within the name
does not imply globalness (unlike in Perl 5).

The default package for the main program is C<GLOBAL>.
(Putting C<module GLOBAL;> at the top of your program
is redundant, except insofar as it tells Perl that the code is Perl
6 code and not Perl 5 code.  But it's better to say C<use v6> for that.)

Module traits are set using C<is>:

    module Foo is bar {...}

An anonymous module may be created with either of:

    module {...}
    module :: {...}

The second form is useful if you need to apply a trait:

    module :: is bar {...}

=head1 Exportation

Exportation is now done by trait declaration on the exportable item:

    module Foo;                                # Tagset...
    sub foo is export                   {...}  #  :DEFAULT, :ALL
    sub bar is export(:DEFAULT :others) {...}  #  :DEFAULT, :ALL, :others
    sub baz is export(:MANDATORY)       {...}  #  (always exported)
    sub bop is export(:ALL)             {...}  #  :ALL
    sub qux is export(:others)          {...}  #  :ALL, :others

Constants (and enums) are also exportable items. As are variables declared
in C<our> scoping:

    our @foo is export = <foo bar>
    our %bar is export = <foo bar>
    our $baz is export = "foobar"
    constant $FOO is export = "foobar"
    enum FooBar is export (:baz(1))

Every compunit has a C<UNIT> package, which gets a lexically scoped C<EXPORT>
package automatically.  Declarations marked as C<is export> are bound into
it, with their tagsets as inner packages. For example, the C<sub bar> above
will bind as C<< UNIT::EXPORT::DEFAULT::<&bar> >>,
C<< UNIT::EXPORT::ALL::<&bar> >>, and C<< UNIT::EXPORT::others::<&bar> >>.

Tagset names consisting entirely of capitals are reserved for Perl.

Exports contained within a module will also be bound into an our-scoped
C<EXPORT> package nested in the module, again with the tagsets forming
inner packages. This is so the C<import> keyword can be used with a package
to import from it; the lexical C<IMPORT> package in C<UNIT>, on the other<commit_msg>Hint a bit at "is export" for methods<commit_after>=encoding utf8

=head1 TITLE

Synopsis 11: Compilation Units

=head1 AUTHORS

    <NAME> <<EMAIL>>
    <NAME> <<EMAIL>>

=head1 VERSION

    Created: 27 Oct 2004

    Last Modified: 15 Mar 2014
    Version: 42

=head1 Overview

This synopsis discusses those portions of Apocalypse 12 that ought to have
been in Apocalypse 11.

=head1 Units

Perl 6 code is compiled per compilation unit, or I<compunit> for short.  These
are loaded with a C<use>, C<need> or C<require> statement (usually at compile
time).  Or they are created as a string in a variable and compiled with an
C<EVAL> statement (usually at runtime).  This synopsis is mostly about
compunits loaded at compile time.

In the common vernacular of a Perl 5 developer, a I<module> is the same as the
file that contains the source code of a package.  For Perl 6 developers, this
is generally not much different.  However, such a I<module> is really a
compunit that may contain 0 or more package-like statements, some of which
may be I<module>.  Confusing?  Yes it is.  On top of that, Perl 6 allows
different versions of the same compunit to be installed in a single
I<repository>.  And it allows compunits from other languages to be loaded.

In Perl, the C<use> statement is really just telling Perl to find a compunit
for the given name and load its contents.  Whether that name is the name of a
C<package>, C<module>, C<class>, C<grammar> or C<role>, a combination of these
or something else entirely in a C<slang>, is B<not> known at the moment the
compunit is searched for (and hopefully found).  Only when the contents of the
compunit are compiled, does Perl find out what's inside.

In Perl 5, the compunit's name to filename translation is generally mechanical.
C<Foo::Bar> will always refer to C<Foo/Bar.pm> in a directory: it does not need
any outside information to find out the name of the file to be loaded.

Perl 6 however, only knows about I<repositories> that contain compunits.  Each
repository is represented as an object with the L<CompUnitRepo> interface in
the C<@*INC> array.  Whenever a compunit needs to be loaded, each element in
the C<@*INC> is queried for the compunit, and any candidates are returned.
An exception occurs if there is no candidate, or more than one candidate that
matches the requirement.  Otherwise, the contents of the compunit is then
obtained and loaded.

There are 2 standard implementations of the C<CompUnitRepo> interface:
L<CompUnitRepo::Local::File> and L<CompUnitRepo::Local::Installation>.  The
first is used whenever you're specifying the C<-I> parameter when running
Perl 6.  The second is always used when searched for locally installed
compunits as files in directories.  Of course, one is free to devise any
other way of storing and searching for compunits, as long as C<API> is the
same.

See L<S22/"Distributions, Recommendations, Delivery and Installation"> for
more information about the C<CompUnitRepo> interface.

=head1 Modules

As in Perl 5, a C<module> is just a kind of package.  Unlike in Perl 5, modules
and classes are declared with separate keywords, but they're still just
packages with extra behaviors.  In the case of modules, the extra behavior is
the availability of the C<export> trait and any associated support for Perl 6
standard export semantics.

A module is declared with the C<module> keyword.  There are two basic
declaration syntaxes:

    module Foo; # rest of scope is in module Foo
    ...

    module Bar {...}    # block is in module Bar

A named module declaration can occur as part of an expression, just like
named subroutine declarations.

Since there are no barewords in Perl 6, module names must be predeclared,
or use the sigil-like C<::ModuleName> syntax.  The C<::> prefix does not
imply globalness as it does in Perl 5.  (Use C<GLOBAL::> for that.)

A bare (unscoped) C<module> declarator declares a nested C<our> module
name within the current package.  However, at the start of a compunit,
the current package is C<GLOBAL>, so the first such declaration in the
file is automatically global.

X<use>
You can use C<our module> to explicitly declare a module in the current
package.  To declare a lexically scoped module, use C<my module>.
Module names are always searched for from innermost scopes to outermost.
As with an initial C<::>, the presence of a C<::> within the name
does not imply globalness (unlike in Perl 5).

The default package for the main program is C<GLOBAL>.
(Putting C<module GLOBAL;> at the top of your program
is redundant, except insofar as it tells Perl that the code is Perl
6 code and not Perl 5 code.  But it's better to say C<use v6> for that.)

Module traits are set using C<is>:

    module Foo is bar {...}

An anonymous module may be created with either of:

    module {...}
    module :: {...}

The second form is useful if you need to apply a trait:

    module :: is bar {...}

=head1 Exportation

Exportation is now done by trait declaration on the exportable item:

    module Foo;                                # Tagset...
    sub foo is export                   {...}  #  :DEFAULT, :ALL
    sub bar is export(:DEFAULT :others) {...}  #  :DEFAULT, :ALL, :others
    sub baz is export(:MANDATORY)       {...}  #  (always exported)
    sub bop is export(:ALL)             {...}  #  :ALL
    sub qux is export(:others)          {...}  #  :ALL, :others

Methods also take the "is export" trait: the method will then be exported
as a I<multi sub> that takes the object as the first parameter:

    method close (IO::Handle:D) is export { ... }

Constants (and enums) are also exportable items. As are variables declared
in C<our> scoping:

    our @foo is export = <foo bar>
    our %bar is export = <foo bar>
    our $baz is export = "foobar"
    constant $FOO is export = "foobar"
    enum FooBar is export (:baz(1))

Every compunit has a C<UNIT> package, which gets a lexically scoped C<EXPORT>
package automatically.  Declarations marked as C<is export> are bound into
it, with their tagsets as inner packages. For example, the C<sub bar> above
will bind as C<< UNIT::EXPORT::DEFAULT::<&bar> >>,
C<< UNIT::EXPORT::ALL::<&bar> >>, and C<< UNIT::EXPORT::others::<&bar> >>.

Tagset names consisting entirely of capitals are reserved for Perl.

Exports contained within a module will also be bound into an our-scoped
C<EXPORT> package nested in the module, again with the tagsets forming
inner packages. This is so the C<import> keyword can be used with a package
to import from it; the lexical C<IMPORT> package in C<UNIT>, on the other
{'fraction_non_alphanumeric': 0.07175925925925926, 'fraction_numerical': 0.007561728395061728, 'mean_word_length': 3.7545854732208364, 'pattern_counts': {'":': 0, '<': 152, '<?xml version=': 0, '>': 152, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '754630', 'n_tokens_mistral': 3823, 'n_tokens_neox': 3600, 'n_words': 1978}