1PFT::Conf(3)          User Contributed Perl Documentation         PFT::Conf(3)
2
3
4

NAME

6       PFT::Conf - Configuration parser for PFT
7

SYNOPSIS

9           PFT::Conf->new_default()        # Using default
10           PFT::Conf->new_load($root)      # Load from conf file in directory
11           PFT::Conf->new_load_locate()    # Load from conf file, find directory
12           PFT::Conf->new_load_locate($cwd)
13
14           PFT::Conf::locate()             # Locate root
15           PFT::Conf::locate($cwd)
16
17           PFT::Conf::isroot($path)        # Check if location exists under path.
18
19           use Getopt::Long;
20           Getopt::Long::Configure 'bundling';
21           GetOptions(
22               PFT::Conf::wire_getopt(\my %opts),
23               'more-opt' => \$more,
24           );
25           PFT::Conf->new_getopt(\%opts);  # Create with command line options
26

DESCRIPTION

28       Automatic loader and handler for the configuration file of a PFT site.
29
30       The configuration is a simple YAML file with a conventional name.  Some
31       keys are mandatory, while other are optional. This module allows a
32       headache free check for mandatory ones.
33
34
35       Many constructors are available, here described:
36
37       new_default
38           Creates a new configuration based on environment variables and
39           common sense.
40
41           The configuration can later be stored on a file with the "save_to"
42           method.
43
44       new_load
45           Loads a configuration file which must already exist. Accepts as
46           optional argument the name of a directory (not encoded), which
47           defaults on the current directory.
48
49           This constructor fails with "croak" if the directory does not
50           contain a configuration file.
51
52       new_load_locate
53           Works as "new_load", but before failing makes an attempt to locate
54           the configuration file in the parent directories up to the root
55           level.
56
57           This is handy for launching commands from the command line without
58           worrying on the current directory: it works as long as your cwd is
59           below a PFT root directory.
60
61       wire_getopt and new_getopt
62           This is a two-steps constructor meant for command line
63           initializers.
64
65           An example of usage can be found in the SYNOPSIS section. In short,
66           the auxiliary function "PFT::Conf::wire_getopt" provides a list of
67           ready-to-use options for the "GetOpt::Long" Perl module. It expects
68           a hash reference as argument, which will be used as storage for
69           selected options. The "new_getopt" constructor expects as argument
70           the same hash reference.
71
72   Shared variables
73       $PFT::Conf::CONF_NAME is a string. Defines the name of the
74       configuration file.
75
76   Utility functions
77       isroot
78           The "PFT::Conf::isroot" function searches for the configuration
79           file in the given directory path (not encoded).
80
81           Returns "undef" if the file was not found, and the encoded file
82           name (according to locale) if it was found.
83
84       locate
85           The "PFT::Conf::locate" function locates a PFT configuration file.
86
87           It accepts as optional parameter a directory path (not encoded),
88           defaulting on the current working directory.
89
90           Possible return values:
91
92           The input directory itself if the configuration file was found in
93           it;
94           The first encountered parent directory containing the configuration
95           file;
96           "undef" if no configuration file was found, up to the root of all
97           directories.
98
99   Methods
100       save_to
101        Save the configuration to a file. This will also update the inner root
102        reference, so the intsance will point to the saved file.
103
104
105
106perl v5.36.0                      2023-01-20                      PFT::Conf(3)
Impressum