NAME

SelectiveImporting - Selective importing, and making aliases from modules

SYNOPSIS

Installation: zef install SelectiveImporting

use SelectiveImporting;

use JSON::Fast :select<&to-json &from-json>; # or just `use JSON::Fast`
use JSON::Tiny :select('&to-json' => '&to-json-tiny', '&from-json' => '&from-json-tiny');

# say &to-json.package;        # (Fast)
# say &from-json.package;      # (Fast)
# say &to-json-tiny.package;   # (Tiny)
# say &from-json-tiny.package; # (Tiny)

DESCRIPTION

Aims:

• Import selectively

• Avoid name conflicts

Behavior after use SelectiveImporting:

• if there is no arglist in use statement, e.g., use JSON::Fast

  • use behaves as usual

• else if there is no Pair "select" => !Bool

  • use behaves as usual

• else if there is Pair "select" => !Bool (handled as a List, "select" => ([Str | Pair]*))

  • if Str

    • import it

  • if Pair ('a' => 'b')

    • import a and rename it to b

  • Special Pairs

    • "our" => ([Str | Pair]*) for importing items marked as our

    • :exportSub: whether importing all from sub EXPORT or not

  • Notes in this case

    • all implicit tags will be ignored, like :DEFAULT, :MANDATORY, must be marked explicitly

    • items generated by sub EXPORT are not imported by default, use :exportSub in :select to enable it if not :select some

    • if tags or :exportSub exist, it will import all items from them, and rename items using Str|Pair except :our(...); if there is not any alias, import without renaming

    • if items don't exist in given :tag, it will import from :ALL

How to import via :select:

• class X: 'X'

• routine f: '&f'

• variable $a: '$a' (@a, %a)

• sub postfix:<!>: '&postfix:<!>'

• enum X <a b c d>: 'X'

  • could import 'a', 'b' to use them directly instead of X::a via :select<X a b>

• constant X: 'X'

• package X: 'X'

Use cases:

• use XXX :select<a b $c &d>

• use XXX :select('a', 'b')

• use XXX :select('a' => 'aa', 'b' => 'bb')

• use XXX :select('a' => 'aa', 'b' => 'bb', 'c', 'd')

• use XXX :select(|<c d>, 'a' => 'aa', 'b' => 'bb', 'e')

• use XXX :select(|<c d>, 'a' => 'aa', 'b' => 'bb', :exportSub)

• use XXX :select(|<c d>, 'a' => 'aa', 'b' => 'bb', :exportSub, :our<oa ob>)

• use XXX :select(|<c d>, 'a' => 'aa', 'b' => 'bb', :exportSub, :our('oa' => 'oaa', 'ob' => 'obb', 'oc'))

• use XXX :DEFAULT, :select<a b>

• use XXX :tag1, :tag2, :select<a b>

Skip something when import via :except:

• use XXX :except('a', '&c')

• use XXX :select('a', 'b'), :except('b') will not import 'b'

• could be used when import :tag

How to use other words instead of select:

• use SelectiveImporting ({:select("get")},);

• then use XXX :get(...)

• also ({:except("skip")},)

• please check examples/change-key.raku for more details

Examples:

• examples/*.raku

• t/*.rakumod *.rakutest

Note:

• It modifies the default do_import in Perl6/World.nqp

• It doesn't work in REPL

• It doesn't deal with EXPORTHOW

Ref:

• https://docs.raku.org/language/modules#Exporting_and_selective_importing

• https://github.com/rakudo/rakudo/blob/master/src/Perl6/World.nqp

• https://github.com/FROGGS/p6-if

Similar module

• https://raku.land/zef:wukgdu/CustomImporting (which imports items and makes aliases through function)

• https://raku.land/zef:lizmat/from (which inspires :except)

AUTHOR

wukgdu [email protected]

https://github.com/wukgdu

COPYRIGHT AND LICENSE

Copyright 2022 wukgdu

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.