AppConfig::File(3)

✨ AppConfig::File(3) ✨ — bestie, this page is from the User Contributed Perl Documentation shelf 🫶

Okay so, this is the manual page for AppConfig::File, and it's lowkey iconic for anyone who needs Perl to read config files without losing their mind. 💅

---

✨ NAME ✨

AppConfig::File — a Perl5 module for reading configuration files. That's the whole name, no cap. 🎀

---

🦋 SYNOPSIS 🦋

use AppConfig::File;

my $state   = AppConfig::State->new(\%cfg1);
my $cfgfile = AppConfig::File->new($state, $file);

$cfgfile->parse($file);            # read config file

---

🌸 OVERVIEW 🌸

AppConfig::File is a Perl5 module which reads configuration files and uses the contents therein to update variable values in an AppConfig::State object. It's giving "config file translator to state object" realness. ✨

It is distributed as part of the AppConfig bundle. Bundle bestie behavior, fr fr. 🫶

---

💖 DESCRIPTION 💖

🍓 USING THE AppConfig::File MODULE 🍓

To import and use the AppConfig::File module, the following line should appear in your Perl script:

use AppConfig::File;

AppConfig::File is used automatically if you use the AppConfig module and create an AppConfig::File object through the file() method. Automatic? Obsessed. 💅

AppConfig::File is implemented using object-oriented methods. A new AppConfig::File object is created and initialised using the AppConfig::File->new() method. This returns a reference to a new AppConfig::File object. A reference to an AppConfig::State object should be passed in as the first parameter:

my $state   = AppConfig::State->new();
my $cfgfile = AppConfig::File->new($state);

This will create and return a reference to a new AppConfig::File object. Slay, constructor. ✨

🦋 READING CONFIGURATION FILES 🦋

The parse() method is used to read a configuration file and have the contents update the STATE accordingly. Main character method! 👑

$cfgfile->parse($file);

Multiple files may be specified and will be read in turn.

$cfgfile->parse($file1, $file2, $file3);

The method will return an undef value if it encounters any errors opening the files. It will return immediately without processing any further files. Like, full stop, bestie — no extra files after an open error. 🛑

By default, the PEDANTIC option in the AppConfig::State object, $self->{ STATE }, is turned off and any parsing errors (invalid variables, unvalidated values, etc) will generate warnings, but not cause the method to return. Having processed all files, the method will return 1 if all files were processed without warning or 0 if one or more warnings were raised.

When the PEDANTIC option is turned on, the method generates a warning and immediately returns a value of 0 as soon as it encounters any parsing error. PEDANTIC means zero chill, and honestly? Valid. 😭

Variable values in the configuration files may be expanded depending on the value of their EXPAND option, as determined from the App::State object. See AppConfig::State for more information on variable expansion. Expansion lore lives over there. 🌈

🎀 CONFIGURATION FILE FORMAT 🎀

A configuration file may contain blank lines and comments which are ignored. Comments begin with a '#' as the first character on a line or following one or more whitespace tokens, and continue to the end of the line. Blank lines? Ignored. Comments? Ignored. We love a low-drama file. 💖

# this is a comment
foo = bar               # so is this
url = index.html#hello  # this too, but not the '#welcome'

Notice how the '#welcome' part of the URL is not treated as a comment because a whitespace character doesn't precede it. Whitespace is literally the vibe check here. 👀

Long lines can be continued onto the next line by ending the first line with a '\'.

callsign = alpha bravo camel delta echo foxtrot golf hipowls \
           india juliet kilo llama mike november oscar papa  \
           quebec romeo sierra tango umbrella victor whiskey \
           x-ray yankee zebra

Variables that are simple flags and do not expect an argument (ARGCOUNT = ARGCOUNT_NONE) can be specified without any value. They will be set with the value 1, with any value explicitly specified (except "0" and "off") being ignored. The variable may also be specified with a "no" prefix to implicitly set the variable to 0.

