NAME

       Acme::constant - Like constant, except actually not.

SYNOPSIS

           use Acme::constant ACME => 42;
           print "ACME is now ", ACME, ".\n";
           ACME = 84;
           print "But now, ACME is ", ACME, "\n";

           use Acme::constant LIST => 1, 2, 3;
           print "Second element of list is ", (LIST)[1], ".\n";
           (LIST) = (4, 5, 6);
           print "But now, the second element is ", (LIST)[1], "\n";

DESCRIPTION

       This pragma lets you make inconstant constants, just like the constants the users of Ruby
       or Opera (before Opera 14, that is) already enjoyed.

       Unlike Perl constants, that are replaced at compile time, Acme constants, in true dynamic
       programming language style, can be modified even after declaration.

       Just like constants generated with standard "use constant" pragma, the constants declared
       with "use Acme::Constant" don't have any sigils.  This makes using constants easier, as
       you don't have to remember what sigil do constants use.

NOTES

       As the Perl compiler needs to know about which barewords are keywords, constants have to
       defined in "BEGIN" section. Usually, this is not a problem, as "use" statement is
       automatically put in implicit "BEGIN" section, but that also means you cannot dynamically
       create constants.  For example, in the example below, the "DEBUG" constant is always
       created, with value 1, as "use" is processed when Perl parser sees it.

           if ($ENV{DEBUG}) {
               use Acme::constant DEBUG => 1; # WRONG!
           }

       It's possible to dynamically use this module using if module, however, this is likely to
       cause problems when trying to use constant that doesn't exist.

           use if $ENV{DEBUG}, Acme::constant => DEBUG => 1;

       You can also use directly use "import" method, in order to conditionally load constant.

           BEGIN {
               require Acme::constant;
               Acme::constant->import(DEBUG => 1) if $ENV{DEBUG};
           }

       However, usually the good idea to declare constant anyway, as using undefined constants in
       strict mode causes Perl errors (and sometimes could be parsed incorrectly).

           use Acme::constant DEBUG => $ENV{DEBUG};

       Constants belong to the package they were defined in. When you declare constant in some
       module, the constant is subroutine declared in it.  However, it's possible to export
       constants with module such as Exporter, just as you would export standard subroutine.

           package Some::Package;
           use Acme::constant MAGIC => "Hello, world!\n";

           package Some::Other::Package;
           print Some::Package::MAGIC; # MAGIC directly won't work.

   List constants
       Just like standard constant module, you can use lists with this module. However, there are
       few catches you should be aware of.

       To begin with, you cannot use list constants in scalar context. While constant module lets
       you do this, I believe allowing something like this can open can of worms, because
       constant with one element is just as valid constant (that wouldn't return 1). Something
       like this won't work.

           use Acme::constant NUMBERS => 1..6;
           print 'Found ', scalar NUMBERS, " numbers in NUMBERS.\n"; # WRONG!

       Instead, to count number of elements in the constant, you can use the "() =" trick, that
       lets you count elements in any sort of list.

           use Acme::constant NUMBERS => 1..6;
           print 'Found ', scalar(() = NUMBERS), " numbers in NUMBERS.\n";

       Also, as "use" statement arguments are always parsed in the list context, sometimes you
       could be surprised with argument being executed in list context, instead of scalar
       context.

           use Acme::constant TIMESTAMP => localtime; # WRONG!

       Usually, when this happens, it's possible to use "scalar" operator in order to force
       interpretation of code in scalar context.

           use Acme::constant TIMESTAMP => scalar localtime;

       Constants return lists, not arrays (you don't use "@" syntax, do you?), so in order to get
       single element, you will need to put a constant in parenthesis.

           use Acme::constant NUMBERS => 1..6;
           print join(" ", (NUMBERS)[2..4]), "\n";

   Assignments
       The assignments are done using standard "=" operator.

           use Acme::constant SOMETHING => 1;
           SOMETHING = 2;
           print "Something is ", SOMETHING, ".\n";

           use Acme::constant ARRAY => 1, 2, 3;
           my $four = 7;
           ($four, ARRAY) = (4, 5, 6);
           print "Something is ", join(", ", ARRAY), ", and four is $four.\n";

       There are also catches about assignments. Perl normally runs the part after "=" operator
       in scalar context, unless leftside argument is a list or array. As inconstant constant is
       neither a list or array, the argument on right side is ran in scalar context. For example,
       following code will only save 2, as comma operator is ran in scalar context.

           use Acme::constant SOMETHING => 0;
           SOMETHING = (1, 2); # WRONG!
           print "Something is ", join(", ", SOMETHING), ".\n";

       In order to force list interpretation, you need to put constant in the parenthesis.

           use Acme::constant SOMETHING => 0;
           (SOMETHING) = (1, 2);
           print "Something is ", join(", ", SOMETHING), ".\n";

       Similarly, you cannot modify list constant in scalar context, as Perl expects you put a
       list, not a single value.

           use Acme::constant SOMETHING => (1, 2);
           SOMETHING = 3; # WRONG!
           print "Something is ", SOMETHING, ".\n";

       To fix that, you need to put constant in parenthesis. This is only needed when constant
       has different number of elements than one, so after such assignment, you can use normal
       assignment, without parenthesis.

           use Acme::constant SOMETHING => (1, 2);
           (SOMETHING) = 3;
           print "Something is ", SOMETHING, ".\n";
           SOMETHING = 4;
           print "Something is now ", SOMETHING, ".\n";

       Also, the localization of Acme constants is broken, and while it will change the value, it
       won't change value back after leaving the block.  This is related to that you cannot
       localize lexicals and references in Perl 5.

           use Acme::constant PI => 4 * atan2 1, 1;
           {
               local PI = 3;
               print "PI = ", PI, "\n";
           }
           print "PI = ", PI, "\n";

CAVEATS

       Other than caveats mentioned here, general caveats about constants also exist. Unlike
       standard constants module, constants with names like "STDIN STDOUT STDERR ARGV ARGVOUT ENV
       INC SIG" can be used outside "main::" package, because of different method of generating
       constants.

       The constants can be problematic to use in context that automatically stringifies the
       barewords. For example, the following code is wrong.

           use Acme::constant KEY => "acme";
           my %hash;
           $hash{KEY} = 42; # Works like $hash{"KEY"} = 42;

       Instead, you should use following code.

           use Acme::constant KEY => "acme";
           my %hash;
           $hash{(KEY)} = 42;

DIAGNOSTICS

       Can't call %s in scalar context
           (F) You tried to call constant containing constant containing different numbers than
           one in scalar context. As it's hard to determine what you mean, you have to
           disambiguate your call. If you want to get count of elements, you may want to assign
           it to "()", like "() = CONSTANT". If you want to get last element, use
           "(CONSTANT)[-1]".

       Can't modify non-lvalue subroutine call
           (F) You tried to assign single value to constant containing an array.  This won't
           work, as Perl expects a list to be assigned. If you really want to assign an single
           element, use "(CONSTANT) = $value" syntax.

           This error is provided by Perl, and as such, it could be confusing, as constant
           actually is lvalue, just assigned in wrong context.

       Useless localization of subroutine entry
           (W syntax) You tried to localize constant with "local" operator. This is legal, but
           currently has no effect. This may change in some future version of Perl, but in the
           meantime such code is discouraged.

       Useless use of "Acme::constant" pragma
           (W) You did "use Acme::constant;" without any arguments. This isn't very useful. If
           this is what you mean, write "use Acme::constant ();" instead.

SEE ALSO

       constant - Builtin constant module.

       Readonly - Constant scalars, arrays, and hashes.

BUGS

       Please use GitHub <https://github.com/GlitchMr/Acme-constant/issues> to report bugs.

SOURCE

       The source code for Acme::constant is available can be found
       <https://github.com/GlitchMr/Acme-constant/>.

COPYRIGHT

       Copyright 2013 by Konrad Borowski <glitchmr@myopera.com>.