The aim will be to implement it all in NQP if possible.
The source code must always be the absolute source of all information. Everything else should act as a cache. That means *.pir files and databases of metadata may be automatically or manually derived from the *.pm files, but they may not add information (from the command line, for example).
If there is to be cached metadata in future, it should be stored in files as close to the corresponding source files as possible. If modules are precompiled to *.pir files, those files will be stored in the same directories as their corresponding *.pm source files, with identical names apart from the extension.
Classes may contain other classes, which provides sufficient hierarchy.
Rakudo will implement module, in order to contain sub definitions that do not belong to any class.
There should be only one :ver and :auth name part per source code file, in order to keep the implementation simple. In order to keep users sane, multiple :ver or :auth name parts in the same source file will make the using program die with a NYI error.
The following is ok (loaded by "use Foo::Bar:ver<1.2.3>:auth<baz>"):
# in Foo/Bar.pm
class Foo::Bar:ver<1.2.3>:auth<baz> { # or module, grammar etc
...
class Baz {
...
}
}The following (nested class declarations) will not be implemented in Rakudo *:
# in Foo.pm
module Foo { # or class Foo, grammar Foo etc
class Bar:ver<1.2.3>:auth<baz> {
...
}
}If you want to use Unicode in your module names, your file system must support Unicode as well. If you want users without Unicode file names to use your modules, don't use Unicode in your module names.
Rakudo effectively gives the following output to -e'.say for @*INC'
~/.perl6/lib
parrot_install/lib/2.1.0-devel/languages/perl6/lib
.The . entry may be removed from the default @*INC because it creates a security risk, but it is needed in the medium term for the build process to conveniently find Test.pm.
Unlike the Perl 5 case, all matching candidate files in all applicable directories will be considered, so in most cases the order of directories in @*INC is not significant. If copies of the same module name with the same :auth and :ver name parts exist in the same or even different directories, Rakudo may arbitrarily use any one of those files and ignore the others. The module installer utility should try to prevent such duplication arising, but should tolerate it if it already exists.
If multiple instances of a module exist, they may be distributed among all the @*INC directories. Folders correspond to packages (aka namespaces) and they are not allowed to have :ver and :auth name parts.
In every directory, file name collisions are avoided by optionally inserting a unique .infix in the name before the .pm extension. The following would all match a use Foo; command:
Foo.pm
Foo.1.pm
Foo.12345.pmCurrently only digits are being considered, but anything within reason between the two dots should be allowed, and is under the control of the module installer. The infix characters are meaningless. Only the code inside the file specifies :ver and :auth.
In commands such as use, the :auth and :ver name parts are independently optional. Rakudo * will do only exact matches on :auth and :ver name parts, because the alternative gives headaches...
Consider the example "use Foo::Bar:ver<1.2.3>:auth<baz>"
Rakudo * will look for files matching Foo/Bar.pm and Foo/Bar.*.pm from every starting point listed in @*INC. Rakudo will then open each file in turn and partially (how?) parse the content to extract the first :ver and :auth values, building a list of the results. Caching will probably be added soon after the initial implementation works, in order to reduce the obvious overheads.
If the use specified an :auth or a :ver, the values must match, and non-matching files are disqualified.
Rakudo will consider files in the user's local directories (. and ~/.perl6/lib) that omit :auth and :ver values. Modules in the parrot_install tree should all have :auth and :ver.
If the :ver is not specified, Rakudo must select the file containing the highest :ver value. Files without :ver are considered as having the lowest possible :ver value. Multiple files without :ver, or multiple files with the same :ver, will result in an arbitrary selection.
There is a Perl 5 stub implementation of the module finding algorithm in the rmp repository http://github.com/moritz/rmp in the file loader-fulllist.pl. Commit bits to that repo are handed out freely; just ask hugme on #perl6 :-).