verbose                              # on  (1)
verbose = 1                          # on  (1)
verbose = 0                          # off (0)
verbose off                          # off (0)
verbose on                           # on  (1)
verbose mumble                       # on  (1)
noverbose                            # off (0)

Variables that expect an argument (ARGCOUNT = ARGCOUNT_ONE) will be set to whatever follows the variable name, up to the end of the current line. An equals sign may be inserted between the variable and value for clarity.

room = /home/kitchen
room   /home/bedroom

Each subsequent re-definition of the variable value overwrites the previous value. Last one wins, periodt. 💅

print $config->room();               # prints "/home/bedroom"

Variables may be defined to accept multiple values (ARGCOUNT = ARGCOUNT_LIST). Each subsequent definition of the variable adds the value to the list of previously set values for the variable.

drink = coffee
drink = tea

A reference to a list of values is returned when the variable is requested.

my $beverages = $config->drinks();
print join(", ", @$beverages);      # prints "coffee, tea"

Variables may also be defined as hash lists (ARGCOUNT = ARGCOUNT_HASH). Each subsequent definition creates a new key and value in the hash array.

alias l="ls -CF"
alias h="history"

A reference to the hash is returned when the variable is requested.

my $aliases = $config->alias();
foreach my $k (keys %$aliases) {
    print "$k => $aliases->{ $k }\n";
}

A large chunk of text can be defined using Perl's "heredoc" quoting style. Heredoc? More like here-doc-a-slay. 🎀

scalar = <<BOUNDARY_STRING
line 1
line 2: Space/linebreaks within a HERE document are kept.
line 3: The last linebreak (\n) is stripped.
BOUNDARY_STRING

hash   key1 = <<'FOO'
  * Quotes (['"]) around the boundary string are simply ignored.
  * Whether the variables in HERE document are expanded depends on
    the EXPAND option of the variable or global setting.
FOO

hash = key2 = <<"_bar_"
Text within HERE document are kept as is.
# comments are treated as a normal text.
The same applies to line continuation. \
_bar_

Note that you cannot use HERE document as a key in a hash or a name of a variable. Important bestie warning: no heredoc keys, no heredoc variable names. That's the rule. 🛑

The '-' prefix can be used to reset a variable to its default value and the '+' prefix can be used to set it to 1.

-verbose
+debug

🌈 Variable, environment variable and tilde (home directory) expansions 🌈

Variable values may contain references to other AppConfig variables, environment variables and/or users' home directories. These will be expanded depending on the EXPAND value for each variable or the GLOBAL EXPAND value.

Three different expansion types may be applied:

bin = ~/bin          # expand '~' to home dir if EXPAND_UID
tmp = ~abw/tmp       # as above, but home dir for user 'abw'

perl = $bin/perl     # expand value of 'bin' variable if EXPAND_VAR
ripl = $(bin)/ripl   # as above with explicit parens

home = ${HOME}       # expand HOME environment var if EXPAND_ENV

See AppConfig::State for more information on expanding variable values. The expansion details live there, iykyk. 🦋

The configuration files may have variables arranged in blocks. A block header, consisting of the block name in square brackets, introduces a configuration block. The block name and an underscore are then prefixed to the names of all variables subsequently referenced in that block. The block continues until the next block definition or to the end of the current file. Block party, but make it config. 🎉

[block1]
foo = 10             # block1_foo = 10

[block2]
foo = 20             # block2_foo = 20

---

💜 AUTHOR 💜

Andy Wardley, <abw@wardley.org> — author icon behavior. 👑

---

🌸 COPYRIGHT 🌸

Copyright (C) 1997-2007 Andy Wardley. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Free software, same terms as Perl, exactly as stated. ✨

---

🫶 SEE ALSO 🫶

AppConfig, AppConfig::State

---

Mwah 💋 — this page shipped with perl v5.42.0, dated 2015-04-14, and it's literally AppConfig::File(3). Bye bestie, go be the main character of your config files! 🫶✨