{
    "content": [
        {
            "type": "text",
            "text": "# Exporter::Tiny::Manual::Importing (perldoc)\n\n## NAME\n\nExporter::Tiny::Manual::Importing - importing from Exporter::Tiny-based modules\n\n## DESCRIPTION\n\nFor the purposes of this discussion we'll assume we have a module called \"MyUtils\" which exports\nfunctions called \"frobnicate\", \"red\", \"blue\", and \"green\". It has a tag set up called \":colours\"\nwhich corresponds to \"red\", \"blue\", and \"green\".\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION** (6 subsections)\n- **DIAGNOSTICS**\n- **SEE ALSO**\n- **AUTHOR**\n- **COPYRIGHT AND LICENCE**\n- **DISCLAIMER OF WARRANTIES**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Exporter::Tiny::Manual::Importing",
        "section": "",
        "mode": "perldoc",
        "summary": "Exporter::Tiny::Manual::Importing - importing from Exporter::Tiny-based modules",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 8,
                "subsections": [
                    {
                        "name": "Basic importing",
                        "lines": 28
                    },
                    {
                        "name": "Renaming imported functions",
                        "lines": 52
                    },
                    {
                        "name": "Importing by regexp",
                        "lines": 11
                    },
                    {
                        "name": "Import functions into another package",
                        "lines": 10
                    },
                    {
                        "name": "Lexical subs",
                        "lines": 31
                    },
                    {
                        "name": "Unimporting",
                        "lines": 16
                    }
                ]
            },
            {
                "name": "DIAGNOSTICS",
                "lines": 27,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT AND LICENCE",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "DISCLAIMER OF WARRANTIES",
                "lines": 4,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Exporter::Tiny::Manual::Importing - importing from Exporter::Tiny-based modules\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "For the purposes of this discussion we'll assume we have a module called \"MyUtils\" which exports\nfunctions called \"frobnicate\", \"red\", \"blue\", and \"green\". It has a tag set up called \":colours\"\nwhich corresponds to \"red\", \"blue\", and \"green\".\n\nMany of these tricks may seem familiar from Sub::Exporter. That is intentional. Exporter::Tiny\ndoesn't attempt to provide every feature of Sub::Exporter, but where it does it usually uses a\nfairly similar API.\n",
                "subsections": [
                    {
                        "name": "Basic importing",
                        "content": "It's easy to import a single function from a module:\n\nuse MyUtils \"frobnicate\";\n\nOr a list of functions:\n\nuse MyUtils \"red\", \"green\";\n\nPerl's \"qw()\" shorthand for a list of words is pretty useful:\n\nuse MyUtils qw( red green );\n\nIf the module defines tags, you can import them like this:\n\nuse MyUtils qw( :colours );\n\nOr with a hyphen instead of a colon:\n\nuse MyUtils qw( -colours );\n\nHyphens are good because Perl will autoquote a bareword that follows them:\n\nuse MyUtils -colours;\n\nAnd it's possible to mix function names and tags in the same list:\n\nuse MyUtils qw( frobnicate :colours );\n"
                    },
                    {
                        "name": "Renaming imported functions",
                        "content": "It's possible to rename a function you're importing:\n\nuse MyUtils \"frobnicate\" => { -as => \"frob\" };\n\nOr you can apply a prefix and/or suffix. The following imports the function and calls it\n\"myfrobinatething\".\n\nuse MyUtils \"frobnicate\" => { -prefix => \"my\", -suffix => \"thing\" };\n\nYou can apply a prefix/suffix to all functions you import by placing the hashref first in the\nimport list. (This first hashref is referred to as the global options hash, and can do some\nspecial things.)\n\nuse MyUtils { prefix => \"my\" }, \"frobnicate\";\n\nDid you notice that we used \"-prefix\" and \"-suffix\" in the normal options hash, but \"prefix\" and\n\"suffix\" (no hyphen) in the global options hash? That's a common pattern with this module.\n\nYou can import the same function multiple times with different names:\n\nuse MyUtils\n\"frobnicate\" => { -as => \"frob\" },\n\"frobnicate\" => { -as => \"frbnct\" };\n\nTags can take the \"-prefix\" and \"-suffix\" options too. The following imports \"colourred\",\n\"colourgreen\", and \"colourblue\":\n\nuse MyUtils -colours => { -prefix => \"colour\" };\n\nYou can also set \"-as\" to be a coderef to generate a function name. This imports functions\ncalled \"RED\", \"GREEN\", and \"BLUE\":\n\nuse MyUtils -colours => { -as => sub { uc($[0]) } };\n\nNote that it doesn't make sense to use \"-as\" with a tag unless you're doing this coderef thing.\nCoderef \"as\" also works in the global options hash.\n\nDO NOT WANT!\nSometimes you want to supply a list of functions you don't want to import. To do that, prefix\nthe function with a bang. This imports everything except \"frobnicate\":\n\nuse MyUtils qw( -all !frobnicate );\n\nYou can add the bang prefix to tags too. This will import everything except the colours.\n\nuse MyUtils qw( -all !:colours );\n\nNegated imports always \"win\", so the following will not import \"frobnicate\", no matter how many\ntimes you repeat it...\n\nuse MyUtils qw( !frobnicate frobnicate frobnicate frobnicate );\n"
                    },
                    {
                        "name": "Importing by regexp",
                        "content": "Here's how you could import all functions beginning with an \"f\":\n\nuse MyUtils qw( /^F/i );\n\nOr import everything except functions beginning with a \"z\":\n\nuse MyUtils qw( -all !/^Z/i );\n\nNote that regexps are always supplied as *strings* starting with \"/\", and not as quoted regexp\nreferences (\"qr/.../\").\n"
                    },
                    {
                        "name": "Import functions into another package",
                        "content": "Occasionally you need to import functions not into your own package, but into a different\npackage. You can do that like this:\n\nuse MyUtils { into => \"OtherPkg\" }, \"frobnicate\";\n\nOtherPkg::frobincate(...);\n\nHowever, Import::Into will probably provide you with a better approach which doesn't just work\nwith Exporter::Tiny, but all exporters.\n"
                    },
                    {
                        "name": "Lexical subs",
                        "content": "Often you want to make use of an exported function, but don't want it to \"pollute\" your\nnamespace.\n\nThere is this Sub::Exporter::Lexical thing that was designed as a plugin for Sub::Exporter, but\nExporter::Tiny's API is close enough that it will work. Do you remember that global options\nhash? Just use that to tell Exporter::Tiny to use an alternative sub installer.\n\n{\nuse Sub::Exporter::Lexical lexicalinstaller => { -as => \"lex\" };\nuse MyUtils { installer => lex }, \"frobnicate\";\n\nfrobnicate(...);  # ok\n}\n\nfrobnicate(...);  # not ok\n\nAnother way to do lexical functions is to import a function into a scalar variable:\n\nmy $func;\nuse MyUtils \"frobnicate\" => { -as => \\$func };\n\n$func->(...);\n\nYou can even provide a hashref to put all imported functions into as part of that global options\nhash I mentioned earlier.\n\nmy %funcs;\nuse MyUtils { into => \\%funcs }, \"frobnicate\";\n\n$funcs{frobnicate}->(...);\n"
                    },
                    {
                        "name": "Unimporting",
                        "content": "You can unimport the functions that MyUtils added to your namespace:\n\nno MyUtils;\n\nOr just specific ones:\n\nno MyUtils qw(frobnicate);\n\nIf you renamed a function when you imported it, you should unimport by the new name:\n\nuse MyUtils frobnicate => { -as => \"frob\" };\n...;\nno MyUtils \"frob\";\n\nUnimporting using tags and regexps should mostly do what you want.\n"
                    }
                ]
            },
            "DIAGNOSTICS": {
                "content": "Overwriting existing sub '%s::%s' with sub '%s' exported by %s\nA warning issued if Exporter::Tiny is asked to export a symbol which will result in an\nexisting sub being overwritten. This warning can be suppressed using either of the\nfollowing:\n\nuse MyUtils { replace => 1 }, \"frobnicate\";\nuse MyUtils \"frobnicate\" => { -replace => 1 };\n\nOr can be upgraded to a fatal error:\n\nuse MyUtils { replace => \"die\" }, \"frobnicate\";\nuse MyUtils \"frobnicate\" => { -replace => \"die\" };\n\nRefusing to overwrite existing sub '%s::%s' with sub '%s' exported by %s\nThe fatal version of the above warning.\n\nCould not find sub '%s' exported by %s\nYou requested to import a sub which the package does not provide.\n\nCannot provide an -as option for tags\nBecause a tag may provide more than one function, it does not make sense to request a single\nname for it. Instead use \"-prefix\" or \"-suffix\".\n\nPassing options to unimport '%s' makes no sense\nWhen you import a sub, it occasionally makes sense to pass some options for it. However,\nwhen unimporting, options do nothing, so this warning is issued.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "Exporter::Shiny, Exporter::Tiny.\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Toby Inkster <tobyink@cpan.org>.\n",
                "subsections": []
            },
            "COPYRIGHT AND LICENCE": {
                "content": "This software is copyright (c) 2013-2014, 2017 by Toby Inkster.\n\nThis is free software; you can redistribute it and/or modify it under the same terms as the Perl\n5 programming language system itself.\n",
                "subsections": []
            },
            "DISCLAIMER OF WARRANTIES": {
                "content": "THIS PACKAGE IS PROVIDED \"AS IS\" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,\nWITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR\nPURPOSE.\n",
                "subsections": []
            }
        }
    }
}