{ "content": [ { "type": "text", "text": "# Import::Into (perldoc)\n\n## NAME\n\nImport::Into - Import packages into other packages\n\n## SYNOPSIS\n\npackage My::MultiExporter;\nuse Import::Into;\n# simple\nsub import {\nThing1->import::into(scalar caller);\n}\n# multiple\nsub import {\nmy $target = caller;\nThing1->import::into($target);\nThing2->import::into($target, qw(import arguments));\n}\n# by level\nsub import {\nThing1->import::into(1);\n}\n# with exporter\nuse base qw(Exporter);\nsub import {\nshift->exporttolevel(1);\nThing1->import::into(1);\n}\n# no My::MultiExporter == no Thing1\nsub unimport {\nThing1->unimport::outof(scalar caller);\n}\nPeople wanting to re-export your module should also be using Import::Into. Any exporter or\npragma will work seamlessly.\nNote: You do not need to make any changes to Thing1 to be able to call \"import::into\" on it.\nThis is a global method, and is callable on any package (and in fact on any object as well,\nalthough it's rarer that you'd want to do that).\n\n## DESCRIPTION\n\nWriting exporters is a pain. Some use Exporter, some use Sub::Exporter, some use\nMoose::Exporter, some use Exporter::Declare ... and some things are pragmas.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS**\n- **WHY USE THIS MODULE**\n- **SEE ALSO**\n- **ACKNOWLEDGEMENTS**\n- **AUTHOR**\n- **CONTRIBUTORS**\n- **COPYRIGHT**\n- **LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Import::Into", "section": "", "mode": "perldoc", "summary": "Import::Into - Import packages into other packages", "synopsis": "package My::MultiExporter;\nuse Import::Into;\n# simple\nsub import {\nThing1->import::into(scalar caller);\n}\n# multiple\nsub import {\nmy $target = caller;\nThing1->import::into($target);\nThing2->import::into($target, qw(import arguments));\n}\n# by level\nsub import {\nThing1->import::into(1);\n}\n# with exporter\nuse base qw(Exporter);\nsub import {\nshift->exporttolevel(1);\nThing1->import::into(1);\n}\n# no My::MultiExporter == no Thing1\nsub unimport {\nThing1->unimport::outof(scalar caller);\n}\nPeople wanting to re-export your module should also be using Import::Into. Any exporter or\npragma will work seamlessly.\nNote: You do not need to make any changes to Thing1 to be able to call \"import::into\" on it.\nThis is a global method, and is callable on any package (and in fact on any object as well,\nalthough it's rarer that you'd want to do that).", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 40, "subsections": [] }, { "name": "DESCRIPTION", "lines": 9, "subsections": [] }, { "name": "METHODS", "lines": 29, "subsections": [] }, { "name": "WHY USE THIS MODULE", "lines": 98, "subsections": [] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "ACKNOWLEDGEMENTS", "lines": 3, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "CONTRIBUTORS", "lines": 4, "subsections": [] }, { "name": "COPYRIGHT", "lines": 2, "subsections": [] }, { "name": "LICENSE", "lines": 2, "subsections": [] } ], "sections": { "NAME": { "content": "Import::Into - Import packages into other packages\n", "subsections": [] }, "SYNOPSIS": { "content": "package My::MultiExporter;\n\nuse Import::Into;\n\n# simple\nsub import {\nThing1->import::into(scalar caller);\n}\n\n# multiple\nsub import {\nmy $target = caller;\nThing1->import::into($target);\nThing2->import::into($target, qw(import arguments));\n}\n\n# by level\nsub import {\nThing1->import::into(1);\n}\n\n# with exporter\nuse base qw(Exporter);\nsub import {\nshift->exporttolevel(1);\nThing1->import::into(1);\n}\n\n# no My::MultiExporter == no Thing1\nsub unimport {\nThing1->unimport::outof(scalar caller);\n}\n\nPeople wanting to re-export your module should also be using Import::Into. Any exporter or\npragma will work seamlessly.\n\nNote: You do not need to make any changes to Thing1 to be able to call \"import::into\" on it.\nThis is a global method, and is callable on any package (and in fact on any object as well,\nalthough it's rarer that you'd want to do that).\n", "subsections": [] }, "DESCRIPTION": { "content": "Writing exporters is a pain. Some use Exporter, some use Sub::Exporter, some use\nMoose::Exporter, some use Exporter::Declare ... and some things are pragmas.\n\nExporting on someone else's behalf is harder. The exporters don't provide a consistent API for\nthis, and pragmas need to have their import method called directly, since they effect the\ncurrent unit of compilation.\n\n\"Import::Into\" provides global methods to make this painless.\n", "subsections": [] }, "METHODS": { "content": "$package->import::into( $target, @arguments );\nA global method, callable on any package. Loads and imports the given package into $target.\n@arguments are passed along to the package's import method.\n\n$target can be an package name to export to, an integer for the caller level to export to, or a\nhashref with the following options:\n\npackage\nThe target package to export to.\n\nfilename\nThe apparent filename to export to. Some exporting modules, such as autodie or strictures,\ncare about the filename they are being imported to.\n\nline\nThe apparent line number to export to. To be combined with the \"filename\" option.\n\nlevel\nThe caller level to export to. This will automatically populate the \"package\", \"filename\",\nand \"line\" options, making it the easiest most constent option.\n\nversion\nA version number to check for the module. The equivalent of specifying the version number on\na \"use\" line.\n\n$package->unimport::outof( $target, @arguments );\nEquivalent to \"import::into\", but dispatches to $package's \"unimport\" method instead of\n\"import\".\n", "subsections": [] }, "WHY USE THIS MODULE": { "content": "The APIs for exporting modules aren't consistent. Exporter subclasses provide exporttolevel,\nbut if they overrode their import method all bets are off. Sub::Exporter provides an into\nparameter but figuring out something used it isn't trivial. Pragmas need to have their \"import\"\nmethod called directly since they affect the current unit of compilation.\n\nIt's ... annoying.\n\nHowever, there is an approach that actually works for all of these types.\n\neval \"package $target; use $thing;\"\n\nwill work for anything checking caller, which is everything except pragmas. But it doesn't work\nfor pragmas - pragmas need:\n\n$thing->import;\n\nbecause they're designed to affect the code currently being compiled - so within an eval, that's\nthe scope of the eval itself, not the module that just \"use\"d you - so\n\nsub import {\neval \"use strict;\"\n}\n\ndoesn't do what you wanted, but\n\nsub import {\nstrict->import;\n}\n\nwill apply strict to the calling file correctly.\n\nOf course, now you have two new problems - first, that you still need to know if something's a\npragma, and second that you can't use either of these approaches alone on something like Moose\nor Moo that's both an exporter and a pragma.\n\nSo, a solution for that is:\n\nuse Module::Runtime;\nmy $sub = eval \"package $target; sub { usemodule(shift)->import(\\@) }\";\n$sub->($thing, @importargs);\n\nwhich means that import is called from the right place for pragmas to take effect, and from the\nright package for caller checking to work - and so behaves correctly for all types of exporter,\nfor pragmas, and for hybrids.\n\nAdditionally, some import routines check the filename they are being imported to. This can be\ndealt with by generating a #line directive in the eval, which will change what \"caller\" reports\nfor the filename when called in the importer. The filename and line number to use in the\ndirective then need to be fetched using \"caller\":\n\nmy ($target, $file, $line) = caller(1);\nmy $sub = eval qq{\npackage $target;\n#line $line \"$file\"\nsub { usemodule(shift)->import(\\@) }\n};\n$sub->($thing, @importargs);\n\nAnd you need to switch between these implementations depending on if you are targeting a\nspecific package, or something in your call stack.\n\nRemembering all this, however, is excessively irritating. So I wrote a module so I didn't have\nto anymore. Loading Import::Into creates a global method \"import::into\" which you can call on\nany package to import it into another package. So now you can simply write:\n\nuse Import::Into;\n\n$thing->import::into($target, @importargs);\n\nThis works because of how perl resolves method calls - a call to a simple method name is\nresolved against the package of the class or object, so\n\n$thing->methodname(@args);\n\nis roughly equivalent to:\n\nmy $coderef = $thing->can('methodname');\n$coderef->($thing, @args);\n\nwhile if a \"::\" is found, the lookup is made relative to the package name (i.e. everything\nbefore the last \"::\") so\n\n$thing->Package::Name::methodname(@args);\n\nis roughly equivalent to:\n\nmy $coderef = Package::Name->can('methodname');\n$coderef->($thing, @args);\n\nSo since Import::Into defines a method \"into\" in package \"import\" the syntax reliably calls\nthat.\n\nFor more craziness of this order, have a look at the article I wrote at\n which covers coderef abuse and the\n\"${\\...}\" syntax.\n\nAnd that's it.\n", "subsections": [] }, "SEE ALSO": { "content": "I gave a lightning talk on this module (and curry and Safe::Isa) at YAPC::NA 2013\n.\n", "subsections": [] }, "ACKNOWLEDGEMENTS": { "content": "Thanks to Getty for asking \"how can I get \"use strict; use warnings;\" turned on for all\nconsumers of my code?\" and then \"why is this not a module?!\".\n", "subsections": [] }, "AUTHOR": { "content": "mst - Matt S. Trout (cpan:MSTROUT) \n", "subsections": [] }, "CONTRIBUTORS": { "content": "haarg - Graham Knop (cpan:HAARG) \n\nMithaldu - Christian Walde (cpan:MITHALDU) \n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (c) 2012 the Import::Into \"AUTHOR\" and \"CONTRIBUTORS\" as listed above.\n", "subsections": [] }, "LICENSE": { "content": "This library is free software and may be distributed under the same terms as perl itself.\n", "subsections": [] } } } }