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

NAME

OP::Constants - Loads .oprc values as Perl constants

DESCRIPTION

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

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

An example .oprc is included in the top level directory of this distribution, and also given later in this document. Copy this file to the proper location, or just run bin/opconf (also included with this distribution) to generate this for your local system and current user.

SECURITY

The .oprc file represents the keys to the kingdom.

Treat your .oprc 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 OP::Constants:

 use OP::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 OP::Constants;

 my $dbUser = OP::Constants::dbUser;
 my $dbPass = OP::Constants::dbPass;

EXAMPLE

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

  ---
  ldapHost: ldap
  yamlRoot: /opt/op/yaml
  sqliteRoot: /opt/op/sqlite
  scratchRoot: /tmp
  dbHost: localhost
  dbPass: ~
  dbPort: 3306
  dbUser: op
  memcachedHosts:
    - 127.0.0.1:31337
  rcsBindir: /usr/bin
  rcsDir: RCS
  syslogHost: ~

HOST-SPECIFIC OVERLAYS

After loading .oprc, OP::Constants checks for the presence of a file named .oprc-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 .oprc.

  > hostname
  foo.example.com

  > cat $OP_HOME/.oprc-foo.example.com
  ---
  dbHost: stgdb.example.com

CUSTOM RC FILES

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

Just as .oprc, the custom rc file must contain valid YAML, and it lives under $ENV{OP_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| OP::Constants |;

  OP::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 $OP_HOME/.myapprc-foo.example.com
  ---
  dbHost: stgdb.example.com

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

DIAGNOSTICS

  • No .oprc found

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

  • Some symbol not exported

      Uncaught exception from user code:
        "______" is not exported by the OP::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 OP found an .oprc, but the required symbol wasn't in the file. To fix this, add the missing named constant to your .oprc. This typically happens when the .oprc which was loaded is for an older version of OP than is actually installed.

    This error may also be thrown when the .oprc 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 .oprc-foo, whereas:

      > hostname
  foo.example.com

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

SEE ALSO

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

This file is part of OP.