Modules
Exporting and Selective Importing
is export
packages(包), subroutines(子例程), variables(變量), constants(常量) 和 enums(枚舉) , 通過(guò)在它們的名字后面添加 is export 特性來(lái)導(dǎo)出系奉。
unit module MyModule;
our $var is export = 3;
sub foo is export { ... };
constant $FOO is export = "foobar";
enum FooBar is export <one two three>;
# Packages like classes can be exported too
class MyClass is export {};
# If a subpackage is in the namespace of the current package
# it doesn't need to be explicitly exported
class MyModule::MyClass {};
就像所有的 traits 一樣, 如果應(yīng)用到子例程(routine)上, "is export" 應(yīng)該出現(xiàn)在參數(shù)列表的后面:
sub foo (Str $string) is export {...}
你可以給 is export 傳遞命名參數(shù)以組織要導(dǎo)出的符號(hào), 然后導(dǎo)入程序? (importer) 可以剔除和選擇導(dǎo)入哪一個(gè)。有 3 個(gè)預(yù)先定義好的標(biāo)簽： ALL, DEFAULT, MANDATORY（強(qiáng)制的）撒遣。
# lib/MyModule.pm
unit module MyModule;
sub bag is export { ... }
sub pants is export(:MANDATORY) { ... }
sub sunglasses is export(:day) { ... }
sub torch is export(:night) { ... }
sub underpants is export(:ALL) { ... }
# main.pl
use lib 'lib';
use MyModule; #bag, pants
use MyModule :DEFAULT; #the same
use MyModule :day; #pants, sunglasses
use MyModule :night; #pants, torch
use MyModule :ALL; #bag, pants, sunglasses, torch, underpants
UNIT::EXPORT::*
表象之下, 其實(shí) is export 是把符號(hào)添加到 EXPORT 命名空間中的 UNIT 作用域包中拯钻。例如, is export(:FOO) 會(huì)把目標(biāo)添加到 UNIT::EXPORT::FOO 包中部凑。這正是 Perl 6 決定導(dǎo)入什么所做的参袱。
unit module MyModule;
sub foo is export { ... }
sub bar is export(:other) { ... }
等價(jià)于:
unit module MyModule;
my package EXPORT::DEFAULT {
our sub foo { ... }
}
my package EXPORT::other {
our sub bar { ... }
}
多數(shù)時(shí)候, is export 足夠用了, 但是當(dāng)你想動(dòng)態(tài)生成要導(dǎo)出的符號(hào)時(shí), EXPORT 包就很有用了。例如：
# lib/MyModule.pm
unit module MuModule;
my package EXPORT::DEFAULT {
for <zero one two three four>.kv -> $number, $name {
for <sqrt log> -> $func {
OUR::{'&' ~ $func ~ '-of-' ~ $name } := sub { $number."$func()" };
}
}
}
# main.pl
use MyModule;
say sqrt-of-four; #-> 2
say log-of-zero; #-> -Inf
EXPORT
你可以用一個(gè) EXPORT 子例程導(dǎo)出任意符號(hào)盯漂。 EXPORT 必須返回一個(gè) Map, 在 map 里面鍵是符號(hào)名, 鍵值是想要的值集乔。符號(hào)名應(yīng)該包含(如果有的話(huà))關(guān)聯(lián)類(lèi)型去件。
class MyModule::Class { ... }
sub EXPORT {
{
'$var' => 'one',
'@array' => <one two three>,
'%hash' => { one => 'two', three => 'four'},
'&doit' => sub { ... },
'ShortName' => MyModule::class
}
}
# main.pl
use lib 'lib';
use MyModule;
say $var;
say @array;
say %hash;
doit();
say ShortName.new; #-> MyModule::Class.new
注意, EXPORT 不能聲明在包內(nèi), 因?yàn)槟壳暗?rakudo(2015.09) 好像把 EXPORT 當(dāng)作 compunit 的一部分而非包的一部分。
雖然 UNIT::EXPORT 包處理傳遞給 use 的命名參數(shù), 而 EXPORT sub 處理位置參數(shù)扰路。如果你把位置參數(shù)傳遞給 use, 那么這些參數(shù)會(huì)被傳遞給 EXPORT. 如果傳遞了位置參數(shù), 那么 module 就不再需要導(dǎo)出默認(rèn)符號(hào)了尤溜。你仍然可以伴隨著你的位置參數(shù), 通過(guò)顯式地給 use 傳遞 :DEFAULT 參數(shù)來(lái)導(dǎo)入它們。
# lib/MyModule
class MyModule::Class {}
sub EXPORT($short_name?) {
{
do $short_name => MyModule::Class if $short_name
}
}
sub always is export(:MANDATORY) { say "works" }
#import with :ALL or :DEFAULT to get
sub shy is export { say "you found me!" }
# main.pl
use lib 'lib';
use MyModule 'foo';
say foo.new(); #MyModule::Class.new
always(); #OK - is imported
shy(); #FAIL - won't be imported
發(fā)布模塊
如果你已經(jīng)寫(xiě)了一個(gè) Perl 6模塊, 你想把它分享到社區(qū), 我們會(huì)很高興地把它放到 Perl 6 模塊文件夾清單中汗唱。Perl 6 modules directory
現(xiàn)在, 你需要使用 git 對(duì)你的模塊進(jìn)行版本控制宫莱。
這需要你有一個(gè) Github 帳號(hào), 以使你的模塊能被從它的 Github 倉(cāng)庫(kù)中分享出去。
要分享你的模塊, 按照下面說(shuō)的做：
創(chuàng)建一個(gè)以你的模塊命名的工程文件夾哩罪。 例如, 如果你的模塊是
Vortex::TotalPerspective, 那么就創(chuàng)建一個(gè)叫做Vortex::TotalPerspective的工程文件夾授霸。這個(gè)工程目錄的名字也會(huì)被用作 Github 倉(cāng)庫(kù)的名字。-
讓你的工程目錄看起來(lái)像這樣：
Vortex-TotalPerspective/ |-- lib | `-- Vortex | `-- TotalPerspective.pm |-- LICENSE |-- META.info |-- README.md `-- t `-- basic.t如果你的工程包含能幫助主模塊完成工作的其它模塊, 它們應(yīng)該被放到你的 lib 目錄中像這樣組織：
lib `-- Vortex |-- TotalPerspective.pm `-- TotalPerspective |-- FairyCake.pm `-- Gargravarr.pmREADME.md文件是一個(gè) markdown 格式的文件, 它稍后會(huì)被 Github 自動(dòng)渲染成 HTML關(guān)于 LICENSE 文件, 如果你沒(méi)有其它選擇, 就是用和 Rakudo Perl 6 一樣的 LICENSE 把际插。僅僅把它的原始 license 復(fù)制/粘貼進(jìn)你自己的 LICENSE 文件中碘耳。
如果你還沒(méi)有任何測(cè)試, 現(xiàn)在你可以忽略
t目錄 和basic.t文件。關(guān)于如何寫(xiě)測(cè)試, 你可以看看其它模塊是怎么使用Test的框弛。它和 Perl'5 的Test::More很類(lèi)似藏畅。如果要文檔化你的模塊, 在你的模塊中使用 Perl 6 Pod 標(biāo)記。歡迎給模塊寫(xiě)文檔, 并且為了瀏覽的方便, 一旦 Perl 6 module directory(或其它網(wǎng)站) 開(kāi)始把 Pod 文檔渲染成 HTML, 寫(xiě)文檔尤為重要功咒。
-
讓你的
META.info文件看起來(lái)像這樣:{ "name" : "Vortex::TotalPerspective", "version" : "0.1.0", "description" : "Wonderful simulation to get some perspective.", "author" : "Your Name", "provides" : { "Vortex::TotalPerspective" : "lib/Vortex/TotalPerspective.pm" }, "depends" : [ ], "source-url" : "git://github.com/you/Vortex-TotalPerspective.git" }關(guān)于選擇版本號(hào)的方案, 或許使用 "major.minor.patch" （查看 the spec on versioning 獲取詳細(xì)信息 ）。如果版本號(hào)現(xiàn)在對(duì)你或你的用戶(hù)來(lái)說(shuō)不重要, 你可以給版本那兒放上一顆星(*)绞蹦。
在
provides一節(jié), 包含進(jìn)你的發(fā)布中提供的所有命名空間力奋。- 把你的工程放在 git 版本控制之下, 如果你還未這樣做。
- 一旦你對(duì)你的工程滿(mǎn)意了, 在 Github 上為它創(chuàng)建一個(gè)倉(cāng)庫(kù)幽七。必要的話(huà), 查看 Github's help docs景殷。 你的 Github 倉(cāng)庫(kù)的名字應(yīng)該和你工程目錄的名字一樣。創(chuàng)建完 Githhub 倉(cāng)庫(kù)后, Github 會(huì)為你展示怎么配置你的本地倉(cāng)庫(kù)以獲悉你的 Github 倉(cāng)庫(kù)澡屡。
- 把你的工程推送到 Github
- 在 IRC 頻道找個(gè)人幫你展示怎么把你的模塊添加到ecosystem, 或者讓他們是否能替你添加猿挚。
- pull 請(qǐng)求被接收之后, 等個(gè)把小時(shí)。如果你的模塊沒(méi)有出現(xiàn)在 http://modules.perl6.org/ , 請(qǐng)到 http://modules.perl6.org/log/update.log 翻看log 日志文件, 以查找是否有錯(cuò)誤驶鹉。
就是這樣啦绩蜻！ 感謝為 Perl 6 社區(qū)做貢獻(xiàn)！
如果你想嘗試安裝你的模塊, 使用熊貓 panda 安裝工具, 這已經(jīng)包含在 Rakudo Perl 6 中了:
panda install Vortex::TotalPerspective這會(huì)下載你的模塊到它自己的工作目錄(~/.panda), 在那兒創(chuàng)建 build, 并把模塊安裝到
~/.perl6
