.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MooX::ConfigFromFile::Role::SortedByFilename 3pm"
.TH MooX::ConfigFromFile::Role::SortedByFilename 3pm "2022-12-11" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MooX::ConfigFromFile::Role::SortedByFilename \- allows filename based sort algorithm for multiple config files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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 { \*(AqRIGHT_PRECEDENT\*(Aq };
\&
\&  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"
\&    }
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "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).
.PP
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 \f(CW@File::ConfigDir::extensible_bases\fR.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "sorted_loaded_config"
.IX Subsection "sorted_loaded_config"
This role modifies the builder for \fIsorted_loaded_config\fR by sorting
the loaded files from \fIraw_loaded_config\fR by filename, extension
and location in the filesystem, respectively.
.PP
Let's assume the affected setup has a \fI\s-1CLI\s0\fR interface named \f(CW\*(C`oper\*(C'\fR
with \fIsub commands\fR like \f(CW\*(C`git\*(C'\fR provides them, too. And the company
using the application does it well by defining staging environments
like \f(CW\*(C`DEV\*(C'\fR (Development), \f(CW\*(C`TEST\*(C'\fR (Testing), \f(CW\*(C`INT\*(C'\fR (Integration) and
\&\f(CW\*(C`PROD\*(C'\fR (Production).  For the example, the \fIsub commands\fR shall be
\&\f(CW\*(C`deploy\*(C'\fR and \f(CW\*(C`report\*(C'\fR.
.PP
This will give you possible \f(CW\*(C`config_prefix_map\*(C'\fRs of
.PP
.Vb 10
\&  # main command
\&  [\*(Aqoper\*(Aq]
\&  [\*(Aqoper\*(Aq, \*(Aqdev\*(Aq]
\&  [\*(Aqoper\*(Aq, \*(Aqtest\*(Aq]
\&  [\*(Aqoper\*(Aq, \*(Aqint\*(Aq]
\&  [\*(Aqoper\*(Aq, \*(Aqprod\*(Aq]
\&  # deploy sub\-command
\&  [\*(Aqoper\*(Aq, \*(Aqdeploy\*(Aq]
\&  [\*(Aqoper\*(Aq, \*(Aqdeploy\*(Aq, \*(Aqdev\*(Aq]
\&  [\*(Aqoper\*(Aq, \*(Aqdeploy\*(Aq, \*(Aqtest\*(Aq]
\&  [\*(Aqoper\*(Aq, \*(Aqdeploy\*(Aq, \*(Aqint\*(Aq]
\&  [\*(Aqoper\*(Aq, \*(Aqdeploy\*(Aq, \*(Aqprod\*(Aq]
\&  # report sub\-command
\&  [\*(Aqoper\*(Aq, \*(Aqreport\*(Aq]
\&  [\*(Aqoper\*(Aq, \*(Aqreport\*(Aq, \*(Aqdev\*(Aq]
\&  [\*(Aqoper\*(Aq, \*(Aqreport\*(Aq, \*(Aqtest\*(Aq]
\&  [\*(Aqoper\*(Aq, \*(Aqreport\*(Aq, \*(Aqint\*(Aq]
\&  [\*(Aqoper\*(Aq, \*(Aqreport\*(Aq, \*(Aqprod\*(Aq]
.Ve
.PP
This will result in (let's further assume, developers prefer \f(CW\*(C`JSON\*(C'\fR,
operators prefer \f(CW\*(C`YAML\*(C'\fR) following possible config filenames:
.PP
.Vb 10
\&  [
\&    # main command
\&    \*(Aqoper.json\*(Aq,
\&    \*(Aqoper.yaml\*(Aq,
\&    \*(Aqoper\-dev.json\*(Aq,
\&    \*(Aqoper\-dev.yaml\*(Aq,
\&    \*(Aqoper\-test.json\*(Aq,
\&    \*(Aqoper\-test.yaml\*(Aq,
\&    \*(Aqoper\-int.json\*(Aq,
\&    \*(Aqoper\-int.yaml\*(Aq,
\&    \*(Aqoper\-prod.json\*(Aq,
\&    \*(Aqoper\-prod.yaml\*(Aq,
\&    # deploy sub\-command
\&    \*(Aqoper\-deploy.json\*(Aq,
\&    \*(Aqoper\-deploy.yaml\*(Aq,
\&    \*(Aqoper\-deploy\-dev.json\*(Aq,
\&    \*(Aqoper\-deploy\-dev.yaml\*(Aq,
\&    \*(Aqoper\-deploy\-test.json\*(Aq,
\&    \*(Aqoper\-deploy\-test.yaml\*(Aq,
\&    \*(Aqoper\-deploy\-int.json\*(Aq,
\&    \*(Aqoper\-deploy\-int.yaml\*(Aq,
\&    \*(Aqoper\-deploy\-prod.json\*(Aq,
\&    \*(Aqoper\-deploy\-prod.yaml\*(Aq,
\&    # report sub\-command
\&    \*(Aqoper\-report.json\*(Aq,
\&    \*(Aqoper\-report.yaml\*(Aq,
\&    \*(Aqoper\-report\-dev.json\*(Aq,
\&    \*(Aqoper\-report\-dev.yaml\*(Aq,
\&    \*(Aqoper\-report\-test.json\*(Aq,
\&    \*(Aqoper\-report\-test.yaml\*(Aq,
\&    \*(Aqoper\-report\-int.json\*(Aq,
\&    \*(Aqoper\-report\-int.yaml\*(Aq,
\&    \*(Aqoper\-report\-prod.json\*(Aq,
\&    \*(Aqoper\-report\-prod.yaml\*(Aq,
\&  ]
.Ve
.PP
For a particular invoking (\f(CW\*(C`oper report\*(C'\fR in \f(CW\*(C`int\*(C'\fR stage) following
files exists:
.PP
.Vb 9
\&  [
\&    \*(Aq/etc/oper.json\*(Aq,                 # global configuration by developers
\&    \*(Aq/etc/oper.yaml\*(Aq,                 # global configuration by operating policy
\&    \*(Aq/opt/ctrl/etc/oper.json\*(Aq,        # vendor configuration by developers
\&    \*(Aq/opt/ctrl/etc/oper.yaml\*(Aq,        # vendor configuration by operating policy
\&    \*(Aq/opt/ctrl/etc/oper\-int.yaml\*(Aq,    # vendor configuration by stage operating policy
\&    \*(Aq/opt/ctrl/etc/oper\-report.yaml\*(Aq, # vendor configuration by report operating team
\&    \*(Aq/home/usr4711/oper\-report.yaml\*(Aq, # usr4711 individual configuration (e.g. for template adoption)
\&  ]
.Ve
.PP
The default sort algorithm will deliver
.PP
.Vb 9
\&  [
\&    "/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"
\&  ]
.Ve
.PP
This role will change the sort algorithm to deliver
.PP
.Vb 9
\&  [
\&    "/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"
\&  ]
.Ve
.PP
Which will cause that all policy configuration will override the
developer defaults and user configuration override policy settings.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jens Rehsack, \f(CW\*(C`<rehsack at cpan.org>\*(C'\fR
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2018 Jens Rehsack.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the \s-1GNU\s0 General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See <http://dev.perl.org/licenses/> for more information.