README for ISA.pm Time-stamp: "1999-02-02 21:42:35 MST" NAME ISA -- modify and/or freeze a class's @ISA at compile time SYNOPSIS package Cat::Himalayan; use ISA qw(-use Cat::Persian Cat::Siamese); ...basically the same as: package Cat::Himalayan; BEGIN { push @ISA, 'Cat::Persian'; } use Cat::Persian; BEGIN { push @ISA, 'Cat::Siamese'; } use Cat::Siamese; DESCRIPTION A class's @ISA is a list of its superclasses (AKA base classes, AKA generic classes). See the perlobj manpage or the perltoot manpage for details. ISA.pm is a simple module allowing you to manipulate your class's @ISA list at compile-time. OPTIONS You call ISA.pm by saying "use ISA OPTION, OPTION, OPTION;", for example: use ISA 'Cat::Persian', 'Cat::Himalayan'; or, to represent the list another way, "use ISA qw(OPTION, OPTION, OPTION);", for example: use ISA qw(Cat::Persian Cat::Himalayan); The most popular important options are "-use", "-freeze", and CLASSNAME. But for the sake of completeness, these are all the possible options: CLASSNAME A classname (basically anything non-null that doesn't begin with a "-" or a "!") is interpreted as a classname to add to the @ISA for the calling package. The classname is added to the end, unless you've set "-start". If it's already in @ISA, it won't be added to the list, unless you set "-force". [Note that if you specify a classname with apostrophes (which is obsolescent), like "Tree'DAG_Node", it is added to @ISA with double- colons, like "Tree::DAG_Node". Similarly, saying "::Foo::Bar" is added as "main::Foo::Bar" -- but who'd ever have a class rooted under "main", regardless of which way you refer to it?] !CLASSNAME This removes all instances of the given classname from the @ISA. -use This turns on the "automagical use" mode (which is off by default), which is effective for just this line, like force mode (see below). In "automagical use" mode, for each classname you ask ISA.pm to add to the @ISA list, ISA.pm will try to "use" that class if it looks like it hasn't been used yet. In other words, this: package Tree::Palm; use ISA qw(-use Tree::DAG_Node); is basically the same as saying: package Tree::Palm; BEGIN { push @ISA, 'Tree::DAG_Node'; } BEGIN { eval "package Tree::Palm; use Tree::DAG_Node;" } Note that you shouldn't use this mode except with modules that never export any symbols (and a class generally shouldn't!). Note also that automagical use mode does a simple "use Foo::Bar" -- there's no way to have it say "use Foo::Bar 1.10" or "use Foo::Bar qw(pati pata)". If you want that, use an explicit `use' instead: use Foo::Bar qw(pati pata); use ISA qw(Foo::Bar); If ISA.pm tries to automagically use a class, but fails, this will cause a fatal error. Note also that when ISA checks to see whether a class has been used yet, it doesn't care what package or context it was used in. But that's irrelevant for classes that don't export anything. -!use This turns "automagical use" mode back off. -freeze This freezes the contents of @ISA. Any subsequent attempts to alter it again thru "use ISA ..." result in a fatal error. In future versions of ISA.pm, "-freeze" will (hopefully!) make the given @ISA unalterable, such that attempts to change it will result in a fatal error. For the time being, however, ISA.pm uses an END block to check that all frozen @ISAs have the same contents as what they had when they were frozen; any changes will be noted as pesky `warn'ings. Once you freeze an @ISA list, you can't unfreeze it. Why freeze @ISA? Because the list of what your class's superclasses are is a basic fact about the class, not something you should go changing after your code has started running. Consider -freeze to be a sanity checker. -clear Clears the contents of @ISA. -start Normally, requesting that a classname be added to @ISA will (if it's not already in there) add it to the end of the list. However, if you want it added to the beginning (assuming it's not already in there), use '-start'. This is effective only for the given call. For example: use ISA qw(Foo); # line 1 use ISA qw(-start Bar Ziz); # line 2 use ISA qw(Baz); # line 3 This will leave an @ISA of `qw(Bar Ziz Foo Baz)', because "-start" is effective only for line 2. -end This cancels a preceding "-start", so that subsequently adding a classname to @ISA will (if it's not already in there) add it to the end of the list. -force This puts ISA.pm in "force mode". In force mode, trying to add a class name to @ISA will always add it, regardless of whether it's already there. By default, force mode is off. This leaves force mode on for just this call to ISA.pm. For example: use ISA qw(Foo::Bar Foo::Quux); # line 1 use ISA qw(-force Foo::Bar Zaz::Zoo); # line 2 use ISA qw(Foo::Quux); # line 3 Here, the "-force" in line 2 is effective for just that call to @ISA -- so that "Foo::Bar" is added to @ISA again. ("Zaz::Zoo" is added, too, just as it would be normally.) However, in line 3, we're back to the default no-force mode, and so "Foo::Quux" isn't added to @ISA again, since it's already there. Force mode is useful in combination with "-start", to forcedly move a class name to the start of @ISA, regardless of whether it's in there already: use ISA qw(-force -start Thing::Prime); However, you could just as easily do effectively the same thing by removing the class in question from @ISA, then restoring it at the beginning, like so: use ISA qw(!Thing::Prime -start Thing::Prime); -!force This turns force mode back off. -debug This puts puts ISA.pm in "debug mode" -- just like setting $ISA::Debug to 1. This makes ISA.pm spew lots of verbose garbage useful for diagnosing bugs in (or relating to) ISA.pm. -!debug This turns off ISA.pm's debug mode. NOTES Note that ISA.pm and `Class::ISA' are different things. Thanks to Eric Watt (Arkuat) Forste for the idea of tying @ISA. Thanks to Tim Bunce for writing lib.pm, and to whoever wrote Exporter.pm -- these were both useful precedents to ISA.pm. COPYRIGHT Copyright (c) 1999 Sean M. Burke. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHOR Sean M. Burke `sburke@netadventure.net' PREREQUISITES This suite requires Perl 5; I've only used it under Perl 5.004, so for anything lower, you're on your own. ISA.pm doesn't use any nonstandard modules. INSTALLATION You install ISA.pm, as you would install any perl module library, by running these commands: perl Makefile.PL make make test make install If you want to install a private copy of ISA.pm in your home directory, then you should try to produce the initial Makefile with something like this command: perl Makefile.PL LIB=~/perl DOCUMENTATION POD-format documentation is included in ISA.pm. POD is readable with the 'perldoc' utility. See ChangeLog for recent changes. MACPERL INSTALLATION NOTES Don't bother with the makefiles. Just move ISA.pm into your MacPerl site_lib or lib directory. SUPPORT Questions, bug reports, useful code bits, and suggestions for ISA.pm should just be sent to me at sburke@netadventure.net AVAILABILITY The latest version of ISA.pm is available from the Comprehensive Perl Archive Network (CPAN). Visit to find a CPAN site near you.