1
=head1 S11-Modules proposal for Rakudo * implementation
3
The aim will be to implement it all in NQP if possible.
5
=head1 Overriding Principle
7
The source code must always be the absolute source of all information.
8
Everything else should act as a cache. That means *.pir files and
9
databases of metadata may be automatically or manually derived from the
10
*.pm files, but they may not add information (from the command line, for
13
If there is to be cached metadata in future, it should be stored in
14
files as close to the corresponding source files as possible.
15
If modules are precompiled to *.pir files, those files will be stored
16
in the same directories as their corresponding *.pm source files, with
17
identical names apart from the extension.
19
=head1 Restrictions and limitations
21
=head2 No C<package> keyword
23
Classes may contain other classes, which provides sufficient hierarchy.
25
Rakudo will implement C<module>, in order to contain sub definitions
26
that do not belong to any class.
28
=head2 Only simplest :ver and :auth implementation
30
There should be only one C<:ver> and C<:auth> name part per source code
31
file, in order to keep the implementation simple. In order to keep
32
users sane, multiple C<:ver> or C<:auth> name parts in the same source
33
file will make the using program die with a NYI error.
35
The following is ok (loaded by "use Foo::Bar:ver<1.2.3>:auth<baz>"):
38
class Foo::Bar:ver<1.2.3>:auth<baz> { # or module, grammar etc
45
The following (nested class declarations) will not be implemented in
49
module Foo { # or class Foo, grammar Foo etc
50
class Bar:ver<1.2.3>:auth<baz> {
55
=head2 No Unicode mangling in file names
57
If you want to use Unicode in your module names, your file system must
58
support Unicode as well. If you want users without Unicode file names
59
to use your modules, don't use Unicode in your module names.
61
=head2 Retain @*INC to specify where searching begins
63
Rakudo effectively gives the following output to -e'.say for @*INC'
66
parrot_install/lib/2.1.0-devel/languages/perl6/lib
69
The . entry may be removed from the default @*INC because it creates a
70
security risk, but it is needed in the medium term for the build process
71
to conveniently find F<Test.pm>.
73
Unlike the Perl 5 case, all matching candidate files in all applicable
74
directories will be considered, so in most cases the order of
75
directories in @*INC is not significant. If copies of the same module
76
name with the same C<:auth> and C<:ver> name parts exist in the same or
77
even different directories, Rakudo may arbitrarily use any one of those
78
files and ignore the others. The module installer utility should try to
79
prevent such duplication arising, but should tolerate it if it already
82
=head2 Room for wriggling on file names
84
If multiple instances of a module exist, they may be distributed among
85
all the @*INC directories. Folders correspond to packages (aka
86
namespaces) and they are not allowed to have :ver and :auth name parts.
88
In every directory, file name collisions are avoided by optionally
89
inserting a unique .infix in the name before the .pm extension. The
90
following would all match a C<use Foo;> command:
96
Currently only digits are being considered, but anything within reason
97
between the two dots should be allowed, and is under the control of the
98
module installer. The infix characters are meaningless. Only the code
99
inside the file specifies :ver and :auth.
101
=head1 Searches in C<use>, C<need> and C<require> commands
103
In commands such as C<use>, the :auth and :ver name parts are
104
independently optional. Rakudo * will do only exact matches on :auth
105
and :ver name parts, because the alternative gives headaches...
107
Consider the example "use Foo::Bar:ver<1.2.3>:auth<baz>"
109
Rakudo * will look for files matching Foo/Bar.pm and Foo/Bar.*.pm from
110
every starting point listed in @*INC. Rakudo will then open each file
111
in turn and partially (how?) parse the content to extract the first :ver
112
and :auth values, building a list of the results. Caching will
113
probably be added soon after the initial implementation works, in order to
114
reduce the obvious overheads.
116
If the C<use> specified an C<:auth> or a C<:ver>, the values must match,
117
and non-matching files are disqualified.
119
Rakudo will consider files in the user's local directories (. and
120
~/.perl6/lib) that omit :auth and :ver values. Modules in the
121
parrot_install tree should all have :auth and :ver.
123
If the :ver is not specified, Rakudo must select the file containing the
124
highest :ver value. Files without :ver are considered as having the
125
lowest possible :ver value. Multiple files without :ver, or multiple
126
files with the same :ver, will result in an arbitrary selection.
128
=head1 Implementation notes
130
There is a Perl 5 stub implementation of the module finding algorithm in the
131
rmp repository L<http://github.com/moritz/rmp> in the file
132
C<loader-fulllist.pl>. Commit bits to that repo are handed out freely; just
133
ask hugme on #perl6 :-).
added
removed
docs/S11-Modules-proposal.pod
