NAME

Const::Exporter - Declare constants for export.

VERSION

version v1.3.0

SYNOPSIS

Define a constants module:

  package MyApp::Constants;
  our $zoo => 1234;
  use Const::Exporter
     tag_a => [                  # use MyApp::Constants /:tag_a/;
        'foo'  => 1,             # exports "foo"
        '$bar' => 2,             # exports "$bar"
        '@baz' => [qw/ a b c /], # exports "@baz"
        '%bo'  => { a => 1 },    # exports "%bo"
     ],
     tag_b => [                  # use MyApp::Constants /:tag_b/;
        'foo',                   # exports "foo" (same as from ":tag_a")
        '$zoo',                  # exports "$zoo" (as defined above)
     ];
  # `use Const::Exporter` can be specified multiple times
  use Const::Exporter
     tag_b => [                 # we can add symbols to ":tab_b"
        'moo' => $bar,          # exports "moo" (same value as "$bar")
     ],
     enums => [
       [qw/ goo gab gub /] => 0, # exports enumerated symbols, from 0..2
     ],
     default => [qw/ foo $bar /]; # exported by default

and use that module:

  package MyApp;
  use MyApp::Constants qw/ $zoo :tag_a /;
  ...

 use Const::Exporter;
 my %myconstants = (
        'foo'  => 1,
        '$bar' => 2,
        '@baz' => [qw/ a b c /],
        '%bo'  => { a => 1 },
 );
 # ... do stuff
 Const::Exporter->import(
      constants => [%myconstants],        # define constants for exporting
      default   => [ keys %myconstants ], # export everything in %myconstants by default
 );

DESCRIPTION

This module allows you to declare constants that can be exported to other modules.

To declare constants, simply group then into export tags:

  package MyApp::Constants;
  use Const::Exporter
    tag_a => [
       'foo' => 1,
       'bar' => 2,
    ],
    tag_b => [
       'baz' => 3,
       'bar',
    ],
    default => [
       'foo',
    ];

Constants in the "default" tag are exported by default (that is, they are added to the @EXPORTS array).

When a constant is already defined in a previous tag, then no value is specified for it. (For example, "bar" in "tab_b" above.) If you do give a value, Const::Exporter will assume it's another symbol.

Your module can include multiple calls to "use Const::Exporter", so that you can reference constants in other expressions, e.g.

  use Const::Exporter
    tag => [
        '$zero' => 0,
    ];
  use Const::Exporter
    tag => [
        '$one' => 1 + $zero,
    ];

or even something more complex:

  use Const::Exporter
     http_ports => [
        'HTTP'     => 80,
        'HTTP_ALT' => 8080,
        'HTTPS'    => 443,
     ];
  use Const::Exporter
     http_ports => [
        '@HTTP_PORTS' => [ HTTP, HTTP_ALT, HTTPS ],
     ];

Constants can include traditional constant symbols, as well as scalars, arrays or hashes.

Constants can include values defined elsewhere in the code, e.g.

  our $foo;
  BEGIN {
     $foo = calculate_value_for_constant();
  }
  use Const::Exporter
    tag => [ '$foo' ];

Note that this will make the symbol read-only. You don't need to explicitly declare it as such.

Enumerated constants are also supported:

  use Const::Exporter
    tag => [
      [qw/ foo bar baz /] => 1,
    ];

will define the symbols "foo" (1), "bar" (2) and "baz" (3).

You can also specify a list of numbers, if you want to skip values:

  use Const::Exporter
    tag => [
      [qw/ foo bar baz /] => [1, 4],
    ];

will define the symbols "foo" (1), "bar" (4) and "baz" (5).

You can even specify string values:

  use Const::Exporter
    tag => [
      [qw/ foo bar baz /] => [qw/ feh meh neh /],
    ];

however, this is equivalent to

  use Const::Exporter
    tag => [
      'foo' => 'feh',
      'bar' => 'meh',
      'baz' => 'neh',
    ];

Objects are also supported,

   use Const::Exporter
    tag => [
      '$foo' => Something->new( 123 ),
    ];

KNOWN ISSUES

  use Const::Exporter
  =head2 a
  =cut
    a => [ foo => 1 ],
  =head2 b
  =cut
    b => [ bar => 2 ];

  =head2 a
  =cut
  use Const::Exporter
    a => [ foo => 1 ];
  =head2 b
  =cut
  use Const::Exporter
    b => [ bar => 2 ];

SUPPORT FOR OLDER PERL VERSIONS

This module requires Perl v5.10.1 or later.

Future releases may only support Perl versions released in the last ten years.

SEE ALSO

See Exporter for a discussion of export tags.

SOURCE

The development version is on github at <https://github.com/robrwo/Const-Exporter> and may be cloned from <git://github.com/robrwo/Const-Exporter.git>

BUGS

Please report any bugs or feature requests on the bugtracker website <https://github.com/robrwo/Const-Exporter/issues>

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Robert Rothenberg <rrwo@cpan.org>

CONTRIBUTORS

• Slaven Rezić <slaven@rezic.de>
• B. Estrade <estrabd@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2014-2024 by Robert Rothenberg.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)