From e2c77d430c533e3b78048f719ac234e5364886a9 Mon Sep 17 00:00:00 2001 From: mberends Date: Sun, 7 Mar 2010 15:33:58 +0000 Subject: [PATCH] [docs/S11-Modules-proposal.pod] the outcome of the S11 Modules discussion at the Copenhagen Perl 6 Hackathon --- docs/S11-Modules-proposal.pod | 126 ++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 docs/S11-Modules-proposal.pod diff --git a/docs/S11-Modules-proposal.pod b/docs/S11-Modules-proposal.pod new file mode 100644 index 00000000000..d6cbf43f697 --- /dev/null +++ b/docs/S11-Modules-proposal.pod @@ -0,0 +1,126 @@ +=head1 S11-Modules proposal for Rakudo * implementation + +The aim will be to implement it all in NQP if possible. + +=head1 Overriding Principle + +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. + +=head1 Restrictions and limitations + +=head2 No C keyword + +Classes may contain other classes, which provides sufficient hierarchy. + +Rakudo will implement C, in order to contain sub definitions +that do not belong to any class. + +=head2 Only simplest :ver and :auth implementation + +There should be only one C<:ver> and C<:auth> name part per source code +file, in order to keep the implementation simple. In order to keep +users sane, multiple C<:ver> or C<: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"): + + # in Foo/Bar.pm + class Foo::Bar:ver<1.2.3>:auth { # or module, grammar etc + ... + class Foo::Bar::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 { + ... + } + } + +=head2 No Unicode mangling in file names + +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. + +=head2 Retain @*INC to specify where searching begins + +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 F. + +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 C<:auth> and C<: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. + +=head2 Room for wriggling on file names + +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 C command: + + Foo.pm + Foo.1.pm + Foo.12345.pm + +Currently 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. + +=head1 Searches in C, C and C commands + +In commands such as C, 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" + +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. Cacheing will +probably be added soon after the initial implemention works, in order to +reduce the obvious overheads. + +If the C specified an C<:auth> or a C<: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.