txt: ## dist_zef-wukgdu-SelectiveImporting.md
  # 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 `Pair`s
      * `"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 [wukgdu365@yahoo.com](mailto:wukgdu365@yahoo.com)
  
  <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.
  