NAME

       MooX::ConfigFromFile::Role::SortedByFilename - allows filename based sort algorithm for
       multiple config files

SYNOPSIS

         package MyApp::Cmd::TPau;

         use DBI;
         use Moo;
         use MooX::Cmd with_configfromfile => 1;

         with "MooX::ConfigFromFile::Role::SortedByFilename";
         with "MooX::ConfigFromFile::Role::HashMergeLoaded";

         # ensure hashes are merged by top-most scalar wins
         around _build_config_merge_behavior => sub { 'RIGHT_PRECEDENT' };

         has csv => (is => "ro", required => 1);

         sub execute
         {
             my $self = shift;
             DBI->connect("DBI::csv:", undef, undef, $self->csv);
         }

         __END__
         $ cat etc/myapp.json
         {
           "csv": {
             "f_ext": ".csv/r",
             "f_dir": "data"
             "csv_sep_char": ";",
             "csv_class": "Text::CSV_XS"
           }
         }
         $cat etc/myapp-tpau.json
         {
           "csv": {
             "f_dir": "data/tpau"
           }
         }

DESCRIPTION

       This is an additional role for MooX::ConfigFromFile to allow merging loaded configurations
       in a more predictable order: filename > extension > path.  (Read: When the filename is
       identical, the extensions are compared, when they are identical, the locations are
       compared).

       While filename and file extension are compared on character basis, the sort order of the
       file locations (path) is based on precedence in MooX::File::ConfigDir or File::ConfigDir,
       respectively. This order is defined internally in @File::ConfigDir::extensible_bases.

ATTRIBUTES

   sorted_loaded_config
       This role modifies the builder for sorted_loaded_config by sorting the loaded files from
       raw_loaded_config by filename, extension and location in the filesystem, respectively.

       Let's assume the affected setup has a CLI interface named "oper" with sub commands like
       "git" provides them, too. And the company using the application does it well by defining
       staging environments like "DEV" (Development), "TEST" (Testing), "INT" (Integration) and
       "PROD" (Production).  For the example, the sub commands shall be "deploy" and "report".

       This will give you possible "config_prefix_map"s of

         # main command
         ['oper']
         ['oper', 'dev']
         ['oper', 'test']
         ['oper', 'int']
         ['oper', 'prod']
         # deploy sub-command
         ['oper', 'deploy']
         ['oper', 'deploy', 'dev']
         ['oper', 'deploy', 'test']
         ['oper', 'deploy', 'int']
         ['oper', 'deploy', 'prod']
         # report sub-command
         ['oper', 'report']
         ['oper', 'report', 'dev']
         ['oper', 'report', 'test']
         ['oper', 'report', 'int']
         ['oper', 'report', 'prod']

       This will result in (let's further assume, developers prefer "JSON", operators prefer
       "YAML") following possible config filenames:

         [
           # main command
           'oper.json',
           'oper.yaml',
           'oper-dev.json',
           'oper-dev.yaml',
           'oper-test.json',
           'oper-test.yaml',
           'oper-int.json',
           'oper-int.yaml',
           'oper-prod.json',
           'oper-prod.yaml',
           # deploy sub-command
           'oper-deploy.json',
           'oper-deploy.yaml',
           'oper-deploy-dev.json',
           'oper-deploy-dev.yaml',
           'oper-deploy-test.json',
           'oper-deploy-test.yaml',
           'oper-deploy-int.json',
           'oper-deploy-int.yaml',
           'oper-deploy-prod.json',
           'oper-deploy-prod.yaml',
           # report sub-command
           'oper-report.json',
           'oper-report.yaml',
           'oper-report-dev.json',
           'oper-report-dev.yaml',
           'oper-report-test.json',
           'oper-report-test.yaml',
           'oper-report-int.json',
           'oper-report-int.yaml',
           'oper-report-prod.json',
           'oper-report-prod.yaml',
         ]

       For a particular invoking ("oper report" in "int" stage) following files exists:

         [
           '/etc/oper.json',                 # global configuration by developers
           '/etc/oper.yaml',                 # global configuration by operating policy
           '/opt/ctrl/etc/oper.json',        # vendor configuration by developers
           '/opt/ctrl/etc/oper.yaml',        # vendor configuration by operating policy
           '/opt/ctrl/etc/oper-int.yaml',    # vendor configuration by stage operating policy
           '/opt/ctrl/etc/oper-report.yaml', # vendor configuration by report operating team
           '/home/usr4711/oper-report.yaml', # usr4711 individual configuration (e.g. for template adoption)
         ]

       The default sort algorithm will deliver

         [
           "/etc/oper.json",
           "/etc/oper.yaml",
           "/home/usr4711/oper-report.yaml",
           "/opt/ctrl/etc/oper-int.yaml",
           "/opt/ctrl/etc/oper-report.yaml",
           "/opt/ctrl/etc/oper.json",
           "/opt/ctrl/etc/oper.yaml"
         ]

       This role will change the sort algorithm to deliver

         [
           "/etc/oper.json",
           "/opt/ctrl/etc/oper.json",
           "/etc/oper.yaml",
           "/opt/ctrl/etc/oper.yaml",
           "/opt/ctrl/etc/oper-int.yaml",
           "/opt/ctrl/etc/oper-report.yaml",
           "/home/usr4711/oper-report.yaml"
         ]

       Which will cause that all policy configuration will override the developer defaults and
       user configuration override policy settings.

AUTHOR

       Jens Rehsack, "<rehsack at cpan.org>"

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

       Copyright 2018 Jens Rehsack.

       This program is free software; you can redistribute it and/or modify it under the terms of
       either: the GNU General Public License as published by the Free Software Foundation; or
       the Artistic License.

       See <http://dev.perl.org/licenses/> for more information.

perl v5.28.1                                2019MooX::ConfigFromFile::Role::SortedByFilename(3pm)