Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 134 lines (98 sloc) 5.188 kB
e2c77d4 @mberends [docs/S11-Modules-proposal.pod] the outcome of the S11 Modules discus…
mberends authored
1 =head1 S11-Modules proposal for Rakudo * implementation
2
3 The aim will be to implement it all in NQP if possible.
4
5 =head1 Overriding Principle
6
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
11 example).
12
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.
18
19 =head1 Restrictions and limitations
20
21 =head2 No C<package> keyword
22
23 Classes may contain other classes, which provides sufficient hierarchy.
24
25 Rakudo will implement C<module>, in order to contain sub definitions
26 that do not belong to any class.
27
28 =head2 Only simplest :ver and :auth implementation
29
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.
34
35 The following is ok (loaded by "use Foo::Bar:ver<1.2.3>:auth<baz>"):
36
37 # in Foo/Bar.pm
38 class Foo::Bar:ver<1.2.3>:auth<baz> { # or module, grammar etc
39 ...
1ed54df @mberends [docs/S11-Modules-proposal.pod] remove excessive Foo::Bar, Hackathon++
mberends authored
40 class Baz {
e2c77d4 @mberends [docs/S11-Modules-proposal.pod] the outcome of the S11 Modules discus…
mberends authored
41 ...
42 }
43 }
44
45 The following (nested class declarations) will not be implemented in
46 Rakudo *:
47
48 # in Foo.pm
49 module Foo { # or class Foo, grammar Foo etc
50 class Bar:ver<1.2.3>:auth<baz> {
51 ...
52 }
53 }
54
55 =head2 No Unicode mangling in file names
56
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.
60
61 =head2 Retain @*INC to specify where searching begins
62
63 Rakudo effectively gives the following output to -e'.say for @*INC'
64
65 ~/.perl6/lib
66 parrot_install/lib/2.1.0-devel/languages/perl6/lib
67 .
68
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>.
72
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
80 exists.
81
82 =head2 Room for wriggling on file names
83
cca3cfc @moritz [docs/S11-Modules-proposal.pod] link to prototype module searching fu…
moritz authored
84 If multiple instances of a module exist, they may be distributed among
e2c77d4 @mberends [docs/S11-Modules-proposal.pod] the outcome of the S11 Modules discus…
mberends authored
85 all the @*INC directories. Folders correspond to packages (aka
86 namespaces) and they are not allowed to have :ver and :auth name parts.
87
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:
91
92 Foo.pm
93 Foo.1.pm
94 Foo.12345.pm
95
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.
100
101 =head1 Searches in C<use>, C<need> and C<require> commands
102
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...
106
107 Consider the example "use Foo::Bar:ver<1.2.3>:auth<baz>"
108
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
44f0ec0 @kyleha [docs] Misspellings caught by ispell
kyleha authored
112 and :auth values, building a list of the results. Caching will
0b83903 @Util Fixed various typos in comments and error messages.
Util authored
113 probably be added soon after the initial implementation works, in order to
e2c77d4 @mberends [docs/S11-Modules-proposal.pod] the outcome of the S11 Modules discus…
mberends authored
114 reduce the obvious overheads.
115
116 If the C<use> specified an C<:auth> or a C<:ver>, the values must match,
cd42786 @masak [docs/S11] fixed a small typo
masak authored
117 and non-matching files are disqualified.
e2c77d4 @mberends [docs/S11-Modules-proposal.pod] the outcome of the S11 Modules discus…
mberends authored
118
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.
122
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.
cca3cfc @moritz [docs/S11-Modules-proposal.pod] link to prototype module searching fu…
moritz authored
127
128 =head1 Implementation notes
129
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 :-).
Something went wrong with that request. Please try again.