The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Devel-Ladybug-0.405
/ Devel::Ladybug::Constants

NAME

Devel::Ladybug::Constants - Loads .ladybugrc values as Perl constants

DESCRIPTION

Loads .ladybugrc values as Perl constants, with optional export. Easily extended to support other named rc files.

.ladybugrc is a YAML file containing constant values used by Devel::Ladybug. It should be located under $ENV{LADYBUG_HOME}, which defaults to the current user's home directory ($ENV{HOME} on Unix platforms)

An example .ladybugrc is included in the top level directory of this distribution as ladybugrc-dist, and also given later in this document. Copy this file to the proper location, or just run ladybug-conf (also included with this distribution) to generate this for your local system and current user.

SECURITY

The .ladybugrc file represents the keys to the kingdom.

Treat your .ladybugrc file with the same degree of lockdown as you would with system-level executables and their associated configuration files. It should not be kept in a location where untrusted parties can write to it, or where any unaudited changes can occur.

SYNOPSIS

To import constants directly, just specify them when using Devel::Ladybug::Constants:

 use Devel::Ladybug::Constants qw| dbUser dbPass |;

 my $dbUser = dbUser;
 my $dbPass = dbPass;

To access the constants without importing them into the caller's namespace, just fully qualify them:

 use Devel::Ladybug::Constants;

 my $dbUser = Devel::Ladybug::Constants::dbUser;
 my $dbPass = Devel::Ladybug::Constants::dbPass;

EXAMPLE

The following is an example of an .ladybugrc file. The file contents must be valid YAML:

  ---
  yamlRoot: /opt/op/yaml
  yamlHost: ~
  sqliteRoot: /opt/op/sqlite
  scratchRoot: /tmp
  dbHost: localhost
  dbPass: ~
  dbPort: ~
  dbUser: op
  memcachedHosts:
    - 127.0.0.1:11211
  rcsBindir: /usr/bin
  rcsDir: RCS

HOST-SPECIFIC OVERLAYS

After loading .ladybugrc, Devel::Ladybug::Constants checks for the presence of a file named .ladybugrc-HOSTNAME, where HOSTNAME is the name of localhost as per Sys::Hostname. If the file is found, its values are added as constants, stomping any values of the same key which were loaded from the "global" rc.

For example, the host-specific configuration below would force hypothetical host foo.example.com to connect to a different database than the one specified in .ladybugrc.

  > hostname
  foo.example.com

  > cat $LADYBUG_HOME/.ladybugrc-foo.example.com
  ---
  dbHost: stgdb.example.com

CUSTOM RC FILES

Developers may create self-standing rc files for application-specific consumption. Just use Devel::Ladybug::Constants as a base, and invoke init for the named rc file.

Just as .ladybugrc, the custom rc file must contain valid YAML, and it lives under $ENV{LADYBUG_HOME}.

For example, in a hypothetical <.myapprc>:

  ---
  hello: howdy

Hypothetical package MyApp/Constants.pm makes any keys available as Perl constants:

  package MyApp::Constants;

  use base qw| Devel::Ladybug::Constants |;

  Devel::Ladybug::Constants::init(".myapprc");

  1;

Callers may consume the constants package, requesting symbols for export:

  use MyApp::Constants qw| hello |;

  say hello;

  #
  # Prints "howdy"
  #

Host-specific overlays work with custom RC files as well.

  > hostname
  foo.example.com

  > cat $LADYBUG_HOME/.myapprc-foo.example.com
  ---
  dbHost: stgdb.example.com

  > perl -e 'use MyApp::Constants qw| dbHost |; say dbHost'
  stgdb.example.com

DIAGNOSTICS

  • No .ladybugrc found

    .ladybugrc needs to exist in order for Devel::Ladybug to compile and run. In the event that a .ladybugrc was not found, Devel::Ladybug will exit with an instructive message. Read and follow the provided steps when this occurs.

  • Some symbol not exported

      Uncaught exception from user code:
  "foo" is not exported by the Devel::Ladybug::Constants module
  Can't continue after import errors ...

    This is a compile error. A module asked for a non-existent constant at compile time.

    The most likely cause is that Devel::Ladybug found a .ladybugrc, but the required symbol wasn't in the file. To fix this, add the missing named constant to your .ladybugrc. This typically happens when the .ladybugrc which was loaded is for an older version of Devel::Ladybug than is actually installed.

    This error may also be thrown when the .ladybugrc is malformed. If the named constant is present in the file, but this error is still occurring, check for broken syntax within the file. Missing ":" seperators between key and value pairs, or improper levels of indenting are likely culprits.

  • Host-specific overlay not working

    Verify that the name of the host-specific overlay matches the local host's "hostname" value, including fully-qualified-ness.

      > hostname
  foo

    In the case of non-FQ hostnames, as above, the overlay rc is named .ladybugrc-foo, whereas:

      > hostname
  foo.example.com

    In the fully qualified example above, the overlay rc would be named .ladybugrc-foo.example.com.

SEE ALSO

File::HomeDir, Sys::Hostname, YAML::Syck, constant

This file is part of Devel::Ladybug.